--- tags: [service portal, portal, widget, theme, page, sp_portal, sp_widget, sp_page, sp_theme, AngularJS, Bootstrap 3, self-service, branding, layout, containers, rows, columns] --- # Service Portal Guide for building ServiceNow Service Portal experiences using the Fluent API. Service Portal is a portal framework for building user-facing self-service experiences using AngularJS and Bootstrap 3. This guide covers core portal concepts: portals, pages, widgets, and themes. ## When to Use - Building a branded self-service portal for employees, customers, or partners - Creating custom portal pages with responsive layouts - Developing interactive widgets with client-server communication - Customizing portal appearance with themes, headers, and footers - Setting up navigation menus for portal structure - Creating shared AngularJS services, directives, and factories for widgets - Managing external JavaScript and CSS library dependencies for widgets ## When NOT to Use - Platform UI Pages -- use the UI Page skill instead - Next Experience / UI Builder pages -- different framework entirely - Backend scripts with no UI component (business rules, script includes, etc.) - Flow Designer workflows - Workspace components in Next Experience ## Instructions 1. **Always use dedicated Fluent APIs.** Every Service Portal component has a dedicated API (`ServicePortal`, `SPPage`, `SPWidget`, `SPTheme`, `SPMenu`, `SPAngularProvider`, `SPWidgetDependency`). Never use `Record()` / `Now.table()` for Service Portal components. 2. **Check OOTB components first.** Before creating any widget, theme, or page, check whether an out-of-the-box equivalent already exists. Only create custom components when no suitable OOTB option exists. 3. **Verify uniqueness.** `urlSuffix` (portals), `pageId` (pages), and widget `name`/`id` must be unique across the instance. Always query the instance to verify before creating. 4. **Bootstrap 3 only.** Service Portal uses Bootstrap 3 (not 4 or 5). Use `.panel`, `.btn-default`, `.col-xs-*` through `.col-lg-*`, and the 12-column grid. 5. **AngularJS 1.x only.** Use controller alias `c` (not `$scope`), `ng-repeat`, `ng-click`, `ng-model`. No Angular 2+ syntax. 6. **Separate files for widgets.** Always use `Now.include()` for widget scripts, templates, and styles. Never inline large code blocks. 7. **No placeholders.** Replace all placeholder values with actual data or queried sys_ids. 8. **Query only when referencing existing components.** Do not query before creating new ones. 9. **Scoped app restrictions.** Fluent apps run in scoped context. Use scoped-safe APIs only (e.g., `new GlideDateTime()` instead of `nowDateTime()`). 10. **Run UI diagnostics after install.** After a successful install, verify the portal loads without errors at `/?id=`. 11. **Always share the portal URL.** After successful install, provide the complete URL: `https://.service-now.com/?id=`. ## Key Concepts ### Component Hierarchy ``` Portal (sp_portal) +-- Theme (sp_theme) | +-- Header (sp_header_footer) | +-- Footer (sp_header_footer) +-- Main Menu (sp_instance_menu) +-- Pages (sp_page) +-- Containers -> Rows -> Columns -> Widget Instances (sp_instance) +-- Widgets (sp_widget) +-- Dependencies (sp_dependency) +-- Angular Providers (sp_angular_provider) ``` ### API to Table Mapping | Component | Fluent API | ServiceNow Table | | ----------------- | ---------------------- | --------------------- | | Portal | `ServicePortal()` | `sp_portal` | | Page | `SPPage()` | `sp_page` | | Widget | `SPWidget()` | `sp_widget` | | Theme | `SPTheme()` | `sp_theme` | | Menu | `SPMenu()` | `sp_instance_menu` | | Angular Provider | `SPAngularProvider()` | `sp_angular_provider` | | Widget Dependency | `SPWidgetDependency()` | `sp_dependency` | | Header/Footer | `Record()` | `sp_header_footer` | | CSS Include | `CssInclude()` | `sp_css_include` | | JS Include | `JsInclude()` | `sp_js_include` | ### File Organization ``` fluent/ +-- service-portal/ | +-- portal.now.ts +-- sp-page/ | +-- home/ | | +-- home-page.now.ts | +-- login/ | +-- login-page.now.ts +-- sp-widget/ | +-- my_widget/ | +-- widget.now.ts | +-- server_script.js | +-- client_script.js | +-- template.html | +-- styles.css +-- sp-theme/ | +-- theme.now.ts +-- sp-instance-menu/ | +-- menu.now.ts +-- sp-angular-provider/ | +-- provider.now.ts +-- sp-dependency/ | +-- dependency.now.ts +-- sp-header-footer/ +-- header.now.ts ``` ### Important Technologies Service Portal uses **Bootstrap 3** (not 4/5) and **AngularJS 1.x** (not Angular 2+): - **Bootstrap 3:** 12-column grid, `.panel`, `.btn-default`, `.col-xs-*` through `.col-lg-*` - **AngularJS:** controller alias `c` (not `$scope`), `ng-repeat`, `ng-click`, `ng-model` ### AngularJS Binding Reference | Pattern | Usage | | ----------------------- | ------------------------------------------------------ | | Two-way data binding | `ng-model="c.data.fieldName"` | | Display only | `ng-bind="c.data.value"` or `{{c.data.value}}` | | Remove from DOM | `ng-if="c.data.showSection"` | | Hide/show (keep in DOM) | `ng-show="c.loading"` | | List iteration | `ng-repeat="item in c.data.rows track by item.sys_id"` | | Click handler | `ng-click="c.methodName()"` | | Dynamic class | `ng-class="{'sp-active': c.selected === item.sys_id}"` | | Disable button | `ng-disabled="c.submitting"` | | Input validation state | `ng-class="{'has-error': c.errors.fieldName}"` | ### Widget Script Communication **Server script context:** - `data` -- object passed to client - `input` -- client input from `c.server.get()` / `c.server.update()` - `options` -- widget option values **Client script context:** - `c.data` -- data from server - `c.options` -- widget options - `c.server.get(input)` -- call server (GET) - `c.server.update()` -- call server (POST, sends `c.data` as `input`) - `c.server.refresh()` -- reload widget ## Avoidance - **Never use `Record()` for Service Portal components** -- every component has a dedicated API. `Record()` bypasses validation and uses incorrect field mapping. - **Never use GlideAjax in widgets** -- use `c.server.get()` instead. - **Never omit `setLimit()` on GlideRecord queries** -- runaway queries impact performance. - **Never omit `track by` on `ng-repeat`** -- always use `track by item.sys_id` or `track by $index`. - **Never use Bootstrap 4/5 classes** -- Service Portal uses Bootstrap 3 only. - **Never use `$scope` directly** -- use controller alias `c` (`var c = this`). - **Never use hardcoded hex colors in widget CSS** -- always use theme SCSS variables. - **Never use raw `px` values for `font-size`** -- use `$sp-text-*` or `$font-size-*` variables. - **Never use `!important` in widget CSS** -- increase selector specificity instead. - **Never use inline `style=""` attributes** -- use SCSS classes. - **Never re-add bundled libraries** (jQuery, AngularJS, Bootstrap) -- they are already included in Service Portal. - **Never use `includeOnPageLoad: true`** on dependencies unless truly global -- link to specific widgets instead. - **Never use `href="#"` on anchor elements** -- use `ng-click` with a button instead. - **Never use `alert()` or `console.log()` in widgets** -- use `sp-alert` component and `gs.error()` / `gs.info()` server-side. ## Implementation Workflow 1. **Understand requirements** -- identify components needed and their relationships. Use the decision trees below. 2. **Check OOTB reusability** -- check OOTB widgets, themes, and pages before creating any custom component. 3. **Create components bottom-up** -- start with dependencies and providers, then widgets, then pages, then themes and menus, finally the portal. 4. **Verify unique identifiers** -- query the instance to confirm `urlSuffix`, `pageId`, and widget names are unique. 5. **Validate configuration** -- verify all references are valid and no `Record()` API usage. 6. **Generate code** -- use dedicated Fluent API constructors, include all required fields, replace all placeholders. 7. **Run UI diagnostics** -- after install, verify the portal loads without errors. 8. **Share the portal URL** with the user. ## Decision Trees ### Portal ``` "Create/update a portal" +-- Existing portal? | +-- YES -> Query sp_portal, update only changed fields | +-- NO -> Use ServicePortal() to create new +-- Theme? | +-- DEFAULT -> Always use OOTB theme (Coral first, La Jolla second) | +-- User specifies custom branding OOTB cannot satisfy -> Create SPTheme() +-- Navigation/menu? +-- YES -> Create SPMenu() (theme must have header set) +-- NO -> Skip ``` ### Widget ``` "Create/update a widget" +-- Existing widget satisfies the need? | +-- YES -> Query sp_widget, reuse it | +-- NO -> Create new with separate files (Now.include()) +-- Needs external libraries? | +-- YES -> SPWidgetDependency() + SPWidget() | +-- NO -> SPWidget() only +-- Needs shared services/directives? | +-- YES -> SPAngularProvider() + SPWidget() | +-- NO -> SPWidget() only ``` ### Theme ``` "Create/update a theme" +-- Portal already has a theme? | +-- YES -> Use existing theme. Only update customCss if user explicitly requests branding changes | +-- NO -> Check OOTB themes (Coral first). Create custom only if no suitable OOTB option exists ``` --- ## API Reference: Portal (sp_portal) For the full property reference, see the `serviceportal-api` topic. ### Portal Guidelines - Always query `sp_portal` by `url_suffix` before creating to verify the suffix is unique - Only one portal should have `defaultPortal: true` - Page references can be sys_id strings or SPPage object references - M2M relationships (catalogs, knowledge bases) use arrays of objects, not arrays of strings - Menu display requires all three: portal `theme` + theme `header` + portal `mainMenu` ### Portal Example ```typescript fluent import "@servicenow/sdk/global"; import { ServicePortal } from "@servicenow/sdk/core"; export const employeePortal = ServicePortal({ $id: Now.ID["employee_portal"], title: "Employee Portal", urlSuffix: "emp", theme: theme, // SPTheme object or sys_id mainMenu: menu, // SPMenu object or sys_id homePage: homePage, // SPPage object or sys_id catalogs: [{ catalog: "", order: 100, active: true }], knowledgeBases: [{ knowledgeBase: "", order: 100, active: true }] }); ``` --- ## API Reference: Page (sp_page) For the full property reference (pages, containers, rows, columns, instances), see the `sppage-api` topic. ### Page Guidelines - `pageId` is globally unique across ALL Service Portal pages on the instance. Never use bare generics like `"home"` or `"dashboard"` -- always prefix with a portal identifier (e.g., `"hr-home"`, `"esc-request-catalog"`) - Always query `sp_page` by `id=` before creating - Use `container` width for centered content, `container-fluid` for full-width backgrounds - Column sizes in a row must sum to 12 - Use `nestedRows` for complex multi-level layouts within a single column - Background images use `Now.attach('./path/to/image.png')` with `backgroundStyle: 'cover'` for hero banners ### Page Example ```typescript fluent import "@servicenow/sdk/global"; import { SPPage } from "@servicenow/sdk/core"; export const homePage = SPPage({ pageId: "hr-home", title: "Home", public: true, containers: [ { $id: Now.ID["home_hero_container"], name: "Hero Section", width: "container-fluid", backgroundImage: Now.attach("./images/hero-bg.jpg"), backgroundStyle: "cover", order: 1, rows: [ { $id: Now.ID["home_hero_row"], order: 1, columns: [ { $id: Now.ID["home_hero_col"], size: 12, instances: [ { $id: Now.ID["home_hero_instance"], widget: heroWidget, order: 1 } ] } ] } ] } ] }); ``` --- ## API Reference: Widget (sp_widget) For the full property reference, see the `spwidget-api` topic. ### Widget Guidelines - Widget `name` and `id` must be unique across the instance -- always query before creating - Always use separate files via `Now.include()` for scripts, templates, and styles - Client script pattern: bare function with `api.controller`, `var c = this`, no IIFE - Templates always use controller alias `c`: `{{c.data.field}}`, never `{{data.field}}` - Never use GlideAjax -- use `c.server.get()` instead - Every GlideRecord query must have `setLimit()` - Every `ng-repeat` must have `track by` - Initialize all `data.*` properties at the top of server script - Use `optionSchema` for configurable behavior instead of hardcoded values - No raw hex in widget CSS -- use theme SCSS variables ### Scoped Application Restrictions Fluent apps run in scoped context. Global scope functions are not allowed: | Global (NOT allowed) | Scoped Alternative | | --------------------- | ------------------------------------- | | `nowDateTime()` | `new GlideDateTime()` | | `getXMLWait()` | `c.server.get()` or REST API | | `gs.print()` | `gs.info()`, `gs.error()` | ### Widget Example ```typescript fluent import "@servicenow/sdk/global"; import { SPWidget } from "@servicenow/sdk/core"; export const myWidget = SPWidget({ $id: Now.ID["my_widget"], name: "My Widget", htmlTemplate: Now.include("./template.html"), clientScript: Now.include("./client_script.js"), serverScript: Now.include("./server_script.js"), customCss: Now.include("./styles.css"), optionSchema: [ { name: "table", label: "Table Name", type: "string", default_value: "incident", section: "Data" }, { name: "max_records", label: "Max Records", type: "integer", default_value: "10", section: "Data" } ] }); ``` ### Server Script Pattern ```javascript // server_script.js (function () { data.records = []; data.success = false; data.message = ""; try { if (input && input.action === "submit") { var gr = new GlideRecord("incident"); gr.initialize(); gr.short_description = input.short_description; var id = gr.insert(); data.success = !!id; data.message = id ? gr.getValue("number") + " created." : "Insert failed."; return; } // Initial load var gr = new GlideRecord("incident"); gr.addQuery("active", true); gr.orderByDesc("sys_created_on"); gr.setLimit(options.max_records || 50); gr.query(); while (gr.next()) { data.records.push({ sys_id: gr.getUniqueValue(), number: gr.getValue("number"), short_description: gr.getValue("short_description"), state: gr.getDisplayValue("state") }); } } catch (e) { gs.error("Widget error: " + e.message); data.message = "An error occurred."; } })(); ``` ### Client Script Pattern ```javascript // client_script.js api.controller = function (spUtil) { var c = this; c.loading = false; c.submitting = false; c.data = c.data || {}; c.submit = function () { c.submitting = true; c.server .get({ action: "submit", short_description: c.form.short_description }) .then(function (r) { if (r.data.success) { c.data.successMsg = r.data.message; c.form = {}; } else { c.data.errorMsg = r.data.message || "An error occurred."; } c.submitting = false; }); }; }; ``` ### HTML Template Pattern ```html

