Building applications in source code

Create and develop custom applications in source code using familiar development tools and processes.

Overview of development in source code

You can create applications in code using the ServiceNow IDE on the ServiceNow AI Platform or locally in Visual Studio Code Desktop with the ServiceNow SDK.

In either development environment, you use ServiceNow Fluent, a domain-specific programming language, to define the metadata that makes up applications. ServiceNow Fluent includes APIs for defining the different types of metadata.

With the ServiceNow IDE or ServiceNow SDK, you can also create JavaScript modules and use third-party libraries in your application to optimize code reuse in scripts within an application scope.

Developing and maintaining applications in source code enables you to work in familiar development environments, create and modify complex applications, manage code in source control more easily, and catch errors at build time.

ServiceNow IDEDevelop applications in code in an IDE on the ServiceNow AI Platform.

ServiceNow SDKDevelop applications in code locally and upload changes to an instance.

Comparison of the ServiceNow IDE and the ServiceNow SDK

Feature	ServiceNow IDE	ServiceNow SDK
Development environment	Online ServiceNow instance	Local development and the ability to work offline
User interface	IDE based on Visual Studio Code for the Web	Visual Studio Code Desktop
Collaboration	View any user's changes in real time in code or embedded ServiceNow AI Platform user interfaces. Collaborate with other developers on applications in source control.	Download changes from an instance and install local changes to an instance using the ServiceNow SDK CLI to collaborate with other users. Collaborate with other developers on applications in source control.
Source control	Supports the most common Git functionality and integrating with a Git provider of your choice. One concurrent branch per repository per instance (or developer sandbox).	Full support
Application conversion	Support for converting existing applications not created with the ServiceNow IDE or ServiceNow SDK.	Support for converting existing applications not created with the ServiceNow IDE or ServiceNow SDK.
ServiceNow Fluent	Full support The ServiceNow Fluent Language server is included with the ServiceNow IDE.	Full support The ServiceNow Fluent Language server can be installed from the Visual Studio Code Extension Marketplace.
JavaScript modules and third-party libraries	Full support	Full support
Now Assist for Code	Code auto-complete support for scripts. For information about activation, see Now Assist for Code.	Not supported
Build Agent	Full support. Build Agent is accessed from a chat panel in the ServiceNow IDE. For information about activation, see Build Agent.	Not supported

Application structure

Applications created or converted with the ServiceNow IDE or ServiceNow SDK include source code files and metadata XML files. The package.json and now.config.json files define the application structure, which is similar to that of Node.js applications or Node Package Manager (npm) packages.

Figure 1. Default structure of an application created in the ServiceNow IDE

By default, applications include the following directories and files. You can modify certain aspects of the application structure to suit your needs in the now.config.json file.

.vscode

Directory containing recommended Visual Studio Code extensions.

dist

Directory containing the build artifacts for packaging. This directory includes the following subdirectories:

• app: Directory containing the built metadata XML files.
• static: Directory containing the built static asset files.

metadata

Directory containing the application metadata (XML) of the application, such as table schemas and business rules, organized in the same directory structure as existing ServiceNow applications.

Remarque :

Application metadata shouldn't be edited from the XML files. Edit application metadata in the source code or on the ServiceNow AI Platform.

node_modules

Directory containing the third-party Node.js modules on which your application depends.

src

Directory containing the source code of your application. This directory includes the following subdirectories:

• client: Directory containing the client-side files for developing user interfaces.
• fluent: Directory containing ServiceNow Fluent code in .now.ts files. The generated subdirectory contains the application files converted to ServiceNow Fluent.
• server: Directory containing JavaScript module code in .js or .ts files.

target

Directory containing an installable package (.zip file) to upload to an instance.

.eslintrc.json

File containing the ESLint configuration. ESLint helps identify and fix issues in the application code.

.gitignore

File containing a list of directories or files for Git to ignore. These files aren't tracked in source control.

now.config.json

File containing the ServiceNow application configuration. The now.config.json file must be in the base directory for an application.

You can configure the directory structure for an application by adding the following parameters. For example:

{
  "scope": "x_snc_example_app",
  "scopeId": "2f8400eb07426110f736e28f69d3017a",
  "name": "ExampleApp",
  "dependencies": {
    "global": {
      "tables": ["incident"],
      "roles": ["admin"],
    },
    "x_custom": {
      "tables": ["custom_table"]
    }
  },
  "metadataDir": "metadata",
  "fluentDir": "src/fluent",
  "generatedDir": "generated",
  "serverModulesDir": "src/server",
  "clientDir": "src/client",
  "appOutputDir": "dist/app",
  "staticContentDir": "dist/static",
  "packOutputDir": "target",
  "modulePaths": {
      "src/server/*.ts": "dist/server/*.js",
    },
  "staticContentPaths": {
      "src/client/*.html": "dist/static/*.html",
    },
  "ignoreTransformTableList": ["ua_table_licensing_config", "sys_embedded_help_role"],
  "taxonomy": {
        "mapping": {
            "sys_script": "scripts/server/rules",
            "custom_table": "my-custom-folder/my-nested-folder"
        },
        "fallbackFolderName": "unclassified" 
    }
}

Tableau 1. Supported now.config.json parameters

