Function: Form(config)

Creates a form definition (sys_ui_form) for a ServiceNow table with sections and layout blocks.

The Form API creates the following ServiceNow records:

• sys_ui_form — Main form record linking table and view
• sys_ui_form_section — Join table linking form to sections
• sys_ui_section — Section records with caption and layout
• sys_ui_element — Individual field elements within sections
• sys_ui_annotation — Annotation records (when type: 'annotation')

Parameters

config

Form<keyof Tables>

Properties:

• sections (required): Array<FormSection<T>> Array of form sections containing layout blocks. At least one section is required.

• table (required): T The ServiceNow table this form is associated with. Must have scope prefix for scoped apps (e.g., sn_my_app_).

• view (required): string | Record<'sys_ui_view'> View name string or reference to a sys_ui_view record. Use default_view for the default view.

• roles (optional): (string | Role)[] Array of role names or Role objects that have access to this form.

• user (optional): string | Record<'sys_user'> Personalize the form for a specific user. Can be a string username or a reference to a sys_user record.

Examples

Basic Form with Default View

Create a simple form with two sections on the default view using one-column layout.

import { Form, default_view } from '@servicenow/sdk/core'

export const basicForm = Form({
    table: 'sn_my_app_task',
    view: default_view,
    sections: [
        {
            caption: 'Details',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        { field: 'name', type: 'table_field' },
                        { field: 'description', type: 'table_field' },
                    ],
                },
            ],
        },
        {
            caption: 'Assignment',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        { field: 'assigned_to', type: 'table_field' },
                        { field: 'state', type: 'table_field' },
                    ],
                },
            ],
        },
    ],
})

Comprehensive Form — All Element Types

Create a form with two-column layout, annotation, formatter, related list, custom view, and role-based access.

import { Form, Record } from '@servicenow/sdk/core'

export const opsView = Record({
    $id: Now.ID['ops_view'],
    table: 'sys_ui_view',
    data: { name: 'operations', title: 'Operations' },
})

export const comprehensiveForm = Form({
    table: 'sn_my_app_task',
    view: opsView,
    roles: ['admin', 'itil'],
    sections: [
        {
            caption: 'Overview',
            content: [
                {
                    layout: 'two-column',
                    leftElements: [
                        { field: 'name', type: 'table_field' },
                        { field: 'category', type: 'table_field' },
                    ],
                    rightElements: [
                        { field: 'priority', type: 'table_field' },
                        { field: 'assigned_to', type: 'table_field' },
                    ],
                },
                {
                    layout: 'one-column',
                    elements: [
                        {
                            type: 'annotation',
                            annotationId: Now.ID['task_notice'],
                            text: 'Review all fields before saving.',
                            isPlainText: true,
                            annotationType: 'Info_Box_Blue',
                        },
                        { field: 'description', type: 'table_field' },
                    ],
                },
            ],
        },
        {
            caption: 'Activity',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        {
                            type: 'formatter',
                            formatterRef: 'Activities_Filtered',
                        },
                    ],
                },
            ],
        },
        {
            caption: 'Related Tasks',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        {
                            type: 'list',
                            listType: '12M',
                            listRef: 'task_sla.task',
                        },
                    ],
                },
            ],
        },
    ],
})

Custom Formatter and Annotation Type via Record API

Create a form that references custom formatter and annotation type records instead of built-in constants.

import { Form, Record } from '@servicenow/sdk/core'

// Custom formatter — `formatterName` is derived from the record's `formatter` field
export const myFormatter = Record({
    $id: Now.ID['parent_breadcrumb_formatter'],
    table: 'sys_ui_formatter',
    data: {
        name: 'parent_breadcrumb',
        type: 'formatter',
        formatter: 'parent_crumbs.xml',
        table: 'sn_my_app_task',
        active: true,
    },
})

export const myAnnotationType = Record({
    $id: Now.ID['custom_warning_banner'],
    table: 'sys_ui_annotation_type',
    data: {
        name: 'Custom Warning Banner',
        active: true,
        style: 'background-color: #fff3cd; border: 1px solid #ffc107; padding: 12px; border-radius: 4px; color: #856404;',
    },
})

export const customRecordsForm = Form({
    table: 'sn_my_app_task',
    view: 'custom_refs_view',
    sections: [
        {
            caption: 'Custom Elements',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        {
                            type: 'annotation',
                            annotationId: Now.ID['custom_notice'],
                            text: '<b>Warning:</b> Custom styled annotation.',
                            isPlainText: false,
                            annotationType: myAnnotationType,
                        },
                        {
                            type: 'formatter',
                            formatterRef: myFormatter,
                        },
                    ],
                },
            ],
        },
    ],
})

Formatter Variants

Shows all formatterName resolution paths: predefined key, explicit override, custom Record, and raw GUID.

import { Form, Record } from '@servicenow/sdk/core'

// Custom formatter record — formatterName derived from the `formatter` field
export const appFormatter = Record({
    $id: Now.ID['parent_breadcrumb_formatter_1'],
    table: 'sys_ui_formatter',
    data: {
        name: 'parent_breadcrumb',
        type: 'formatter',
        formatter: 'parent_crumbs.xml',
        table: 'sn_my_app_task',
        active: true,
    },
})

export const formatterVariantsForm = Form({
    table: 'sn_my_app_task',
    view: 'formatter_demo',
    sections: [
        {
            caption: 'Formatter Variants',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        // 1. Predefined key — formatterName auto-derived (activity.xml)
                        {
                            type: 'formatter',
                            formatterRef: 'Activities_Filtered',
                        },
                        // 2. Custom Record — formatterName derived from record's `formatter` field
                        {
                            type: 'formatter',
                            formatterRef: appFormatter,
                        },
                        // 3. Raw GUID — formatterName must be provided (not derivable)
                        {
                            type: 'formatter',
                            formatterName: 'custom_formatter.xml',
                            formatterRef: 'aabbccdd11223344aabbccdd11223344',
                        },
                    ],
                },
            ],
        },
    ],
})

M2M Related List and Custom Relationship

Create a form with many-to-many and custom relationship related lists.

import { Form, Record } from '@servicenow/sdk/core'

export const incidentToProblem = Record({
    $id: Now.ID['inc_to_problem'],
    table: 'sys_relationship',
    data: {
        name: 'Incident to Problem',
        basic_apply_to: 'sn_my_app_task',
        basic_query_from: 'problem',
        reference_field: 'problem_id',
    },
})

export const relatedListsForm = Form({
    table: 'sn_my_app_task',
    view: 'relationships_view',
    sections: [
        {
            caption: 'Many-to-Many',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        {
                            type: 'list',
                            listType: 'M2M',
                            listRef: 'm2m_task_project.task_ref',
                        },
                    ],
                },
            ],
        },
        {
            caption: 'Custom Relationship',
            content: [
                {
                    layout: 'one-column',
                    elements: [
                        {
                            type: 'list',
                            listType: 'custom',
                            listRef: incidentToProblem,
                        },
                    ],
                },
            ],
        },
    ],
})