My Incidents

  • {{record.number}} -- {{record.short_description}} {{record.state}}

No records found.

``` --- ## API Reference: Theme (sp_theme) For the full property reference, see the `sptheme-api` topic. ### Menu Display Prerequisites Navigation menus will NOT appear unless ALL THREE are set: 1. Portal has `theme` configured 2. Theme has `header` configured (an `sp_header_footer` record) 3. Portal has `mainMenu` configured ### CSS Variable Rules - Only `--now-*` tokens exist as platform CSS custom properties. Never invent token names. - Use `sp-rgb(--now-token, #hex) !default` when a verified `--now-*` token exists for the color. - Use hex directly when no token exists. Never invent a token name. - Always add `!default` to allow per-portal variable overrides. ### Navbar Color Alignment (Required When Overriding `$brand-primary`) When `customCss` declares a custom `$brand-primary`, you MUST also set these 8 navbar variables: ```scss $navbar-inverse-bg: $brand-primary !default; $navbar-inverse-border: darken($brand-primary, 6.5%) !default; $navbar-inverse-link-color: $btn-primary-color !default; $navbar-inverse-link-hover-color: $btn-primary-color !default; $navbar-inverse-link-active-color: $btn-primary-color !default; $navbar-inverse-brand-color: $btn-primary-color !default; $navbar-inverse-toggle-icon-bar-bg: $btn-primary-color !default; $navbar-inverse-toggle-border-color: darken($brand-primary, 10%) !default; ``` Skip this when using an OOTB theme or when `$brand-primary` is not being overridden. ### Theme Guidelines - Always check for an existing theme first -- query the portal's `theme` field before any theme work - Never create a new theme when one already exists on the portal - Always reuse existing headers -- only create custom when explicitly requested - Header is mandatory for menu display ### OOTB Themes | Name | Sys ID | Description | | --------------------- | ---------------------------------- | ----------------------------------- | | Coral | `281507c44317d210ca4c1f425db8f2fd` | Coral color-scheme branding | | La Jolla | `a7a6e78277002300a6e592718a10617a` | Modern flat design | | Stock | `79315153cb33310000f8d856634c9c4b` | Default baseline theme | | Stock - High Contrast | `f84873986711320023c82e08f585ef6a` | Accessibility-compliant | | EC Theme | `9b6f06d71bb8f85047582171604bcb9c` | Employee Center default | | Portal Next Experience| `f548bd34845a1110f87767389929c667` | Next-gen portal (Polaris) | When no custom theme is needed, prefer Coral first, then La Jolla. Always verify existence on instance before referencing. ### Theme Example ```typescript fluent import "@servicenow/sdk/global"; import { SPTheme } from "@servicenow/sdk/core"; export const brandedTheme = SPTheme({ $id: Now.ID["branded_theme"], name: "Branded Theme", customCss: ` $brand-primary: sp-rgb(--now-color--primary-1, #0047ab) !default; $brand-primary-dark: darken(#0047ab, 12%) !default; $link-color: sp-rgb(--now-color--primary-1, #0047ab) !default; $body-bg: sp-rgb(--now-color_background--secondary, #f4f5f7) !default; $navbar-inverse-bg: $brand-primary !default; $navbar-inverse-border: darken($brand-primary, 6.5%) !default; $navbar-inverse-link-color: $btn-primary-color !default; $navbar-inverse-link-hover-color: $btn-primary-color !default; $navbar-inverse-link-active-color: $btn-primary-color !default; $navbar-inverse-brand-color: $btn-primary-color !default; $navbar-inverse-toggle-icon-bar-bg: $btn-primary-color !default; $navbar-inverse-toggle-border-color: darken($brand-primary, 10%) !default; `, header: "bf5ec2f2cb10120000f8d856634c9c0c", footer: "feb4f763df121200ba13a4836bf26320", logo: Now.attach("logo.png"), logoAltText: "Company Logo" }); ```