Use custom table fields in user criteria records

This is for:

Developer System Administrator

This article describes how to use custom table fields in a ServiceNow user criteria record with advanced (scripted) permissions to replicate the ServiceNow user permissions and index who can access source items through a Coveo-powered search interface in ServiceNow.

Though Coveo for ServiceNow supports base user criteria permissions in ServiceNow, user criteria records with advanced permissions are not supported by default. If you chose to replicate the ServiceNow item permission system in your Coveo-powered search interface by selecting the Same users and groups as in your content system content security option, you can use custom table fields to retrieve user email information from a ServiceNow user criteria record.

The custom table fields allow the security identity provider associated to your ServiceNow source to query a system table that’s referenced in a user criteria scripted permission and index the security permissons.

By default, the ServiceNow security provider in your Coveo organization checks for the presence of three Coveo-specific table fields in user criteria records based on the following preset column (field) names.

  • u_coveo_table: Specifies the system table to query.

  • u_coveo_query: Specifies the filter or condition to apply to the query in the system table.

  • u_coveo_output: Specifies the field(s) from which to retrieve user emails in the system table.

To use custom table fields to index security permissions from a user criteria record with advanced permissions:

  1. Add Coveo-specific table fields to user criteria records.

  2. Populate the custom table fields in a user criteria record.

Note

Instead of creating Coveo-specific table fields, you can use your existing custom table fields. Since the ServiceNow security provider can only check for one set of three custom fields, you must either use Coveo-specific table fields or your existing table fields.

Add Coveo-specific table fields to user criteria records

  1. Access the Now Platform UI of your ServiceNow instance.

  2. Navigate to System Definition > Tables.

  3. Find and open the User Criteria system table.

  4. Create the u_coveo_table field:

    1. In the Columns tab, click New.

    2. In the Type field, enter String.

    3. In the Column label field, enter Table.

    4. In the Column name field, enter u_coveo_table.

    5. In the Max length field, enter the maximum number of characters (that is, 255).

    6. Click Submit.

  5. Create the u_coveo_query field:

    1. In the Columns tab, click New.

    2. In the Type field, enter String.

    3. In the Column label field, enter Query.

    4. In the Column name field, enter u_coveo_query.

    5. In the Max length field, enter the maximum number of characters (that is, 255).

    6. Click Submit.

  6. Create the u_coveo_output field:

    1. In the Columns tab, click New.

    2. In the Type field, enter String.

    3. In the Column label field, enter Fields.

    4. In the Column name field, enter u_coveo_output.

    5. In the Max length field, enter the maximum number of characters (that is, 255).

    6. Click Submit.

Note

To mark the custom fields as Coveo-specific fields, you can add Coveo to the Column label entry (that is, Query - Coveo), or you can modify the form design for the User Criteria system table so that the custom table fields appear in a separate “Coveo” section.

custom table fields form

Populate table field data in a user criteria record

Once you’ve added custom table fields, populate the field data for the user criteria records for which you want the ServiceNow security provider to index user permissions.

  1. Access the Now Platform UI of your ServiceNow instance.

  2. Navigate to Service Catalog > User Criteria.

  3. Find and open the user criteria record with scripted permissions for which you want the ServiceNow security provider to retrieve user permissions.

  4. In the Table field, enter the system table that’s referenced in the advanced permission script.

  5. (optional) In the Query field, enter the condition or filter to apply when querying the table.

  6. In the Fields field, enter the field(s) from which to retrieve user emails in the system table. If the system table contains a reference to another table, you can also retrieve user email data from the referenced table by using dot-walking syntax. Dot-walking references a field by building a chain of field names separated by dots (that is, manager.email). Separate multiple entries in this field with a comma (,).

Examples

For the scripted permission in the image below, the system table is customer_contact, and the field in the table that contains the user emails is email. Since a filter or condition for the query is not required, you leave the Query field blank.

custom table field example simple

For the scripted permission in the image below, the system table is sys_user, the condition to apply when querying the table is location=e458f8a56f9a1100f5db57ee2c3ee406^u_personstatus=A, and the field in the system table that contains the user emails is email. Since the system table contains a reference to another table from which you want to also retrieve the manager’s email, you enter manager.email using dot-walking syntax.

custom table field example complex

Use existing table fields

If you choose to use existing fields in user criteria records instead of Coveo-specific fields, you can use at most three separate fields and the field data for each must be consistent with the data that’s expected when using the Coveo-specific table fields. Since the ServiceNow security provider can only check for one set of three custom fields, you must either use Coveo-specific table fields or your existing table fields.

To use your existing table fields, you must modify the ServiceNow security provider JSON configuration to check for the presence of the existing table fields instead of the Coveo-specific table fields.

  1. On the Security Identities (platform-ca | platform-eu | platform-au) page, click the ServiceNow security provider that’s associated to your ServiceNow source, and then click More > Edit JSON in the Action bar.

  2. In the JSON configuration text field, add the following JSON in the parameters section, where:

    • CustomCriteriaTableField is the parameter for the table field that specifies the system table to query.

    • CustomCriteriaQueryField is the parameter for the table field that specifies the filter or condition to apply to the query in the system table.

    • CustomCriteriaOutputField is the parameter for the table field that specifies the field(s) from which to retrieve user emails in the system table.

    • column_name is the name of the corresponding table field.

     "CustomCriteriaTableField": {
 "value": "column_name"
 },
 "CustomCriteriaQueryField": {
   "value": "column_name"
 },
 "CustomCriteriaOutputField": {
   "value": "column_name"
 },

  3. Click Save.

Example

If the column names for your table fields are u_table, u_condition, and u_retrieve, the JSON should be as follows:

custom table fields json example