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.

Before starting development, refer to Google OneBox for Enterprise Design Principles, which provides information about how to design a OneBox module. Google also provides the Custom KeyMatch OneBox (http://code.google.com/p/custom-keymatch-onebox/).

For information about Onebox module limitations, see Specifications and Usage Limits.

Back to top

Introduction

Google OneBox gives users access to real-time data through a simple, fast, and easy to configure search interface.

A OneBox defines a search type, the keyword that invokes the search, and the way that a search appliance obtains and returns information after a user invokes a search. You can define any number of OneBox modules, and a user search page can display results from multiple OneBox modules.

A OneBox module consists of the following components:

You define this information on a search appliance by entering the information in the Admin Console or by specifying the information in an XML configuration file and importing it. For information on XML schema, see the OneBox Module Definition XML Reference.

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.

The name “OneBox” refers to the search box that provides access to information from many sources. OneBox can also refer to the formatted output that appears in response to specific query keywords.

The following figure shows the OneBox that displays on Google.com. Here, a user searches for american 102:

In this example, the search interprets a user’s entry for an airline name and a number as a request for flight information. The OneBox results appear above other search results and are visually distinguished from the other results.

Google OneBox for Enterprise brings the power and simplicity of search to provide fast access to information in an enterprise network. Using Google OneBox for Enterprise, you can create Onebox modules that provide users with real-time business data from enterprise resource planning (ERP) systems, customer relationship management (CRM) applications, or business intelligence analysis.

For example, you can create OneBox modules for the following types of company information:

You can create OneBox modules for the following types of educational information:

A search appliance can resolve OneBox queries using an internal or external provider. You specify provider information in an XML file that the search appliance interprets to determine how to resolve the OneBox query. The search appliance returns internal OneBox queries directly to the user interface. A search appliance can also resolve queries externally, through calls to external systems.

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.

Back to top

Summary of Steps to Define and Deploy a OneBox Module

Google enables you to define a OneBox module that you can trigger by a keyword or a regular expression, or instead of triggering, the OneBox can appear on every search query. A OneBox module can either search a collection or access a URL for a site that returns XML results. You can define a OneBox from the search appliance’s Admin Console. This section introduces the procedures described in this document.

To define and deploy a OneBox module:

Back to top

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:

Working with an XML configuration file:

Back to top

Defining a OneBox Module in the Admin Console

To define a OneBox module in the Admin Console:

After the search appliance crawls the content in the collection, you can test your OneBox from search.

Back to top

Defining a OneBox Module Using an XML Configuration File

To define a OneBox from an XML configuration file:

<?xml version="1.0" encoding="UTF-8"?>

  <GoogleEnterpriseSources xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <onebox type="external">

  ...

<?xml version="1.0" encoding="UTF-8"?>

<GoogleEnterpriseSources xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <onebox type="external">

    <name>directory_example</name>

    <description>This sample OneBox queries a phone directory</description>

    ...

  </onebox>

</GoogleEnterpriseSources>

Next, create a trigger as described in Creating a Trigger.

Creating a Trigger

A trigger determines which search queries invoke a OneBox module. A trigger can be a keyword, type of phrase, or a regular expression. You specify the module’s keyword in the trigger element. The format of the trigger element is as follows:

<trigger triggerType="when_to_trigger">trigger_word</trigger>

You can define a trigger in the XML configuration file or by creating and editing a OneBox in the Admin Console.

The table below lists the triggerType attribute values.

 

Attribute	Description	Example
null	Invoke trigger on every query.	<trigger triggerType="null"></trigger>
keyword	Invoke in response to one or more keywords. Specify keyword as the value of the element.	<trigger triggerType="keyword">directory</trigger>
regex	Invoke when a query matches a regular expression.	<trigger triggerType="regex">directory (.*)</trigger>

The trigger element is optional. If you omit a trigger, the OneBox module invokes on every query.

Triggering on Every Query

If you have a high-bandwidth provider and network and query traffic is not a concern, the search appliance can invoke a module on every query. In that case, a provider must determine whether the module should return results to the user. You can achieve the best user experience by returning OneBox results only when they enhance a user’s overall search results.

Triggering 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. If you want the keyword trigger to invoke on a word other than the first word, use a regular expression.

To define a trigger in the XML configuration file, specify the <trigger> element as follows:

<onebox type="external">

  <name>directory_example</name>

  <description>This sample OneBox queries a phone directory</description>

  <trigger triggerType="keyword">directory</trigger>

  ...

</onebox>

To specify multiple keywords, the <trigger> tag could appear as follows:

<trigger triggerType="keyword">directory|dir|d:|phone</trigger>

This example shows how you can use multiple keywords to provide abbreviated versions of a keyword or an alternative keyword.

Triggering When the Query Matches a Regular Expression

If you use a regular expression trigger, a search appliance compares the search query to the regular expression pattern and invokes the OneBox module if the query and the pattern match. OneBox supports regular expressions as defined by the Perl Compatible Regular Expressions library (PCRE) at http://perldoc.perl.org/perlre.html. Enclose each expression in parentheses. You can separate multiple expressions with a space, for example,

<trigger triggerType="regex">(i) (.*) report</trigger> 

ignores case and matches any word before report.

The table below lists common regular expression rules.

 

Syntax	Description
(.*)	Match any character zero or more times; that is, match any word
(.?)	Match a single character
(\d+)	Match a digit one or more times
(i)	Ignore case
([a-z]+)	Match lowercase letters one or more times
(?: values)	Match specific keyword values

The following are examples of the common regular expression rules:

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. Note that the regular expression language used by OneBox triggers is not the same as the Google regular expressions that a search appliance uses for URL patterns.

Specifying and Calling a Provider

A OneBox provider can be internal or external. An internal provider is a collection on a search appliance. An external provider is an application outside a search appliance.

Using an Internal Provider

To use an internal provider, specify the <collection> element (see the element collection) and use the name of the collection as defined on a search appliance. The following example specifies an internal provider using the InternalNews collection for the news trigger:

<onebox type="internal">

  <name>news</name>

  <description>This sample OneBox queries an intranet news source</description>

  <trigger triggerType="keyword">news</trigger>

  <collection>InternalNews</collection>

  <resultsTemplate></resultsTemplate>

</onebox>

Using an External Provider

To specify an external provider, use the <providerURL> element (see the element providerURL) to specify the location of an external provider with the following guidelines:

http://server.mydomain.com:port/directory/...

https://secure.server.mydomain.com:port/directory/...

The following example specifies Acme.com as the external provider for the directory trigger:

<onebox type="external">

  <name>directory_example</name>

  <description>This sample OneBox queries a phone directory</description>

  <security userAuth="none"/>

  <trigger triggerType="keyword">directory</trigger>

  <providerURL>http://directory.corp.acme.com/cgi-bin/phonebook</providerURL>

  <resultsTemplate>{xslt template} <resultsTemplate/>

</onebox>

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 name-value 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 HTTP GET commands that the search appliance constructs and sends to the example Acme.com external provider:

GET http://directory.corp.acme.com/cgi-bin/phonebook? 

apiMaj=1&apiMin=0&oneboxName=directory_example&

ipAddr=10.72.1.3&authType=none&lang=en&query=smith

GET https://directory.corp.acme.com/cgi-bin/phonebook? 

apiMaj=1&apiMin=0&oneboxName=secure_example&

ipAddr=10.72.1.3&lang=en&authType=basic&userName=jdoe&password=Co0lOneBoX&query=smith

The OneBox trigger term is not sent in the GET command. In the examples, the user enters directory smith, but the GET command includes only smith as the value for the query parameter. The complete set of input parameters from a search appliance are defined in Call Parameters.

Receiving a Provider’s Response

Upon receiving the a request from a search appliance, a provider processes the input parameters and compiles a result set to return to the search appliance. The provider response must conform to the OneBox Results Schema (see OneBox Results Schema Reference).

The following example shows the results from a directory smith query and the directory items for William Smith and Bill Smith. The <MODULE_RESULT> tag contains the information sent from the provider for the search results:

<?xml version="1.0" encoding="UTF-8"?>

<OneBoxResults>

  <provider>ACME Employee Directory</provider>

  <title>

    <urlText>13 results in the ACME directory</urlText>

    <urlLink>http://directory.corp.acme.com/cgi-bin/search?smith</urlLink>

  </title>

  <IMAGE_SOURCE>http://directory.corp.acme.com/images/directory.jpg

    </IMAGE_SOURCE>

  <MODULE_RESULT>

    <U>http://directory.corp.acme.com/cqi-bin/lookup?empid=448473</U>

    <Field name="display">Smith, William</Field>

    <Field name="firstname">William</Field>

    <Field name="lastname">Smith</Field>

    <Field name="phone">617-555-1234</Field>

    <Field name="email">wsmith@acme.com</Field>

    <Field name="picture">http://directory.corp.acme.com/cqi-bin/lookup? 

      photo=448473</Field>

  </MODULE_RESULT>

  <MODULE_RESULT>

    <U>http://directory.corp.acme.com/cqi-bin/lookup?empid=22638</U>

    <Field name="display">Smith, Bill R.</Field>

    <Field name="firstname">Bill</Field>

    <Field name="lastname">Smith</Field>

    <Field name="phone">617-555-9345</Field>

    <Field name="email">bsmith@acme.com</Field>

    <Field name="picture">http://directory.corp.acme.com/cqi-bin/lookup? 

      photo=22638</Field>

  </MODULE_RESULT>

</OneBoxResults>

Transforming XML to HTML

You can transform the XML results into HTML by means of an XSLT stylesheet template.

The <Field> elements (see the element MODULE_RESULT) are available for both external and internal OneBox provider.

The <Field> elements provide data about the results from a provider, and you can specify parameters to improve the display of the results data. In the directory example, the provider sends the search appliance two results and title display information:

The <Field> element’s name attribute provides the information for the OneBox.

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 <resultsTemplate> element. For example, you can specify the directory example as follows:

 

13 results in the ACME directory
	William Smith - wsmith@acmecorp.com - (617) 555-1234 Bill R. Smith - bsmith@acmecorp.com - (617) 555-9345

The XSLT template transforms the associated results into HTML suitable for display. The following XSLT example creates an HTML table and transforms the <Field> name attributes:

<xsl:template name="directory">

  <table border="0" cellpadding="1" cellspacing="0">

    <tbody>

      <tr>

        <td colspan="2">

          <nobr>

            <a>

              <xsl:attribute name="href">

                <xsl:value-of select="title/urlLink"/>

              </xsl:attribute>

              <b>

                <xsl:value-of select="title/urlText"/>

              </b>

            </a>

          </nobr>

        </td>

      </tr>

      <tr>

        <td valign="top" width="40">

          <img>

            <xsl:attribute name="src">

     <xsl:value-of select="IMAGE_SOURCE"/>

            </xsl:attribute>

          </img>

        </td>

        <td valign="top" width="99%">

          <xsl:for-each select="MODULE_RESULT">

            <font size="-1">

              <b>

                <a>

                  <xsl:attribute name="href">

     <xsl:value-of select="U"/>

                  </xsl:attribute>

                  <xsl:value-of select="Field[@name=’firstname’]"/> 

                  <xsl:value-of select="Field[@name=’lastname’]"/>

                </a>

              </b> - 

     <xsl:value-of select="Field[@name=’email’]"/> -

              <xsl:value-of select="Field[@name=’phone’]"/>

            </font>

            <br/>

          </xsl:for-each>

        </td>

      </tr>

    </tbody>

  </table>

</xsl:template>

The stylesheet template must begin with the <xsl:template> element, which is matched to generate the HTML results. The <xsl:template> element must include a name attribute, and must not include the match attribute, which interferes with other stylesheet operations in the search appliance’s front end. You can include other <xsl:template> elements within the stylesheet.

If you do not specify an XSLT template, the search appliance uses the default template. The default XSLT template only returns a maximum of three results.

Checking the Visual Layout

You can verify an XSLT template by:

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. The match statement in the wrapper is not permitted in a search appliance template.

Creating a Wrapper

To create a wrapper:

<xsl:output method="xml" />

  <xsl:template match="OneBoxResults">

  <html>

  <body>

    <xsl:call-template name="directory"/>

  </body>

  </html>

</xsl:template>

java -jar c:\saxon\saxon8.jar -t directory.xml dirtest.xsl > test.html

call start firefox test.html

Adding a Secure Connection to the Provider

After defining a OneBox module, you can add advanced features to ensure security of data and provide additional user functionality.

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. The certificate is validated using the Certificate Authority and Certificate Revocation List information that is configured on the search appliance. If the provider requests a mutually authenticated certificate, the search appliance transmits its certificate as configured in the Admin Console.

Another form of authentication between a search appliance and the provider is HTTP Basic authentication. With this method, the search appliance sends a username and password in the HTTP header to the provider. To enable HTTP Basic authentication, set the <GSA_username> and <GSA_password> elements with a username and password that represent a provider “account” that is associated with the search appliance. The search appliance makes HTTP Basic authentication requests with each request to the provider. When using HTTP Basic authentication in production, always use SSL to avoid passing credentials over the network in clear text.

It’s a good idea to disable security before testing a provider so that debugging is easier. After the provider is functioning properly, enable the secure connection.

Defining User-Specific Results and Access Control

The search appliance provides document-level security, so that users can view search results only for content to which they have access. Google Search Appliance supports HTTP Basic authentication, NTLM HTTP authentication, and LDAP authentication plus forms-based single sign-on (SSO) systems. OneBox also supports user-based information retrieval, and can interoperate with these access control schemes.

If you use user level access control, you must specify the userAuth attribute in the <security> element (see the element security) of the module definition. When a secure search is executed against a search appliance (access=a), OneBox modules with user access level control configured are called.

The userAuth attribute can have one of the following values:

You can use a mixture of these access control mechanisms on OneBox modules within the same user query, but the search appliance may need to prompt the user for credentials or forward their session to a single sign on login page. The Google Search Appliance supports prompting the user for only one set of credentials (username and password for HTTP Basic authentication, NTLM HTTP, and LDAP) and one forms-based login per query.

For information on each authentication method and how to configure authentication on the Admin Console, see Managing Search for Controlled-Access Content.

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:

You can use or suppress these options. You can use the options if the provider can use them to enhance search results. You might prefer to suppress these options to make the call to the provider smaller and decrease network overhead.

To suppress the optional data, you specify attributes on the top level <onebox> element. The following example suppresses the optional data in our directory example:

<?xml version="1.0" encoding="UTF-8"?>

  <GoogleEnterpriseSources xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <onebox type="external" suppressDateTime="true" suppressIPAddr="true">

  ...

Handling Errors and Lookup Failures

Sometimes a provider cannot return a result set. For example, a provider could fail to return results because the provider’s request to its data source times out, because authentication fails, or because the provider’s data lookup completes, but returns zero results. In such a case, a provider should send a results message with the following characteristics:

Optionally, a provider can use the <Diagnostics> element to return more detailed information.

When a search appliance receives a response whose <resultCode> element is set to an explicit value other than success, the search appliance logs the response. The user’s search results do not include OneBox results from a provider or any explicit indication of a failure.

An error condition appears as XML code in the <resultCode> element. In the following example, the ACME employee directory requires a username and password, and in this example, the password passed is incorrect:

<?xml version="1.0" encoding="UTF-8"?>

<OneBoxResults xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <resultCode>"securityFailure"</resultCode>

  <Diagnostics>invalid password</Diagnostics>

  <provider>ACME Employee Directory</provider>

</OneBoxResults>

If a OneBox provider becomes unreachable and a search appliance receives an HTTP error code, the search appliance logs the error. No error is shown to the user.

Tips

This section provides information about how to use OneBox more effectively.

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:

http://gsa42/search?q=query&site=default_collection&btnG=Google+Search

&access=p&entqr=0&sort=date%3AD%3AL%3Ad1&output=xml_no_dtd

&client=default_frontend&ud=1&oe=UTF-8&ie=UTF-8

&proxystylesheet=default_frontend

http://gsa42/search?q=query&site=default_collection&btnG=Google+Search

&access=p&entqr=0&sort=date%3AD%3AL%3Ad1&output=xml_no_dtd

&client=default_frontend&ud=1&oe=UTF-8&ie=UTF-8

The browser now displays the results XML used to display the results. You can use this technique to compare XML results with the results page formatted by your XSLT template.

Back to top

Testing with the OneBox Simulator

Google provides an open source simulator that you can use to test a OneBox module and XSLT stylesheet.

Downloading the OneBox Simulator

You can download the OneBox simulator from http://google-developers.appspot.com/search-appliance/download/downloadsdk.

Creating an XSLT File

Create an XSLT style sheet and rename the file as projects.xsl for use with the simulator:

<xsl:template name="projects">

  (your XSL code)

</xsl:template>

Your XSLT code can contain other xsl:template elements. Ensure that you do not include the match attribute in the XSLT code for a OneBox module.

Editing customer-onebox.xsl to Call Your XSL File

Edit the customer-onebox.xsl file to point to the projects.xsl file as follows:

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet xmlns:xsl=" http://www.w3.org/1999/XSL/Transform" version="1.0">

  <!-- edit the xsl:include to point to your stylesheet file -->

  <xsl:include href="projects.xsl"/>

  <!-- change the xsl:call-template to call your template’s name -->

  <xsl:template name="holder" match="OBRES">

    <div class="oneboxResults">

      <table>

        <xsl:call-template name="projects"/>

      </table>

    </div>

  </xsl:template>

</xsl:stylesheet>

This file calls your stylesheet for all OneBox results, whether or not the results come from the projects OneBox. In a search appliance, the customer-onebox.xsl file only passes results to your style sheet. The customer-onebox.xsl cannot be used as a OneBox module because it contains a match statement.

Merging a OneBox Module Output with the Search Results

To merge a OneBox module output with the search results:

<OneBoxResults>

  <provider>Corporate Project Database</provider>

  <title>

    <urlText>Lookup results for project 1</urlText>

    <urlLink>http://www.mycompany.com/cgi-bin/projects?projectId=1</urlLink>

  </title>

  <IMAGE_SOURCE>http://www.mycompany.com/icons/favicon.ico</IMAGE_SOURCE>

  <MODULE_RESULT>

    <U>http://www.mycompany.com/cgi-bin/projects?projectId=1</U>

<Field name="ProjectName">NextGen</Field>

    <Field name="ProjectStatus">Green</Field>

  </MODULE_RESULT>

</OneBoxResults>

<ENTOBRESULTS>

  <OBRES module_name="projects">

    <provider>Corporate Project Database</provider>

    <title>

      <urlText>Lookup results for project 1</urlText>

      <urlLink>

        http://www.mycompany.com/cgi-bin/projects?projectId=1

      </urlLink>

    </title>

    <IMAGE_SOURCE>http://www.mycompany.com/icons/favicon.ico</IMAGE_SOURCE>

    <MODULE_RESULT>

      <u> http://www.mycompany.com/cgi-bin/projects?projectId=1</u>

      <Field name="ProjectName">NextGen</Field>

      <Field name="ProjectStatus">Green</Field>

    </MODULE_RESULT>

  </OBRES>

</ENTOBRESULTS>

Applying the Overall Stylesheet to the Merged XML Output

The gsa_default_stylesheet.en.xsl, the overall stylesheet, includes customer- onebox.xsl that includes projects.xsl. After you apply gsa_default_stylesheet.en.xsl, the simulator transforms the merged results page into HTML for you to view. You can use any available XSLT tool such as XML Spy, OxygenXML, tools from the major software vendors, or open source tools.

The simulator requires that you use the projects.xsl name. The stylesheet name that you specify in the Admin Console must appear in the following places:

Notes:

Back to top

OneBox Module Definition XML Reference

You can define a OneBox module by editing an XML file and importing the file into the Admin Console from Content Sources > OneBox Modules. Alternatively, you can enter these settings from the same Admin Console page by editing an existing OneBox module or by defining a new OneBox module.

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.

The GoogleEnterpriseSources element contains the following elements:

Note: The globals element provides the Admin Console with the maximum number of OneBox results per search and the OneBox response timeout in milliseconds. Do not put the globals element in your XML file. Similarly, the Admin Console uses the ModulesPerFrontend element internally. Do not put the ModulesPerFrontend element in your XML file.

onebox Element

The onebox element provides the root element of a onebox module definition. This element contains all of the settings for a module.

Note: Do not set the id= attributes that appear in the onebox.xsd file. The search appliance does not use any of the id attributes.

Syntax

<onebox type="type" suppressDateTime="true-false" suppressIPAddr="true-false">

  <name>string</name>

  <security userAuth="authType" id="security">

    <GSA_username>username</GSA_username>

    <GSA_password>password</GSA_password>

  </security>

  <description>string</description>

  <trigger triggerType="null_keyword_regex">keyword1|keyword2|keywordn</trigger>

  <providerURL>url</providerURL>

  <collection>name</collection>

  <resultsTemplate>

    ...

  </resultsTemplate>

</onebox>

The onebox.xsd elements are as follows:

<onebox> attributes_and_child_elements </onebox>

Required. Indicates OneBox configuration parameters.

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.

Child Elements

 

Element	Description
name	<name>string</name> Required. The name of the OneBox module. The name can be up to 32 characters in length and must contain at least one character. The name can consist only of the characters A–Z, a–z, 0–9, dot, and dash.
security	<security>child-elements</security> Optional. Defines user-level access control and security between the search appliance and the provider. User-level access is defined by the userAuth attribute and security between the search appliance and a provider is defined by means of the GSA_username and GSA_password attributes. The <security> element has the following attribute: • userAuth="none"|"basic"|"LDAP"|"SSO" Required if the <security> element is present. The type of user-level access control to apply. If you specify a value other than none, you must configure the search appliance with the appropriate settings. The <security> element contains the following child elements: • <GSA_username>username</GSA_username> Optional. The user name for the search appliance, in an HTTP Basic authentication request to the provider. The maximum user name length is 32 characters. If you define this element, the appliance makes an HTTP Basic authentication request to the provider passing the credentials defined in the HTTP header. If authentication is not required, specify without a value as <GSA_username></GSA_username>. • <GSA_password>password</GSA_password> Optional. The password for the search appliance, in an HTTP Basic authentication request to the provider. The maximum password length is 32 characters. If you define this element, the appliance makes an HTTP Basic authentication request to the provider passing the credentials defined in the HTTP header. If authentication is not required, specify without a value as <GSA_password></GSA_password>.
description	<description>text</description> 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	<trigger>keyword_or_regex</trigger> Optional. The trigger expression determines when the search appliance invokes the module. For information on regular expression syntax, see Triggering When the Query Matches a Regular Expression. You can specify multiple trigger values by separating each value with an OR symbol or a pipe (|). For example, you can specify <trigger> bug|CR </trigger>. The trigger element has the following required attribute: • triggerType="null"|"keyword"|"regex" Required if the <trigger> element is present. The triggerType can have one of the following values: • null—Trigger the keyword on every search. The OneBox module then appears in all search results. • keyword—Trigger only when a search string starts with the indicated keyword or keywords. • regex—Trigger when a search string matches the regular expression statement. For information on the regular expression syntax, see Triggering When the Query Matches a Regular Expression.
collection	<collection>collection_name</collection> Optional. Specifies the collection that is the provider for an internal OneBox module. If the type attribute of the onebox element is set to internal, this element must contain a collection name. The collection name can be up to 32 characters in length.
providerURL	<providerURL>url</providerURL> Optional. A fully qualified URL to which the GET request is passed for an external OneBox module. If the type attribute of the onebox element is set to external, this element must contain a URL. If the URL uses the HTTPS protocol, the search appliance creates a secure (SSL) session with the provider.
resultsTemplate	<resultsTemplate>child_elements</resultsTemplate> Optional. The search appliance uses the XSLT template to convert the XML response from the provider into HTML for the end user. The top level element must be the <xsl:template> element which will be matched to generate the HTML results. The <xsl:template> element must include a name attribute, and must not include have the match attribute, which interferes with other stylesheet operations in the search appliance front end. You can include other <xsl:template> elements within the stylesheet.

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...)
authType	required	The authentication mechanism used to provide user-specific information.	One of the following values: none, basic, ldap, or sso
dateTime	optional	Date and time of the query on the calling search appliance.	Text, UTC format
ipAddr	optional	The IP address of the originating user.	IP address
lang	required	The language of the user’s browser where the query originated.	Text, two-character language code, such as EN, JP, or DE
oneboxName	required	Name of the OneBox module. Must match the OneBox Module definition specified in the Admin Console.	Text, no spaces
password	optional	The password for the user if HTTP Basic authentication is being used.	Text
P0, P1, P2, ..., Pn	required	Match groups from the regular expression evaluation (if applicable)	Text
query	required	The query string from the user’s query to a search appliance. The query string does not include the trigger term.	UTF-8 encoded and URL-escaped text
userName	optional	The user identity for secure or personalized results from a provider: • If authType=basic, userName is the username of the search user. • If authType=ldap, userName is the distinguished name (DN) from the LDAP server. • If authType=sso, userName is the user of the cookie used by a provider.	Text

