Home

Crawl and Index

Serving
  Front Ends
    Output Format
    KeyMatch
    Related Queries
    Filters
    Remove URLs
    OneBox Modules
  Query Settings
  OneBox Modules
  Document Preview Module
  Result Biasing
  Dynamic Navigation
  Suggestions
  Access Control
  Head Requestor Deny Rules
  Policy ACLs
  Universal Login
  Universal Login Auth Mechanisms
    Cookie
    HTTP
    Client Certificate
    Kerberos
    SAML
    Connectors
    LDAP
  Universal Login Form Customization
  Flexible Authorization
  Alerts
  Language Bundles

Status and Reports

Connector Administration

Social Connect

Cloud Connect

GSA Unification

GSAⁿ

Administration

More Information

Serving > OneBox > OneBox Modules

Use the Serving > OneBox > OneBox Modules page to define a new OneBox module or edit the definition of an existing OneBox module. You can use OneBox modules to display specially formatted information from a collection or from an external provider. A OneBox can appear when a keyword is entered or on every search request.

This help topic covers the following OneBox pages:

• OneBox Module definition. (Name, Description, Trigger, Provider, and Security sections).
  If so, view the following sections:
  • Before Starting these Tasks
  • OneBox Module Definition Options
  • Completing the OneBox Module Definition Options
  • Subsequent Task
  • For More Information


• OneBox Stylesheet Template. Edit XSL (Import Stylesheet, Browse, Save XSLT Spreadsheet)
  If so, view the following sections:
  • Before Starting these Tasks
  • OneBox Stylesheet Template
  • OneBox Stylesheet Options
  • Completing the OneBox Stylesheet Options
  • Subsequent Task
  • For More Information

Before Starting these Tasks

Before completing the information for a OneBox, complete the tasks shown in the following table.

OneBox Module Definition Options

You can start editing a OneBox module by specifying a Description. Then fill in the remaining information and click Save the OneBox Definition.

The OneBox definition options are as follows.

Completing the OneBox Module Definition Options

The sections that follow provide additional information about each option on the OneBox Module definition page.

Name and Description

The Name field displays a name that you've already specified.

The Description identifies the OneBox module.

Both name and description are hidden from users and used only for administrative purposes.

Trigger

The trigger for a OneBox module defines the condition that invokes the OneBox module. A OneBox module can be triggered for every search query, or for queries that start with a keyword or match a regular expression.

Note: If a trigger invokes a OneBox module, but the OneBox module does not return results, neither the user's results page or the Test Center returns an explicit indicator. For an explicit record, you must look at the log for the OneBox module.

Always Trigger Option

If you select Always trigger, the search appliance invokes this OneBox module for all search queries. Use this trigger option only after careful consideration! In most cases, triggers that use keywords or regular expressions are better choices for returning relevant results and ensuring user satisfaction.

You can use this trigger in these cases:

• If the information provided by this OneBox module always applies to the queries for a particular front end.
• If the OneBox provider contains advanced logic to determine the relevance of results, and withholds results that are not highly relevant.

Examples that use this type of trigger:

• A front end serves only engineering employees and is used on a page that provides information about previous projects. The OneBox module searches a collection of project documentation.
• A project management system returns project status information only when the search query contains a project name or employee name that is present in the system. If there is no relevant data, the provider responds with an error.

Keywords Option

If you select Keywords, you must specify one or more keywords. If a user's search query starts with one of the keywords, the search appliance invokes this OneBox module.

To specify multiple keywords, use a vertical bar (|) as a separator.

Examples that use this type of trigger:

The search appliance passes the query to an internal OneBox provider differently from the way it passes the query to an external OneBox provider, as follows:

• If the provider is internal (another collection on this search appliance), the search appliance removes the keyword and passes the rest of the query to the provider. For example, if the user enters phone angelo and the keyword trigger is phone, the search appliance passes angelo to the internal provider.
• If the provider is external, the search appliance passes the entire query to the provider.

If the specified keyword appears anywhere else in the search query, the trigger is not invoked. To allow use of a keyword anywhere in a search query, use a regular expression trigger.

Regular Expression Option

If you select Regular expression, you can create a pattern to which the search appliance compares a search query. If the query matches the pattern, the OneBox module is invoked.

OneBox triggers support regular expressions as defined by the Perl Compatible Regular Expressions library (PCRE).

Examples of this type of trigger:

• The regular expression status (.*) matches a query if the user types status and a project name.
• The regular expression distance from (.*) to (.*) matches a query such as distance from Paris to Rome.
• The regular expression \d+ matches a query such as 123.
• The regular expression (?i)([a-z']+[a-z ][a-z']*[a-z]) airport(?: (?:status|delays?|conditions))? matches a query such as LAX airport conditions or EWK airport delays.

