Define application metadata in source code using the ServiceNow Fluent domain-specific programming language.

Overview of ServiceNow Fluent

ServiceNow Fluent is a domain-specific language (DSL) based on TypeScript for defining the metadata files [sys_metadata] that make up applications and includes APIs for the different types of metadata, such as tables, roles, ACLs, business rules, and Automated Test Framework tests.

Developers define this metadata in a few lines of code instead of through a form or builder tool user interface. Applications created or converted with the ServiceNow IDE or ServiceNow SDK support developing in ServiceNow Fluent.

ServiceNow Fluent supports two-way synchronization, which allows changes to metadata to be synced from other Now Platform user interfaces into source code and changes to source code to be synced back to metadata across the instance.
Note: The Automated Test Framework Test API supports only one-way synchronization. After defining an ATF test in source code, if the metadata is modified outside of the source code, those changes aren't synchronized and reflected in the source code.

To get started using the ServiceNow IDE or ServiceNow SDK, see the ServiceNow IDE or ServiceNow SDK documentation.

APIs

ServiceNow Fluent includes APIs for the following types of metadata. You can use the Record API to define application metadata that doesn't have a dedicated API.

For details about the APIs and examples, see ServiceNow Fluent API reference and the ServiceNow SDK examples GitHub repository.

  • Access control lists (ACLs)
  • Application menus
  • Automated Test Framework tests
  • Business rules
  • Client scripts
  • Lists
  • Properties
  • Records
  • Roles
  • Scripted REST APIs
  • Tables

Usage

In files with the .now.ts extension, use objects in the ServiceNow Fluent APIs to define metadata in the application. You must also include the required imports for the APIs from @servicenow/sdk/core.

The following example includes the definitions of a table, client script, and business rule in the application. The business rule uses a function from the script.js JavaScript module.
import '@servicenow/sdk/global'
import { BusinessRule } from '@servicenow/sdk/core'
import { ClientScript } from '@servicenow/sdk/core'
import { Table, DateColumn, StringColumn } from '@servicenow/sdk/core'
import { showStateUpdate } from '../server/script.js'

//creates todo table, with three columns (deadline, status and task)
export const x_snc_example_to_do = Table({
    name: 'x_snc_example_to_do',
    schema: {
        deadline: DateColumn({ label: 'deadline' }),
        state: StringColumn({
            label: 'State',
            choices: {
                ready: { label: 'Ready' },
                completed: { label: 'Completed' },
                in_progress: { label: 'In Progress' },
            },
        }),
        task: StringColumn({ label: 'Task', maxLength: 120 }),
    },
})

//creates a client script that pops up 'Table loaded successfully!!' message everytime todo record is loaded
ClientScript({
    $id: Now.ID['cs0'],
    name: 'my_client_script',
    table: 'x_snc_example_to_do',
    active: true,
    applies_extended: false,
    global: true,
    ui_type: 'all',
    description: 'Custom client script generated by Now SDK',
    messages: '',
    isolate_script: false,
    type: 'onLoad',
    script: script`function onLoad() {
        g_form.addInfoMessage("Table loaded successfully!!")
    }`,
})

//creates a business rule that pops up state change message whenever a todo record is updated
BusinessRule({
    $id: Now.ID['br0'],
    action: ['update'],
    table: 'x_snc_example_to_do',
    script: showStateUpdate,
    name: 'LogStateChange',
    order: 100,
    when: 'after',
    active: true,
})

After building the application, this source code generates the following application metadata files on the instance.

Figure 1. Application metadata generated from ServiceNow Fluent code
Application files generated from the example code.
Tip: You can use the following directives in a code comment to help manage your code:
  • @fluent-ignore: Suppresses ServiceNow Fluent diagnostic warnings and errors in the following line of code.
  • @fluent-disable-sync: Turns off syncing changes to a ServiceNow Fluent object. Use before a call expression (for example, Record({ ... })) to turn off syncing for that object and its child objects. Only use this directive if you want to ignore changes made outside of the source code to the object and never update it when syncing.
  • @fluent-disable-sync-for-file: Turns off syncing changes to a ServiceNow Fluent file (.now.ts). Use in the first line of the file to turn off syncing for all code in the file. Only use this directive if you want to ignore changes made outside of the source code to the file and never update it when syncing.