Google Search Appliance Google OneBox for Enterprise Developer’s Guide Google Search Appliance software version 6.
Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 www.google.com May 2010 © Copyright 2012 Google, Inc. All rights reserved. Google and the Google logo are registered trademarks or service marks of Google, Inc. All other trademarks are the property of their respective owners. Use of any Google solution is governed by the license agreement included in your original contract.
Contents Google OneBox for Enterprise Developer’s Guide ...........................................................
Google OneBox for Enterprise Developer’s Guide A OneBox module provides real-time access to data from an external source, or a collection on a search appliance. This document describes how to define a OneBox module and how to use the OneBox Simulator (http:/ /google-developers.appspot.com/search-appliance/download/downloadsdk), which enables you to test your OneBox code before putting your code on a search appliance.
Google.com uses the OneBox extensively to provide users with access to information in different content repositories, such as Google News, Google Images, and Google Book Search. On Google.com, the use of OneBox also provides real-time data such as weather, flight tracking, package tracking, and movie times. Google.com provides a single text entry box instead of a complex interface for specifying information types.
Google implements the OneBox request/response technology in XML, which enables you to make changes easily to the OneBox functionality. You can add OneBox functions by defining and implementing OneBox modules. Note: A OneBox module cannot use a rewritten query term expanded by the query expansion feature. A OneBox module always uses the original query term before a query expansion occurs. For more information on query expansion, see “Widening Searches” in Creating the Search Experience.
Planning When defining a OneBox module, you need to work with the Admin Console for configuration and may need additional software to facilitate your use of OneBox modules: • First time use, define the OneBox from the Admin Console. For more information, see “Defining a OneBox Module in the Admin Console” on page 7. • Using an internal provider, you can define your OneBox from the Admin Console or with an XML configuration file. For more information, see “Using an Internal Provider” on page 11.
3. 4. In the Trigger section, click one of the following choices: • Always Trigger—Cause the OneBox to appear on every search query. For more information, see “Triggering on Every Query” on page 9. • Keywords—Specify one or more words that a can user can enter that cause a OneBox to appear. Separate multiple keywords with a pipe symbol. For example, phone|contact|info. For more information, see “Triggering in Response to Specific Keywords” on page 10.
3. Give the module a (see the element “name” on page 23) and (see the element “description” on page 24). The name references the OneBox module on the outbound call from the search appliance. The description explains the module’s functionality to search appliance administrators and appears in the Admin Console. PAGE 10Triggering in Response to Specific Keywords Our directory example uses a keyword trigger, directory. A keyword trigger must be the first word of the user’s search query, so that the search appliance invokes a module when the search query has the form directory Bill Smith but not when the search query has the form employee directory. You can specify multiple keywords by separating each word with a pipe symbol, for example, directory|phone|contact.
• The regular expression (?i)([a-z]+) airport(?: (?:status|delays?|conditions))? matches queries such as the following: • lax airport conditions • SFO airport delays • newark airport status A regular expression provides great flexibility, but you must ensure that a search appliance rapidly evaluates the expression so as not to degrade performance during searches.
Use of OneBox with an external provider starts with a search request that matches the trigger. In response, a search appliance issues a standard HTTP GET command to the provider. The request from a search appliance to the provider is a URL that combines the provider host and path with a set of namevalue pairs. The name-value pairs start with a question mark and use an ampersand (&) characters to separate the input parameters that are sent to the provider.
The following example shows the results from a directory smith query and the directory items for William Smith and Bill Smith. The tag contains the information sent from the provider for the search results: ACME Employee Directory <urltext>13 results in the ACME directory</urltext> <urllink>http://directory.corp.acme.com/cgi-bin/search?smith</urllink> http://directory.corp.acme.
Formatting the Results Both internal and external providers respond to a OneBox call with XML results. Google enforces a vertical limit of 150 pixels on the HTML for the output. To display the results as HTML, the OneBox module definition can contain an XSLT template that a search appliance applies in a front end. You specify the XSLT template inside the element. For example, you can specify the directory example as follows: 13 results in the ACME directory William Smith - wsmith@acmecorp.
The XSLT template transforms the associated results into HTML suitable for display.
Checking the Visual Layout You can verify an XSLT template by: • Using the OneBox Simulator (see “Testing with the OneBox Simulator” on page 19). • Inserting a temporary wrapper element in the XSLT file. The wrapper enables you to see how the OneBox results appears, but doesn’t provide an interface for testing different parameters as does the OneBox Simulator. Note: If you use the wrapper code to verify your layout, you must remove the wrapper code before deploying your template on a search appliance.
When sensitive information passes between a search appliance and an external provider, it’s best to use an SSL connection for secure data transfer. You do this by specifying the external provider URL as https in the OneBox module definition. The secure URL causes the search appliance to establish a protected session for transferring data, and request a valid certificate from the provider.
Passing Optional Contextual Data The OneBox system can pass a set of contextual data that is useful in developing an external provider and determining more personalized, relevant results. The following additional contextual information is passed to the provider: • Date and time of the query • IP address of the querying user’s machine • Language of the query as defined by a user’s browser setting You can use or suppress these options.
Checking XML Results When you are troubleshooting a OneBox module that has a running provider, you can issue a query, change the URL, and then view the XML results. To view XML results: 1. Display the search page and issue a query that invokes the OneBox provider. 2. In the address bar of the browser window, remove the &proxystylesheet=front_end parameter from the URL.
Editing customer-onebox.xsl to Call Your XSL File Edit the customer-onebox.xsl file to point to the projects.xsl file as follows: PAGE 214. Edit search.xml to appear as follows: Corporate Project Database <urltext>Lookup results for project 1</urltext> <urllink> http://www.mycompany.com/cgi-bin/projects?projectId=1 </urllink> http://www.mycompany.com/icons/favicon.ico http://www.mycompany.
Module Definition Schema The OneBox module definition schema file is available in the onebox.xsd file, which is available in the OneBox simulator download (http://google-developers.appspot.com/search-appliance/download/ downloadsdk). Your OneBox module definition XML file must conform to this schema. For information about GET call parameters, see “Call Parameters” on page 25.
Element Attributes Attribute Description type="internal"|"external" Required. The type of onebox module, internal (calling a collection) or external (calling an external provider). suppressDateTime="true"|"false" Optional. Determines whether the search appliance passes date and time information to the external provider. suppressIPAddr="true"|"false" Optional. Determines whether the search appliance passes the IP address of the querying user’s machine.
Element Description description text Optional. A textual description of what the OneBox module does. This value is important if you plan to make the modules that you develop available for others to use. The description can contain up to 512 characters. trigger keyword_or_regex Optional. The trigger expression determines when the search appliance invokes the module.
Call Parameters A GET request from a search appliance is sent to the external provider as specified in the OneBox module definition. The table below lists the parameters in a GET call. Parameter Required Description Type of Value apiMaj required API major version number. Changes in this value may break compatibility. Integer (1, 2, 3...) apiMin required API minor version number. Changes in this value do not break compatibility. Integer (0, 1, 2, 3...
OneBox Results Schema Reference Results are returned to a search appliance in the form of XML that conforms to the OneBox Results schema. Results Definition Schema The results definition schema file is available in the oneboxresults.xsd file, which is included in the OneBox simulator download (http://google-developers.appspot.com/search-appliance/download/ downloadsdk). Note: Do not set the id= attributes that appear in the oneboxresults.xsd file. The search appliance does not use any of the id attributes.
OneBoxResults Elements The OneBoxResults element supports the following child elements: Element Description resultCode result_code Optional, a single use of this tag is permitted. The return code is from the OneBox provider. The value success is assumed if no value is returned, and results are processed only on success. Although this element is optional, it is good practice to always return a result code.
Element Description IMAGE_SOURCE image_url Optional. A link to the image that displays in the OneBox results. MODULE_RESULT child_elements Optional. Describes the results that the provider sends to the search appliance. The search appliance supports up to eight MODULE_RESULT blocks from external providers, or up to three from an internal provider. The absence of this element means that there were no search results found for the query.
Index Symbols E &proxystylesheet 19 elements collection 11, 24 description 9, 24 Diagnostics 18, 27 field 13 globals 22 GoogleEnterpriseSources 22 GSA_password 17 GSA_username 17 IMAGE_SOURCE 28 MODULE_RESULT 18, 28 ModulesPerFrontEnd 22 name 9, 23 onebox 8, 18, 22 OneBoxResults 27 provider 27 providerURL 11, 24 resultCode 18, 27 resultsTemplate 14, 24 security 17, 23 title 27 trigger 9, 24 errors 18 example OneBox module 5 external provider adding a secure connection 17 description 6 methods for defini
gsa_default_stylesheet.en.
