Service Portal API - ServiceNow Fluent

  • Release version: Australia
  • Updated March 12, 2026
  • 13 minutes to read

    • The Service Portal API defines custom widgets [sp_widget] for portal pages.

    Note:
    For the latest ServiceNow Fluent API documentation and examples, see the ServiceNow Fluent API reference and ServiceNow SDK examples repository on GitHub.

    For general information about portals, see Service Portal.

    SPWidget object

    Create a custom widget [sp_widget] to include on a portal page.

    For general information about creating custom widgets, see Developing custom widgets.

    Table 1. Properties
    Name Type Description
    $id String or Number Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs.

    Format: Now.ID['String' or Number]
    name String Required. A name for the widget.
    category String The type of widget.
    Valid values:
    • standard
    • otherApplications
    • custom
    • sample
    • knowledgeBase
    • servicePortal
    • serviceCatalog

    Default: custom
    clientScript Script A client-side script that defines the AngularJS controller. This property supports inline JavaScript or a reference to another file in the application that contains a script.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide an inline script, use string literals or template literals for multiple lines of code: 'Script' or `Script`.
    Default: 
    api.controller=function() { /* widget controller */ var c = this;};
    serverScript Script A server-side script that sets the initial widget state, sends data to the widget's client script using the data object, or runs server-side queries. This property supports inline JavaScript or a reference to another file in the application that contains a script.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide an inline script, use string literals or template literals for multiple lines of code: 'Script' or `Script`.
    Default:
    (function () { /* populate the 'data' object */ /* e.g., data.table = $sp.getValue('table'); */ })();
    controllerAs String A variable for a reference to the controller in the directive's scope. The client script accesses the server data object using the c.data variable by default.

    Default: c
    htmlTemplate String The body HTML code that defines what is rendered when the page is shown. It can contain either static XHTML, dynamically generated content defined as Jelly, or call script includes and UI Macros. This property supports a reference to another file in the application that contains HTML or inline HTML.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide inline HTML, use string literals or template literals for multiple lines of code: 'HTML' or `HTML`.
    Default:
    <div><!-- your widget template --></div>
    customCss String The CSS or SCSS that defines the widget style. This property supports a reference to another file in the application that contains CSS or inline CSS.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide inline CSS, use string literals or template literals for multiple lines of code: 'CSS' or `CSS`.
    dataTable String The table in which to store widget instance options. To define a custom option schema, you can add fields to a table that extends the Widget Instance [sp_instance] table and set your widget to use the extension table as a data source. For more information, see Store instance options in a table.

    Default: sp_instance
    demoData String or Object Data that demonstrates the widget functionality. This property supports inline strings, a reference to another file in the application that contains JSON, or inline JSON serializable objects.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide inline JSON, use an object with key and value pairs: { key: value }.
    description String A description of the widget and its purpose.
    docs Reference The variable identifier of the Service Portal documentation [sp_documentation] that provides additional information about the widget and its purpose.

    To define Service Portal documentation, see Record API - ServiceNow Fluent.
    fields Array A list of column names from the data table to use in the widget option schema.
    hasPreview Boolean Flag that indicates whether you can preview the widget from the Widget Editor.
    Valid values:
    • true: You can preview the widget from the Widget Editor.
    • false: You can't preview the widget from the Widget Editor.

    Default: false
    id String A unique ID for the widget. The ID can't contain spaces.
    linkScript Script A link function that uses AngularJS to directly manipulate the DOM. This property supports inline JavaScript or a reference to another file in the application that contains a script.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide an inline script, use string literals or template literals for multiple lines of code: 'Script' or `Script`.
    Default: 
    function link(scope, element, attrs, controller) { }
    roles Array A list of variable identifiers of Role objects or names of roles that can access the widget. For more information, see Role API - ServiceNow Fluent.
    optionSchema Array A list of parameters that a Service Portal administrator (sp_admin) can configure for a widget instance. The widget option schema supports reusing a widget and uniquely configuring instances of the widget on different pages. For more information, see Widget option schema.
    optionSchema: [
  {
    name: 'String',
    label: 'String',
    section: 'String',
    type: 'String',
    defaultValue: 'String',
    hint: 'String'
  },
...
]
    • name: Required. The name of the parameter.
    • label: Required. A label for the parameter that appears in the widget instance options.
    • section: Required. The section of the widget instance options in which the parameter appears.
      Valid values:
      • data
      • behavior
      • documentation
      • presentation
      • other
    • type: Required. The data type of the parameter.
      Valid values:
      • string
      • boolean
      • integer
      • reference
      • choice
      • fieldList
      • fieldName
      • glideList
      • glyphIcon
    • defaultValue: The default value of the parameter.
    • hint: A short description of the parameter that displays as tooltip when hovering over it.
    public Boolean Flag that indicates whether the widget is available to unauthenticated users.
    Valid values:
    • true: Unauthenticated users can access the widget.
    • false: Only authenticated users can access the widget.

    Default: false
    dependencies Array A list of variable identifiers of SPWidgetDependency objects or names or sys_ids of dependencies for the widget. For more information, see SPWidgetDependency object.
    angularProviders Array A list of variable identifiers of SPAngularProvider objects or names or sys_ids of Angular providers for the widget. For more information, see SPAngularProvider object.
    templates Array A list of Angular ng-templates [sp_ng_template] to associate with the widget. Angular ng-templates contain content that is rendered only when you instruct it to render.
    templates: [
  {
    $id: Now.ID['String' or Number]
    id: 'String'
    htmlTemplate: 'HTML' or `HTML` 
  },
  ...
]
    • $id: Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id.

      Format: Now.ID['String' or Number]

    • id: Required. The ID of the Angular ng-template.
    • htmlTemplate: Required. The HTML template content. This property supports a reference to another file in the application that contains HTML or inline HTML.
    $meta Object Metadata for the application metadata.
    With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.
    $meta: {
      installMethod: 'String'
}
    Valid values for installMethod:
    • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
    • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.
    		 
    import { SPWidget } from '@servicenow/sdk/core'

