---
sourceDocument: Australia ServiceNow AI Platform Administration
sourceDocumentLink: https://www.servicenow.com/docs/r/platform-administration

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia ServiceNow AI Platform Administration

ft:clusterId :

    - platadm

bundleId :

    - platadm

workflow :

    - Platform


---

# Create custom data lookups

# Create custom data lookups {#ariaid-title1}

* Release version: Australia
* 
* Updated March 12, 2026
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 minutes to read

Creating custom data lookups involves adding a lookup value, creating the definition, and activating data lookup.

## Create a custom data lookup table {#ariaid-title2}

Create a custom table to store lookup data.
The custom table must extend the Data Lookup Matcher Rules `[dl_matcher]`
table. For example, this custom lookup table stores information about VIP callers and
incident assignments.  
{#create-custom-data-lookup__table_n5p_l2q_wq__entry__2}

| Field | Sample value |
|-|-|
| Label | VIP Caller Lookup |
| Table name | u_vip_caller_lookup |
| Extends base table | dl_matcher |
| Create new module | True |
| Add module to menu | System Policy |
[Table 1. Custom data lookup table]

{#create-custom-data-lookup__table_n5p_l2q_wq}

## Add a data lookup value to the data lookup table {#ariaid-title3}

The columns of a data lookup table contain both matcher and setter field
data.

### Before you begin

Role required: admin

### About this task

Each data lookup is a query that searches for a row containing values that match the
matcher fields. The data lookup then returns the value listed in the setter fields.
For example, this Priority Data Lookup \[dl_u_priority\] table lists the combinations
of impact and urgency (matcher fields) that produce a particular priority value
(setter field).  
{#t_AddADLValueToTheDataLookupTable__table_yjm_xgq_wq__entry__2}

| Matcher fields || Setter field |
|-|-|-|
| Impact | Urgency | Priority |
| 1 - High | 1 - High | 1 - Critical |
| 1 - High | 2 - Medium | 2 - High |
| 1 - High | 3 - Low | 3 - Moderate |
| 2 - Medium | 1 - High | 2 - High |
| 2 - Medium | 2 - Medium | 3 - Moderate |
| 2 - Medium | 3 - Low | 4 - Low |
| 3 - Low | 1 - High | 3 - Moderate |
| 3 - Low | 2 - Medium | 4 - Low |
| 3 - Low | 3 - Low | 5 - Planning |
[Table 2. Lookup table]

{#t_AddADLValueToTheDataLookupTable__table_yjm_xgq_wq}

### Procedure

1. In the navigation filter, enter the name of the new custom lookup table.  
   For example, <kbd class="ph userinput">u_vip_caller_lookup.list</kbd>.
2. Configure the list and create new fields.  
   For this example, create the new fields in the following table.  
   {#t_AddADLValueToTheDataLookupTable__table_xnv_13q_wq__entry__3}

   | Name | Type | Field length or Table to reference |
   |-|-|-|
   | Caller | Reference | User \[sys_user\] |
   | Priority | Integer |   |
   | Assignment Group | Reference | Group \[sys_user_group\] |
   [Table 3. New fields]

   {#t_AddADLValueToTheDataLookupTable__table_xnv_13q_wq}

   For more information, see [Configuring lists on the ServiceNow AI Platform](https://www.servicenow.com/docs/QPLRl9Eu8aSM6GUiZSar~A "Users with the appropriate roles can configure various aspects of lists. Configuration changes apply to all users.").
3. From the table list, select New and enter appropriate matcher and setter field values.  
   For example:  
   {#t_AddADLValueToTheDataLookupTable__table_gjm_j3q_wq__entry__2}

   | Matcher field | Setter fields ||
   |-|-|-|
   | Caller | Priority | Assignment Group |
   | Beth Anglin | 2 | VIP Issues |
   | Fred Luddy | 1 | VIP Issues |
   [Table 4. New matcher and setter field values]

   {#t_AddADLValueToTheDataLookupTable__table_gjm_j3q_wq}  
   Note:  
   Each row in a data lookup table must be unique.

## Create a data lookup definition record {#ariaid-title4}

Data lookup requires a definition record that specifies how to set one or more field
values when specified conditions are met.

### Before you begin

Role required: admin

### Procedure

1. Navigate to AllSystem PolicyRulesData Lookup Definitions.
2. Select New.
3. Select Data Lookup Rule.
4. Complete the Data Lookup Rule form using the following table.  
   {#t_CreateADataLookupDefinRec__table_qcb_2jk_t1b__entry__2}

   | Field | Description |
   |-|-|
   | Name | Enter a unique name to identify the definition record. |
   | Source Table | Select the table containing the fields you want to automatically update with lookup values. Data Lookup Definitions are not inherited by extension tables. For example, a Data Lookup Definition on the Task table cannot match values on the Incident table. |
   | Matcher Table | Select the table containing the lookup values. This table should always start with a u_ prefix. This table can be any table within the current scope containing the lookup values. Note: The list shows only tables and database views that are in the same scope as the catalog data lookup definition. |
   | Active | Select this check box to run this data lookup rule. Clear the check box to ignore this data lookup rule. |
   | Run on form change | Select this check box to automatically look up values whenever a user or onChange client script changes a field value on a source table form. Note: This does not include changes automatically made by other data lookup rules, such as the Priority Lookup Rules. |
   | Run on insert | Select this check box to automatically look up values whenever a user creates a new record. |
   | Run on update | Select this check box to automatically look up values whenever a user saves or updates a record. |
   [Table 5. Data lookup definitions fields]

   {#t_CreateADataLookupDefinRec__table_qcb_2jk_t1b}
5. Select and hold (or right-click) the form header and select Save.
6. From the Matcher Field Definitions related list, click New.
7. Complete the Matcher Field Definitions using the following table.  
   A data lookup only occurs on fields with matcher field definitions. The data
   lookup uses the values of the source table fields to look up one or more
   values from the matcher table. Note that data lookup does not work with
   Journal type fields.
   {#t_CreateADataLookupDefinRec__table_avq_1qq_wq__entry__2}

   | Field | Description |
   |-|-|
   | Data Lookup | Displays the name of the parent data lookup definition record. |
   | Source table field | Select the field from the source table that contains the data to match. |
   | Matcher table field | Select the field from the matcher table that contains the data to match. This table can be any table within the current scope containing the lookup values. |
   | Exact lookup match | Select this check box to require the matcher table to contain a matching row for every possible combination of values (including empty values). Clearing this check box means that any empty values in the matcher table match any value. For example, suppose the Priority field is empty in the matcher table. When this check box is selected, there is a match only when the Priority value is empty in the source table row. When this check box is cleared, the empty matcher field value matches any value in the source table field. Note: If the lookup does not require an exact match, matcher table rows containing empty values are treated as wild cards, matching all values. |
   [Table 6. Matcher field definitions fields]

   {#t_CreateADataLookupDefinRec__table_avq_1qq_wq}
8. Select Submit.
9. From the Setter Field Definitions related list, click New.
10. Complete the Setter Field Definitions form using the following table.  
    {#t_CreateADataLookupDefinRec__table_m2j_yqq_wq__entry__2}

    | Field | Description |
    |-|-|
    | Data Lookup | Displays the name of the parent data lookup definitions record. |
    | Source table field | Select the field from the source table that the data lookup updates. |
    | Matcher table field | Select the field from the matcher table that provides the new value for the update. |
    | Always replace | Select this check box to replace any existing value with a value from the data lookup. Clear this check box to ignore the update if the field has an existing value. |
    [Table 7. Setter field definitions fields]

    {#t_CreateADataLookupDefinRec__table_m2j_yqq_wq}
11. Select Submit.
12. Select Update.

## Create a data lookup module {#ariaid-title5}

You can create a module for data lookup so it appears in the instance application navigator.

### Before you begin

Role required: admin

### Procedure

1. Navigate to AllSystem DefinitionApplication Menus, then select an application to add the module to.
2. In the Modules related list, select New.
3. Configure a module for the data lookup table you created using the following properties.  
   {#t_CreateADataLookupModule__table_rxn_bsq_wq__entry__2}

   | Property | Required value |
   |-|-|
   | Table | Select the data lookup table you created in Step 2. For example u_vip_caller_lookup. |
   | Link type | List of Records |
   [Table 8. Module properties]

   {#t_CreateADataLookupModule__table_rxn_bsq_wq}
4. Select Submit.
{#t_CreateADataLookupModule__steps_l55_3rq_t1b}

## Troubleshooting data lookup {#ariaid-title6}

If the custom data lookup definition rules are not behaving as expected, check for
certain conditions.
* Verify that the data lookup definition is set to run on the appropriate events.
* Verify that the matcher field is not read-only. Because users cannot change read-only fields, user interactions cannot trigger an on form change event for read-only fields.
* Verify a client script is not changing a field value. Client scripts can trigger Run on form change events even on read-only fields.
* Verify that the data in the matcher table is correct.
* If the lookup requires an exact match, verify that there is a matcher table row for each possible combination (including blank values). The lookup fails if cannot find a matching value.
* Verify that you have not created a recursive rule, such as:If Field A = 1, then Field B =2. If Field B = 2, then Field A = 2.

{#troubleshooting-data-lookup__ul_jst_vsq_wq}

*[\>]: and then