--- tags: [service portal menu, angular provider, widget dependency, header footer, portal css, scss, ootb widgets, ootb pages, bootstrap, sp_instance_menu, sp_angular_provider, sp_dependency, sp_header_footer] --- # Service Portal Extended Reference Extended reference for ServiceNow Service Portal covering menus, angular providers, widget dependencies, headers/footers, CSS/theming, out-of-the-box widgets and pages, and troubleshooting. ## API Reference: Menu (sp_instance_menu) For the full property reference (menus and menu items), see the `spmenu-api` topic. ### Menu Item Types | Type | Additional Fields | Description | | ------------- | -------------------------------- | ------------------------------- | | `page` | `page` (reference, required) | Links to an SP page | | `url` | `url`, `urlTarget` | External or internal URL | | `sc` | (none) | Service Catalog home | | `sc_category` | `scCategory`, `page` | Service Catalog category | | `sc_cat_item` | `catItem`, `page` | Specific catalog item | | `kb` | (none) | Knowledge Base home | | `kb_topic` | `kbTopic`, `page` | Knowledge topic | | `kb_article` | `kbArticle`, `page` | Specific knowledge article | | `kb_category` | `kbCategory`, `page` | Knowledge category | | `filtered` | `table`, `filter`, display fields| Dynamic content based on filter | | `scripted` | `script` | Server-side generated items | ### Menu Widget Selection Always use an existing OOTB menu widget. Always set the `widget` field on menu records. | Widget Name | Typical sys_id (verify on instance) | Recommended Use | | ---------------- | ----------------------------------------- | ---------------------------- | | Header Menu | `5ef595c1cb12020000f8d856634c9c6e` | Standard portal navigation | | Icon Menu List | `88979930cb01020000f8d856634c9caa` | Menu with icon per item | | Single Icon Menu | `5edf4c21cb21020000f8d856634c9cba` | Compact icon dropdown | ### Menu Example ```typescript fluent import "@servicenow/sdk/global"; import { SPMenu } from "@servicenow/sdk/core"; export const mainMenu = SPMenu({ $id: Now.ID["main_menu"], title: "Main Menu", widget: "5ef595c1cb12020000f8d856634c9c6e", items: [ { $id: Now.ID["home_item"], type: "page", label: "Home", page: "", glyph: "home", order: 100 }, { $id: Now.ID["services_item"], type: "sc", label: "Services", glyph: "briefcase", order: 200, childItems: [ { $id: Now.ID["it_services"], type: "sc_category", label: "IT Services", scCategory: "", page: "", order: 100 } ] }, { $id: Now.ID["kb_item"], type: "kb", label: "Knowledge", glyph: "book", order: 300 } ] }); ``` --- ## API Reference: Angular Provider (sp_angular_provider) For the full property reference, see the `spangularprovider-api` topic. ### Provider Types | Type | Returns | When to Use | | ----------- | --------------------------------- | ------------------------------------------------- | | `directive` | Directive Definition Object (DDO) | Custom HTML elements/attributes, reusable UI | | `service` | Object with methods | Shared logic, state management, utility functions | | `factory` | Object or primitive | Configurable objects, API integration layers | ### Provider Guidelines - Function name MUST match the `name` field exactly - Services and factories must return an object (not `this`, not primitives) - Directives must return a Directive Definition Object - Link providers to widgets via `angularProviders` array in `SPWidget()` - Avoid circular dependencies between providers - Use string concatenation for HTML inside template literals to avoid quote conflicts ### Provider Example: Service ```typescript fluent import "@servicenow/sdk/global"; import { SPAngularProvider } from "@servicenow/sdk/core"; export const dataService = SPAngularProvider({ $id: Now.ID["data_service"], name: "dataService", type: "service", script: ` function dataService($http) { return { getRecords: function(table, limit) { return $http.get('/api/now/table/' + table, { params: { sysparm_limit: limit || 10 } }); } }; } ` }); ``` ### Linking Provider to Widget Widget client scripts, server scripts, HTML, and CSS use `Now.include()` because the Service Portal widget runtime does not support modules. ```typescript fluent import { SPWidget } from "@servicenow/sdk/core"; import { dataService } from "../../sp-angular-provider/provider.now"; export const myWidget = SPWidget({ $id: Now.ID["my_widget"], name: "My Widget", angularProviders: [dataService], clientScript: Now.include("./client_script.js"), htmlTemplate: Now.include("./template.html"), serverScript: Now.include("./server_script.js") }); ``` ```javascript // client_script.js api.controller = function (dataService) { var c = this; dataService.getRecords("incident", 5).then(function (response) { c.data.records = response.data.result; }); }; ``` --- ## API Reference: Widget Dependency (sp_dependency) For the full property reference (dependencies, JsInclude, CssInclude), see the `spwidgetdependency-api` topic. ### Bundled Libraries (Do NOT Re-Add) SP already includes these globally. Adding them again causes version conflicts: - jQuery - AngularJS - Bootstrap 3 CSS/JS - Bootstrap 3 Glyphicons ### Dependency Guidelines - Lower `order` numbers load first. Always load base libraries before plugins. - Use minified CDN URLs with version pinning (e.g., `library@4.17.21`) - One dependency per library -- share across multiple widgets - Always use HTTPS URLs - Link dependencies to widgets via `dependencies` array in `SPWidget()` ### Dependency Example ```typescript fluent import "@servicenow/sdk/global"; import { SPWidgetDependency, JsInclude, CssInclude } from "@servicenow/sdk/core"; export const select2Dep = SPWidgetDependency({ $id: Now.ID["select2_dep"], name: "Select2", jsIncludes: [ { order: 100, include: JsInclude({ $id: Now.ID["select2_js"], name: "Select2 JS", url: "https://cdn.jsdelivr.net/npm/select2@4.1.0/dist/js/select2.min.js" }) } ], cssIncludes: [ { order: 100, include: CssInclude({ $id: Now.ID["select2_css"], name: "Select2 CSS", url: "https://cdn.jsdelivr.net/npm/select2@4.1.0/dist/css/select2.min.css" }) } ] }); ``` --- ## API Reference: Header/Footer (sp_header_footer) Headers and footers have no dedicated Fluent API. Use the generic `Record()` constructor. For the property reference, see the `SPHeaderFooter` topic. ### OOTB Headers and Footers Always reuse OOTB headers and footers first. Only create custom when explicitly requested. | Record | Sys ID | | ------------- | ---------------------------------- | | Stock Header | `bf5ec2f2cb10120000f8d856634c9c0c` | | Sample Footer | `feb4f763df121200ba13a4836bf26320` | Always verify existence on instance: `{ table: "sp_header_footer", encodedQuery: "sys_id=" }` ### Header Example ```typescript fluent import "@servicenow/sdk/global"; import { Record } from "@servicenow/sdk/core"; export const customHeader = Record({ $id: Now.ID["custom_header"], table: "sp_header_footer", data: { name: "Custom Portal Header", template: Now.include("./header_template.html"), client_script: Now.include("./header_client.js"), css: Now.include("./header_styles.css") } }); ``` --- ## CSS and Theming Reference ### SCSS Variable Rules for Widget CSS Never invent custom SCSS variable names. Service Portal compiles widget CSS as SCSS with only the portal theme's `css_variables` injected. Undefined variables are silently dropped. Before writing any widget CSS: 1. Look up the portal's theme from the portal definition 2. Only use SCSS variables from the theme's `css_variables` or from the extended Bootstrap/SP defaults 3. If a needed variable does not exist, use SCSS functions (`darken()`, `lighten()`, `rgba()`) on an existing variable 4. Never use hardcoded hex, rgb, or rgba values ### Extended Bootstrap/SP Defaults (Always Available) `$border-radius-base` -- `$border-radius-large` -- `$border-radius-small` -- `$font-size-base` -- `$font-size-small` -- `$font-size-large` -- `$btn-primary-color` -- `$panel-primary-text` -- `$link-color` -- `$state-success-bg` -- `$state-warning-bg` -- `$state-danger-bg` -- `$state-info-bg` -- `$alert-success-border` -- `$alert-warning-border` -- `$alert-danger-border` -- `$alert-info-border` -- `$body-bg` -- `$component-active-bg` -- `$btn-default-border` -- `$panel-border-color` -- `$input-border` -- `$input-border-focus` ### Coral Theme SCSS Variable Reference #### Backgrounds | Use Case | Variable | | ------------------------- | ---------------------------------- | | Card / surface background | `$background-primary` | | Page background | `$sp-page-bg` | | Subtle / muted background | `$background-secondary` | | Heavier subtle background | `$background-tertiary` | | Input field background | `$sp-form-field--background-color` | #### Borders | Use Case | Variable | | -------------------------------- | ------------------- | | Default border (cards, dividers) | `$border-tertiary` | | Medium emphasis border | `$border-secondary` | | Strong emphasis border | `$border-primary` | #### Text | Use Case | Variable | | -------------------------------- | --------------------- | | Primary text | `$text-color` | | Secondary text | `$text-secondary` | | Muted / helper text | `$text-muted` | | White text (on dark backgrounds) | `$btn-primary-color` | #### Brand Colors | Use Case | Variable | | ---------------------------- | ------------------------ | | Primary brand | `$brand-primary` | | Primary dark (hover) | `$brand-primary-dark` | | Primary lighter (highlights) | `$brand-primary-lighter` | | Success | `$brand-success` | | Warning | `$brand-warning` | | Danger | `$brand-danger` | | Info | `$brand-info` | | Link color | `$link-color` | ### Spacing Scale Use only these values. Never use arbitrary pixel values. | Variable | Value | Use Case | | -------------- | ----- | ----------------------------------- | | `$sp-space-1` | 4px | Icon gaps, badge padding | | `$sp-space-2` | 8px | Input padding, label gaps | | `$sp-space-3` | 12px | Button padding Y, tight sections | | `$sp-space-4` | 16px | Base unit -- form group gap | | `$sp-space-5` | 24px | Card padding, section gap | | `$sp-space-6` | 32px | Between major sections | | `$sp-space-7` | 48px | Page top padding, empty states | | `$sp-space-8` | 64px | Full-bleed sections | ### Typography Scale Every `font-size` must use a theme variable -- never a raw pixel value. | Variable | Value | Use Case | | ---------------- | ----- | -------------------------------- | | `$sp-text-xs` | 12px | Badges, timestamps, captions | | `$sp-text-sm` | 14px | Helper text, table metadata | | `$sp-text-base` | 16px | Body, labels, table cells | | `$sp-text-md` | 18px | Card titles, sub-headings | | `$sp-text-lg` | 22px | Section headings | | `$sp-text-xl` | 26px | Page title | | `$sp-text-2xl` | 32px | Hero / banner headings | ### Icon Size Scale | Variable | Value | Use Case | | -------------- | ----- | ----------------------------- | | `$sp-icon-xs` | 12px | Badge / chevron icons | | `$sp-icon-sm` | 16px | Button / inline / alert icons | | `$sp-icon-md` | 20px | Card / stat tile icons | | `$sp-icon-lg` | 32px | Section / feature icons | | `$sp-icon-xl` | 48px | Empty state / hero icons | ### Bootstrap Grid Patterns | Layout Type | Bootstrap Classes | | ----------------------- | ---------------------------------- | | Full-width | `col-md-12` | | Main + sidebar | `col-md-8` + `col-md-4` | | Equal 2-column | `col-md-6 col-xs-12` x 2 | | 3-column cards | `col-md-4 col-sm-6 col-xs-12` x 3 | | 4-column stat tiles | `col-md-3 col-sm-6 col-xs-12` x 4 | Always add `col-xs-12` -- every column must stack on mobile. ### CSS Anti-Patterns | Anti-Pattern | Correct Replacement | | ---------------------------------- | -------------------------------------------- | | `style=""` inline on elements | Use SCSS class | | Raw hex values in widget CSS | Use `$brand-primary`, `$text-color` etc. | | `
` tags for spacing | Use margin/padding utilities | | `!important` in widget CSS | Increase selector specificity | | Input without `