Google Search Appliance OneBox for Enterprise Developers Guide - Manual (Page 18)

Google Search Appliance: Google OneBox for Enterprise Developer’s Guide 18
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. 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 element. The following
example suppresses the optional data in our directory example:
...
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:
• The value of the element is lookupFailure, securityFailure, or timeout.
• There are no instances of the element.
Optionally, a provider can use the element to return more detailed information.
When a search appliance receives a response whose 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 element. In the following example, the
ACME employee directory requires a username and password, and in this example, the password
passed is incorrect:
"securityFailure"
invalid password
ACME Employee Directory
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.