Use extension points to customize your deployment

This is for:

Developer System Administrator

Coveo for ServiceNow comes with an extension point allowing you to extend some aspects of the Coveo functionality. This feature contains methods that make it possible to:

  • Add custom JavaScript Search Framework options to your widgets.

  • Add custom mapping between a ServiceNow language ID and a Coveo JavaScript Search Framework language culture file key for localization of Coveo for ServiceNow search interfaces.

  • Provide custom translations to display in your Coveo for ServiceNow search interfaces.

  • Add custom, additional data to the context sent to Coveo along with queries.

  • Customize the fields that trigger or don’t trigger a query when using the Insight Panel.

  • Modify the payload when generating an authentication search token from the Insight Panel search interface.

Create an implementation

  1. Navigate to System Extension Points > Scripted Extension Points.

  2. On the Extension Points page, click the extension whose name ends with coveo_1_0.CoveoExtensions. This is a built-in example of the available methods. For details on these methods, see the Reference section.

  3. On the CoveoExtensions extension point page, under Related Links, click Create implementation.

    Note

    Although you can create several implementations for the Coveo extension point, you can’t create two implementations that contain the same method. You must instead add condition to your method to ensure it applies as desired.

  4. On the page that opens, you can edit the implementation script or replace it with your own custom script.

Should you encounter errors or unexpected behaviors with your implementation, reach out to Coveo Support for help.

Reference

The Coveo for ServiceNow extension point contains several functions that you can use to customize your end users' search experience.

  • getJsUiOptions allows you to add custom JavaScript Search Framework options to your widgets.

  • getJsUiTranslations allows you to provide custom translations to display in your Coveo for ServiceNow search interfaces.

  • getJsUiCultureMap allows you to create a custom mapping between a ServiceNow language ID and a Coveo JavaScript Search Framework language culture file key for localization of Coveo for ServiceNow search interfaces.

  • getCustomContext allows you to add custom, additional data to the context sent to Coveo along with queries.

  • getFieldsToIgnore allows you to specify record form fields whose content won’t be sent to Coveo.

  • getFieldsToInclude allows you to specify record form fields whose content will be sent to Coveo.

  • getRecordCreator allows you to modify the record creator value that’s used to fetch the user on which to base Insight Panel User Actions.

  • xref:getsearchtokenrequestbody-function,getSearchTokenRequestBody] allows you to modify the body of the request that’s sent to generate a search token for authentication.

getJsUiOptions (function)

You can use the getJsUiOptions function to set custom properties for the search interface widgets. The function returns a JavaScript object that Coveo for ServiceNow uses to set the properties of a Coveo for ServiceNow search interface while initializing it. See Passing Component Options in the init Call for details on this process.

Note

The getJsUiOptions function applies your customization to all widgets in your Coveo for ServiceNow deployment. If you want to add an option to a certain widget only, use the widgetOptions attributes to specify a function condition.
Example
getJsUiOptions: function getJsUiOptions(widgetOptions) {
    if (widgetOptions.scope == 'CustomerServicePortal' && widgetOptions.component == 'FullSearchPage') {
    return {
        Pager: {
        numberOfPages: 9
        }
    };
    }

    return {};
}

getJsUiTranslations (function)

The getJsUiTranslations function allows you to customize the localization of the search interface widget. This function returns a dictionary of key/value pairs for each language.

You might encounter some particular situations while applying your customizations. See Special Cases for details.

Example
getJsUiTranslations: function getJsUiTranslations(widgetOptions) {
    return {
    en: {
        AreYouSureDeleteFilter: "Are you sure you want to delete the filter {0} with the expression {1}",
        Results: "Result<pl>s</pl>"
    }
    };
}

getJsUiCultureMap (function)

The getJsUiCultureMap function allows you to add custom mapping between a ServiceNow language ID and a Coveo JavaScript Search Framework language culture file key.

Coveo for ServiceNow search interfaces leverage the default localized strings in the Coveo JavaScript Search Framework. By default, a Coveo-powered search interface displays the localized strings that correspond to the current user’s language in ServiceNow based on a preconfigured mapping between ServiceNow language IDs and Coveo JavaScript Search Framework language culture file keys.

If you need to add a custom mapping that is not supported by default, such as to support a new language ID in ServiceNow or a new language culture file in Coveo JavaScript Search Framework, you can do so using the getJsUiCultureMap function.

Example

You created a new en-us language record in ServiceNow. Since en-us is not supported in the default mapping for Coveo for ServiceNow, you map it to the corresponding culture file key (en) in the Coveo JavaScript Search Framework as follows:

getJsUiCultureMap(defaultMap) {
        defaultMap['en-us'] = 'en';
        return defaultMap;
}

Default localization mapping

The following table shows the default mapping between the ServiceNow language IDs and the Coveo JavaScript Search Framework language culture file keys.

Language ServiceNow language ID Coveo culture file key

English

en

en

French

fr

fr

French (Quebec)

fq

fr

Chinese (Simplified)

zh

zh-cn

Czech

cs

cs

Dutch

nl

nl

Finnish

fi

fi

German

de

de

Hungarian

hu

hu

Italian

it

it

Japanese

ja

ja

Korean

ko

ko

Norwegian

nb

no

Polish

pl

pl

Portuguese (Brazil)

pt

pt-br

Russian

ru

ru

