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.

For AI agents and developers: This document covers the keys.ts file structure. For how to use Now.ID in your Fluent code — including key naming conventions, identity vs. referencing, and common mistakes — see the Now.ID topic.

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 — any string is valid; kebab-case (e.g. 'validate-on-insert') is conventional
• The sys_id is auto-generated on first build and stable thereafter — renaming a key creates a new record and orphans the old one
• IDE autocomplete suggests existing keys when you type Now.ID['
• For full naming guidance see the Now.ID topic

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

For a detailed explanation of Now.ID — including build mechanics, key naming conventions, identity vs. referencing records, and common mistakes — see the Now.ID topic.

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 --frozenKeys in CI — prevents a build from silently regenerating keys.ts when the committed file is out of date; see the CI Integration topic for setup
• Use meaningful key names — 'validate-priority-on-insert' is better than '1'
• Don't worry about composite keys — they're fully automatic