A regular expression provides great flexibility, but you must ensure that the expression can be evaluated rapidly. A regular expression that requires too much processing time could cause a noticeable performance degradation.

Note: The regular expression language used by OneBox triggers differs slightly from the GNU-based URL patterns described in the section "Rules for Valid URL Patterns" in "Administering Crawl: Constructing URL Patterns," which is linked to the Google Search Appliance help center.

Provider

A OneBox provider can be another collection on this search appliance or an external program that receives requests, obtains data from a data source, and returns results.

• Collection: If this search appliance supports multiple collections, and this OneBox module queries another collection, select the collection name from the drop-down menu. An internal OneBox module does a full-text search and return results that are formatted according to the stylesheet template.
• External provider: If this OneBox module queries an external provider, specify the URL of the provider. You can use HTTP while you are developing and testing OneBox modules. For production, use HTTPS for a secure connection.

Search User Access Control

The data source associated with an external provider that may require authentication of the user requesting the data. Certain data may be restricted to members, managers, people in a particular department, or people with a particular security clearance. Specify the access control used for this OneBox module:

• None: No authentication is needed.
• Basic: The search appliance prompts the user for a name and password and forwards those credentials to the provider.
• LDAP: The LDAP directory server authenticates the user. The search appliance passes the user's distinguished name (DN) to the provider.
• SSO: The search appliance passes the user's single sign on (SSO) cookie to the provider. To use this option, you must configure forms authentication.

External Provider Security

The search appliance can connect securely to the external OneBox provider. If you specify a provider URL that uses the HTTPS protocol, an SSL connection is established, and the search appliance requires a certificate from the provider.

If a provider requires a certificate from the search appliance, the search appliance provides the certificate. For more information SSL configuration, refer to SSL Settings and Certificate Authorities.

Note: The search appliance does not allow a self-signed certificate from an external provider.

External providers may require the use of authentication and that the search appliance supply user name and password credentials.

To specify authentication for access to an external provider:

1. Check the option Authenticate Google Search Appliance to the provider by sending a username and password.
2. Specify the username and password used by the search appliance. If the external provider uses LDAP, the user name is the distinguished name. If the authentication is SSO, the user field is the SSO cookie.

If you need to view the password for the external provider, click Export from Serving > OneBox Modules for the OneBox. This option creates an XML file that you can store on a computer and then view with a browser. The password is listed in the <GSA_password> tag.

Save the OneBox Definition

When you are done configuring the OneBox module, click Save OneBox Definition. The Serving > OneBox Modules page reappears, displaying a table that contains your new OneBox module.

If you click Edit for a specific OneBox module, this configuration page reappears, with a new section at the bottom, to allow you to edit the OneBox Stylesheet Template.

OneBox Stylesheet Template

An XSLT stylesheet template specifies the display of OneBox results. Detailed information about the stylesheet template and its contents is available in the OneBox Developer's Guide.

Click Edit XSL to make in-line changes to the default template. You can select and copy the stylesheet, edit in another editor, and then paste the edited stylesheet back inline. When you are done, click Save XSLT Stylesheet.

OneBox Stylesheet Options

The OneBox Stylesheet options are shown in the following table.

Completing the OneBox Stylesheet Options

To specify an XSLT stylesheet for the OneBox module:

1. If you have an XSLT stylesheet on your local computer, enter its file name in the Import Stylesheet edit box or click the Browse button to locate the file on your computer. Alternatively, you can copy the contents of a stylesheet to your computer's clipboard and paste its contents into the edit window on this page.
2. If needed, you can change the stylesheet in the edit box by selecting text, deleting, and adding new content.
3. When done, click Save XSLT Stylesheet. If you wish to abandon changes you made to the stylesheet, click Restore Default. Because there is no prompt to be sure that you want to erase the stylesheet, before clicking this button, select the edit box contents, and copy them to your computer's clipboard. If needed, you can then paste the content back into the edit box or save the clipboard contents in a file for later use.
4. Click Back to list of OneBox Modules to return to Serving > OneBox Modules.

Subsequent Task

After creating a OneBox module, you can enable it for a front end on the Serving > Front Ends > OneBox Modules page.

For More Information

For more information about OneBox modules, see the following topics:

• Serving > Front Ends > OneBox Modules
• Serving > OneBox
• "OneBox for Enterprise Developer's Guide," which is linked to the Google Search Appliance help center
• "OneBox for Enterprise Design Principles," which is linked to the Google Search Appliance help center
• Google OneBox for Enterprise Simulator