--- sourceDocument: Yokohama Build or modify applications sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/application-development Release : - yokohama ft:locale : - en-US ft:publication_title : - Yokohama Build or modify applications ft:clusterId : - cadev bundleId : - cadev workflow : - Development, Data, and Analytics --- # Service Portal API # Service Portal API - ServiceNow Fluent {#ariaid-title1} * Release version: Yokohama * * Updated March 12, 2026 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 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](https://servicenow.github.io/sdk/) and [ServiceNow SDK examples repository](https://github.com/ServiceNow/sdk-examples) on GitHub. For general information about portals, see [Service Portal](https://www.servicenow.com/docs/access?context=c_ServicePortal&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). **Related concepts** * [ServiceNow Fluent](https://www.servicenow.com/docs/~uRaWXiuRJuyUsvJypBknQ "Define application metadata in source code using the ServiceNow Fluent domain-specific programming language.") ## SPWidget object {#ariaid-title2} Create a custom widget \[sp_widget\] to include on a portal page. For general information about creating custom widgets, see [Developing custom widgets](https://www.servicenow.com/docs/access?context=widget-dev-guide&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). {#fluent-sp-widget-object__table_egv_ymg_kfc__entry__3}{#fluent-sp-widget-object__d2381e297} | 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). 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 {#fluent-sp-widget-object__ul_d33_d1s_4fc} 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide an inline script, use string literals or template literals for multiple lines of code: ``'Script' or `Script```. {#fluent-sp-widget-object__ul_zr2_zvg_5fc} 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide an inline script, use string literals or template literals for multiple lines of code: ``'Script' or `Script```. {#fluent-sp-widget-object__d2381e517} 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide inline HTML, use string literals or template literals for multiple lines of code: ``'HTML' or `HTML```. {#fluent-sp-widget-object__ul_mkt_z5g_5fc} Default:
| | 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide inline CSS, use string literals or template literals for multiple lines of code: ``'CSS' or `CSS```. {#fluent-sp-widget-object__ul_bfb_mqd_1gc} | | 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](https://www.servicenow.com/docs/access?context=c_WidgetInstanceOptions&version=yokohama&pubname=yokohama-platform-user-interface§ion=sp-instance-ext-table&ft:locale=en-US). 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide inline JSON, use an object with key and value pairs: `{ key: value }`. {#fluent-sp-widget-object__ul_jff_2dh_dgc} | | 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](https://www.servicenow.com/docs/TPuAIpTcWh9Xd1b7Via69w#record-api-now-ts "The Record API defines records in any table. Use the Record API to define application metadata that doesn't have a dedicated ServiceNow Fluent API."). | | 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. {#fluent-sp-widget-object__ul_gk3_fs4_sfc} 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide an inline script, use string literals or template literals for multiple lines of code: ``'Script' or `Script```. {#fluent-sp-widget-object__d2381e517} 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](https://www.servicenow.com/docs/hdrGz27sawyUt1lx7pLLJA#role-api-now-ts "The Role API defines roles [sys_user_role] that grant specific permissions to users of an application."). | | 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](https://www.servicenow.com/docs/access?context=c_WidgetInstanceOptions&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). 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 {#fluent-sp-widget-object__ul_e5y_mbf_1gc} * type: Required. The data type of the parameter. Valid values: * string * boolean * integer * reference * choice * fieldList * fieldName * glideList * glyphIcon {#fluent-sp-widget-object__ul_p4m_1cf_1gc} * defaultValue: The default value of the parameter. * hint: A short description of the parameter that displays as tooltip when hovering over it. {#fluent-sp-widget-object__ul_wv1_gbf_1gc} | | 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. {#fluent-sp-widget-object__ul_its_d2c_sfc} 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](https://www.servicenow.com/docs/OrZ3blah8UT5Sdsr46I5bA#fluent-sp-widget-dependency-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."). | | 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](https://www.servicenow.com/docs/OrZ3blah8UT5Sdsr46I5bA#fluent-sp-angular-provider-object "Create an Angular Provider [sp_angular_provider] to reuse components in multiple widgets and improve portal performance."). | | 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]` {#fluent-sp-widget-object__now-id-desc2} * 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. {#fluent-sp-widget-object__ul_zlz_3cp_sfc} | | $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. {#fluent-sp-widget-object__ul_n3q_y3s_42c} | [Table 1. Properties] {#fluent-sp-widget-object__table_egv_ymg_kfc} 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 {#ariaid-title3} Create an Angular Provider \[sp_angular_provider\] to reuse components in multiple widgets and improve portal performance. {#fluent-sp-angular-provider-object__table_egv_ymg_kfc__entry__3}{#fluent-sp-angular-provider-object__now-id-desc2} | 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). * To provide an inline script, use string literals or template literals for multiple lines of code: ``'Script' or `Script```. {#fluent-sp-angular-provider-object__ul_zr2_zvg_5fc} | | type | String | The type of Angular provider. Valid values: * directive * factory * service {#fluent-sp-angular-provider-object__ul_xzh_bds_4fc} 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. {#fluent-sp-angular-provider-object__ul_n3q_y3s_42c} | [Table 2. Properties] {#fluent-sp-angular-provider-object__table_egv_ymg_kfc} 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 {#ariaid-title4} 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](https://www.servicenow.com/docs/access?context=widget-dependencies&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). {#fluent-sp-widget-dependency-object__table_egv_ymg_kfc__entry__3}{#fluent-sp-widget-dependency-object__now-id-desc2} | 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). 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. {#fluent-sp-widget-dependency-object__ul_gcm_d2s_4fc} 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](https://www.servicenow.com/docs/OrZ3blah8UT5Sdsr46I5bA#fluent-css-include-object "Create a CSS include [sp_css_include] to reference a style sheet or external CSS in a widget dependency."). 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](https://www.servicenow.com/docs/OrZ3blah8UT5Sdsr46I5bA#fluent-js-include-object "Create a JS include [sp_js_include] to reference a UI script or external JavaScript code in a widget dependency."). 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. {#fluent-sp-widget-dependency-object__ul_n3q_y3s_42c} | [Table 3. Properties] {#fluent-sp-widget-dependency-object__table_egv_ymg_kfc} 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 {#ariaid-title5} Create a CSS include \[sp_css_include\] to reference a style sheet or external CSS in a widget dependency. {#fluent-css-include-object__table_egv_ymg_kfc__entry__3}{#fluent-css-include-object__now-id-desc2} | 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). 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](https://www.servicenow.com/docs/access?context=styling-right-to-left-languages&version=yokohama&pubname=yokohama-platform-user-interface&ft:locale=en-US). | | 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. {#fluent-css-include-object__ul_v1h_p2p_sfc} 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. {#fluent-css-include-object__ul_n3q_y3s_42c} | [Table 4. Properties] {#fluent-css-include-object__table_egv_ymg_kfc} import { CssInclude } from '@servicenow/sdk/core' const localCss = CssInclude({ $id: '22bcf16da81e2bc0340c53d50d531adf', name: 'Sample Styles', spCss: '50e3e32aa321b1c7d1945c5f423228bd', }) ## JsInclude object {#ariaid-title6} Create a JS include \[sp_js_include\] to reference a UI script or external JavaScript code in a widget dependency. {#fluent-js-include-object__table_egv_ymg_kfc__entry__3}{#fluent-js-include-object__now-id-desc2} | 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](https://www.servicenow.com/docs/3RTnzOESnTILKQIIO7V1sg "ServiceNow Fluent language constructs provide additional functionality for development in source code with ServiceNow Fluent APIs."). 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. {#fluent-js-include-object__ul_n3q_y3s_42c} | [Table 5. Properties] {#fluent-js-include-object__table_egv_ymg_kfc} import { JsInclude } from '@servicenow/sdk/core' const localJs = JsInclude({ $id: '98239e4eadfac88b01cce7daa23b6fc3', name: 'Sample Framework', sysUiScript: 'b67af05645f738df1f286bb3e9ecd55f', })