Parameter	Description
dependencies	The items in another application scope on which your application depends. You must specify the application scope and the dependency type and names or sys_ids. "dependencies": { "<scope>": { "<type>": ["<sys_id or name>"], ... }, ... } For more information, see Download ServiceNow Fluent application dependencies.
metadataDir	Directory containing the application's metadata as XML files. Default: metadata
fluentDir	Directory containing ServiceNow Fluent files (.now.ts) that define application metadata in source code. Default: src/fluent
generatedDir	Directory containing generated ServiceNow Fluent files, including existing application metadata converted into ServiceNow Fluent code. This directory is relative to the directory defined with the fluentDir parameter. Default: generated
serverModulesDir	Directory containing the JavaScript or TypeScript files to be built into JavaScript modules for use in server-side scripts. Default: src/server
clientDir	Directory containing the client-side files for developing user interfaces with React. Default: src/client
appOutputDir	Directory to output the build artifacts to for packaging. The pack and install commands refer to this directory package the artifacts. Default: dist/app
staticContentDir	Directory to output the static asset files used for developing user interfaces. Default: dist/static
packOutputDir	Directory to output the installable package (.zip file) when building the application. The install command refers to this directory to install the package. Default: target
serverModulesIncludePatterns	A list of file patterns to include when building JavaScript modules. Default: [ "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.cts", "**/*.cjs", "**/*.mts", "**/*.mjs", "**/*.json" ]
serverModulesExcludePatterns	A list of file patterns to exclude when building JavaScript modules. Default: [ "**/*.test.ts", "**/*.test.js", "**/*.d.ts" ]
trustedModules	A list of npm packages to identify as trusted (or internal). Trusted modules have access to ServiceNow APIs. For example: "trustedModules": [ "<package-name>", // Specific package "@servicenow/*" // All packages from an organization ] In the EcmaScript Module [sys_module] table, the External source field is set to false for trusted modules. Avertissement : Only add dependencies that you trust completely as trusted modules. Valid patterns: Fully qualified package names, such as '@servicenow/sdk'. Organization prefixes with a wildcard, such as '@servicenow/*' or '@mycompany/*'.
modulePaths	A map of the module source files to their equivalent output files for if you use a custom transpilation step before building the application. For more information, see Using TypeScript in JavaScript modules with the ServiceNow SDK. Avertissement : You can't use this parameter and the tsconfigPath parameter. Configuring both results in an error.
staticContentPaths	A map of the client-side source files to the output paths for static asset files.
tsconfigPath	A path to a tsconfig.json file with custom options for transpiling TypeScript into JavaScript during the build process. Specifying a tsconfigPath generates diagnostic results from TypeScript using the tsconfig.json file. Avertissement : You can't use this parameter and the modulePaths parameter. Configuring both results in an error. Default: .
ignoreTransformTableList	A list of tables to ignore when transforming application metadata into source code.
tableDefaultLanguage	The BCP 47 code of a default language for field labels [sys_documentation] in a table or column. Th default language is used to resolve field labels with multiple languages. Default: en
tableOutputFormat	The type of build artifacts for table metadata XML generated from ServiceNow Fluent code. Valid values: bootstrap: The build process outputs a bootstrap XML file with the <database> root element for the table, field label XML files [sys_documentation], licensing configuration XML files [ua_table_licensing_config], and auto-numbering XML files [sys_number]. component: The build process outputs XML files for each component of the Table API. Default: bootstrap
taxonomy	A configuration for organizing generated ServiceNow Fluent files, which maps table names to directories and defines a fallback directory. The default taxonomy configuration uses ServiceNow standard table classifications to add generated ServiceNow Fluent files in a logical directory structure within the fluent/generated directory when metadata is initially transformed into ServiceNow Fluent code. For example: Business rules [sys_script] are added to the fluent/generated/server-development/business-rule directory. Script includes [sys_script_include] are added to the fluent/generated/server-development/script-include directory. You can override the default mappings or configure additional ones. In the following example, the configuration overrides the default directory for business rules [sys_script] and the fallback folder and configures an additional mapping for metadata from a custom table. "taxonomy": { "mapping": { "sys_script": "scripts/server/rules", "custom_table": "my-custom-folder/my-nested-folder" }, "fallbackFolderName": "unclassified" } mapping: An object that maps table names to directories. Directory paths are relative to the directory configured with the generatedDir parameter and must include only lowercase letters, numbers, hyphens, underscores, and slashes to separate subdirectories. fallbackFolderName: A name for a directory to use for tables that don't have a default or a custom mapping configured. Within this directory, ServiceNow Fluent files are added to subdirectories named after the table, such as src/fluent/generated/other/x-unmapped-table/. Default: Default taxonomy mappings are defined for all standard ServiceNow tables and are automatically applied when no custom configuration is defined in the now.config.json for an application. The default value of fallbackFolderName is other.

now.prebuild.mjs

Auto-updated file containing complete information about dependencies and their versions. This file is only available with the ServiceNow SDK.

package-lock.json

Auto-updated file containing complete information about dependencies and their versions. This file is only available with the ServiceNow SDK.

package.json

File containing information about your application and custom or third-party module dependencies. The package.json file must be in the base directory for an application. On an instance, the package.json path is specified in the Package JSON field of the custom application record [sys_app] in the format <scope>/<package-name>/<version>/package.json.

Related applications and features

JavaScript APIs

Use JavaScript APIs in scripts that you write to change the functionality of applications or when you create applications.

Concepts associés

• ServiceNow Fluent
• JavaScript modules and third-party libraries
• User interface development with React