SPWidget({
    $id: 'my_simple_widget',
    name: 'My Simple Widget',
    category: 'knowledgeBase',
    clientScript: Now.include('./client.js'),
    serverScript: Now.include('./server.js'),
    controllerAs: '$ctrl',
    customCss: Now.include('./custom_css.css'),
    dataTable: 'sp_instance',
    demoData: { message: 'Hello, World!' },
    description: 'This is a test widget',
    docs: widgetDoc,
    htmlTemplate: Now.include('./template.html'),
    fields: ['color', 'class_name'],
    hasPreview: true,
    id: 'my-simple-widget',
    linkScript: Now.include('./link.client.js'),
    optionSchema: [
        {
            name: 'my_option',
            label: 'My Option',
            type: 'string',
            section: 'behavior'
        }
    ],
    roles: [manager, 'admin'],
})

    SPAngularProvider object

    Create an Angular Provider [sp_angular_provider] to reuse components in multiple widgets and improve portal performance.

    Table 2. Properties
    Name Type Description
    $id String or Number Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs.

    Format: Now.ID['String' or Number]
    name String Required. A name for the Angular provider.
    clientScript Script A client-side script to reuse in widgets.This property supports inline JavaScript or a reference to another file in the application that contains a script.
    Format:
    • To use text content from another file, refer to a file in the application using the following format: Now.include('path/to/file'). For more information, see ServiceNow Fluent language constructs.
    • To provide an inline script, use string literals or template literals for multiple lines of code: 'Script' or `Script`.
    type String The type of Angular provider.
    Valid values:
    • directive
    • factory
    • service

    Default: directive
    requires Array A list of variable identifiers of other SPAngularProvider objects or names or sys_ids of Angular providers.
    $meta Object Metadata for the application metadata.
    With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.
    $meta: {
      installMethod: 'String'
}
    Valid values for installMethod:
    • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
    • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.
    		 
    import { SPAngularProvider } from '@servicenow/sdk/core'
const OTHER_ANGULAR_PROVIDER = 'd11f285fe069e1f119b44bd05c0770aa'

