Adding Columns to an Out-of-Scope Table

Guide for adding custom columns to a platform or cross-scope table using augments. Use this when your application needs to attach fields to a table defined in another scope.

When to Use

• Your app needs to store custom data on a platform table (e.g., adding a field to incident)
• The target table is defined in another scope and you cannot modify it directly
• You want to extend a global or vendor table without creating a child table

Instructions

1. Export a Table with augments: 'table_name': Set augments to the full name of the target table (e.g., 'incident'). The exported variable name must match this value.
2. Use the target table's name as-is: Provide the full table name (e.g., 'incident'), not a scoped variant. Do not include a name property — augments replaces it.
3. Prefix all column names with your scope: Column names must begin with your application scope prefix (e.g., x_acme_) to avoid collisions with existing or future platform fields.
4. Configure augments, schema, and optionally index: You may declare an index on columns you add or on pre-existing columns of the target table (see "Indexing Columns"). All other Table properties (extends, label, display, audit, etc.) are not available when augments is set — the TypeScript compiler will flag them.

Key Concepts

What augments Does

Setting augments to a table name tells the Fluent SDK that this Table definition adds columns to an existing table rather than creating a new one. The build produces sys_dictionary records for each column in schema but does not create a sys_db_object record, since the table already exists on the platform.

Column Naming

Columns added to out-of-scope tables must be prefixed with your application scope to prevent naming conflicts. A column named status on incident could clash with the platform's own state or future fields; x_acme_status is unambiguous and tied to your scope.

Indexing Columns

You can declare an index array, exactly as on a table you define with name. The element may reference columns you add (the keys of schema) or pre-existing columns of the target table.

Avoidance

• Never omit the scope prefix from column names — unprefixed columns risk collisions with platform fields, both now and after upgrades.
• Never set other table properties alongside augments — properties like label, extends, and audit describe table ownership, which does not apply here. The TypeScript compiler enforces this.
• Do not use augments to create a new table — if the target table does not already exist on the platform, use a standard Table definition with name instead.

API Reference

For the full property reference, see the table-api topic.

Examples

Add a Custom Field to the Incident Table

import { Table, StringColumn } from '@servicenow/sdk/core'

export const incident = Table({
    augments: 'incident',
    schema: {
        x_acme_escalation_reason: StringColumn({
            label: 'Escalation Reason',
            maxLength: 500,
        }),
    },
})

Add Multiple Fields to the Task Table

import { Table, StringColumn, BooleanColumn } from '@servicenow/sdk/core'

export const task = Table({
    augments: 'task',
    schema: {
        x_acme_reviewed: BooleanColumn({ label: 'Reviewed' }),
        x_acme_reviewer_notes: StringColumn({ label: 'Reviewer Notes' }),
    },
})

Add and Index a Custom Field

import { Table, StringColumn } from '@servicenow/sdk/core'

export const incident = Table({
    augments: 'incident',
    schema: {
        x_acme_correlation_key: StringColumn({ label: 'Correlation Key', maxLength: 100 }),
    },
    index: [{ name: 'idx_correlation_key', unique: false, element: 'x_acme_correlation_key' }],
})