The keys.ts File

Every Fluent project has an auto-generated keys.ts file that maps human-readable identifiers to ServiceNow sys_ids. It's the registry that makes Now.ID['my-record'] work.

Location

src/fluent/generated/keys.ts

This file is auto-generated by the build system — you should not normally need to edit it by hand.

Purpose

ServiceNow identifies every record by a 32-character sys_id (e.g., 4103297d12554b488d489c0bf1ceff19). Working with raw sys_ids in source code is error-prone and unreadable. The keys file solves this by mapping meaningful names to sys_ids:

$id: Now.ID['validate-on-insert']  // readable
// resolves to sys_id: '4103297d12554b488d489c0bf1ceff19'

Structure

import '@servicenow/sdk/global'

declare global {
    namespace Now {
        namespace Internal {
            interface Keys extends KeysRegistry {
                explicit: {
                    'validate-on-insert': {
                        table: 'sys_script'
                        id: '4103297d12554b488d489c0bf1ceff19'
                    }
                    'my-acl': {
                        table: 'sys_security_acl'
                        id: 'a3a4966e8c38446d8e1c25620e4e73f4'
                    }
                }
                composite: [
                    {
                        table: 'sys_documentation'
                        id: '00e80b3ed0124620a32c6f9ac0472cf4'
                        key: {
                            name: 'x_myapp_table'
                            element: 'name'
                            language: 'en'
                        }
                    }
                ]
                deleted: {}
            }
        }
    }
}

Key types

Explicit keys

Direct mappings from a developer-chosen name to a table and sys_id. These are created when you use $id: Now.ID['some-name'] in your Fluent code.

explicit: {
    'my-business-rule': {
        table: 'sys_script'
        id: '4103297d12554b488d489c0bf1ceff19'
    }
}

• You choose the key name — it can be any string ('my-rule', 'validate-on-insert', '1')
• The sys_id is auto-generated on first build and stable thereafter
• IDE autocomplete suggests existing keys when you type Now.ID['

Composite keys

For records identified by a combination of field values (coalesce keys) rather than a single developer-chosen name. These are auto-generated for child and descendant records like table columns, documentation entries, and choice values.

composite: [
    {
        table: 'sys_choice'
        id: 'ae25f03b01c14366942460e8cfeec032'
        key: {
            name: 'x_myapp_task'
            element: 'state'
            value: 'todo'
        }
    }
]

You don't interact with composite keys directly — they're managed by the build system.

Deleted keys

Tracks records that have been removed from the project. This prevents sys_id reuse and enables clean uninstall.

How Now.ID works

First build — key is new

// In your .now.ts file:
BusinessRule({
    $id: Now.ID['my-new-rule'],  // Key doesn't exist yet
    ...
})

The build system:

1. Sees 'my-new-rule' is not in keys.ts
2. Generates a new sys_id
3. Adds the entry to keys.ts
4. Uses that sys_id in the XML output

Subsequent builds — key exists

// In your .now.ts file:
BusinessRule({
    $id: Now.ID['my-new-rule'],  // Key exists in keys.ts
    ...
})

The build system:

1. Looks up 'my-new-rule' in keys.ts
2. Finds the existing sys_id
3. Uses the same sys_id — ensuring the record is updated, not duplicated

Best practices

• Don't edit keys.ts manually unless you need to fix a specific mapping
• Do commit keys.ts to version control — it's the source of truth for record identity
• Use meaningful key names — 'validate-priority-on-insert' is better than '1'
• Don't worry about composite keys — they're fully automatic