SPAngularProvider({
    $id: 'my_angular_provider',
    name: 'my_angular_provider',
    clientScript: Now.include('my_angular_provider.client.js'),
    type: 'directive',
    requires: [OTHER_ANGULAR_PROVIDER]
})

    SPWidgetDependency object

    Create a widget dependency [sp_dependency] to link JavaScript and CSS files to widgets and use third-party libraries, external style sheets, or Angular modules.

    Dependencies are loaded asynchronously from the server when needed. Widgets can have as many or as few dependencies as needed. However, the more you add, the more content a widget must download to render on the page. Keep dependencies as small as possible for more efficient load times. For more information, see Create a widget dependency.

    Table 3. Properties
    Name Type Description
    $id String or Number Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs.

    Format: Now.ID['String' or Number]
    name String Required. The name of the widget dependency.
    angularModuleName String The name of the Angular module to load if the JS include is an Angular module.
    includeOnPageLoad Boolean Flag that indicates when the dependency loads on a page.
    Valid values:
    • true: The dependency loads with the initial page load.
    • false: The dependency loads only when the linked widget is loaded on a page.

    Default: false
    cssIncludes Array A list of variable identifiers of CssInclude objects or sys_ids of CSS includes and their order. For more information, see CssInclude object.
    cssIncludes: [
  {
    order: Number,
    include: 'String' or Reference,
  },
  ...
]
    jsIncludes Array A list variable identifiers of JsInclude objects or sys_ids of JS includes and their order. For more information, see JsInclude object.
    jsIncludes: [
  {
    order: Number,
    include: 'String' or Reference,
  },
  ...
]
    portalsForPageLoad Array A list of sys_ids of portals [sp_portal] that load the widget dependency. If empty, the dependency is included on the page load for all portals.
    $meta Object Metadata for the application metadata.
    With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.
    $meta: {
      installMethod: 'String'
}
    Valid values for installMethod:
    • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
    • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.
    		 
    import { SPWidgetDependency } from '@servicenow/sdk/core'

SPWidgetDependency({
    $id: 'samplejs',
    name: 'Sample',
    angularModuleName: 'samplejs',
    includeOnPageLoad: true,
    portalsForPageLoad: ['b4572a48262a16df3032b48cef75a853', 'fe12dbbed14bd3f712f0787141c2f656'],
    cssIncludes: [
        {
            order: 100,
            include: localCss,
        },
        {
            order: 200,
            include: '94112ccb0fb3c2ed072b01d3cb401196',
        },
    ],
    jsIncludes: [
        {
            order: 100,
            include: localJs,
        },
        {
            order: 200,
            include: 'f8af18a5e6c71a3702c4f2038b43cf62',
        },
    ],
})

    CssInclude object

    Create a CSS include [sp_css_include] to reference a style sheet or external CSS in a widget dependency.

    Table 4. Properties
    Name Type Description
    $id String or Number Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs.

    Format: Now.ID['String' or Number]
    name String Required. The name of the CSS include.
    url String The URL to an external CSS file. This property is required if a style sheet isn't provided with the spCss property.
    spCss String The sys_id of a style sheet [sp_css]. This property is required if an external CSS file isn't provided with the url property.
    rtlCssUrl String The URL to an external right-to-left (RTL) CSS file for mirroring the direction of a widget when the session language is a right-to-left language, such as Hebrew. For more information, see Styling for right-to-left languages in portals.
    lazyLoad Boolean Flag that indicates how to load the CSS Include. This property applies only if you use the spCSS property to specify a style sheet.
    Valid values:
    • true: The CSS include loads asynchronously to improve page load time.
    • false: The CSS include doesn't load asynchronously.

    Default: false
    $meta Object Metadata for the application metadata.
    With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.
    $meta: {
      installMethod: 'String'
}
    Valid values for installMethod:
    • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
    • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.
    		 
    import { CssInclude } from '@servicenow/sdk/core'

const localCss = CssInclude({
    $id: '22bcf16da81e2bc0340c53d50d531adf',
    name: 'Sample Styles',
    spCss: '50e3e32aa321b1c7d1945c5f423228bd',
})

    JsInclude object

    Create a JS include [sp_js_include] to reference a UI script or external JavaScript code in a widget dependency.

    Table 5. Properties
    Name Type Description
    $id String or Number Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs.

    Format: Now.ID['String' or Number]
    name String Required. The name of the JS include.
    url String The URL to an external JavaScript file. The URL should be an absolute path. This property is required if a UI script isn't provided with the sysUiScript property.
    sysUiScript String The sys_id of a UI script [sys_ui_script]. This property is required if an external JavaScript file isn't provided with the url property.
    $meta Object Metadata for the application metadata.
    With the installMethod property, you can map the application metadata to an output directory that loads only in specific circumstances.
    $meta: {
      installMethod: 'String'
}
    Valid values for installMethod:
    • demo: Outputs the application metadata to the metadata/unload.demo directory to be installed with the application when the Load demo data option is selected.
    • first install: Outputs the application metadata to the metadata/unload directory to be installed only the first time an application is installed on an instance.
    		 
    import { JsInclude } from '@servicenow/sdk/core'

const localJs = JsInclude({
    $id: '98239e4eadfac88b01cce7daa23b6fc3',
    name: 'Sample Framework',
    sysUiScript: 'b67af05645f738df1f286bb3e9ecd55f',
})