@servicenow/sdk - v4.9.0
    Preparing search index...

    Interface DataLookupConfig<S, M>

    Configuration for a Data Lookup Definition (dl_definition).

    A Data Lookup Definition automates field population on a source table by matching source record field values against rows in a custom matcher table (which must extend dl_matcher), then copying matched field values back to the source record.

    The lookup fires as a server-side business rule on insert and/or update, and optionally client-side when watched fields change on the form.

    DataLookup({
        $id: Now.ID['assignment-lookup'],
        name: 'Assignment Lookup',
        sourceTable: 'incident',
        matcherTable: 'dl_u_assignment',
        runOnUpdate: true,
        matchRules: [
            { sourceField: 'category', matcherField: 'category' },
        ],
        setRules: [
            { targetField: 'assignment_group', matcherField: 'assignment_group' },
        ],
    })
    interface DataLookupConfig<
        S extends TableName = TableName,
        M extends TableName = TableName,
    > {
        $id: string | number | ExplicitKey<string>;
        $override?: Record<string, string | number | boolean>;
        active?: boolean;
        matcherTable: M;
        matchRules?: DataLookupMatchRule<S, M>[];
        name: string;
        protectionPolicy?: "read" | "protected";
        runOnFormChange?: boolean;
        runOnInsert?: boolean;
        runOnUpdate?: boolean;
        setRules?: DataLookupSetRule<S, M>[];
        sourceTable: S;
    }

    Type Parameters

    Index

    Properties

    $id $override? active? matcherTable matchRules? name protectionPolicy? runOnFormChange? runOnInsert? runOnUpdate? setRules? sourceTable

    Properties

    $id: string | number | ExplicitKey<string>
    $override?: Record<string, string | number | boolean>

    Set properties not directly supported by this API.

    active?: boolean

    When false, disables this definition and all its associated rules. Defaults to true.

    matcherTable: M

    The matcher table that drives the lookup — must be a table that extends dl_matcher in sys_db_object. Each row in this table defines a set of field values; when all match rules pass for a source record, the matched row's values are copied to the source record.

    Custom matcher tables must extend dl_matcher (e.g., 'dl_u_assignment', 'dl_u_priority'). The build will succeed if you provide an incorrect table, but the lookup will not fire on the instance — verify the table hierarchy in sys_db_object before deploying.

    matchRules?: DataLookupMatchRule<S, M>[]

    Field pairs that determine which rows in the matcher table match the source record. Each rule compares a source table field value against the corresponding matcher table field.

    name: string

    Unique name for this data lookup definition. Maximum 40 characters.

    protectionPolicy?: "read" | "protected"

    Controls edit/view access for other developers after the application is installed.

    • read: Others can see the script logic but not change it.
    • protected: Others cannot change this record.
    • Omit to allow other developers to customize this record.
    runOnFormChange?: boolean

    When true, re-runs the lookup client-side whenever any matchRules source field changes on a form. Defaults to true.

    runOnInsert?: boolean

    When true, fires this lookup as a server-side business rule on record insert. Defaults to true.

    runOnUpdate?: boolean

    When true, fires this lookup as a server-side business rule on record update. Defaults to false — must be explicitly enabled to fire on updates.

    setRules?: DataLookupSetRule<S, M>[]

    Field pairs that define which matcher table field values are copied back to the source record when a matching row is found.

    sourceTable: S

    The table on which this lookup fires — the table whose records receive the auto-populated values. Can be any OOB or custom table (e.g., 'incident', 'change_request', 'x_myapp_orders').

    Settings

    Member Visibility

    On This Page

    Properties