getCustomContext (function)

The getCustomContext function allows you to inject additional user context in a query. This information can then be leveraged in Usage analytics reports or by Coveo Machine Learning. By default, the query already contains some information about the user, but it can be enriched thanks to this function.

Example
getCustomContext: function getCustomContext(widgetOptions, userContext) {
    userContext["company_name"] = "Coveo";
    return userContext;
}

widgetOptions

Option Description

scope (string, optional)

The scope of the Coveo search interface widget.

component (string, optional)

The component of the Coveo search interface widget.

searchPageId (string, optional)

The ID of the ServiceNow page template in which you embedded the Main Search widget. Users will be redirected to this page to view their search results.

getFieldsToIgnore (function)

You can use the getFieldsToIgnore function when implementing the Insight Panel.

By default, editing the content of any record form field triggers a query to Coveo, which in turn updates the Insight Panel. Moreover, the content of all form fields is sent as context information for Coveo Machine Learning (Coveo ML) purposes.

If you want to avoid triggering a query when some fields are edited frequently or contain irrelevant data, or if some fields contain sensitive data that you don’t want to send to Coveo, the getFieldsToIgnore function allows you to filter the fields to send. In other words, you can create a list of the field you don’t want to send to Coveo.

In the returned array, list the fields that shouldn’t trigger a query and be sent as context information.

Note

Instead of listing the fields to ignore, you can list the fields that will trigger a query and be sent as context information by using the getFieldsToInclude function.
Example
getFieldsToIgnore: function(widgetOptions) {
        return ['priority', 'cmdb_id'];
    },

widgetOptions

Option Description

scope (string, optional)

The scope of the Insight Panel.

component (string, optional)

The component of the Insight Panel.

searchPageId (string, optional)

The ID of the ServiceNow page template in which you embedded the Main Search widget. Users will be redirected to this page to view their search results.

getFieldsToInclude (function)

You can use the getFieldsToInclude function when implementing the Insight Panel.

By default, editing the content of any record form field triggers a query to Coveo, which in turn updates the Insight Panel. Moreover, the content of all form fields is sent as context information for Coveo Machine Learning (Coveo ML) purposes.

Use the getFieldsToInclude function if you want to trigger a query only when certain fields are edited.

In the returned array, list the fields that will trigger a query and be sent as context information.

Note

Instead of listing the fields to include, you can list the fields to ignore that won’t trigger a query and be sent as context information by using the getFieldsToIgnore function.
Example
getFieldsToInclude: function(widgetOptions) {
        return ['short_description', 'category'];
    },

widgetOptions

Option Description

scope (string, optional)

The scope of the Insight Panel.

component (string, optional)

The component of the Insight Panel.

searchPageId (string, optional)

The ID of the ServiceNow page template in which you embedded the Main Search widget. Users will be redirected to this page to view their search results.

getRecordCreator (function)

You can use the getRecordCreator function when implementing the Insight Panel.

The getRecordCreator function lets you modify the record creator value that’s used to fetch the user on which to base the Insight Panel User Actions.

Typically, the actions that appear in User Actions are associated with the customer who opened the incident or case. By default, the Insight Panel fetches the email address of the user that’s specified in the opened by record form field, as set in the Insight Panel’s Table Creator Field (Configurable Workspace) or tableCreatorField (Agent Workspace) configuration.

Use the getRecordCreator function to overwrite the table creator value that’s configured for the Insight Panel so that it fetches the user based on custom criteria, such as a user name instead of an email address.

Note

Dot-walking syntax is supported.
Example
getRecordCreator: function getRecordCreator(widgetOptions) {
    if (!widgetOptions.tableName || !widgetOptions.recordSysId) {
        return;
    }
    var record = new GlideRecord(widgetOptions.tableName);
    record.get(widgetOptions.recordSysId);
	var hashedUserName = btoa(record.getElement('opened_by.user_name').toString());
	return hashedUserName;
  }

widgetOptions

Option Description

scope (string, optional)

The scope of the Insight Panel.

component (string, optional)

The component of the Insight Panel.

searchPageId (string, optional)

The ID of the ServiceNow page template in which you embedded the Main Search widget. Users will be redirected to this page to view their search results.

tableName (string, optional)

The table name of the current record.

recordSysId (string, optional)

The system ID of the current record.

tableCreatorField (string, optional)

The value of the table creator field parameter.

getSearchTokenRequestBody (function)

You can use the getSearchTokenRequestBody function when implementing the Insight Panel.

The getSearchTokenRequestBody function allows you to modify the body of the request when generating an authentication search token from a Coveo Insight Panel search interface in ServiceNow. This is useful, for instance, if you want to anonymize or edit the identity of users.

By default, the payload is the email address of the logged-in user in the ServiceNow instance.

Example
getSearchTokenRequestBody: function getSearchTokenRequestBody(tokenBody, scope, component, seeProfileOf) {
    tokenbody.userIds = [
        {
           name: `asmith@example.com`,
           provider: `Email Security Provider`,
           type: `User`
        }
    ];
    return tokenBody;
    };

Options

Option Description

tokenBody (object, optional)

The body of the request. See Request body properties for options.

scope (string, optional)

The scope of the Insight Panel.

component (string, optional)

The component of the Insight Panel.

seeProfileOf (object, optional)

The user identifier in ServiceNow that’s used to retrieve User Actions.