Certain parameters can be suppressed if the appropriate attributes are set on the <onebox> element. Access control settings are only passed if the OneBox module is configured to include user-level access control. If the provider is configured to use basic authentication between the search appliance and the provider (<GSA_username> and <GSA_password> elements are defined, see the element security) then the GET request will include these parameters in the HTTP header.

Back to top

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.

Your OneBox module definition XML file must conform to this schema.

Syntax

<OneBoxResults>

  <resultCode>result_code</resultCode>

  <Diagnostics>failure_reason</Diagnostics>

  <provider>provider_name</provider>

  <searchTerm>query_escape</searchTerm>

  <totalResults>total_results_escape</totalResults>

  <title>

    <urlText>results_title</urlText>

    <urlLink>results_url</urlLink>

  </title>

  <IMAGE_SOURCE>image_url</IMAGE_SOURCE>

  <MODULE_RESULT>

    <U>url</U>

    <Title>title</Title>

    <Field name="name1">value1</Field>

    <Field name="name2">value2</Field>

    <Field name="nameN">valueN</Field>

  </MODULE_RESULT>

</OneBoxResults>

OneBoxResults Elements

The OneBoxResults element supports the following child elements:

 

Element	Description
resultCode	<resultCode>result_code</resultCode> 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. The value can be one of the following: • success • lookupFailure • securityFailure • timeout
Diagnostics	<Diagnostics>failure_reason</Diagnostics> Optional, a single use of this tag is permitted. If a lookup fails, the provider uses this element to send diagnostic information and sets the resultCode attribute to a value other than success. It is not illegal to send a diagnostic alone, or with a resultCode of success, but the diagnostic message may be logged differently depending on the implementation. The failure reason string can be up to 256 characters in length.
provider	<provider>provider_name</provider> Optional, a single use of this tag is permitted. The name of the provider. If this is an internal provider, specify the collection name. The name need not match the name provided in the OneBox module definition, and can be more descriptive than that name. This string can be a brand, URL, or other identifying information. The provider name can be up to 128 characters in length.
title	<title>child-elements</title> Optional, a single use of this tag is permitted. The title of the result, consisting of a line of text and a link to the full result set from the provider. If one of the child elements is present, both must be present. The title element contains the following child elements: • <urlText>results_title</urlText> Required if you specify the <title> element. The title text for the results, for example, Search Results. The title can be up to 40 characters in length. • <urlLink>results_url</urlLink> Required if you specify the <title> element. The URL to the results.
IMAGE_SOURCE	<IMAGE_SOURCE>image_url</IMAGE_SOURCE> Optional. A link to the image that displays in the OneBox results.
MODULE_RESULT	<MODULE_RESULT>child_elements</MODULE_RESULT> 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. The MODULE_RESULT element has the following child elements: • <U>url</U> Optional. The URL for the results. • <Title>module_title</Title> Optional, only one title is permitted in a MODULE_RESULT block. The title of the results. • <Field name="field_name" [any] >field_value</Field> Name-value pairs for each returned item. For internal OneBox providers, you can have any number of Field elements. For an external Onebox provider only, you can add up to 8 <Field> elements. This element has the following attributes: • name="text"—The name attribute allows you to give the field a name for results formatting and processing. The default XSLT template uses this attribute to format results. • [any]—You can add additional to the Field element for formatting results.