For a from-scratch native widget, see Going native at the end.

The Cool Clock — what we're working with

The OOB Service Portal widget has an id of widget-cool-clock and exactly two configurable options:

[
  { "name": "zone",    "default_value": "America/Los_Angeles",
    "section": "Data",         "label": "TimeZone",          "type": "string" },
  { "name": "c_color", "default_value": "red",
    "section": "Presentation", "label": "Second hand color", "type": "string" }
]

We are not going to rewrite Cool Clock. The whole point of this exercise is that we don't have to. The widget already exists, it already works in Service Portal, and the Service Portal Bridge will run it inside sn_aiux unchanged. All we're building is the sn_aiux adapter.

Step 1 — create the adapter

Navigate to /aiux/builder/widgets and click Create new widget.

• Custom element name (id): cool-clock-aix
• Widget name: Cool Clock
• Description: Bridges the OOB widget-cool-clock Service Portal widget into an sn_aiux experience.
• Category: custom

Set the Component field to:

import { html } from 'lit';
import { AIUXWidgetElement } from '@servicenow/aiux-components-core';

class CoolClockAix extends AIUXWidgetElement {
  static properties = {
    zone:    { type: String },
    c_color: { type: String },
  };

  createRenderRoot() { return this; }

  constructor() {
    super();
    this.zone = 'America/Los_Angeles';
    this.c_color = 'red';
  }

  render() {
    const options = {
      zone:    this.zone,
      c_color: this.c_color,
    };
    return html`
      <aiux-angular-element
        .widgetId=${'widget-cool-clock'}
        .options=${options}>
      </aiux-angular-element>`;
  }
}

Set the Input schema field to mirror the SP widget's options so the Builder UI surfaces them:

{
  "zone":    { "type": "String", "description": "TimeZone (e.g. America/Los_Angeles)" },
  "c_color": { "type": "String", "description": "Second hand color" }
}

Leave the Server script field as the empty IIFE. The original widget-cool-clock already has its own server script and the bridge will run it.

Step 2 — drop it on a page or preview it

Open a sys_aix_page in your experience and add a cool-clock-aix widget instance. Configure zone and c_color from the inline form.

Alternatively - just click the preview tab.

Step 3 — see it run

The Lit wrapper mounts. The framework spins up <aiux-angular-element>, which boots the embedded AngularJS Service Portal runtime inside the Lit DOM, looks up widget-cool-clock by its sp_widget.id, runs that widget's server script with the supplied options, and renders the existing template inside your sn_aiux page. The clock ticks. The second hand is the color you asked for. The timezone is the one you asked for. Nothing about the widget itself changed.

That's the whole pattern. One server script, written once. Twenty lines of Lit adapter. Zero rewrites for the actual widget logic. Multiply that by every widget in your existing portal and you can see why the bridge is a bigger deal than the rest of the framework combined.

For the mechanism in detail and the three OOB widgets that ship using this pattern, see Widgets → Service Portal Bridge.

Going native

The Cool Clock is the safe story — bring what you have, get it on the screen, ship. The other half of the pitch is what happens when you write a widget natively against sn_aiux. For that, build the $aiux showcase: a small Lit widget whose server script exercises each of the four documented methods on $aiux and renders the live return values with DaisyUI.

It exercises every layer in one component:

• Server script — calls $aiux.getParameter, $aiux.getPathParameter, $aiux.getSearchParameter, and $aiux.getWidget and packages the live results.
• Option schema — a couple of configurable inputs (the parameter name to probe, the widget id to compose).
• Lit + DaisyUI — composes <aiux-alert-message>, aiux-table, aiux-badge to render the results.
• client_tools — declares setProbeKey({ key }) so an AI agent can rerun the probes against a different parameter name.

The full source is in Widgets → AI Integration.

• sn_aiux_ia_config — AI Experience Framework Components for Now Assist Setup
• sn_aiux_builder — the Builder app itself, served at /aiux/builder/...

AI Experience Framework Builder - ServiceNow Store

ServiceNow App Store: AI Experience Framework Builder by ServiceNow - Widget creation and playground experience for ServiceNow AIX widgets

ServiceNow Store

• sn_aiux_components — the OOB widget library (Form, Catalog Item, Order Guide, Activity Stream, Breakout, etc.)

AI Experience Framework Components - ServiceNow Store

ServiceNow App Store: AI Experience Framework Components by ServiceNow - Common experience components for the AI Experience Framework

ServiceNow Store

All three must be installed and activated before any sys_aix_* records are addressable.

Verifying the install

Once the apps are present, the Application Navigator gets a new Application called AI Experience Framework (AIUX) with sub-modules for:

• Experiences sys_aix_experience
• Pages sys_aix_page
• Containers sys_aix_container
• Widgets sys_aix_widget
• Widget Instances sys_aix_widget_instance
• Widget Dependencies sys_aix_dependency
• Dashboards sys_aix_dashboard
• Menus sys_aix_menu
• Themes sys_aix_theme

Anyone who's spent time in the Service Portal application navigator will recognize the shape — it's deliberately the same. ServiceNow has clearly internalized that the path to adoption runs through familiarity, and it built the navigation accordingly.

You can also confirm the install by hitting the Builder directly: https://<your-instance>.service-now.com/aiux/builder/widgets. If you see the widget catalog, the framework is live.

If you install Employee Slate - you can hit this directly via: https://<your-instance>.service-now.com/aiux/employeeslate/home

Employee Slate Core - ServiceNow Store

ServiceNow App Store: Employee Slate Core by ServiceNow - The AI-native employee experience for any service, task, and approval.

ServiceNow Store

Permissions

The Builder UI requires the aix_widget_admin role to create or edit widgets, and aix_canvas_admin to edit dashboards. Plain admin is sufficient for both.

Earlier patches

sn_aiux is not present before Zurich Patch 9. The bundle (/sncapps/aix/assets/...), the sys_aix_* tables, and the /aiux/<suffix>/<page> URL pattern all rely on platform plumbing that arrived with Zurich P9. If you're on an earlier patch, the store apps will install but the runtime won't resolve.

What to do next

Try Your first widget — a walkthrough that takes a real out-of-the-box Service Portal widget and surfaces it inside an sn_aiux experience in roughly twenty lines of Lit.

(function(data, options, input) {
  // ...
})(data, options, input);

Same JavaScript, same gs.* / GlideRecord / GlideAggregate / GlideDateTime surface you've used for a decade. If you've written Service Portal server scripts, you already know 95% of what runs here. This page only covers the 5% that's new or worth re-stating in an sn_aiux context. For the full reference of standard server APIs, see Reference → Intellisense dump.

Server-script globals

Three globals are populated for you on every invocation:

Plus everything the platform exposes server-side:

$aiux — the AIUX scriptable

The widget server-script context. A pure-JavaScript scriptable, not a Rhino-bridged Java object — getClass() will fail, for...in returns nothing. Don't try to introspect it; the surface is enumerated here.

Four documented methods:

Choosing between the three getters

getParameter is the omnibus call — it walks experience → page → path → search → request and returns the first hit. Use it when you don't care which surface the value came from.

getPathParameter and getSearchParameter are the precise versions for when you do care. Example: sys_id could appear in both /record/incident/:sys_id and ?sys_id=.... If you need to distinguish, call the specific getter directly.

data.sys_id  = $aiux.getParameter('sys_id');           // first wins
data.path_id = $aiux.getPathParameter('sys_id');       // path only
data.query_id = $aiux.getSearchParameter('sys_id');    // query only

$aiux.getWidget — composition

$aiux.getWidget is the spiritual successor to Service Portal's $sp.getWidget. Calling it server-side returns the fully-populated data and properties of another sys_aix_widget. You pass options (the same shape the wrapped widget's input_schema declares), the framework executes that widget's server script, and you get its output back.

const childData = $aiux.getWidget('people-card', {
  user_sys_id: gs.getUserID(),
});
// childData = { properties: {...}, tagName: 'people-card' }

That return value powers two patterns:

• Render <${childData.tagName}> in your Lit template (with unsafeStatic) to embed the other widget.
• Use childData.properties to compose a custom UI that includes the other widget's data without rendering its template.

For the broader AI composition story see AI Integration.

The GlideSPScriptable sidecar pattern

The one piece of gs.* worth flagging specifically. When an AIUX widget needs a portal-scoped $sp context — for parameter-passing helpers, cart/catalog state, anything that historically required new GlideSPScriptable('portal_id') — bind it to the AIUX sidecar sp_portal record:

const AIUX_PORTAL_ID = "7cf6e70a3f123210860f2248001f8b63";  // sp_portal "aiuxsp"
var sp = new GlideSPScriptable(AIUX_PORTAL_ID);

The OOB Activity Stream widget does this verbatim. The sys_id is stable across instances — aiuxsp is the SP portal record that ships with the AIUX apps, and GlideSPScriptable bound to it gives you the same $sp.* surface you'd have inside a real Service Portal page.

This is the one place server-script code legitimately reaches into Service Portal infrastructure. See Experiences → Overview for the framework-level context.

Server → client data flow

Your server script populates data. On the client, the Lit widget reads it via this.data (provided automatically by AIUXWidgetElement):

// server script
(function(data, options, input) {
  data.user = { id: gs.getUserID(), name: gs.getUser().getDisplayName() };
})(data, options, input);

// component
render() {
  return html`<p>Hello, ${this.data?.user?.name}</p>`;
}

To re-run the server script (for refresh after an action, or to fetch with new options): this.server.refresh(). To send an explicit payload: this.server.get({ action: 'doThing', data: {...} }) — the server script receives the payload as input.

// server script handling an action
(function(data, options, input) {
  if (input && input.action === 'doThing') {
    // mutate via GlideRecord, populate data with the result
  }
})(data, options, input);

For the full this.server.* API see Component → Instance members.

What's not on this page

The standard server-side APIs — gs.*, GlideRecord, GlideQuery, GlideAggregate, GlideDateTime, GlideUser, GlideSession, attachments, encryption, schedules, table hierarchy, and the rest — work exactly as they do anywhere else on the platform. They're not framework-specific and they're not re-documented here.

If you need a quick lookup, the Intellisense reference has the full surface as a single searchable artifact, or the official ServiceNow docs are authoritative for behavior and edge cases.

Three of the nineteen out-of-the-box widgets are pure adapters around existing Angular Service Portal widgets, surfacing them inside an sn_aiux experience with no modifications to the underlying widget. The mechanism is a Lit custom element called <aiux-angular-element>, and the pattern it enables is the migration story for anything you've already built.

<aiux-angular-element>

A Lit element that, at mount time, bootstraps the embedded AngularJS Service Portal engine inside the Lit DOM, looks up an sp_widget by id, runs that widget's server script with the supplied options, and renders its Angular template inside the sn_aiux shell.

Usage from inside a sys_aix_widget Lit component:

render() {
  return html`
    <aiux-angular-element
      .widgetId=${'widget-form'}
      .options=${this.options}>
    </aiux-angular-element>`;
}

Two property bindings, both with the . prefix (Lit JS bindings, not HTML attributes):

How it works at runtime

When the Lit component mounts <aiux-angular-element>:

1. The framework spins up the embedded AngularJS Service Portal runtime inside the Lit DOM tree.
2. It looks up the sp_widget record by id.
3. It runs that widget's server script with options populated from .options.
4. It renders the widget's Angular template + client_script inside the shell.

The wrapped widget runs exactly as it does in Service Portal. $sp parameter passing works. gs.* and GlideRecord work. The widget's data object is populated by its own server script.

The three OOB bridge widgets

Here's the entire component for the Form widget — a complete, working bridge in twenty lines:

import { html } from 'lit';
import { AIUXWidgetElement } from '@servicenow/aiux-components-core';
import { locationService } from '@servicenow/aiux-services';

class FormWidget extends AIUXWidgetElement {
  createRenderRoot() { return this; }
  constructor() {
    super();
    const params = locationService.params();
    this.options = {
      table: params.table,
      sys_id: params.sys_id,
      hideRelatedLists: true,
    };
  }
  render() {
    return html`
      <aiux-angular-element
        .widgetId=${'widget-form'}
        .options=${this.options}>
      </aiux-angular-element>`;
  }
}

The Form widget's own server script is empty — there's nothing for it to do. All the work happens inside widget-form.

When to use the bridge

Use the bridge when:

• A complex Angular widget already exists and works. Catalog items, order guides, record forms, anything with cart logic, variable trees, or form-engine bindings.
• You want to ship an sn_aiux experience quickly without rewriting your widget library.
• You're migrating an existing Service Portal portal to sn_aiux and want the cutover to be invisible to end users.

Use native Lit when:

• You're building a new widget from scratch.
• The widget needs client_tools for AI agent integration (the bridge layer can't expose those on the embedded widget).
• The widget is presentational and doesn't need the Service Portal scriptable runtime.

The two coexist inside the same page. A typical real-world experience mixes native Lit widgets with bridged Service Portal widgets without anyone noticing the seam.

The theming sidecar

When you bridge a Service Portal widget into sn_aiux, the embedded Angular renderer needs a theme to style the widget with. That's where the sp_portal record with url_suffix aiuxsp comes in — it's a sidecar that carries the theme used to reskin embedded SP widgets so they render against Tailwind/DaisyUI tokens instead of looking like 2016-era Bootstrap dropped into a modern page.

sn_aiux itself does not run on Service Portal. The aiuxsp portal record only matters when SP widgets get bridged in. Pure-Lit sn_aiux widgets never touch it. See Experiences → Overview for the framework-level context.

Worked example

For a step-by-step walkthrough that takes the OOB Cool Clock Service Portal widget and surfaces it inside an sn_aiux page, see Getting Started → Your first widget.

Pick whichever fits the task. The web components give you semantics, accessibility, slotting, and configurable behavior in one tag. The utility classes give you fine-grained composition without writing CSS. Most real widgets use both.

Pre-built <aiux-*> components

All registered globally — just use the tag. Where a side-effect import is needed, it looks like import '@servicenow/aiux-components-core/aiux-alert-message'.

Attribute vs property: lowercase kebab-case names like is-modal are HTML attributes. Names prefixed with . (e.g. .items) are Lit JS property bindings — used when the value is a non-string (an array, object, etc.).

<aiux-accordion-group>

Collapsible sections with arrow or plus icons.

<aiux-alert-message>

Inline alert / banner.

<aiux-calendar-component>

Month-view calendar with selectable date.

<aiux-carousel-slider>

Slideshow with optional autoplay, dot indicators, and navigation buttons.

<aiux-dialog>

Modal or non-modal dialog with header, body, and footer slots.

<aiux-icon>

Inline icon rendered from the framework's icon library.

<aiux-live-region>

ARIA live region for accessibility announcements.

<aiux-loader>

Spinner / loading indicator.

<aiux-pagination-nav>

Page-number navigation control.

<aiux-tab-group>

Tabbed sections.

<aiux-toast-notification>

Stand-alone toast (the notifications service produces these — see Component → Services).

<aiux-time-selector>

12/24-hour time input.

DaisyUI utility classes

Tailwind plus DaisyUI is bundled with sn_aiux, with every class prefixed aiux-. Common ones you'll reach for:

• Cards: aiux-card, aiux-card-body, aiux-card-title, aiux-card-bordered, aiux-shadow-md
• Tables: aiux-table, aiux-table-zebra, aiux-table-sm
• Badges: aiux-badge, aiux-badge-primary, aiux-badge-outline, aiux-badge-ghost
• Buttons: aiux-btn, aiux-btn-primary, aiux-btn-dash, aiux-btn-ghost
• Alerts (utility variant): aiux-alert, aiux-alert-info, aiux-alert-error
• Modals (utility variant): aiux-modal, aiux-modal-open, aiux-modal-toggle
• Layout: aiux-bg-base-100, aiux-bg-base-200, aiux-divider, aiux-overflow-x-auto
• Typography: aiux-text-sm, aiux-text-xs, aiux-opacity-70, aiux-opacity-60
• Spacing: aiux-p-3, aiux-rounded

When in doubt, search the bundled CSS file (/sncapps/aix/assets/aiux-kit-*.css) for the class name you want — every DaisyUI utility ships with the aiux- prefix applied.

Picking between a component and a utility

• Use <aiux-alert-message> when you want a configurable, accessible, dismissible alert with a typed type attribute.
• Use aiux-alert aiux-alert-info classes when you just need a styled box around your own content.
• Use <aiux-dialog> when you want a real modal with focus trapping, escape handling, and a backdrop.
• Use aiux-modal utility classes when you want to style a custom overlay that doesn't behave like a true modal.

The pattern generalizes: pre-built component for behavior + accessibility, utility classes for composition.

• best_for — natural-language hint the AI agent reads to decide when to invoke the widget.
• client_tools — JSON manifest of UI actions the widget exposes to the agent at runtime.
• this.aiContext / setAiContext(ctx) — per-instance AI context the widget can write into.
• $aiux.getWidget(widgetId, options?) — server-side composition primitive that lets one widget pull another widget's fully-populated data, enabling widget orchestration.

This page covers each in turn.

best_for

A field on the sys_aix_widget record. It's a free-text description engineered for the agent's decision-making, not the developer's — written so an LLM reading the field list can match a user's intent to the right widget.

Example, from the OOB Activity Stream widget:

Displaying ticket or record activity history with comments, work notes, and attachments in a chronological timeline. Ideal for case management, incident tracking, and any record that needs a conversation-style activity feed with the ability to post new entries.

Write best_for the way you'd write a tool description for an agent prompt: be concrete about what the widget shows, what kind of records it works on, and when an agent should reach for it instead of something else.

client_tools

A JSON field on the widget record that declares a set of UI actions the widget exposes to AI agents. Each tool has a description (read by the LLM to decide whether to call it), an arguments schema, and a JS handler bound to the widget instance.

Example, from Activity Stream:

{
  "postComment": {
    "description": "[IMMEDIATE ACTION - UI CONTROL] Posts a comment to the activity stream. EXECUTE THIS TOOL when user wants to add a comment, note, or message to the ticket/record. This posts to the journal field (comments or work notes depending on configuration). Keywords: comment, post, add note, reply, respond, message.",
    "arguments": [
      { "name": "input", "type": "string", "description": "The comment text to post to the activity stream", "required": true }
    ]
  }
}

The widget's Lit class registers a matching static client_tools entry so the framework can dispatch the call into a real JS method when the agent fires it:

class ActivityStream extends AIUXWidgetElement {
  static client_tools = {
    postComment: {
      definition: ActivityStream.prototype.post,
      description: '[IMMEDIATE ACTION - UI CONTROL] Posts a comment to the activity stream. EXECUTE THIS TOOL when user wants to add a comment, note, or message to the ticket/record.',
      arguments: [
        { name: 'input', type: 'string', description: 'The comment text to post', required: true }
      ]
    }
  };
}

Description conventions

OOB widgets share a few writing patterns worth copying:

• [IMMEDIATE ACTION - UI CONTROL] prefix when the agent should call the tool eagerly, without confirmation.
• Keyword list at the end (Keywords: comment, post, add note, reply, respond, message.) — explicit triggers the LLM can match against user phrasing.
• EXECUTE THIS TOOL when ... — capitalized, imperative, action-trigger phrasing.

What OOB widgets expose

A non-exhaustive tour of client_tools declarations across the OOB library:

The Breakout Game is a deliberate teaching example — four tools that map cleanly to natural user requests ("reset the game", "pause the game", "what's the score?", "make it harder") and the implementation is small enough to read in one sitting.

this.aiContext and setAiContext(ctx)

Each widget instance gets an aiContext slot the framework reads when constructing agent prompts. Use this.setAiContext(ctx) to write a structured object describing the widget's current state.

firstUpdated() {
  this.setAiContext({
    record: { table: 'incident', sys_id: this.sysId },
    state: this.data?.state,
    assignee: this.data?.assignee?.display_value,
  });
}

When the agent has access to the widget, that context is part of the prompt — letting the LLM make better decisions about which client_tools to invoke and with what arguments. Update the context whenever the widget's state changes.

$aiux.getWidget — server-side composition

The composition primitive that Service Portal had as $sp.getWidget, preserved and renamed for the new framework. Inside a widget's server script:

const childData = $aiux.getWidget('people-card', {
  user_sys_id: gs.getUserID(),
});
// childData = { properties: {...}, tagName: 'people-card' }

$aiux.getWidget executes another widget's server script with the supplied options and returns its data and rendered properties. You can then either:

• Render the returned tagName directly in your Lit template, or
• Use the returned properties to compose a custom UI that includes the other widget's data without rendering its template.

This is how the AIUX equivalent of <sp-widget> works under the hood. It also lets agentic widgets orchestrate other widgets server-side without round-tripping through the client.

If you've never written Lit before, the official documentation is the canonical reference. The cheat sheet here is just the surface that ships in the sn_aiux bundle, with the import paths you'll actually need inside a widget.

Templating: html, css, svg

import { html, css, svg, nothing } from 'lit'

Use html inside render(), css inside static styles, and nothing as a conditional-render escape hatch:

render() {
  return html`
    <h2>${this.title}</h2>
    ${this.showDetails ? html`<p>${this.body}</p>` : nothing}
  `;
}

Standard directives

Each directive is imported from its own submodule. All return DirectiveResult and are interpolated into an html template the same way as values.

Example combining repeat and classMap:

import { repeat } from 'lit/directives/repeat.js';
import { classMap } from 'lit/directives/class-map.js';

render() {
  return html`
    <ul>
      ${repeat(this.items, item => item.sysId, item => html`
        <li class=${classMap({ active: item.sysId === this.selectedId })}>
          ${item.label}
        </li>`)}
    </ul>`;
}

ContextConsumer — read context state

import { ContextConsumer } from 'lit'

A ContextConsumer lets your widget read state published by another part of the tree. Combine with the Lit contexts the framework exposes — routeContext, experienceContext, etc.

new ContextConsumer(host, {
  context: routeContext,
  subscribe: true,
  callback: (value) => { /* called on every change */ },
})

Reactive properties

Declared via static properties on your class:

class MyWidget extends AIUXWidgetElement {
  static properties = {
    title:        { type: String  },
    count:        { type: Number  },
    enabled:      { type: Boolean },
    items:        { type: Array   },
    config:       { type: Object  },
  };
}

Any change to a declared property schedules a re-render. Use this.requestUpdate(name?, oldValue?) to force one manually.

Lifecycle (Lit-side)

The standard Lit lifecycle is available on every widget. For the AIUX-specific addition onDataChange, see Component.

For raw Lit (html, css, repeat, etc.) see the Lit page. For the pre-built <aiux-*> web components see Daisy. For the server side see Server Script.

Base classes

Imports from @servicenow/aiux-components-core.

Minimal widget skeleton:

import { html } from 'lit';
import { AIUXWidgetElement } from '@servicenow/aiux-components-core';

class MyWidget extends AIUXWidgetElement {
  static properties = {
    title: { type: String },
  };
  createRenderRoot() { return this; }
  render() {
    return html`<h2>${this.title}</h2>`;
  }
}

Instance members (this.*)

Available on any AIUXWidgetElement.

Lifecycle hooks

Static class members

class MyWidget extends AIUXWidgetElement {
  // Reactive properties — same as Lit
  static properties = {
    sysId: { type: String },
    count: { type: Number },
  };

  // Component-scoped CSS (alternative to the widget record's `style` field)
  static styles = css`
    :host { display: block; }
  `;

  // Inject framework services / directives
  static dependencies = { services: ['i18n', 'notifications'], directives: [] };
  // Shorthand for services-only:
  static dependencies = ['i18n', 'notifications'];

  // AI client tools — see the AI Integration section
  static client_tools = {
    refresh: {
      definition: function() { this.server.refresh(); },
      description: '[UI CONTROL] Reload the widget data.',
      arguments: [],
    },
  };
}

Services

Top-level singletons exported from @servicenow/aiux-services, @servicenow/aiux-utils, and @servicenow/aiux-context. Import the service name to use any of its methods.

i18n — translations

import { i18n } from '@servicenow/aiux-services'

notifications — toast notifications

import { notifications } from '@servicenow/aiux-services'

locationService — routing

import { locationService } from '@servicenow/aiux-services'

recordWatcherService — reactive GlideRecord

import { recordWatcherService } from '@servicenow/aiux-services'

themeService — dark/light mode

import { themeService } from '@servicenow/aiux-services'

mobileAppBridgeService — native mobile bridge

import { mobileAppBridgeService } from '@servicenow/aiux-services'

userPreferencesService — user preferences

import { userPreferencesService } from '@servicenow/aiux-services'

ariaLive — screen-reader announcements

import { ariaLive } from '@servicenow/aiux-services'

snHttp — HTTP client

import { snHttp } from '@servicenow/aiux-utils'

Standalone utilities

import { ... } from '@servicenow/aiux-utils'

Lit contexts

For use with ContextConsumer (see Lit) to read framework state.

import { ... } from '@servicenow/aiux-context'

Example:

import { ContextConsumer } from 'lit';
import { experienceContext } from '@servicenow/aiux-context';

class MyWidget extends AIUXWidgetElement {
  experienceCtx = new ContextConsumer(this, {
    context: experienceContext,
    subscribe: true,
    callback: (value) => { this.experience = value; this.requestUpdate(); },
  });
}

AIUX-specific directives

Lit directives specific to sn_aiux.

import { ... } from '@servicenow/aiux-directives'

This year I flew home from Knowledge and the contrast was loud. The buzzword was Employee Slate, the decks were beautiful, the demos were — in more than one case — static HTML files. Not early-build prototypes with a stubbed backend. Actual screenshotted UIs masquerading as working software. No sessions on how the framework underneath Slate worked. Nothing meaningful to cache. Same product-deck energy as Helsinki, none of the substance. The framework itself — which, spoiler, is called sn_aiux and is the actually interesting object here — is shipping right now on Zurich Patch 9, and it is, depending on how you count, the third time in a decade ServiceNow has reinvented its portal story. (If you don't count UI Builder, it's the second. ServiceNow's product marketing seems to be going with "second.") I figured I'd repeat the experiment: open the bundle on the plane, see how it works, write down what I found.

The short version: Employee Slate is one experience built on a new framework called sn_aiux. Not the framework itself. The framework is the interesting thing. It's a Lit.js + Tailwind + DaisyUI runtime with a deliberate bridge that embeds your existing Angular Service Portal widgets inside Lit components. There's a Service Portal record (sp_portal) sitting next to the framework as a sidecar — it carries the theme that reskins those embedded SP widgets so they don't look like 2016-era Bootstrap dropped into a Tailwind page — but sn_aiux is not running on Service Portal. Nothing you've already built has to be thrown away. New work happens in a stack that's much more familiar to anyone who's written modern web components in the last five years.

This post is the architectural map I wish ServiceNow had handed out.

Availability. sn_aiux ships on Zurich Patch 9. Three store apps must be installed: sn_aiux_ia_config, sn_aiux_builder, sn_aiux_components. 

AI Experience Framework Components - ServiceNow Store

ServiceNow App Store: AI Experience Framework Components by ServiceNow - Common experience components for the AI Experience Framework

ServiceNow Store

AI Experience Framework Builder - ServiceNow Store

ServiceNow App Store: AI Experience Framework Builder by ServiceNow - Widget creation and playground experience for ServiceNow AIX widgets

ServiceNow Store

The naming, untangled

Walking out of Knowledge, I assumed "Slate" was ServiceNow's new word for "portal" — the framework name, the way Service Portal was. It isn't. And to be fair, "Service Portal" wasn't really the framework name either, even though everyone used it that way. The framework called Service Portal shipped with a default portal also called Service Portal, mounted at /sp. That collision haunted every customer conversation for years. "Service Portal the framework, or Service Portal the portal? The one at /sp, or your portal?" It took ServiceNow several releases to ship Employee Center — a real branded employee intranet built on top — and only then did the naming start to separate. The framework was Service Portal. The portal was Employee Center.

sn_aiux is the same shape, told more clearly. The framework is sn_aiux in the codebase (written AIEX in marketing material — when you see /sncapps/aix/..., sys_aix_* tables, or <aiux-angular-element>, that's sn_aiux internals). Slate is the headline experience built on top, analogous to Employee Center — a real, branded, default landing destination. The mapping to what you already know:

• Service Portal is to sn_aiux what framework is to framework.
• An sp_portal record (Employee Center, ESS, whatever) is to a sys_aix_experience record (Slate, your custom landing experience, the Builder itself) what a portal is to an experience.
• Pages, widgets, themes — all the supporting concepts have direct equivalents.

The fact that ServiceNow led with the experience name at Knowledge and barely mentioned the framework is, at this point, a pattern.

Where experiences live

I didn't start by digging through Service Portal — but somewhere in the first hour I noticed an sp_portal record titled "AIUX Portal" (sys_id 7cf6e70a3f123210860f2248001f8b63, url_suffix aiuxsp) and felt a small wave of dread. ServiceNow has form for stuffing new technology into old tables and calling it modernization. If sn_aiux experiences were going to be sp_portal rows with extra columns and a Lit veneer, this was going to be a very different post.

Mercifully, they didn't. That sp_portal record isn't where sn_aiux experiences live, and it isn't a runtime host either. It's a sidecar. Its job is to carry the theme that re-skins embedded SP widgets when they get bridged into sn_aiux pages — so an Angular catalog widget renders against Tailwind/DaisyUI tokens instead of Bootstrap defaults — and to provide the portal-scoped $sp context for server scripts that ask for it. Hit /aiuxsp directly and you get a standard service portal homepage almost the same as where Helsinki left it. The actual experience records live in sys_aix_experience, addressable through a different config endpoint:

GET /api/now/aix/config/<url_suffix>
Accept: multipart/mixed

With aiuxsp as the suffix, that endpoint returns 400 "Experience not found" — confirming the sp_portal record isn't an experience. With builder as the suffix, it returns 200 and a full JSON payload describing the SN AIUX Builder experience: its sys_id, theme, telemetry config, landing path, and (interestingly) a list of URL rewrite rules. We'll come back to those.

The URL pattern for any sn_aiux experience comes straight from the bundle:

DEFAULT_PATTERN = new URLPattern({
  pathname: `/${vHostSiteName}/:experience/:page*`
});

vHostSiteName is the constant "aiux". Which means every experience URL is:

/aiux/<experience_url_suffix>/<page_path>

The Builder is at /aiux/builder/widgets.

Slate is at its own suffix. Build your own experience with url_suffix=esc and it's at /aiux/esc/.... Cleanly path-based, deep-linkable, no query strings involved. There is no ?experience= escape hatch — I checked, the entry servlet (/$ai_experience.do) returns byte-identical HTML for every query variation I threw at it. The experience comes from the URL pathname, full stop.

Employee Slate is at /aiux/employeeslate.

The schema in one paragraph

Twenty-nine sys_aix_* tables back the framework, all in the global scope.

Tables

Two inheritance signals are worth lingering on. sys_aix_widget extends sys_ux_widget — not sp_widget. That's structurally significant but not historically loaded: sys_ux_widget doesn't have meaningful tenancy outside sn_aiux today, so the inheritance is more about declaring family than joining an existing one. What's notable is what didn't come along for the ride: sn_aiux did not inherit UI Builder's metadata-in-tables philosophy. Your widget's component lives in a single component field as readable Lit source, not scattered across fifteen rows of sys_ux_* records you have to assemble in your head to understand what the thing does. Everyone who looked at UIB, tried to author a macroponent, and quietly closed the tab: this is your moment of vindication. The good idea from that lineage (modern web components) is here. The bad idea (the component as a relational graph) didn't make the trip.

The other inheritance worth noticing is sys_aix_notification_content_config extending sys_notification_content — joining the existing notification-content rows for Service Portal, Next Experience, Virtual Agent, and Workspace. sn_aiux is plugging into a shared platform-wide notification family rather than reimplementing one. Most other AIEX tables extend sys_metadata, so everything is update-set-capturable for promotion. Good news for migrations.

One concept sn_aiux did borrow from UI Builder that Service Portal never had: sys_aix_app_shell. It's a level above the experience — a chrome/header/navigation wrapper shared across multiple experiences. UIB has the same idea for its UX apps; Service Portal sort of expected you to handle it inside every portal's theme and header widgets. Having a dedicated record for it is the right call, especially if you're going to ship more than one experience under a single brand.

The Application Navigator menu reinforces all of this. Once the apps are installed, you get a fresh module called AI Experience Framework (AIUX) with sub-modules for Experiences, Pages, Containers, Widgets, Widget Instances, Widget Dependencies, Dashboards, Menus, and Themes.

Read that list back to yourself slowly. Anyone who's spent more than ten minutes inside the Service Portal application navigator should be having a strong sense of déjà vu. The shape of the framework is, very deliberately, the shape of the framework people already know. ServiceNow has clearly internalized that the path to adoption runs through familiarity, and it built the navigation accordingly.

The widget, in detail

A sys_aix_widget record looks a lot like an sp_widget record if you squint, with a few additions. Same id slug. Same name, description, style. The server script field uses the identical IIFE signature — (function(data, options, input) { ... })(data, options, input) — and inside that script you have the same gs.*, GlideRecord, GlideSPScriptable APIs you've always had. The Activity Stream widget literally instantiates new GlideSPScriptable("7cf6e70a3f..."), the same aiuxsp portal sys_id we found earlier. This is where the sidecar earns its keep: an sn_aiux widget that wants a portal-scoped $sp reaches into the SP record next door. Not every widget needs it — pure-Lit widgets ignore the sidecar entirely — but the option is there for the ones that do.

What's different is the component field. Instead of an Angular template plus a controller function, it holds a Lit.js web-component class:

import { html } from 'lit';
import { AIUXWidgetElement } from '@servicenow/aiux-components-core';

class MyWidget extends AIUXWidgetElement {
  static properties = { sysId: { type: String } };
  render() {
    return html`<div class="aiux-card">...</div>`;
  }
}

The styling system is Tailwind under DaisyUI, both bundled and prefixed under aiux-*. If you've ever written lit-html and reached for DaisyUI's card, btn, or modal semantic classes, you already know 90% of the surface area. The learning curve is real but short.

Two new fields show up that Service Portal never had. best_for is a natural-language description of when to use the widget — engineered for an AI agent to read and decide whether to invoke. client_tools is a JSON manifest of UI actions the widget exposes back to the agent. Activity Stream's client_tools declares a postComment tool whose description starts with [IMMEDIATE ACTION - UI CONTROL] and lists keyword triggers. It's a typed contract between the widget and the conversational layer.

The Service Portal bridge

The single most important architectural decision in sn_aiux is this: it doesn't replace sp_widget. It embeds it.

Three of the nineteen out-of-the-box widgets are pure adapters around existing Angular Service Portal widgets. The Form widget (form-widget) wraps widget-form. The Catalog Item widget wraps widget-sc-cat-item-v2. The Order Guide widget wraps widget-sc-order-guide-v2. The pattern is the same in all three: a few lines of Lit that read URL params, build an options object, and hand it off to a custom element called <aiux-angular-element>.

Here's the entire Form widget component 

import { html } from 'lit';
import { AIUXWidgetElement } from '@servicenow/aiux-components-core';
import { locationService } from '@servicenow/aiux-services';

class FormWidget extends AIUXWidgetElement {
  createRenderRoot() { return this; }
  constructor() {
    super();
    const params = locationService.params();
    this.options = {
      table: params.table,
      sys_id: params.sys_id,
      hideRelatedLists: true,
    };
  }
  render() {
    return html`
      <aiux-angular-element
        .widgetId=${'widget-form'}
        .options=${this.options}>
      </aiux-angular-element>`;
  }
}

That's it. <aiux-angular-element> is the runtime adapter. At mount time it bootstraps the embedded AngularJS Service Portal engine inside the Lit DOM, looks up widget-form by its sp_widget.id, runs that widget's server script with the supplied options, and renders its Angular template inside the modern shell. The Form widget's own server script is empty — there's nothing for it to do.

This is the migration story. Your Service Portal investment isn't deprecated. For any widget that already works — and especially the complex ones with cart logic, variable trees, form-engine bindings — you wrap it in twenty lines of Lit and ship it inside an sn_aiux experience. New work happens in pure Lit. The two live in the same page.

Porting a real widget: the Cool Clock

The bridge pattern is easier to internalize when you actually use it on something real, so let's pick a widget every long-time Service Portal developer has seen: Cool Clock (widget-cool-clock). It ships out of the box on every instance — an analog clock face with a configurable timezone and a configurable color for the second hand. Its option_schema is exactly two fields:

[
  {
    "name": "zone",
    "default_value": "America/Los_Angeles",
    "section": "Data",
    "label": "TimeZone",
    "type": "string"
  },
  {
    "name": "c_color",
    "default_value": "red",
    "section": "Presentation",
    "label": "Second hand color",
    "type": "string"
  }
]

We are not going to rewrite Cool Clock. The whole point of the exercise is that we don't have to. The widget already exists, it already works in Service Portal, and <aiux-angular-element> will run it unchanged. All we're building is the sn_aiux adapter.

Open /aiux/builder/widgets and create a new sys_aix_widget:

• Custom element name (id): cool-clock-aix
• Widget name: Cool Clock
• Description: Bridges the OOB widget-cool-clock Service Portal widget into an sn_aiux experience.

Set the component field to:

import { html } from 'lit';
import { AIUXWidgetElement } from '@servicenow/aiux-components-core';

class CoolClockAix extends AIUXWidgetElement {
  static properties = {
    zone:    { type: String },
    c_color: { type: String },
  };

  createRenderRoot() { return this; }

  constructor() {
    super();
    this.zone = 'America/Los_Angeles';
    this.c_color = 'red';
  }

  render() {
    const options = {
      zone:    this.zone,
      c_color: this.c_color,
    };
    return html`
      <aiux-angular-element
        .widgetId=${'widget-cool-clock'}
        .options=${options}>
      </aiux-angular-element>`;
  }
}

Set the input_schema to mirror the SP widget's options so the Builder UI can configure them:

{
  "zone":    { "type": "String", "description": "TimeZone (e.g. America/Los_Angeles)" },
  "c_color": { "type": "String", "description": "Second hand color" }
}

Leave the server script field as the empty IIFE. The original widget-cool-clock already has its own server script and the bridge will run it.

Drop cool-clock-aix onto a sys_aix_page, set zone and c_color from the inline configuration, and reload. The Lit wrapper mounts. <aiux-angular-element> boots the embedded Angular runtime. The runtime looks up widget-cool-clock by its sp_widget.id, runs its server script with options = { zone, c_color }, and renders the existing template inside your sn_aiux page. The clock ticks. The second hand is the color you asked for. The timezone is the one you asked for. Nothing about the widget itself changed.

That's the whole pattern. A widget that has shipped on every Service Portal instance for the better part of a decade now runs inside sn_aiux with zero modifications and roughly twenty-five lines of Lit. Multiply that by every widget in your existing portal and you can start to see why the bridge is a bigger deal than the rest of the framework combined.

The migration tax, in theory

The config payload from /api/now/aix/config/builder includes an array I almost skipped past on first read. It looks like this:

{ "source_type": "portal_page", "portal_page": "kb_article",
  "parameter_mapping": { "sys_id": "sys_id" },
  "to_aiux_page": "/knowledge/:sys_id" },

{ "source_type": "processor", "processor": "kb_view.do",
  "parameter_mapping": { "sys_kb_id": "article_id" },
  "to_aiux_page": "/knowledge/:article_id" },

{ "source_type": "processor", "processor": "sc_cat_item.do",
  "parameter_mapping": { "sys_id": "item_id" },
  "to_aiux_page": "/catalog/:item_id" }

These records live in sys_aix_url_rewrite_rule. Two source_type values appear in the OOB data: portal_page (a hit on a Service Portal sp_page) and processor (a hit on a legacy .do processor URL). The intent is clear: intercept incoming legacy URLs and translate them into the equivalent sn_aiux paths so existing deep links — kb_view.do?sys_kb_id=XYZ, sc_cat_item.do?sys_id=ABC, a custom processor someone wrote years ago — keep resolving after you switch an experience over.

That's the intent. I want to be honest that I haven't fully confirmed it's working end-to-end yet. The table is present, the rule shape is sensible, the config endpoint returns the rules — but the actual rewriter component that consumes them is somewhere I haven't traced, and I haven't tested a clean cutover with a legacy URL coming in from email. File this one under "promising mechanism, verify before you bet a rollout on it." Worth keeping a close eye on the table, the relevant sys_aix_url_rewrite_rule records, and the rewrite behavior under the network panel before you tell stakeholders the old links will just work.

The 404 page is a Breakout game (again)

Anyone who spent enough time poking at the default /sp portal back in the day knows that the Service Portal 404 page also rendered a Breakout game. It was a tiny piece of personality buried in sp_page and the matching widget, and most customers stripped it out before going to production. sn_aiux brings it back, and this is the homage I didn't know I needed.

Navigate to /aiux/builder (no page path) and the experience tries to land on /home. There is no page in sys_aix_page with path_pattern: /home for the Builder experience, so the router falls through to the 404 page (/not-found). The 404 page embeds a widget called breakout-game, which is a fully implemented, fully playable clone of Atari Breakout — scoreboard, lives counter, paddle, the works (02-builder-home-404-breakout.png, page-12-breakout-editor-preview.png).

It's also a real widget in sys_aix_widget, with a real description that gives the new joke away: "Demonstrating client tools functionality and interactive widget capabilities. A fun example widget that showcases how AI agents can interact with widgets through client tools." The Breakout widget exposes four client_tools — reset-game, pause-game, get-game-state, set-difficulty — so on top of being a nostalgic callback, the 404 page is now doing double duty as the framework's onboarding demo for the agent-widget interaction model.

I respect the continuity. A small thing, but it tells you where the framework's center of gravity is: every page is a widget composition, including the system's own error states, and every widget that can be configured can also be driven by an AI. And ten years later, someone at ServiceNow still thinks the right easter egg is Breakout.

What I took away

After two and a half hours and some altitude, the picture that settled out is this. sn_aiux is ServiceNow's third swing at the portal problem in ten years — though, again, the official scoreboard reads "second." What's striking is how deliberately it leans back into the parts of Service Portal that worked and that customers built a mountain of stuff on. The server-script model is unchanged. gs.*, GlideRecord, GlideSPScriptable all behave the way they always have. The widget unit-of-authoring — a record with a server script, a template, a stylesheet, an option schema — is the same shape, just modernized underneath. Angular-1 templates become Lit web components. Bootstrap CSS becomes Tailwind/DaisyUI. The application-navigator menu is, structurally, the Service Portal menu re-photographed. None of that is accidental.

It's also a very ServiceNow move in the bigger sense. The platform has a long-running habit of bringing the old thing along while embracing the new one — Update Sets that survived a dozen rewrites, scoped applications grafted onto a global-scope foundation, Flow Designer running alongside Workflow Editor for years. sn_aiux fits the pattern. Your existing sp_widget library isn't deprecated; it's wrapped. Your sys_metadata extensions promote the same way they always did. The bridge layer (<aiux-angular-element>) is a first-class runtime feature, not a forgotten compatibility shim, and that single decision is what makes adoption a non-decision rather than a project.

If sn_aiux had told everyone rebuild your widgets, adoption would have stalled the way Now Experience adoption did. Instead, ServiceNow let you keep every Angular widget you've ever written and surface it in the new world with twenty lines of glue. The framework is compelling enough on its own merits — the AI surface, the URL routing, the Builder UX — but the bridge is what makes "should we" stop being the interesting question.

The thing I'd do first, if I were starting a real project on this: pick one Service Portal page that gets a lot of traffic, stand up a new sys_aix_experience, wrap the existing widgets with the Cool Clock pattern, populate sys_aix_url_rewrite_rule so the old URLs should continue to work (and verify they actually do), and ship. Iterate from there.

One closing ask of ServiceNow, while I'm here. Lit, Tailwind, and DaisyUI are genuinely good choices. Lit ships releases a couple of times a year. Tailwind ships breaking changes. DaisyUI is already on v5. Please keep this stack current. Service Portal sat on AngularJS for ten years past the point Google started telling people to migrate. If the next time someone has to write a post like this is Knowledge 2036 because the framework underneath has fossilized again, the migration calculus is going to look very different. Pick a refresh cadence that's shorter than the lifespan of a Toyota Corolla.

Ten years on, I still think the framework rewards curiosity. The plane ride home from Knowledge has become a tradition. I'd like to keep it.

References

• The runtime bundle: /sncapps/aix/assets/index-D24AXy2E.js (~2.4 MB — contains the URL pattern, route context, experience loader, and DaisyUI styles)
• The experience config endpoint: GET /api/now/aix/config/<url_suffix> (Accept: multipart/mixed)
• The 29-table list: sys_db_object_list.do?sysparm_query=nameSTARTSWITHsys_aix
• Five tables to read first: sys_aix_experience, sys_aix_page, sys_aix_widget, sys_aix_widget_instance, sys_aix_url_rewrite_rule
• The OOB widget to read first: Form (form-widget) — the canonical SP-bridge pattern in twenty lines

The Problem Every Partner Knows

If you're a ServiceNow partner, you've probably had this experience: you're trying to figure out what certifications your team needs to earn a specific Product Line Achievement, or what's actually in a Suite Certification, and you end up in a maze of clicks on the Now Learning portal that never quite gives you a straight answer.

"Suite Certification — CSM Professional." Great. What does that require? Click. Click. Click. Scroll. Open a new tab. Cross-reference with the partner guide PDF from last quarter. Wonder if it's been updated. Give up and Slack someone who already figured it out.

It shouldn't be this hard.

What We Were Trying to Do

At Semaphore, we're a Specialist partner. We're always thinking about our certification strategy — which certs unlock which PLAs, where the overlap is, and where we can get the most coverage with the least duplication of effort across our team.

The problem is that ServiceNow's certification data is fragmented across multiple places. The Now Learning portal shows individual achievements, but it doesn't give you a clean view of the hierarchy — which suite certifications are composed of which underlying certs, which of those underlying certs are themselves suite certifications (yes, they nest), and which individual micro-certs or CIS exams are shared across multiple suites.

That last part is the real strategic question. If a single CIS exam is required by eight different suite certifications, that's a high-leverage cert to push your team toward. But you can't see that from the portal UI.

What the Data Reveals

There are currently 30 active Suite Certifications in the partner program, requiring a combined pool of about 50 unique individual achievements (CIS exams, Micro-Certifications, Accreditations, and the CSA). That's around 115 total requirement connections.

A few things jumped out immediately.

The hierarchy goes deeper than you'd expect. The ITOM stack chains four levels deep:

• ITOM AIOps Enterprise Plus requires
  • ITOM AIOps Enterprise, which requires
    • ITOM AIOps Pro, which requires
      • ITOM Visibility — which itself requires
        • CIS-Discovery
        • CIS-Service Mapping
        • Agent Client Collector accreditation.

If you're planning your ITOM certification path, you need to understand this full chain, not just the top-level suite.

Shared requirements are everywhere — and they're strategic.

The CIS – Customer Service Management certification is required by eight different suites:

1. CSM Professional
2. FSO Banking
3. FSO Insurance
4. Healthcare & Life Sciences
5. Public Sector Digital Services
6. Retail
7. TMT Service Management
8. Order Management.

If you have a consultant with CIS-CSM, they're one or two additional certs away from any of those suites.

Similarly, the trio of MC - Predictive Intelligence, MC - Performance Analytics, and MC - Virtual Agent shows up in the majority of Professional-tier suites. Get those three done and you've covered a massive chunk of the suite map.

The Now Assist suites are thin wrappers. Each Now Assist Pro Plus suite (ITSM, CSM, HRSD) requires only two things: the corresponding Professional suite certification plus a Now Assist delivery accreditation. That's it. The Professional suite does the heavy lifting underneath.

The CSA is the operational gateway. Six suites require the Certified System Administrator: Workflow Data Fabric, Workplace Service Delivery, Legal Service Delivery, Supplier Lifecycle, Sourcing & Procurement, and Accounts Payable. For any consultant working in those areas, the CSA is table stakes.

We Built an Interactive Tool

Staring at JSON and spreadsheets only gets you so far. We wanted a way to actually see the relationships — which certs feed into which suites, where the overlaps are, and which achievements give you the most bang for your buck.

So we built an interactive dependency wheel that visualizes the entire suite certification hierarchy: https://certifications.semaphorepartners.com/

Each arc around the wheel represents a certification, sized proportionally to the number of requirements it has or the number of suites that require it. Tap any arc to highlight its connections — blue lines show what it requires, orange lines show what requires it. The center displays the selected cert with its connection counts.

The color coding makes the structure immediately visible: blue for suite certifications, orange for CIS exams, green for micro-certifications, purple for accreditations, and teal for the CSA.

Why This Matters for Partners

This isn't just an academic exercise. For a boutique firm like ours, every certification investment has to be deliberate. Training hours cost real money, and we need to be strategic about which certs we pursue and who we assign them to.

Here's what this analysis told us about prioritization:

Highest leverage CIS exam: CIS-CSM, by a wide margin. Eight suites. No other CIS exam comes close.

Highest leverage micro-certs: The Predictive Intelligence / Performance Analytics / Virtual Agent trio. They're shared across all the Professional-tier suites.

Most technically demanding micro-cert: Integration Hub. Required by seven operational suites plus Workflow Data Fabric. It's also the one that actually tests your ability to build integrations — scripted REST, Flow Designer actions, IntegrationHub spokes.

Best entry point: CSA. It's the prerequisite for six suites and is functionally the entry ticket to the certification ecosystem.

What's Next

If there's enough interest in this, we're planning to extend the tool to map certifications directly to Product Line Achievements — so you can answer the question "what does my team need to earn PLA in ITSM?" in one click instead of cross-referencing three different documents.

We've also added direct links to each achievement on the Now Learning portal, so the tool becomes a practical navigation layer on top of ServiceNow's own certification platform.

If you're a ServiceNow partner struggling with the same certification planning challenges, or if you just want to play with the interactive visualization, we'd love to hear from you. Drop us a line or check out the tool here: https://certifications.semaphorepartners.com/.

Semaphore Partners is a boutique ServiceNow consulting firm specializing in ITSM, HRSD, CSM, SPM, and custom integrations. We're a 2026 ServiceNow Partner of the Year — Rising Star Americas recipient with a 5.0 CSAT rating. Learn more at semaphorepartners.com.

The first instinct is to check the mapping. In Integration Hub ETL ($cmdb_integration_studio.do), the Assigned To field was configured correctly: a User Lookup transform using u_userdisplayname as the User Name and u_userprincipalname as the Email, outputting to assigned_to_user. Nothing wrong there.

So the problem must have been upstream. We opened Workflow Studio and looked at the mobiledevices Data Stream action. The Script Parser step (step 4) showed exactly what was being pulled from the Intune API response:

outputs.targetObject.userId = record.userId;
outputs.targetObject.userDisplayName = record.userDisplayName;
outputs.targetObject.userPrincipalName = record.userPrincipalName;

Worth noting: the Service Graph Connector documentation doesn't explicitly tell you which fields are being used in the mapping. Knowing to look here, and knowing what to look for, comes from understanding how the ETL pipeline works end to end. The connector is a black box until you know where to crack it open.

When we checked the import set table (sn_intune_integrat_devices), the picture became clear. The userId field was populating, the Microsoft GUID for the user was coming through, but userDisplayName and userPrincipalName were both blank. This is a pattern we've seen before in ServiceNow: an account can resolve a record's GUID because it has basic read access to the object, but can't retrieve dot-walked attributes because it lacks permission on the related resource. In other words, the ID comes through; the human-readable fields don't.

Our hypothesis was an OAuth permissions gap. When we checked the Microsoft Graph API documentation for the managed device endpoint, it only lists two required permissions:

• DeviceManagementManagedDevices.Read.All
• DeviceManagementManagedDevices.ReadWrite.All

No mention of user permissions. If you stop there, you'd think you were covered. But the ServiceNow documentation for configuring the Intune Service Graph Connector specifies a third permission that the App Registration needs:

• DeviceManagementManagedDevices.Read.All (Application)
• DeviceManagementApps.Read.All (Application)
• User.Read.All (Application)

That last one was missing. Without User.Read.All, the Graph API returns the device record with the user's object ID intact but won't expand any user attributes. No error, no warning, just silently empty fields.

Once we added User.Read.All to the App Registration in the Microsoft portal and triggered a fresh sync, userDisplayName and userPrincipalName started populating in the import set table, the User Lookup transform fired correctly, and Assigned To resolved properly on the CMDB records. Problem solved.

If you're seeing the same thing, devices syncing but Assigned To is still blank, skip straight to your Azure App Registration and verify all three permissions are present. The Microsoft docs alone won't get you there.

For example, if you have many catalog items with a shipping address section, you could create a single, configurable widget for a typeahead address input with API validation. A widget like that could greatly improve both the user experience and the quality of the provided address data. Additionally, if built correctly, adding in the upgraded, custom input to a form can be as easy as adding one new variable record without requiring any changes to the existing form logic.

In this post, I'll walk through three examples of reusable catalog item widgets which cover what I consider to be the most effective patterns and the most common use-cases. For each example, I've included screenshots and the code for the widget. Additionally, if you want to see the widgets in action, you can download Reusable Custom Widgets for Catalog Items from ServiceNow Share where I've added these widgets to an example catalog item.

Example 1: Loading Indicators

Screenshot HTML Client Script CSS

<div id="supernow-loading-field" class="sp-loading-indicator" ng-class="'v'+widget.sys_id" style="display: none;">
  <div></div>
  <div></div>
  <div></div>
</div>

<div id="supernow-loading-block-skeleton" ng-class="'v'+widget.sys_id" style="display: none">
  <div class="supernow-loading-block-skeleton">
    <div class="loading card-title shorter-s"></div>
    <div class="loading table-content"></div>
    <div class="loading card-title shorter-m"></div>
    <div class="loading table-content"></div>
    <div class="loading card-title shorter-xs"></div>
    <div class="loading table-content"></div>
  </div>
</div>

<div id="supernow-loading-block-loader" ng-class="'v'+widget.sys_id" style="display: none">
    <div class="supernow-mug-container">
      <div class="supernow-mug">
        <div class="supernow-coffee"></div>
      </div>
      <span class="loader-text">
        Loading . . .
      </span>
    </div>
</div>

<div id="supernow-loading-overlay" ng-class="'v'+widget.sys_id" style="display: none">
  <div id="supernow-loading-overlay-inner">
    <div class="supernow-mug-container">
      <div class="supernow-mug">
        <div class="supernow-coffee"></div>
      </div>
      <span id="supernow-loading-overlay-text" class="loader-text">
        Loading . . .
      </span>
    </div>
  </div>
</div>

<style>
  #catItemTop > * {
    position: relative;
  }
</style>

api.controller=function($scope, $rootScope) {
	var c = this;
	c.activeLoaders = {};
	c.madeReadOnlyFields = {};
	c.movedOverlay = false;

	/*
		PROPERTIES:
		type
			Description: the type of loader to show (small loading icon next to a field's label, a placeholder loader to indicate field will soon be shown in that area, a loader showing below a field on the form along with loading text, or a whole-form overlay loader that will prevent interacting with the form while loading)
			Value: "field", "block-skeleton", "block-loader", or "overlay"
			Default: "overlay"
		action
			Description: whether to hide or show the loader specified
			Value: "show" or "hide"
			Default: "show" (unless a matching loader already exists and is displayed)
			Applies for type: All
		text: 
			Description: the text to show below the loading animation
			Value: any string
			Default: "Loading . . ."
			Applies for type: "block-loader" and "overlay"
		field:
			Description: the field to attach the loader to or below
			Value: the name of any variable in the catalog item
			Default: the variable embedding this widget
			Applies for type: "field", "block-skeleton", and "block-loader"
		disableField:
			Description: whether the corresponding field should be made read-only while loading
			Value: true or false
			Default: true
			Applies for type: "field", "block-skeleton", and "block-loader"
			
		EXAMPLES:
		{"type": "field", "field": "test", "disableField": false}
		{"type": "block-loader", "field": "test", "action": "show"}
		{"text": "Loading form data . . . ""}
	*/
	var fieldChangeListener = $rootScope.$on("field.change."+$scope.page.field.name, function(evt, parms) {
		if(parms.newValue){
			try{
				var val = JSON.parse(parms.newValue);
				var show = true;
				var el;
				var textElement;
				if(val.type == 'field' || val.type == 'block-skeleton' || val.type == 'block-loader'){
					if(!val.field) val.field = $scope.page.field.name;
					el = document.getElementById("supernow-loading-"+val.type+"-"+val.field);
					if(val.hasOwnProperty('action')){
						show = val.action == 'show';
					}else if(el){
						show = el.style.display == 'none';
					}
					if(show){
						if(!el){
							var p = document.getElementById("supernow-loading-"+val.type);
							el = p.cloneNode(true);
							el.id = "supernow-loading-"+val.type+"-"+val.field;
							var fieldLabel = val.type == 'field' ? $('#'+val.field+' label.field-label')[0] : $('#'+val.field+':has(.form-group)')[0];
							fieldLabel.appendChild(el);
						}
						if(val.type == 'block-loader'){
							textElement = $('#supernow-loading-block-loader-'+val.field+' .loader-text')[0];
							textElement.innerHTML = val.text ? val.text : 'Loading . . .';
						}
						el.style.display = val.type == 'field' ? 'inline-flex' : 'block';
						if(!val.hasOwnProperty('disableField') || val.disableField === true || val.disableField === 'true'){
							if(!$scope.page.g_form.isReadOnly(val.field)){
								c.madeReadOnlyFields[val.field] = true;
								$scope.page.g_form.setReadOnly(val.field, true);
							}
						}
						c.activeLoaders[val.type+'-'+val.field] = true;
					}else{
						el.style.display = 'none';
						if(val.type == 'block-loader'){
							textElement = $('#supernow-loading-block-loader-'+val.field+' .loader-text')[0];
							textElement.innerHTML = '';	
						} 
						if(c.madeReadOnlyFields.hasOwnProperty(val.field)){
							delete c.madeReadOnlyFields[val.field];
							$scope.page.g_form.setReadOnly(val.field, false);
						}
						delete c.activeLoaders[val.type+'-'+val.field];
					}
				}else{
					el = document.getElementById('supernow-loading-overlay');
					textElement = document.getElementById('supernow-loading-overlay-text');
					if(val.hasOwnProperty('action')){
						show = val.action == 'show';
					}else if(el){
						show = el.style.display == 'none';
					}
					if(show){
						if(!c.movedOverlay){
							var catItem = document.getElementById('catalog-form');
							catItem.appendChild(el);
						}
						textElement.innerHTML = val.text ? val.text : 'Loading . . .';
						el.style.display = 'block';
						c.activeLoaders.overlay = true;
					}else{
						el.style.display = 'none';
						textElement.innerHTML = '';
						delete c.activeLoaders.overlay;
					}
				}
			}catch(e){
				console.log('Could not set a loading indicator using the value: '+parms.newValue+'\n\nEnsure that the value you are setting is valid JSON with double quotes around both property names and string values');
			}
			$scope.page.g_form.clearValue($scope.page.field.name);
		}
	});
	$scope.$on("$destroy", fieldChangeListener);

	$scope.page.g_form.$private.events.on('onSubmit', function(){
		if(Object.keys(c.activeLoaders).length){
			$scope.page.g_form.addErrorMessage('Please wait for the form to finish loading');
			return false;
		}
	});	
};

/* block-skeleton */
.supernow-loading-block-skeleton .card-title.loading {
  margin-bottom: 5px;
  height: 14px;
}
.supernow-loading-block-skeleton .card-title.loading.shorter-s{
  width: 25%;
}
.supernow-loading-block-skeleton .card-title.loading.shorter-m{
  margin-top: 21px;
  width: 30%;
}
.supernow-loading-block-skeleton .card-title.loading.shorter-xs{
  margin-top: 21px;
  width: 20%;
}
.supernow-loading-block-skeleton .loading {
  position: relative;
  background-color: #f1f1f1;
  overflow: hidden;
}
.supernow-loading-block-skeleton .table-content.loading {
  border-radius: 4px;
  height: 34px;
  width: 100%;
}
.supernow-loading-block-skeleton .loading::after {
  content: "";
  position: absolute;
  animation: 2s supernow-block-loading linear 0.5s infinite;
  background: linear-gradient(90deg, transparent, #e6e6e6, transparent);
  bottom: 0;
  left: 0;
  right: 0;
  top: 0;
}
@keyframes supernow-block-loading {
  0% {
    transform: translateX(-100%);
  }
  60% {
    transform: translateX(100%);
  }
  100% {
    transform: translateX(100%);
  }
}
/* overlay */ 
#supernow-loading-overlay-inner {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 19;
  background-color: rgba(0, 0, 0, 0.1);
  backdrop-filter: blur(2px);
}
/* coffee mug for overlay and block-loader */
.supernow-mug {
  width: 40px;
  height: 45px;
  display: inline-block;
  position: relative;
  border: 4px solid #206AAA;
  animation: fill 2s linear infinite alternate;
  color: rgba(#a05425, 0.9);
  border-radius: 0 0 4px 4px;
  z-index: 5;
  &::after {
    content: '';
    position: absolute;
    left: 100%;
    top: 50%;
    transform: translateY(-50%);
    border: 4px solid #206AAA;
    width: 20px;
    height: 25px;
    border-radius: 0 8px 8px 0;
  }
}
.supernow-coffee{
  position: absolute;
  left: 2px;
  right: 2px;
  bottom: 2px;
  margin: 2px;
  background: #a05425;
  border-radius: 0 0 6px 6px;
  animation: supernow-coffee 4s ease-in-out infinite alternate-reverse;
}
@keyframes supernow-coffee {
  from {
    top: calc(100% - 35px);
  }
  to {
    top: calc(100% - 7px);
  }
}
.supernow-mug-container .loader-text {
  font-size: 1.3em;
  font-weight: 600;
  color: #206AAA;
  margin-top: 15px;
}
.supernow-mug-container .loader-text {
  color: #002677;
}
.supernow-mug-container{
  display: flex;
  height: 100%;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

This example widget doesn't capture any user input; instead, catalog client scripts can trigger it to show various loading indicators on the form. One example where a widget like this would be useful is if a form includes a slow-running script or API call. In that scenario, you could see issues from the user modifying the values of other variables while the GlideAjax is still running and the data returned from the GlideAjax might no longer be relevant when it finally hits the callback. This widget allows you to make the loading more prominent or use an overlay to prevent user interaction with the form until loading completes.

1. How to create the variable for embedding the widget

To add a widget to a form, you need a variable with:

1. A Type value of Custom, Custom with Label, or Single Line Text.
2. A widget referenced in the Widget (sp_widget) field and/or a value in the Default Value field like {widget: 'supernow-loading-indicators'}.
   1. If using Single Line Text, the Widget field must have a value.
   2. If both are specified and are different, the widget specified in the default value is used.

For this example, we don't want the widget variable itself to display or take up any space on the form. So, we use the Type "Custom" to not have a label included and we check the "Hidden" checkbox for the variable.

2. How to trigger the widget from a client script

The easiest way to communicate to and from a widget is to set values on the form and listen for those changes.

An embedded widget comes with built-in access to g_form through $scope.page.g_form (don't forget to inject $scope into your controller), which makes it easy to set values from the widget. To set up the widget to listen for changes to a variable's value, the most straightforward option is to inject $rootScope into the controller and set up a listener for the event name "field.change". The function attached to that listener will trigger on any variable's value changing, but if you want to listen just for changes to a specific variable, append that variable name to the event name like "field.change.variable_name".

In this example, a client script triggers the widget by setting the value of the variable that embeds the widget. So, it has a watcher like this:

var fieldChangeListener = $rootScope.$on("field.change."+$scope.page.field.name, function(evt, parms) {
   [ . . . ]
});
$scope.$on("$destroy", fieldChangeListener);

Notes:

1. The widget can access the name of the variable it is embedded in by using $scope.page.field.name.
2. The changed variable's value is in the "newValue" property of the second parameter.
3. Important: when setting a watcher on $rootScope, ensure that you clear that watcher when the current scope is destroyed (as shown in the example above)

This example expects a client script to set its variable's value to be an object containing the details of the loading indicator to be shown. The listener clears out the value of its variable so that the value set is treated like a "message", rather than maintaining the state of the loaders in the variable value itself.

3. How to add elements elsewhere in the form

In this example, we want to add loading indicators elsewhere in the form and not be limited to just displaying where the widget's variable is placed. It's easy to use JavaScript to clone, move, or create elements. However, be aware that moving an element preserves its AngularJS linkages to the controller, but cloning or creating an element does not. In this example, that distinction isn't important. However, if the loading elements needed access to the controller scope, you could use an ng-repeat to generate as many elements as needed and move those, instead of cloning and moving.

One other important thing to note is that all the selectors defined in the widget's CSS field will have a class selector of "v" plus the widget's sys_id prepended. This means that elements you move or create outside of the widget's element won't have the widget's CSS applied. For this example, this issue was avoided by manually appending a matching class to each element moved outside the widget and also just defining simple styling inline in the HTML. Alternatively, you could create a <style> element in the HTML or add your styling to a portal-wide stylesheet, but with that approach it's important to keep your selectors very specific as those selectors will apply to the whole page or portal respectively.

4. How to handle onSubmit validation

If your widget needs to perform some validation onSubmit, the officially recommended option would be to keep some hidden variable on the form up to date with whatever data is relevant for the onSubmit check (setting the value of that variable in the widget using $scope.page.g_form.setValue). This allows you to use a normal onSubmit catalog client script to perform validation using the data stored in the hidden variable.

However, that approach makes your reusable widget less "plug and play", as you'll need to add onSubmit client script logic to every form where your widget is included. So, in this example, we use an undocumented g_form event listener with the code: $scope.page.g_form.$private.events.on('onSubmit', function(){ [ . . . ] });. The specified function will work the same as an onSubmit client script, allowing you to block submission using return false;—except in this function you can access all the data from your widget's scope.

Example 2: Time Picker

Screenshot HTML Client Script

<div uib-timepicker 
     ng-model="c.selectedTime" 
     ng-change="c.storeValue()" 
     ng-disabled="page.field.isReadonly()"
     hour-step="options.hourStep" 
     minute-step="options.minuteStep" 
     show-seconds="options.showSeconds" 
     second-step="options.secondStep" 
     show-meridian="options.showMeridian" 
     meridians="options.meridians"
     show-spinners="options.showSpinners" 
     mousewheel="options.mousewheel"
     arrowkeys="options.arrowkeys" 
     readonly-input="options.readonlyInput" 
     min="options.min" 
     max="options.max"> 
</div>

 api.controller=function($scope, $rootScope) {
	var c = this;

	c.dateFromString = function(string){
		if(string){
			var timeParts = string.split(':');
			var hourPart = parseInt(timeParts[0], 10);
			if(hourPart){
				var date = new Date();
				date.setHours(parseInt(timeParts[0], 10));
				if(timeParts.length > 1){ 
					date.setMinutes(parseInt(timeParts[1], 10) || 0);
					if(timeParts.length > 2){
						date.setSeconds(parseInt(timeParts[2], 10) || 0);
					}else{
						date.setSeconds(0);
					}
				}else{
					data.setMinutes(0);
				}
				return date;
			}
		}
		return undefined;
	};
	
	c.stringFromDate = function(date){
		var timeString = '';
		if(date){
			var hours = date.getHours();
			var minutes = date.getMinutes();
			var seconds = date.getSeconds();
			timeString += (hours < 10 ? "0" + hours : hours) + ":";
			timeString += (minutes < 10 ? "0" + minutes : minutes) + ":";
			timeString += $scope.options.showSeconds ? (seconds < 10 ? "0" + seconds : seconds) : '00';
		}
		return timeString;
	};
	
	c.storeValue = function() {
		c.storedValue = c.stringFromDate(c.selectedTime);
		$scope.page.g_form.setValue($scope.page.field.name, c.storedValue);
	};

	var fieldChangeListener = $rootScope.$on("field.change."+$scope.page.field.name, function(evt, parms) {
		if(parms.newValue != c.storedValue){
			c.selectedTime = c.dateFromString(parms.newValue);
		}
	});
	$scope.$on("$destroy", fieldChangeListener);
	
	if(!$scope.options.hasOwnProperty('showSpinners')) $scope.options.showSpinners = true;
	if(!$scope.options.hasOwnProperty('showMeridian')) $scope.options.showMeridian = true;
	if(!$scope.options.hasOwnProperty('showSeconds')) $scope.options.showSeconds = false;
	if(!$scope.options.hasOwnProperty('hourStep')) $scope.options.hourStep = 1;
	if(!$scope.options.hasOwnProperty('minuteStep')) $scope.options.minuteStep = 1;
	if(!$scope.options.hasOwnProperty('secondStep')) $scope.options.secondStep = 1;
	if(!$scope.options.hasOwnProperty('readonlyInput')) $scope.options.readonlyInput = false;
	if(!$scope.options.hasOwnProperty('mousewheel')) $scope.options.mousewheel = true;
	if(!$scope.options.hasOwnProperty('arrowkeys')) $scope.options.arrowkeys = true;
	if(!$scope.options.hasOwnProperty('meridians')) $scope.options.meridians = ['AM', 'PM'];
	$scope.options.max = c.dateFromString($scope.options.max);
	$scope.options.min = c.dateFromString($scope.options.min);
	var currentValue = $scope.page.g_form.getValue($scope.page.field.name);
	c.selectedTime = currentValue.indexOf('{') != -1 ? c.dateFromString($scope.options.defaultTime) : c.dateFromString(currentValue);
	c.storeValue();
};

This example widget shows how to create a reusable option for capturing a type of input not normally supported: a "time" input. Dictionary entries have the type Time available, but variables only have Date and Date/Time. So, if you have a record producer for a record with a time field (like the sys_holiday table), you normally would have to use a Single Line Text variable and either add validation on the form to prevent invalid time values like "5 PM" or use a record producer script to transform the user input into a value that the Time field on the produced record will accept. This Time Picker widget both improves the user experience and ensures data is always in the correct format. This widget displays as an upgraded input pre-submit, supports defining options for each instance, and is integrated with the form so that it can be treated just like any other variable.

1. How to display post-submit

If your widget captures user data, you'll likely want to display that data in the requested item after the form is submitted. (If you're using a record producer, you can skip this section if the variable editor for the submitted information isn't shown on the produced record.) Prior to submitting the form, this post assumes that the catalog items including the custom widgets will only be accessed in the Service Portal where the widget will always display for the variable. However, the submitted requested item can be accessed in all three different UIs: portals, classic environments (native UI), and workspaces. Because the widgets use AngularJS, they won't render in the classic environment or a workspace. There are three main options for displaying the data post-submit:

1. If the data captured by your widget can display as Single Line Text, then the variable with your embedded widget can use that type instead of Custom or Custom with Label.
   1. This will result in Service Portal showing your widget still, while elsewhere it will show as a Single Line Text.
   2. This option is used by this example widget.
   3. Note: the Widget field doesn't show on the variable form for the type Single Line Text; either add the Widget value from the list view of variables or set the type to Custom, update the Widget field, and then switch back to Single Line Text.
2. If the submitted data for the widget needs to display as a different variable type (like a reference or a date), create or use a separate variable for storing the data and displaying post-submit.
   1. Set this variable's value on change of your input or on submit and set the widget variable to only show pre-submit in the catalog item and the other variable to only show post-submit in requested items and catalog tasks.
   2. In example #3, we use this approach and also handle the hiding and showing in the widget's client script itself.
3. If you don't want the submitted data to just display as a normal field and need a custom element to show even in the classic environment and workspaces, your only option is to create a custom UI macro and a custom Next Experience component and include them in the Macro and Macroponent fields in your variable.
   1. This option requires significant work because you have to create entirely new versions of your widget using two totally different frameworks (unless you wanted to go with a complicated solution where your macro and component use an iframe to embed a portal page with just your widget and update your widget to take values from URL parameters—but I wouldn't recommend that).
   2. Also, when using a macro in the classic environment it might not allow you to set the value of that variable using g_form.

2. How to define options for each instance of the widget

For this widget, we use UI Bootstrap's uib-timepicker directive which is included by default in the Service Portal. That directive includes many different options you can specify, like whether to include seconds and whether to use 24- or 12-hour time. In this example, passing options to a specific instance of the widget is not required but is supported (e.g. if you wanted one Work Start variable with a "max" value of 12:59:59 and another Work End variable with a "min" value of 13:00:00).

To specify options for an embedded widget, include an object in the "Default value" field of the variable. For example:

{
   "mousewheel": false,
   "showSeconds": true,
   "defaultTime": "09:00:00",
   "max": "12:59:59"
}

The embedded widget instance can then access the options data in a few different places:

1. From the $scope data. Can use either $scope.options, $scope.widget_parameters, or $scope.widget.options (I don't think there's any difference between these three).
2. From the "options" object in the server script, which can be made available to the client script with a line like: data.options = options; (this option is mainly useful if you have on load server code that depends on and potentially updates the options).
3. From the g_form value of its variable using $scope.page.g_form.getValue($scope.page.field.name);.

If the widget won't display in the portal post-submit and the form doesn't support drafts, the approach used won't matter because the widget will only pull options once on initial catalog item load. Otherwise, you'll need to consider the following:

1. Approach #3 shouldn't be used if the widget overwrites its own g_form value to store the user's input.
2. Approach #1 and #2 will use the current default value from the variable, whereas approach #3 will keep whatever the value was when the form was submitted or the draft was saved. So, approach #3 is great if the options can change and more accurately represent the "current state" of the widget. However, with approach #3 you'll need to be careful about changing your option schema because the widget will still need to support options from previously submitted/saved requests.

Note: if using approach #1 or #2, the options object will also include some properties added by default. So, make sure to not accidentally use the same property name and be aware they are present if you plan to iterate through the options. The options currently included automatically are: preserve_placeholder_size, advanced_placeholder_dimensions, cat_item, sp_widget_dv, sp_column_dv, active, sys_tags, order, and async_load.

3. How to make your widget act like a normal variable

Our goal with a widget like this (which uses type Single Line Text and stores the input in its own variable) is that, other than setting the Widget field and potentially the Default value for the variable, the variable shouldn't require any special handling and should just work the same as any normal variable. With the approach this example uses, the widget only needs a little extra logic for this:

1. For client scripts, UI policies, etc. to be able to get and set the value of your custom input, you'll need to sync the value of your custom input with the variable's g_form value.
   1. The simplest way is to include the following in your input: ng-model="page.fieldValue" ng-model-options="{updateOn: 'blur', getterSetter: true}".
   2. However, in this example, the value needs to be transformed both when getting and setting because the uib-timepicker uses a Date object whereas the variable's value should have a string formatted as "HH:mm:ss". So, for setting the variable's value you can add an ng-blur or ng-change function to your input and have that function transform the value and then store it using $scope.page.g_form.setValue($scope.page.field.name, value);. For updating your custom input when something else changes the variable's value, you can watch for the field.change event on $rootScope (as described in point #2 of the first example) and transform the data before updating the variable you're using for your ng-model.
2. For handling read-only, you'll have to add your own logic to prevent the user from interacting with your custom elements while the widget's variable is read-only. For this example, this was as easy as adding this attribute to the input element: ng-disabled="page.field.isReadonly()".

Example 3: Country Typeahead Picker

Screenshot HTML Client Script CSS Link Function

<div ng-if="c.isVisible">
  <script type="text/ng-template" id="typeaheadAddress.html">
    <a>
        <img ng-src="{{match.model.flags.png}}" width="16">
        <span ng-bind-html="match.label | uibTypeaheadHighlight:query"></span>
    </a>
  </script>
  <div class="form-group country-typeahead">
    <span ng-if="c.isMandatory" class="fa fa-asterisk mandatory" ng-class="{'mandatory-filled': c.selectedCountry}" aria-label="{{c.selectedCountry ? 'Required Filled' : 'Required'}}" role="img"></span>
    <label for="typeahead-{{page.field.name}}">{{c.label}}<span ng-show="c.loadingLocations">
        <div class="loader"></div>
      </span>
    </label>
    <input id="typeahead-{{page.field.name}}" type="text" ng-model="c.selectedCountry" placeholder="Search for country" ng-disabled="c.isReadOnly"
    typeahead-on-select="c.select($item)" uib-typeahead="address as address.name.common for address in c.getLocation($viewValue)"
    typeahead-select-on-blur="false" ng-blur="c.blur()" typeahead-loading="c.loadingLocations" typeahead-template-url="typeaheadAddress.html" typeahead-show-hint="true" 
    typeahead-no-results="noResults" class="form-control" typeahead-wait-ms="300" typeahead-min-length="0" typeahead-popup-limit="10">
  </div>
</div>

api.controller=function($scope, $http, $timeout){
	var c = this;
	var currentValue = $scope.page.g_form.getValue($scope.page.field.name);
	if(currentValue) currentValue = JSON.parse(currentValue);
	if(currentValue && currentValue.linkedField){
		c.select = function(item){
			$scope.page.g_form.setValue(currentValue.linkedField, item.name.common);
		};

		c.blur = function(){
			//timeout to give time for c.select to run first if an option was clicked
			$timeout(function() {}, 500).then(function(){
				//if an option was selected then c.selectedCountry would change from string to object
				if(typeof c.selectedCountry === 'string'){
					if(!c.loadingLocations && c.lastChecked == c.selectedCountry){
						if(!c.lastResults || !c.lastResults.length){
							c.selectedCountry = ''
							if(currentValue) $scope.page.g_form.clearValue(currentValue.linkedField);
						}else if(c.lastResults.length == 1){
							c.selectedCountry = c.lastResults[0];
							if(currentValue) $scope.page.g_form.setValue(currentValue.linkedField, c.lastResults[0].name.common);
						}else if(c.lastResults.length > 1){
							c.selectedCountry = '';
							if(currentValue) $scope.page.g_form.clearValue(currentValue.linkedField);
						}else{
							c.deferBlur = true;
						}
					}else{
						c.deferBlur = true;
					}
				}
			});
		};

		c.getLocation = function(val){
			var apiToUse = val ? 'https://restcountries.com/v3.1/name/'+ val : 'https://restcountries.com/v3.1/all'
			return $http.get(apiToUse, {
				params: {
					fields: 'cca2,cca3,name,translations,nativeName,altSpellings,flags,independent'
				}
			}).then(function(response){
				c.lastChecked = val;
				if(!currentValue.includeTerritories){
					response.data = response.data.filter(function(country) {
						return country.independent === true;
					});
				}
				c.lastResults = response.data;
				$scope.page.g_form.hideFieldMsg($scope.page.field.name, true);
				if(c.deferBlur){
					c.deferBlur = false;
					c.loadingLocations = false;
					c.blur();
				}
				return response.data;
			}, function(response){
				c.lastChecked = val;
				c.lastResults = '';
				$scope.page.g_form.showFieldMsg($scope.page.field.name, 'Could not find a country matching "'+val+'"', 'error');
				if(c.deferBlur){
					c.deferBlur = false;
					c.loadingLocations = false;
					c.blur();
				}
				return [];
			});
		};

		c.init = function(){
			c.selectedCountry = '';
			c.lastResults = '';
			c.lastChecked = '';
			c.deferBlur = false;
			c.isMandatory = $scope.page.g_form.isMandatory(currentValue.linkedField);
			c.isVisible = $scope.page.g_form.isVisible(currentValue.linkedField);
			c.isReadOnly = $scope.page.g_form.isReadOnly(currentValue.linkedField);
			var linkedFieldDetails = $scope.page.g_form.getField(currentValue.linkedField);
			c.label = linkedFieldDetails ? linkedFieldDetails.label : 'Country';
			$scope.page.g_form.$private.events.on("onPropertyChange", function(type, field, attribute, value){
				if(type == 'FIELD' && field == currentValue.linkedField){
					if(attribute == 'visible'){
						c.isVisible = value;
					}else if(attribute == 'readonly'){
						c.isReadOnly = value;
					}else if(attribute == 'mandatory'){
						c.isMandatory = value;
					}else if(attribute == 'messages'){
						$scope.page.g_form.hideFieldMsg($scope.page.field.name, true);
						for(var i = 0; i < value.length; i++){
							$scope.page.g_form.showFieldMsg($scope.page.field.name, value[i].message, value[i].type);
						}
					}else if(attribute == 'label'){
						c.label = value;
					}
				}
			});
			var linkedFieldValue = $scope.page.g_form.getValue(currentValue.linkedField);
			if(linkedFieldValue){
				c.selectedCountry = linkedFieldValue;
				c.deferBlur = true;
				c.getLocation(value);
			}
			$scope.page.g_form.$private.events.on('onChange', function(field, blank, value){
				if(field == currentValue.linkedField){
					if(!c.selectedCountry || typeof c.selectedCountry === 'string' || c.selectedCountry.name.common != value){
						c.selectedCountry = value;
						if(c.selectedCountry){
							c.deferBlur = true;
							c.getLocation(value);
						}
					}
				}
			});
			$scope.page.g_form.$private.events.on('submit', function(){
				$scope.page.g_form.clearValue($scope.page.field.name);
			});
			var el = $('.sp-form-container #'+currentValue.linkedField);
			if(el[0] && el[0].style) el[0].style.display = 'none';
		};
		c.init();
	}else{
		$scope.page.g_form.setDisplay($scope.page.field.name, false);
	}
};

/* loading icon */
.loader {
  border: 2px solid #b7b7b7;
  border-top: 2px solid #3498db;
  border-radius: 50%;
  width: 14px;
  height: 14px;
  animation: spin 2s linear infinite;
  display: inline-block;
}
@keyframes spin {
	0% { transform: rotate(0deg); }	
	100% { transform: rotate(360deg); }
}
/* to limit the height of the dropdown and to include a scrollbar */
.dropdown-menu {
  max-height: 250px;
  overflow-y: auto;
}
.country-typeahead .dropdown-menu::-webkit-scrollbar {
  	 -webkit-appearance: none;
    width: 8px;
}
.country-typeahead .dropdown-menu::-webkit-scrollbar-thumb {
    border-radius: 4px;
    background-color: rgba(0, 0, 0, 0.4);
}
.country-typeahead .dropdown-menu::-webkit-scrollbar-track {
    background-color: rgba(0, 0, 0, 0.1);
}

function link(scope, element, attrs, controller) {
    element.on('mousedown', '.dropdown-menu', function(e){
        if (e.target === e.currentTarget || e.target.classList.contains('dropdown-menu')){
            e.preventDefault();
        }
    });
}

In this example, we are replacing an existing Single Line Text variable called "Country" with a custom input that uses UI Bootstrap's uib-typeahead directive and an API call to restcountries.com to create a typeahead dropdown of country values. Rather than storing the user's input in its own variable like in the previous example, this example stores the data in the existing country variable and mirrors the state of that variable (so that any existing logic referencing the existing variable will automatically apply to this new custom input without needing to be updated).

Storing the user input in the widget's own variable is often simpler, but that approach doesn't work as well if:

1. The captured input needs to be stored as something other than Single Line Text.
2. The input needs to be stored across multiple variables.
3. You don't want to modify the existing variable you'll be replacing (e.g. the variable is within a variable set used by a lot of other forms).
4. You conditionally need to show either the existing variable or the upgraded custom variable.
   1. For example, say you create a similar typeahead field to capture "state" data, but you only have state data for USA. So, when the country is not USA, you want to show an existing Single Line Text variable instead of your new typeahead state picker. By having the custom state picker variable store its value in the existing variable, other logic can use that existing variable's value as the single source of truth for the state value.

This example widget could have been created as a "self-contained" widget like the previous example, but for demonstration purposes we'll show what it would look like if we wanted to create a separate variable for the widget rather than updating the existing Country field to include a widget.

1. How to Determining Pre- or Post-Submit

In this example, post-submit we want to hide the widget's variable and instead show the existing country variable that we copy the data to. We use the variable type Custom because that will keep the the variable from showing in the classic environment or workspaces:

1. In the Classic Environment, a variable with type Custom will not display at all if the variable record has a value for the Widget field and doesn't have a value for the Macro field.
2. In workspaces, the widget won't display (assuming the variable is type Custom and doesn't have a Macroponent value); however, the variable will still take up a small amount of space in the form's variable editor.
   1. If this extra space is unacceptable, you can manually hide the widget variable post-submit. If you want a more reusable option to handle hiding multiple widgets like this, you can add an onLoad client script with UI Type "Mobile / Service Portal" and a script like: g_form.getFieldNames().filter(f => f.startsWith('variables.') && g_form.getControl(f).type == 'macro').forEach(f => g_form.setDisplay(f, false));. You can either create that client script in the catalog item/variable set (and check the boxes for "Applies on Requested Items" and "Applies on Catalog Tasks") or directly in the Requested Item and Catalog Task tables themselves.
3. In the portal, a variable of type Custom with a Widget value will normally display and the widget code will run. So, we have to add handling to our widget to limit its logic to only run pre-submit and to hide the widget's variable post-submit. To identify in the widget's client script whether it is running pre- or post-submit, there are two main options:
   1. OnSubmit of the form, set the value of the widget variable (or some other variable) to be a value that it would never have prior to the form being submitted. This approach is used for this widget. We have logic like this that clears the widget's value onSubmit:

      $scope.page.g_form.$private.events.on('submit', function(){
          $scope.page.g_form.clearValue($scope.page.field.name);
      });

      And we wrap the client code in an if-condition like this so that it only runs when the variable has a value:

      var currentValue = $scope.page.g_form.getValue($scope.page.field.name);
      if(currentValue) currentValue = JSON.parse(currentValue);
      if(currentValue && currentValue.linkedField){

      I prefer clearing the value rather than setting it to a specific value like "submitted", so that the variable won't show a value anywhere, such as the variable summary that shows for approvals.

   2. The other approach relies on the fact that $scope.page.g_form.getUniqueValue(); will always return the sys_id of the catalog item, but post-submit other places will switch to having the sys_id of the submitted request.
      1. Can compare to the g_form object attached to the sp-variable-layout directive, which contains the form both pre- and post-submit:

         c.isPostSubmit = ($scope.page.g_form.getUniqueValue() == angular.element($("sp-variable-layout")).scope().getGlideForm().getUniqueValue()));

      2. Can compare to the g_form object broadcast in the event spModel.gForm.rendered:

         var g_formListener = $rootScope.$on('spModel.gForm.rendered', function(e, gFormInstance) {
         	c.isPostSubmit = (gFormInstance.getSysId() == $scope.page.g_form.getUniqueValue());
         });
         $scope.$on("$destroy", g_formListener);

      3. Can compare to the sys_id in the page's URL (making sure to inject $location into your controller):

         c.isPostSubmit = ($location.search().sys_id == $scope.page.g_form.getUniqueValue());

We don't use Custom with Label because we want this custom input's label to show as mandatory, which isn't supported for the two Custom variable types. Instead, our widget's HTML will include custom label and mandatory asterisk elements that match the styling of normal variables' labels.

2. How to mirror an existing variable

We want this widget set up so that any existing logic that applies to the existing variable (like a UI Policy that makes it read-only or a client script that shows a field message for it) will automatically apply to the new custom variable as well. The goal is that adding this custom country typeahead picker to a form should be as easy as just creating the new Custom type variable referencing this widget and specifying the "linkedField" in the default value.

The steps for achieving this and mirroring an existing variable are:

1. Manually hide the existing variable by setting its element to display: 'none' (which is independent of its status of g_form.isMandatory).
   1. As mentioned earlier, post-submit we'll instead hide the widget's variable and let the existing variable work as normal—no mirroring needed.
   2. In some cases, you might want the existing variable to conditionally show instead of the widget's variable. If that's the case, you won't want to mirror the visible status of the existing variable; instead, you can use normal UI policies or client scripts to handle which field to show. If you need to prevent some client script logic from running while the widget's variable is hidden you can wrap it in an if-statement like: if($scope.page.field.isVisible()){.
2. On load, get the existing variable's current value and its mandatory, visible, and read-only status using g_form and store those values in the widget's scope for the HTML to use for manually setting its custom input to hidden, not mandatory, or disabled.
3. Additionally, set up listeners for syncing the widget's custom input with any changes made to the existing variable or its value.
   1. In this example, we use the private g_form event "onChange" to listen for changes to the existing variable's value and the event "onPropertyChange" to listen for the following changes related to the variable: visible, readonly, mandatory, messages (field messages), and label.
      1. If you prefer not to use the private g_form events, you could instead listen to changes to the existing variable's value using $rootScope, and for the other attributes of the existing variable you could store a reference to its field object retrieved with g_form.getField and use the functions isMandatory, isReadonly, and isVisible included there.
   2. We don't have to worry about syncing anything back to the existing variable other than the value because we're expecting all client scripts and UI policies to reference the existing variable rather than the widget variable itself.

The Great Integration Hub Paradox

ServiceNow's marketing is brilliant in its simplicity. "It just works." or "We have a spoke for that." And when they're demoing to executives, they love showing a pre-built Flow Designer action as part of a spoke.

But, what happens when your customer doesn't pay for that spoke?

Integration Hub's licensing model is confusing. ServiceNow breaks spokes into multiple tiers – Starter, Professional and Enterprise – each requiring separate entitlements. Want to integrate with Box? That's a Professional spoke. Need SAP S/4HANA? Enterprise tier. Oracle HCM? Also Enterprise. The list goes on and on, and we're constanly referencing the latest version of the "pricing-and-packaging-app-engine" document.

Just a sampling of the Professional tier spokes.

Enterprise spokes add even more cost – and more confusion about what's included.

For organizations that only need one or two integrations, paying for an entire spoke tier feels like buying a whole pizza when you just want a slice. And for ServiceNow partners like us, we need to be able to deliver value regardless of what licensing our clients have.

The Old Fashioned Way Still Works

The good news is that you can still build integrations the "old fashioned way." REST Messages, OAuth configurations, and Script Includes aren't going anywhere. They're not deprecated. They're not legacy. They're fully-supported, and – critically – they don't require additional licensing.

We've done this before with SAP, Greenhouse, UKG, and even ESPN's Fantasy Football. Every time, we read the API documentation, set up the authentication, and build exactly what our clients need. No spokes required.

When a client came to us needing to integrate with Box for their employee onboarding process, we didn't hesitate.

Building the Box Integration

Step 1: Creating an OAuth Application in Box

The first step was heading to the Box Developer Console and creating a Custom App with OAuth 2.0 authentication. Box's documentation is excellent here – you specify your redirect URI (pointing to your ServiceNow instance), select the scopes you need, and Box generates your client credentials.

Per the Box documentation, the key scopes we needed were:

• root_readwrite - for folder and file operations
• sign_requests.readwrite - for Box Sign templates

Step 2: Configuring OAuth in ServiceNow

ServiceNow's OAuth framework is under-appreciated. We created an OAuth Entity in ServiceNow with the client ID and secret from Box, configured the token and authorization URLs, and ServiceNow handles the rest – including token refreshes.

This is the magic that spokes obscure: ServiceNow already has robust OAuth2 support built into core platform functionality. The spoke is just a wrapper around capabilities you already have access to.

Step 3: Creating the REST Message

We created a single REST Message called "Box" with OAuth2 authentication pointing to our OAuth profile. Then, for each Box API endpoint we need, we added an HTTP Method:

• Get Folder - GET https://api.box.com/2.0/folders/${folder_id}
• Create Folder - POST https://api.box.com/2.0/folders
• Copy Folder - POST https://api.box.com/2.0/folders/${folder_id}/copy
• Get Sign Templates - GET https://api.box.com/2.0/sign_templates
• Create Sign Request - POST https://api.box.com/2.0/sign_requests

Each method has its parameters defined, and the authentication is inherited from the parent. Want to add a new endpoint later? It's easy, and you can insert & stay on the ones you already have.

Step 4: The Script Include

The real power comes from wrapping everything in a Script Include. Here's the structure we usually use:

ServiceNow lets us add links to forms via UI Actions, which is great! What's not so great is that one cannot easily configure these links to open in a new tab... at least when using server-side UI Actions.

The current wisdom is that you need to use client-side UI Actions...

function myNewTab() {
  g_navigation.openPopup('task_list.do?sysparm_query=active%3Dtrue');
}

This is well and good until you realize that client-side UI Actions can't use current. Without current, we're forced to resort to workarounds like g_scratchpad or GlideAjax. Such workarounds impose extra complexity and make a real headache of building what should be simple page links.

Well... Guess what? There's a better way!

First, a caveat: this trick is for Classic Forms only. This limitation exists because the classic UI uses HTML forms for everything, including UI Actions. HTML forms have a target property, which allows us to change the form submission behavior to open in a new tab.

Let's hop into it. The above example is the whole cake: It opens a new tab, runs some server-side code to compute the link, then redirects the window.

function openOpsView() {
	// Client-Side Code
	var form = g_form.getFormElement();
	var oldTarget = form.target;
	form.target = '_blank';
	g_form.submit('sysverb_no_update_open_approval_flow');
	form.target = oldTarget;
}

if (typeof window === 'undefined') {
	// Server-Side Code
	var baseUrl = '$flow-designer.do#/operations/context/';
	action.setRedirectURL(baseUrl + current.u_approval_context);
	action.setURLParameter('sysparm_nostack', 'true');
}

UI Action Client/Server Interactions (without AJAX!)

Do you hate AJAX Script Includes with a fiery passion? I do – they’re ugly, error-prone, and full of annoying boilerplate! I consider the unfortunate reliance upon AJAX Script Includes within UI Actions to be one of ServiceNow’s foundational sins. It simply should not be this hard to achieve basic user

RelayChristopher Crockett

Breaking down each part individually...

• Client: Setting this true allows us to temporarily change the client-side form's target to _blank. This trick is what causes the UI Action to open a new tab when calling g_form.submit.
• Action Name: The sysverb_no_update_ prefix skips form saving/mandatories.
• Script: The code within our if block is server-side and triggers at the moment the new tab is opening. We use it to compute the link with access to current and then server-side redirect the still-loading tab via action.setRedirectURL

This technique has a few notable downsides...

• Synchronous: Interacting with the original tab is blocked while this runs.
• Classic Forms Only: Not compatible with Lists or Workspaces.

That's about it, really! For more polished parts of your UX, it's still advisable to invest the requisite effort for a g_scratchpad-based implementation, because the blocking is perceptible.

On the other hand: This is certainly better than g_scratchpad for cases where you need to compute links on-demand (e.g. for pageload performance or special behavior). The only alternative in those cases was GlideAjax, which was often overkill.

On the other, other hand: GlideAjax is capable of calling non-blocking server-side code. As clunky as it is, GlideAjax still has good use for more heavy-duty interaction requirements.

What is it?

It's an OOB (out-of-box) notification on the Board Member (vtb_board_member) table, that fires on insert of any record. Since a new visual task board is created for each upgrade [Skipped Records visual task board (VTB)], all admins will receive a notification for every upgrade, patches or hotfix.

Is it that annoying?

No, not really. It's pretty easy to delete an email a few times year. BUT it's been a lot of years (almost 7), and multiply that by a dozen clients, and it ends up being a lot of junk in my inbox (see screenshot).

How to turn it off

Here is the notification itself: /sysevent_email_action.do?sys_id=81e12044b7332300bf6b68a9ee11a91d

You can

1. Turn it off (active = false) or
2. Add a condition to turn it off for certain boards ex: board.nameNOT LIKEPatch

Unfortunately, the usage examples for how to use the API are (at time of writing) factually inaccurate. The examples given only work as-is within ES Modules and will fail if attempted under any other background scripting context.

Script execution error: Script Identifier: null.null.script, Error Description: "fetch" is not defined., Script ES Level: 200
Evaluator: com.glide.script.RhinoEcmaError: "fetch" is not defined.
   script : Line(1) column(0)
==>   1: fetch('google.com');
 Stack trace:
	at null.null.script:1 

Instead, the correct way to access fetch and associated APIs is as follows:

const FetchApis = require('servicenow:fetch');
const response = await FetchApis.fetch('google.com');

As far as we currently know, this is the only such case where APIs are gated behind the servicenow: prefix... though the creation of this new convention certainly implies more to eventually come.

We expect that the documentation will eventually be corrected to reflect the actual usage, since the current incarnation clearly implies an intent to support...

... For the time being, here's an unofficial list of what's in servicenow:fetch:

• fetch: ServiceNow / MDN
• Headers: ServiceNow / MDN
• Request: ServiceNow / MDN
• Response: ServiceNow / MDN
• AbortController: MDN
• AbortSignal: MDN
• File: MDN
• FormData: MDN
• Blob: MDN
• ReadableStream: MDN
• ReadableStreamReader: MDN
• TextDecoder: MDN
• TextEncoder: MDN
• URL: MDN
• URLSearchParams: MDN

The Problem: Custom League, Custom Problems

It's August, which means one thing in my household: fantasy football draft preparation is in full swing. But here's the thing about our keeper league – it's beautifully complex and frustratingly unique. We use custom scoring rules (6-point passing TDs, no PPR), we can keep players from previous seasons, and ESPN's native app doesn't let us designate keepers properly.

Standard fantasy rankings? Useless. Third-party sites? They don't account for our scoring quirks. ESPN's export features? Non-existent for what we need.

As someone who works at Semaphore Partners implementing ServiceNow solutions, I've learned that when you can't find the integration you need, you build it yourself. Even if that means getting creative with undocumented APIs.

The Solution: When There's No API, Become the API Whisperer

Step 1: Network Tab Detective Work

My first move was opening Chrome's Developer Tools and watching what happened when I loaded ESPN's fantasy rankings. After some digging through the Network tab, I discovered the goldmine:

GET: https://lm-api-reads.fantasy.espn.com/apis/v3/games/ffl/seasons/2025/segments/0/leagues/${LEAGUE_ID}

The magic was in the headers – specifically this beautifully complex filter:

X-Fantasy-Filter: {
  "players": {
    "filterStatus": {"value": ["FREEAGENT","WAIVERS"]},
    "filterSlotIds": {"value": [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,23,24]},
    "filterRanksForScoringPeriodIds": {"value": [1]},
    "sortPercOwned": {"sortPriority": 2, "sortAsc": false},
    "sortDraftRanks": {"sortPriority": 100, "sortAsc": true, "value": "STANDARD"},
    "limit": 300
  }
}

You'll also need to copy a cookie from your browser as well, for authentication.

This gives me exactly what I need: all available players with their rankings, ownership percentages, and projected points – all adjusted for our league's specific scoring system.

Step 2: API Testing with RapidAPI

Rather than building a full application, I use RapidAPI (or Paw) to make these calls manually. It's perfect for one-off data pulls and lets me experiment with different filter parameters without writing code.

The response comes back as rich JSON data with everything I need:

{
  "players": [
    {
    "fullName": "Ja'Marr Chase",
    "defaultPositionId": 3,
    "proTeamId": 4,
    "draftRanksByRankType": {
      "STANDARD": {
        "rank": 1,
        "auctionValue": 57
      }
    },
    "ownership": {
      "averageDraftPosition": 1.56,
      "percentOwned": 99.92
    }
  }
  ...

Step 3: Browser Console Magic

Here's where it gets fun. Rather than writing a separate script, I use the browser console to transform the JSON into tab-delimited data which can easily be pasted into Google Sheets:

copy(
  o.players.map(function(x) {
    return [
      x.player.fullName,
      x.player.defaultPositionId,
      x.player.proTeamId,
      x.player.draftRanksByRankType.STANDARD.rank,
      "",
      x.player.ownership.averageDraftPosition,
      x.player.ownership.averageDraftPositionPercentChange,
      x.player.stats[x.player.stats.length-1].appliedTotal
    ].join("\t")
  }).join("\n")
)

This one-liner extracts player name, position, team, rank, ADP, and projected points – perfectly formatted for pasting directly into Google Sheets.

Step 4: Google Sheets as the Ultimate Dashboard

The final piece is my Google Sheets setup. I paste the data and use conditional formatting to:

• Color-code different positions (WRs in blue, RBs in green, etc.)
• Highlight players who are already kept (so I know they're off-limits)
• Create separate columns for each position
  • ex: =QUERY('2025 Raw Data'!A2:J301,"SELECT D, A, J, H, F WHERE I='RB'", -1)

The result? A custom fantasy football dashboard that accounts for our unique league settings and keeper situation.

The Bigger Picture: Integration Philosophy

This little project perfectly illustrates something we live by at Semaphore Partners: there's always a way to integrate, even when there isn't supposed to be one.

Whether it's:

• Legacy systems without modern APIs
• SaaS platforms that don't officially support your use case
• Third-party services with limited export capabilities

The key is being stubborn, determined, and skilled enough to find the data pathways that exist – even if they're not documented or officially supported.

The Technical Lessons

1. Network inspection is your friend – Most modern web apps are API-driven, even if those APIs aren't public
2. Browser dev tools are incredibly powerful – You can do sophisticated data transformation without leaving the browser
3. Don't over-engineer – Sometimes a manual process with the right tools beats a complex automated solution
4. Google Sheets is more powerful than people think – It's often the perfect middle layer between raw data and actionable insights

The Fantasy Football Confession

Has this elaborate data pipeline helped me win my fantasy league?

Absolutely not. In fact, I have finished dead last more often that I would like to admit. In 2015, I even had to take the SATs (as a 25 year old) as punishment.

But this is my year. I can feel it.

And if it's not, well, at least I'll have the most beautifully formatted last-place roster in fantasy football history.

The Challenge: When APIs Cost Too Much

Picture this: you need to import data from a third-party system, but their API costs $25,000 annually. Meanwhile, they'll let you export the same data for free as a file. What option would you choose?

This exact scenario recently came up with a client using Concur. While we'd normally build a sleek API integration (and trust us, we love integrations at Semaphore Partners), the astronomical API pricing forced us to get creative. The client could only drop files on their MID Server, so we needed a solution that worked within those constraints.

A Bit of History

Back in 2014, there was a fantastic app called Remote File Importer on ServiceNow Share (thank you to SNC Guru Mark Stanger!). It solved this exact problem, but ServiceNow Share is no longer active, and finding those old update sets is like searching for buried treasure.

The good news? ServiceNow's newer capabilities make this easier than ever.

Our Solution: A Two-Step Flow

We created a custom Flow Action that grabs files from the MID Server and attaches them to a Data Source in ServiceNow. Once attached, the Data Source treats it like any manually uploaded file and imports it seamlessly.

Here's how it works:

Step 1: MID Server Script

The first step runs a script on the MID Server to locate and read the target file. This step handles all the file system operations and returns the file's base64 encoded content to ServiceNow.

(function execute(inputs, outputs) {
  function getMimeType(extension) {
    switch (extension) {
      case 'jpg':
      case 'jpeg':
        return 'image/jpeg';
      case 'png':
        return 'image/png';
      case 'gif':
        return 'image/gif';
      case 'xlsx':
        return 'application/xlsx';
      default:
        return 'application/octet-stream';
    }
  }
  
  //const file = new Packages.java.io.File(inputs.filePath);
  const file = new Packages.java.io.File(
    inputs.file_path+"\\"+inputs.file_name
  );

  var result = [];

  // Read file and encode to base64
  var fileInputStream = null;
  var base64Data = "";

  var skipReason = "";
  var fileName = "";
  var fileSize = 0;
  var fileExtension = "";
  var fileMimeType = "";
  var fileLastModified = "";
  var base64Data = "";

  // Get basic file info even if we skip it
  try {
    fileName = file.getName() + "";
    fileSize = file.length();
    fileExtension =
      fileName.indexOf(".") !== -1
        ? fileName.split(".").pop().toLowerCase()
        : "";
    fileMimeType = getMimeType(fileExtension);
    fileLastModified = file.lastModified();
  } catch (infoError) {
    skipReason = "Unable to read file information";
  }

  try {
    fileInputStream = new Packages.java.io.FileInputStream(file);
    const bytes = new Packages.java.lang.reflect.Array.newInstance(
      Packages.java.lang.Byte.TYPE,
      fileSize
    );

    fileInputStream.read(bytes);
    base64Data = Packages.java.util.Base64.getEncoder().encodeToString(bytes);
  } finally {
    if (fileInputStream) {
      fileInputStream.close();
    }
  }
   outputs.result = JSON.stringify({
      fileName: fileName,
      fileSize: fileSize,
      fileExtension: fileExtension,
      fileMimeType: fileMimeType,
      fileLastModified: fileLastModified,
      base64Data: base64Data
    });
})(inputs, outputs);

Step 2: Server Script

The second step takes the file content from Step 1 and creates an attachment on your Data Source using server-side code. This transforms the raw file data into a properly formatted ServiceNow attachment.

The ServiceNow documentation includes a subtle mention of this functionality:

But what does that actually mean, How do I use it, and how does it work?

How to use it:

Within your standard Service Portal URLs insert a sysparm_variable_values= then include your variable values as a JSON string.

For example:

Let's use the "Standard Laptop" demo data Catalog Item

/esc?id=sc_cat_item&sys_id=04b7e94b4f7b4200086eeed18110c7fd
&sysparm_variable_values={"Additional_software_requirements":"Follow Semaphore Partners on Linkedin","acrobat":"true"}

How it works:

Most of the code lives in the Service Portal Widget: "SC Catalog Item" (widget-sc-cat-item-v2).

Starting from line 346 (there are other code blocks, but this is the most important)

if (options.disable_url_prefill == "false" && gs.getProperty(ServiceCatalogConstantsSNC.PROPERTIES.SC_ENABLE_URL_PREFILL, "true") == "true") {
    var paramValues = $sp.getParameter("sysparm_variable_values");
    if (paramValues != null) {
        var variables = {};
        try {
            variables = JSON.parse(paramValues);
        } catch (e) {
            // it can be a tinyId
            variables = sn_sc.CatalogVariableUtil.getVariablesFromTiny(paramValues);
        }
        data.variableValueMap = variables;
        populateDisplayValues();
    }
}

The code includes two primary controls:

• options.disable_url_prefill from the options schema

• The constant ServiceCatalogConstantsSNC.PROPERTIES.SC_ENABLE_URL_PREFILL, which points to the system property glide.sc.enable_url_prefill

While the ServiceNow documentation mentions controlling this on a variable basis via "Disable initial slot fill," this option doesn't appear to be available as of the GA release of Zurich.

Practical Use Cases

This feature enables several valuable scenarios:

•Workspace Integration: Prefilling via UI Actions in Workspaces

•Email Communications: Sending links with key fields already populated

•User Convenience: Bookmarking frequently submitted forms with default values

•Portals/ KB: Embedding catalog requests in portal links or knowledge base articles

•Development & Testing: Simplifying testing during development or demos

Important Considerations

Since this functionality is enabled by default in Zurich, consider the following:

1. Remove Legacy Code: Eliminate your legacy catalog client scripts—there should be no reason to maintain this legacy code any longer
2. Security Review: Ensure you're comfortable with this functionality, as it's now more broadly available compared to previous versions where it was more isolated to specific forms/variables
3. Widget Verification: Use the baseline Service Portal Widget "SC Catalog Item" (widget-sc-cat-item-v2) if you had previously cloned it

Although ServiceNow has some documentation on the Side Panel (seen here), it can be helpful to have everything in one spot.

Let us know if there's anything we missed!

Each client may not use every piece of this, but it is important to ensure that you're using the right tool for the job. For example, if they don't need attachments, use Response Templates instead of Email Client Templates. If a client isn't using the Knowledge Base, then Agent Assist or Fulfillment Instructions may not be the best option.

In the enchanted forest of ServiceNow, filters and breadcrumbs serve a similar magical purpose—they're fundamental building blocks that power everything from lists and reports to templates, flows, and notifications. In this data-driven kingdom, filter conditions enable us to intelligently leverage attributes from across the platform, helping us navigate through complex data relationships just like breadcrumbs guide travelers through dark woods.

The Foundation: Encoded Query Syntax - Our Magic Spell

At the heart of ServiceNow's filtering capabilities lies the encoded query syntax—our magic spell for data manipulation. This powerful incantation can be cast in multiple contexts, from URLs to GlideRecords, making it an essential tool for any ServiceNow wizard.

applyEncodedQuery: The Enchanted Configuration

One of my favorite spells when conjuring ServiceNow functionality is the applyEncodedQuery method:

// Once upon a time, in an enchanted forest...
var forestRecord = new GlideRecord('enchanted_forest');
forestRecord.applyEncodedQuery('creatures=giants^realm.name=Fairyland^magical_protection=true');

// Our brave adventurer seeks the golden castle
var questLog = new GlideRecord('hero_quest');
questLog.applyEncodedQuery('destination=golden_castle^companions=breadcrumb_trail^status=active');

This magical example demonstrates how applyEncodedQuery can set values on records directly, much like casting a spell to transform the very nature of our data. This approach is invaluable for configuration purposes—it allows the wise village elders (application owners) to modify quest parameters without exposing them to the arcane code beneath, creating a cleaner separation between the magic and its manifestation.

GlideFilter: The Wise Oracle's Clean Decisions

GlideFilter often provides a much cleaner alternative to messy if conditions scattered throughout our ServiceNow kingdom, acting like a wise oracle that makes clear decisions. The magical benefits are substantial:

• Conditions can be written on ancient scrolls (system properties) or carved into stone tablets (table configurations)
• Our spells become more readable and easier for future wizards to maintain
• Provides flexible handling of case sensitivity and null values—even works with incomplete incantations
• Separates the wisdom of business rules from the mechanics of their implementation

// The oracle speaks in clear, encoded wisdom
var ancientWisdom = 'creature_type=helpful_fairy^location.realm=enchanted_forest^trust_level=high';
var oracle = new GlideFilter(magicalCondition, ancientWisdom);

// Ask the oracle: "Should we trust this forest creature?"
if (oracle.match(currentCreatureRecord)) {
    // The path is safe, continue the journey
    followTheTrail();
}

GlideQueryBreadcrumbs: The Hero of Our Digital Fairy Tale

Last but certainly not least is the least documented character in our story: GlideQueryBreadcrumbs—truly the hero of our digital fairy tale! While we can gather magical conditions from ancient scrolls (system properties), stone tablets (table definitions), or other mystical configuration areas, the real challenge lies in presenting these cryptic runes to the common folk through user-friendly interfaces like Service Portal, UI Pages, or message ravens (email notifications).

You could forge a custom parser to decode these magical runes, but such a tool would fail when encountering sys_ids (unique magical identifiers) or time-based enchantments (complex date formats). This is where our hero enters the story, ready to save the day.

// A cryptic message left by a previous traveler
var mysteriousMessage = 'helpful_guide=a8f98bb0eb32010045e1a5115206fe3a^quest_active=true^last_seen>2024-01-01';

// Our hero transforms the cryptic runes into readable wisdom
var heroicTranslator = new GlideQueryBreadcrumbs();
var readableStory = heroicTranslator.getReadableQuery('traveler_log', mysteriousMessage);
gs.info(readableStory);

// Output: "Helpful Guide is Fairy Godmother AND Quest Active is true AND Last Seen is after January 1, 2024"

This heroic utility transforms cryptic encoded queries into human-readable breadcrumb trails, automatically resolving magical references and formatting time-based enchantments appropriately for display. Unlike Hansel and Gretel's breadcrumbs, these digital ones don't get eaten by birds—they persist to guide future travelers through the same data forest.

The Moral of Our Story

These three magical components work together to create a robust, maintainable approach to data navigation in the ServiceNow kingdom, much like the best fairy tales teach us important lessons:

1. Encoded queries provide the ancient language of data magic
2. GlideFilter serves as our wise oracle for clean, configurable decision-making
3. GlideQueryBreadcrumbs acts as our heroic translator, bridging cryptic technical runes with user-friendly breadcrumb trails

By mastering these enchanted tools, you can build more flexible, maintainable, and user-friendly ServiceNow applications that separate the magic from its configuration, while ensuring that no user ever gets lost in the dark forest of complex data relationships.

And unlike the original fairy tale, these breadcrumbs will never be eaten by birds—they'll always be there to guide you home, no matter how deep into the ServiceNow forest you venture.

And they all lived efficiently ever after... at least until the next release.

Another amazing feature and my personal favorite is the ability to make updates in multiple scopes without making a huge mess in update sets. Using ServiceNow Studio you can set bookmarks while working on a project from any application scope and have them all in one place to work from.  The beautiful thing about this is when you change from one configuration file to another in this one location your application scope and update set will change with the record you are updating. For example, if you are working on a CSM project and making updates in Global, Customer Service, and Customer Project Management applications, when in ServiceNow Studio whichever application file you are configuring the update set and scope will automatically change for you based on the last update set you used in the application scope the configuration is in!

I was pleasantly surprised by how easy it was in just one lab session to feel comfortable changing how I do my development work.  I am quite excited to see what improvements are on the way for this in the future!  I feel quite confident this is something that is not only here to stay but likely will be where developers work from now on.  Give it a try, you won’t regret it!

Here are some screenshots that show these two great features:

Change tabs within ServiceNow Studio and your scope/update set changes for you!

Things to note:

·         This is very new so there are some things that can be a little buggy. I had a tab with the script include that wasn’t letting me search the script include like you normally can but refreshing my browser fixed it.

·         The only way to set bookmarks is to search for the file in the left nav and bookmark it or click on “Recent” and add them to your bookmarks from there. Hopefully at some point there will be a bookmark flag on each tab within ServiceNow Studio that you can add as a bookmark.

Scheduling inline content exports

While not explicitly called out in the product documentation, the Yokohama release includes a few somewhat hidden options in the scheduled export screen that allow for a bit more flexibility in how scheduled Data Visualization exports are rendered.

To kick things off, you'll want to navigate to All > Platform Analytics > Library and select Data Visualizations. It's worth noting here that these same options are not available for Dashboards at this time (and possibly won't be in the future, due to the volume of content these can contain), though the ability to export entire Platform Analytics Dashboards on a schedule as PDF or PowerPoint files is pretty convenient.

Once you've selected the Data Visualization you'd like to embed in an email, you'll want to open the Schedule screen.

From here, you'll want to drill into the File type dropdown menu.

The exact options available are dependent on the type of Data Visualization you're trying to schedule. The screenshot above is from a "Pie" visualization, while "List - Simple" visualizations will include an "Embed LIST" option.

Using the "Add" button, you're able to include multiple Visualizations to embed in a single scheduled export.

With at least one "Embed" option selected, you're able to modify the exact email contents in the "Email Details" section below. The embedded content is added to the WYSIWYG editor in the order in which it was added.

Once the content is arranged as you'd like and at least one recipient is configured, you can test the export by saving and clicking the "Send Now" button.

Results

Immediately upon testing, you should be able to preview the generated email in your system's

Nuances and limitations

This is a very exciting new feature, but there are a handful of things to note before diving in fully.

• If embedding multiple Visualizations, it can be a bit difficult to differentiate them in the WYSIWYG.
• For "List - Simple" visualizations, a raw HTML table is always output including links to all reference records in the Core UI. Workspace links are not supported, and Group By options do not result in multiple tables being generated. The styling of the table and the text that appears below it linking to the Visualization in-platform both seem to be hard-coded, which limits flexibility and potentially the audience of these notifications to users with Platform Analytics access.
• From what I can see, there does not appear to be any support for any kind of company branding in the generated exports using any existing features like Email Templates or Layouts.

Despite these points, this feature requires no custom code and empowers reporting power users to create friendlier experiences for a variety of personas.

The Promise of Platform Analytics

The new Platform Analytics Dashboards represent a significant step forward in ServiceNow reporting capabilities. They offer:

• Improved performance for handling large datasets
• More interactive and dynamic visualizations
• Better integration with other ServiceNow components
• Enhanced customization options for different user needs

The Challenge with Adding Variables

Despite these advantages, there's one particular feature that doesn't quite work as expected yet: adding variables to a list view (List - Simple) report.

Here's what happens:

1. You add a variable as a column to your list view report
2. The column appears in the sidebar
3. You refresh the report, but the column doesn't even show up

This issue has been documented here (8 months ago), and referenced a ServiceNow Support Case (CS7468024) which I'm unable to view.

The Workaround: Manual Intervention

Not being able to take no as an answer, I was able to find this as a workaround.

1. Click Open record on the specific visualization you want to include a variable on
2. Copy and paste the json value into the text editor of your choice, and then format it

3. You'll see that the variable columns are in this format

variables.{catalog item sys_id}.{variable sys_id}

4. For each variable column, remove the Catalog Item's sys_id, so instead it's just

variables.{variable sys_id}

5. Paste the json back in, save the record and refresh the Platform Analytics Dashboard and confirm that the variable columns now show up

Conclusion

Since we've been able to do this in typical reporting for quite some time, it's frustrating that ServiceNow doesn't have a fix for this yet. They tend to release (and market) new features that haven't reached parity yet with existing functionality. However, you should be able to use this workaround until they issue a fix for it.

Easy peasy, let's just do something like current.work_notes = JSON.stringify(myData); right?

Uhh, okay. It's there but it doesn't exactly look great and the readability is abysmal.

Let's do better. We can use the space parameter to improve our formatting: current.work_notes = JSON.stringify(myData, null, 2);.

Well that didn't really work (but it does in gs.log, try it out!). Now we've got these \n 's everywhere and our spaces seem to have been swallowed by the ether.

Let's leverage HTML, that way we have more control:

current.work_notes = '[code]<pre><code>' + JSON.stringify(myData, null, 2).replaceAll('\n', '<br />') + '</code></pre>[/code]';

And we're there! In this final example, we use the [code] tag to tell ServiceNow we intend to render HTML in this work note, then we use the <pre> tag in HTML to preserve white space, then the <code> tag to semantically inform the browser (and screen readers) that the enclosed is code (visually this tag isn't strictly necessary as omitting it in this context will render the same output), and finally we use .replaceAll('\n', '<br />') to convert our newlines to a format that HTML understands.

The Challenge

Lumon Industries, known for its groundbreaking work in data refinement, operates with a distinctive organizational structure where departments are strictly segregated. Their "severed" employees work in completely isolated environments, necessitating specialized workflow management solutions that could maintain strict information boundaries while enabling efficient operations.

The Solution

Working closely with Lumon's management team, Semaphore Partners developed a precision-engineered ServiceNow implementation that respected their unique operational requirements while modernizing their service management capabilities.

Advanced Security Framework

We architected a sophisticated security framework within ServiceNow that mirrors Lumon's strict departmental segregation:

• Role-based access control (ACLs) with granular permissions based on employee status
• Automated workflow state transitions (playbooks & Flow) between severed and non-severed environments
• Secure data partitioning (ServiceNow data separation) to maintain complete separation between departments

Technical Implementation Highlights

Our implementation leveraged several key ServiceNow capabilities:

• Service Portal: Purposefully designed employee portals featuring the signature Lumon green-on-black terminal interface, complete with specialized numeric grid displays for data refinement tasks
• Flow Designer: Automated workflows tracking completion percentages across files like "Le Mars" and managing the sophisticated five-bin refinement sorting system
• Performance Analytics: Real-time monitoring dashboards showing refinement progress (0% to 100%) with dedicated metrics for each data quadrant (00-04)
• CMDB: Comprehensive tracking of refinement terminals, featuring the proprietary Lumon interface with its distinctive number matrix display
• Now Intelligence: AI-powered pattern recognition for identifying scary, malicious, and tumorous numbers within data sets
• Virtual Agent: Automated compliance monitoring for proper number categorization procedures

The Results

The implementation of ServiceNow has transformed Lumon's service management capabilities while maintaining their strict operational requirements:

• 40% reduction in workflow transition times between departments
• 60% improvement in resource allocation efficiency
• Enhanced security compliance through automated controls
• Streamlined incident response times for critical systems

"Semaphore Partners' understanding of our unique operational requirements and their ability to adapt ServiceNow to meet these needs has been invaluable. The platform has become an integral part of our daily operations while maintaining our strict departmental segregation protocols." - Seth Milchick, Supervisor of the Severed Floor, Lumon Industries

Want to learn how Semaphore Partners can help your organization leverage ServiceNow to its full potential? Contact us today for a consultation.

Note: This case study is a work of fiction based on the Apple TV+ series "Severance." While the ServiceNow implementation details are grounded in real platform capabilities, the client company and specific use cases are fictional. The post is intended to demonstrate creative possibilities in enterprise service management through a pop culture lens.

Starting Simple: An Email-Based Integration

When we first approached this project, we opted for a quick-win solution: using Greenhouse’s email notifications as the ingestion point for onboarding data. Every time a candidate accepted an offer, Greenhouse sent an email containing basic information about the candidate and their job. Our integration parsed these emails and used the extracted data to trigger onboarding workflows in ServiceNow.

While this approach helped us go live quickly, it wasn’t without its challenges:

1. Email Format Variability: Greenhouse’s email templates occasionally changed, causing our parsing logic to fail.
2. Limited Data Access: The emails didn’t include all the necessary details, such as job-specific onboarding requirements or candidate preferences, which meant that manual intervention was still required.
3. Duplicate Issues: Multiple emails for the same candidate would often trigger duplicate new hire entries, leading to confusion and errors in the onboarding process.
4. Not a Real Integration: This approach relies on infrastructure outside of the ServiceNow instance, since it's waiting for an email to be sent and then received. It also relies on asynchronous event handling in ServiceNow, which could be overloaded for other reasons.
5. Data-enforcement: Since an email is just a big text field, no data can be enforced (or rejected).

Ultimately, we realized that email-based integration was not a sustainable or scalable solution. We needed a more robust approach that leveraged Greenhouse’s API.

Building a Robust API-Based Integration

To create a seamless integration, we transitioned to Greenhouse’s API. This allowed us to query detailed and consistent data directly from Greenhouse and eliminate reliance on email.

API Overview

Greenhouse's API is well documented here: https://developer.greenhouse.io/harvest.html#introduction

The integration requires an API Token, and authorizes via basic auth using the API token as the username with a blank password. The Greenhouse Dev Center also allows you to specify which endpoints are accessible for which API token. Best practices are to only allow access to the endpoints that are needed.

Querying the Offers Endpoint

Since the process begins once an offer is accepted, the integration begins by querying the GET /offers endpoint periodically from Greenhouse’s API. This endpoint provides information about:

• Candidate ID
• Job ID
• Offer details, including the accepted status and start date

While the Offers API gives us a good starting point, the data it returns is incomplete for our onboarding purposes. For example, the offer information might include the candidate’s ID and job ID, but not their name, email, or job title—critical details for provisioning accounts, equipment, and training.

Supplementing Data with Additional Endpoints

To fill in the gaps, our integration makes additional calls to:

1. Candidate Endpoint (GET /candidates/{id}):

• Retrieves the candidate’s full name and email

2. Job Endpoint (GET /jobs/{id}):

• Provides job title, department, location, and other custom fields relevant to our onboarding workflows

By combining data from these three endpoints, we create a comprehensive onboarding profile for each new hire. This profile includes everything ServiceNow needs to automate onboarding tasks, from creating IT tickets for laptop provisioning to scheduling orientation sessions.

Data Source Details

Our Data Source loads the data by script, since we have to make these three calls to efficiently map and transform all of this data at once.

Our data source only look at Offers that are

• Status = Accepted (see screenshot above)
• Updated after last 14 days + 2 hours
• Starting After today

This also means that our Scheduled Import Set should run at an interval less that 14 days, to ensure we don't miss any accepted offers.

As detailed above, we can get all Offer details with one call, and get all Candidate details with only one call, but unfortunately, the Jobs endpoint doesn't allow for bulk queries. This means that if we have n new offers, we have to make n+ 2 REST Message calls.

(function loadData(import_set_table, data_source, import_log, last_success_import_time) {

    var gdt = new GlideDateTime();
    var startsAfter = gdt.getDate();
    gdt.addDaysLocalTime(-14);
    gdt.addSeconds(-2 * 60 * 60);
    var updated_after = gdt.toString().replace(" ", "T") + ".000Z";

    var message = new sn_ws.RESTMessageV2('Greenhouse', 'offers-recent');

    message.setStringParameter("starts_after", startsAfter);
    message.setStringParameter("updated_after", updated_after);

    var arr = []


    var resultStream = global.ukg_streamData(message);
    var offerStream = resultStream.map(function(x) {
        return {
            "candidate_id": x["candidate_id"].toString(),
            "starts_at": x["starts_at"],
            "opening_id": x["opening"]["opening_id"],
            "job_id": x["job_id"].toString()
        }
    }).chunk(50).flatMap(function(offers) {
        var offersMap = offers.reduce(function(map, item) {
            map[item.candidate_id] = item;
            return map;
        }, {});

        var candidateIDs = Object.keys(offersMap);
        
		var jobIDs = offers.map(function(x) {
            return x.job_id;
        })

        offers.forEach(function(x){
            var message = new sn_ws.RESTMessageV2('Greenhouse', 'job');
            message.setStringParameter("id", x.job_id.toString());
            var response = message.execute();        
            var responseBody = response.getBody();
            var httpStatus = response.getStatusCode();

            if(httpStatus == 200){
                var jobResponse = JSON.parse(responseBody);
                x["remote_office_location"] = jobResponse["custom_fields"]["remote_office_location"];
                x["jobtitle"] = jobResponse["name"];
            }
        })

        var message = new sn_ws.RESTMessageV2('Greenhouse', 'candidates_by_ids');
        message.setStringParameter("candidate_ids", candidateIDs.toString());
        var candidateStream = global.ukg_streamData(message);

        return candidateStream.map(function(candidate) {
            var offerData = offersMap[candidate.id];
            var personalEmail = candidate.email_addresses.find(function(email) {
                return email.type === "personal";
            });
          
            return global.GQ.merge(offerData, {
                "name": candidate.first_name + " " + candidate.last_name,
                "first_name": candidate.first_name,
                "last_name": candidate.last_name,
                "preferred_name": candidate.custom_fields["preferred_name"] || "",                
                "personal_email": personalEmail && personalEmail.value,
                "end_date": candidate.custom_fields["end_date"] || "",
                "location": candidate.custom_fields["office_location"] || ""
            });
        });
    });

    offerStream.forEach(function(result) {
        import_set_table.insert(result);
    });

})(import_set_table, data_source, import_log, last_success_import_time);

Automating Processes to Assist Internal Teams

The integration wasn’t just about gathering data—it was about making life easier for the internal team managing onboarding. In addition to streamlining data tracking, we implemented the following enhancements:

1. Automated Email Reports: Weekly emailed reports detail upcoming new hires, providing the team with a clear overview of who’s starting and when.
2. Automatic Case Creation: Cases are automatically created in ServiceNow two weeks and one week before each new hire’s start date. These cases ensure that key tasks—like equipment setup and access provisioning—are completed on time.

Benefits of the API-Based Approach

Switching to an API-based integration has delivered significant benefits:

1. Data Consistency: By querying Greenhouse directly, we ensure that onboarding workflows always have the most up-to-date information.
2. Scalability: The API handles varying volumes of data seamlessly, enabling us to scale as hiring increases.
3. Improved Team Efficiency: Automated reports and cases reduce manual tracking and ensure nothing falls through the cracks.

Lessons Learned

Looking back, the shift from an email-based integration to an API-based solution has been transformative. However, this evolution taught us a few key lessons:

• Start Simple, But Plan for Growth: Email-based integrations can help you go live quickly, but they’re rarely sustainable for high-volume processes. Be ready to iterate.
• Understand the Data Model: Before building an API integration, familiarize yourself with the platform’s endpoints and data relationships to ensure you’re pulling all necessary information.
• Test for Edge Cases: Not all candidates or jobs are the same. Test your integration with a variety of scenarios to identify gaps in data or logic.

Conclusion

Integrating ServiceNow with Greenhouse Recruiting has not only streamlined our clients’ onboarding processes but also empowered internal teams to manage new hires effectively. By investing in a robust integration, we’ve eliminated manual tracking, automated critical tasks, and ensured a consistent, scalable process for future growth.

If your organization is looking to enhance its onboarding capabilities, we’d love to share more about how we can help. Reach out to us today to start the conversation!

Prior to Workspace, adding a Field Decorator was accomplished by creating a UI Macro. To implement a UI macro a few steps were needed to getting your decorator on a form, including writing code.

Similarly, if you are using one of the Baseline Workspaces (SOW, ITAM, CSM/FSM, HR) or a custom workspace there are some steps to create a Field Decorator. Luckily no Jelly, HTML, or JS is involved. There is mostly no code, there is a bit of JSON to copy/paste, and the rest is all configuration driven.

These steps seems pretty simple/straightforward, but depending on your workspace configuration there may be a few additional steps to make your Field Decorator launch an external URL.

Creating the Field Decorator

1. Navigate to Now Experience Framework > Declarative Actions > Field Decorators
2. Fill in the following fields:
   1. Action label: Provide a descriptive label
   2. Implemented as: UXF Client Action
   3. Specify client action: Open URL
   4. Decorator applies to: Specific field
   5. Field Name: Select a field name to display the icon near
   6. Icon: Select an icon
   7. Table: Select table
3. Save the form
4. Click Related Links > Advanced view
5. Set URL:
   1. Action Attributes > Payload Map > URL
   2. Fill in your URL
   3. use {{actionModelField}}syntax for example notion.so/{{displayValue}}
6. Save the Form
7. Navigate to the Workspace:
   1. Select a Record from the table you configured on the Action Assignment
   2. Confirm your Icon appears next to your field

At this point if you click your field decorator icon, nothing will happen. One additional (undocumented) set of steps is required to make the decorator actually launch/open a URL.

Creating the UX Add-on Event Mapping

1. Navigate to the Action Assignment (Decorator) you created
   1. Related List > UX Add-on Event Mapping
2. Create a new UX Add-on Event Mapping
   1. Fill in the following fields:
      1. Event Mapping Name: Provide a unique name
      2. Source Component: Form
      3. Source Declarative Action: Action Assignment from previous steps
      4. Controller: UI Controller Record Page
      5. Target Event: [Record Page] Item Selected
      6. Target Payload Mapping: Use payload below:

{
    "type": "MAP_CONTAINER",
    "container": {
        "route": {
            "type": "JSON_LITERAL",
            "value": "external"
        },
        "fields": {
            "type": "JSON_LITERAL",
            "value": null
        },
        "params": {
            "type": "JSON_LITERAL",
            "value": null
        },
        "redirect": {
            "type": "JSON_LITERAL",
            "value": null
        },
        "passiveNavigation": {
            "type": "JSON_LITERAL",
            "value": null
        },
        "title": {
            "type": "JSON_LITERAL",
            "value": null
        },
        "multiInstField": {
            "type": "JSON_LITERAL",
            "value": null
        },
        "external": {
            "type": "MAP_CONTAINER",
            "container": {
                "url": {
                    "type": "EVENT_PAYLOAD_BINDING",
                    "binding": {
                        "address": [
                            "url"
                        ]
                    }
                }
            }
        }
    }
}

Introduction

Many organizations leverage Active Directory for good reason—it serves as an excellent central repository for network resources like users, groups, and computers. This data can be imported into ServiceNow, providing visibility into both users as well as Active Directory groups and group memberships.

However, what about valuable data that exists outside Active Directory, such as UKG Human Resource information? UKG stores essential data about users, locations, organizations, and companies, offering deep insights into your organization and its people.

Cross-referencing data across multiple sources of truth can be difficult, tedious, and time-consuming, but allows for a more complete picture of your organization within ServiceNow.

We can leverage ServiceNow to integrate with your sources of truth.

In ServiceNow, we import data from additional sources (in this case, UKG Human Resources) and combine it with existing Active Directory data via Transform Maps to create a single "3-Dimensional" data point. This connects people, places, and things to provide comprehensive insights into your organization.

A great example of this is Location data. A user’s location in Active Directory may just be a string “New Jersey”, but you will need more details. What’s the location’s city, address or zip code? Supplementing this referential data can help with answering ‘how many users are located in each time zone’? Or who is the department head to approve a certain catalog request?

Data Sources / REST Messages

Data Sources / REST Messages act as "getters" of data, enabling ServiceNow to communicate with external sources like UKG Human Resources. You can request various data points such as user start dates, employment status, and location records using REST Messages.

Data requests are secure—authentication is required for accessing sensitive data. With UKG Human Resources, you must provide a username and password with your request to validate access, but also provide a Customer API Key and a User API Key.

Data sources will also allow you to schedule regular data imports to ensure the freshness of the supplemental data.

(function loadData(import_set_table, data_source, import_log, last_success_import_time) {

    var message = new sn_ws.RESTMessageV2('UKG integration', 'employee-employment-details');
    var resultStream = ukg_streamData(message);
    resultStream.forEach(function(result) {
        import_set_table.insert({
            "companyID": result["companyID"],
            "employeeID": result["employeeID"],
            "homeCompany": result["homeCompany"],
            "isHomeCompany": result["isHomeCompany"],
            "primaryJobCode": result["primaryJobCode"],
            "primaryWorkLocationCode": result["primaryWorkLocationCode"],
            "jobTitle": result["jobTitle"],
            "fullTimeOrPartTimeCode": result["fullTimeOrPartTimeCode"],
            "originalHireDate": result["originalHireDate"],
            "employeeTypeCode": result["employeeTypeCode"],
            "supervisorID": result["supervisorID"],
            "employeeStatusCode": result["employeeStatusCode"],
            "employeeNumber": result["employeeNumber"]
        });
    });

})(import_set_table, data_source, import_log, last_success_import_time);

Transform Maps

Transform maps are the "manipulators" of data. They take the data retrieved by Data Sources / REST Messages and organize it properly within ServiceNow by either creating new records or updating existing ones. For ServiceNow to correctly place data, it needs to coalesce data via a unique identifier that's consistent across all data sources. For user data from both UKG and Active Directory, we used the employee ID. After transforming your data, you have a robust, up-to-date "3-Dimensional" data point.

Have questions, or want to recreate the same record visibility within your organization? Feel free to reach out!

Overview

A client was experiencing a strange issue. Dozens and dozens of companies were being created with bogus Chinese, Japanese and Burmese characters following an otherwise normal name. To make matters worse, these companies didn’t have any associated records with them. Was it foreign involvement? Fortunately, not.

What do the characters mean?

Apparently, it’s called Mojibake. I can try to paraphrase, but anything I’ll write would just be regurgitated from wikipedia anyways: https://en.wikipedia.org/wiki/Mojibake

The characters don’t mean anything in succession, but some of my favorite translations were “VMWare Trample Righteous Dazzle” or “Intel Corporation Ken Decorate Hog” (Thanks to Google Translate), Some other examples are pasted below.

How did we track it down?

Looking at the times these records were created, it was clear that they were from SCCM. Then by looking at the sys_import_set_run table, we could track it down to the Software import. Then through the Integration Studio, we could find out the Transform Script it was using to cleanse the company.

Why were they orphaned?

Thanks in part to ServiceNow’s processing logic, the company is created before it is used. Yes, companies are created before the row is even transformed, thanks to this line:

company = new CmdbIntegrationCompanyModelUtil().cleanseCompany(company);

Even if the row is rejected, or the Manufacturer is changed, the company is already created! Not good!

How did we fix it?

We could have easily added a line in CmdbIntegrationCompanyModelUtil, but that’s a high priority file type. Even the script include that calls that one is a high priority file type.

So in order to prevent skipped records on upgrades, the best thing to do is to create a new script include that calls those, and update the “Cleanse Software Model” sys_rte_eb_operation_type record to call that new custom Script Include.

For this major problem, the fix was quite simple. ' The one line of code we added was:

text = text.replace(/[^\\x00-\\x7F].*/, ""):

• terate GmbHḹ鑴܀耀Uninstall
• terate GmbHḹ鑴܀耀Uninstall
• iterate GmbHῙ҅ഀ谀Ⅼ涄쿨´
• iterate GmbHத﷑⠀耀Microsoft
• iterate GmbHၰ쇲℀谀Ⅼ擒쵈ɻ
• iterate GmbHᕑ⮶ఀ谀Ⅼ掎꫘͘
• iterate GmbH᧠⢀㤀耀20240930
• iterate GmbH㐒㐀耀Microsoft
• iterate GmbH㞊⬀耀Software
• iterate GmbH䊵﫣Ѐ耀Microsoft
• iterate GmbH䡍㡪ఀ谀Ⅼ燲̾
• iterate GmbH䩉鰔㐀耀Uninstall
• iterate GmbH侬﬋㴀耀Software
• iterate GmbH棙栓ࠀ耀Microsoft
• iterate GmbH没➹⸀谀Ⅼ泒롰˧
• iterate GmbH滇쭆⸀耀ᆸ榪팀ˆ

The core driver behind SAP's dominance as a platform is their ability to enhance back-end business processes. While SAP excels at these processes, the front-end can be a bit clunky and disconnected. That's why it's an ideal fit for integrating with ServiceNow using the Employee Service Center as the process origin-point and approval flow.

Unfortunately, despite excellent documentation, SAP's jungle of products and versions became quite the confusing mess to figure out. Having someone who’s familiar with the other tool and is willing to lend a hand is a huge asset when it comes to integration. One of the SAP Admins for our client was instrumental in helping us get this project done.

The integration

We began our work for the client with the goal of managing their SAP Purchase Order requests from within the ServiceNow interface.

This effort was focused around requesting a Purchase Order via the Employee Service Center in ServiceNow. In order to achieve this, we needed to introduce a Catalog Item which could display remote SAP items and eventually transmit new Purchase Orders back to SAP. Integrating SAP via Catalog Items enabled creation of powerful workflows, such as the handling of approvals entirely within ServiceNow, before anything ever gets touched on SAP

Authentication

The SAP API is session-based, in other words: before anything else, we must present our credentials and request a new session cookie. This posed an issue, because ServiceNow's user-friendly REST Flows do not expose cookies! The solution here was for us to leverage the lower-level RESTMessageV2 API using JavaScript, which exposed for us the very helpful getCookies method.

var cookies = j2js(response.getCookies());

//Extracting context number from cookies
var contextCookiePrefix = "sap-usercontext=";
var maybeContextNumber = Stream.fromArray(cookies)
  .find(function (cookie) {
    return cookie.startsWith(contextCookiePrefix);
  })
  .map(function (contextCookie) {
    var cookieContent = contextCookie.slice(contextCookiePrefix.length);
    var cookieData = cookieContent.split(";")[0];
    var contextNumber = cookieData.trim().replace(/^sap-client=/, "");
    return contextNumber;
  });
if (maybeContextNumber.isEmpty()) {
  // This should never happen
  gs.error(
    new NiceError(
      "Server response OK but could not find context number given the following cookies: {0}"
    ),
    JSUtil.describeObject(cookies)
  );
}
//Looking for session cookie
var maybeSessionCookie = maybeContextNumber.flatMap(function (contextNumber) {
  return Stream.fromArray(cookies).find(function (cookie) {
    return cookie.startsWith("SAP_SESSIONID_NED_" + contextNumber + "=");
  });
});

Content Length

Another showstopper was the APl's mandatory requirement to pre-compute Content-Length headers on outgoing HTTP messages. This posed another problem because ServiceNow does variable substitution at the very last moment, after our Data Source's last chance to set Content-Length!

We eventually bypassed this issue by manually applying body variable substitution – in JavaScript – long before ServiceNow would normally do it. This required some fairly creative code to pull off:

var templateParameters = {
  netPriceAmount: ritmGr.variables.product_cost,
  // ... and so forth. This is a mapping
  // Keys corresond to Outbound Message variables
  // Values correspond to Request Item variables
  glAccount: ritmGr.variables.gl_account.u_node_name.toString(), // "545208",
};

// Format template parameters as data acceptable by GlideStringUtil.substituteVariables
var jProperties = new Packages.java.util.Properties();
for (var key in templateParameters) {
  var value = String(templateParameters[key]);
  jProperties.put(key, value.replace('"', '\\"'));
  request.setStringParameter(key, value);
}
// Do variable substitution for the body early so we can accurately calculate content-length
var templateContent = request.getRequestBody();
var content = j2js(GlideStringUtil.substituteVariables(templateContent, jProperties));
// SAP blows up if the JSON payload contains whitespace, so guard against that here
var minifiedContent = JSON.stringify(JSON.parse(content));
request.setRequestBody(minifiedContent);
var contentLength = minifiedContent.length;
request.setRequestHeader('Content-Length', contentLength);

Data Sources

Since the Catalog Item needed SAP data, we created multiple scripted Data Sources to pull over the data from SAP, leveraging as much of the Out of box REST Message functions as possible.

var message = new sn_ws.RESTMessageV2('SAP - PO', 'Get Cost Center');
var resultStream = sappo_streamData(message);
resultStream.forEach(function(result) {
	import_set_table.insert({
		"currency": result["CostCntrCurr"],
		"rollup": result["RollUp"],
		"number": result["NodeName"],
		"name": result["NodeDesc"],
		"area": result["ControllingArea"],
		"id": result["ID"],
	});
});

Although these elements were brought over for this Catalog Item, some of them were mapped to out of box tables (Vendors -> core_company, Cost Centers -> cmn_cost_center...), and help supplement the existing user data that we were getting.

Conclusion

Integrating with SAP is possible, but not easy. However, if you (or your client) want ServiceNow to be THE customer-facing portal, then an integration to ERP tools - such as SAP - will be a necessity.

Building an integration like this will enable you to harness ServiceNow’s Service Catalog, Portal, Workflow Engine, and notifications to maintain a consistent branding and messaging across all platforms, even though the final fulfillment of this request will still occur in SAP.

Frequently stumped by this issue, we've poured much time and thought into existing solutions and have created a novel solution worthy of a new place in the pantheon of UI Action design patterns. I'll reveal all below... but in order to get there we'll first need to cover the existing options & limitations. Those already familiar should feel free to skip ahead past... The Managerie. Those simply searching for copyable templates can even skip directly to the bottom!

A Menagerie of Extant UI Actions

Server-Side: The Conventional Solution

The typical UI Action is easy to understand: simply click a button and some Server code gets triggered. These are the backbone of the UI Action paradigm and we'll call them "Server-Side UI Actions".

Designers should use Server-Side UI Actions whenever possible, because all other approaches are necessarily more complex and therefore less desirable. The only reason to be using any other pattern – ours included – is if design requirements exceed the inherent limitations of Server-Side UI Actions. These limitations are born of the inherent architecture of Server-Side UI Actions, illustrated below...

As you can see, there are zero opportunities for the designer to insert user-facing interactions during the moment between UI Action activation and form submission. It's already too late by the time the "Server Script" in our diagram has a chance to run.

This limitation precludes many useful design techniques, such as:

• Modifying the form input without immediately submitting changes.
• Interactive input validations without forcing the user to submit & pray .
• Inserting additional prompts/dialogs into the submission design flow.

Client-Side: A Different Key For a Different Lock

Client-Side UI Actions completely flip the script. They don't cause any Server-side code to run when clicked. Nothing even gets submitted to the Server!

This is actually quite handy for the intended use-case: providing simple shortcuts and on-page doodads which make the user's life easier. It's a great pattern if design requirements don't demand any interaction with the Server...

When you get down to it, the core Server-Side and Client-Side UI Action types actually have very little functional overlap. This is something of a problem, because it is extremely common for designers to desire functionality from both paradigms in the same UI Action!

"Combo" UI Actions: Two For One... Sort Of?

"Combo UI Action" is a term of art invented for the purposes of this article. It's an undocumented yet common variant of the Client-Side UI Action which cleverly sneaks in the ability to execute Server-Side code – almost as if there were actually two different UI Actions belonging to the same button: one Client-Side, one Server-Side. Emphasis on "different"! There's a lot to unpack here, so let's first take a peek at the code...

This technique allows for writing some code which runs client-side and some code which runs Server-Side. It sounds more useful than it actually is – the Server-Side code and the Client-Side code are completely isolated from each other and cannot communicate!

This approach is useful if the intent is to attach some Client-Side pre-validation to an otherwise independent Server-Side UI Action... but it completely falls flat if, for example, the designer wishes to prompt the user for input and then handle that user-provided input via Server-Side code. It really is like have two completely separate UI Actions attached to the same user-facing button – the streams cannot be crossed!

Time for a detour: how does this trick actually work? This is important: even if you've used this pattern before, it's important to understand the underlying mechanics!

Let's start by examining how Server-Side UI Actions internally function:

1. User clicks the button.
2. Button triggers the following client-side code gsftSubmit(this)
3. The g_form is HTTP POSTed to the Server.
4. Code in the "Script" field is triggered on the Server to process the form data.

Steps 1-3 are abstracted away and hidden from the designer, but they exist nevertheless! Now that we understand the mechanics, we can start to appreciate how surprisingly similar Client-Side UI Actions are under the hood:

1. Code in the "Script" field is smuggled into the HTML page during initial load.
2. User clicks the button.
3. Button triggers client-side code from the "On Click" field
   (traditionally, this is used to call one of the functions smuggled in during Step 1)

Client-Side UI Actions essentially have two special traits:

• A copy of your "Script" code gets smuggled into the HTML page.
• Instead of defaulting to gsftSubmit(this) it uses your "On Click" code.

That's it! These two changes alone are what make the two types different. Should one desire, it's entirely possible to create a fake "Client-Side UI Action" that's actually identical to a Server-Side UI Action by simply setting the "On Click" field to gsftSubmit(this) – recall that this is what would've happened automatically were "Client" left unchecked!

Technically this hack does cause an ugly looking error to pop up in the browser console (it tried and failed to run some smuggled Server-Side code)... but we can get around the issue if we just wrap the Server-Side code in a protective IF statement!

Yup. That's the origin of the weird if (typeof window === 'undefined'). Neat!

AJAX: The Only Route to True Interactivity?

Time for the elephant in the room. All of these patterns are nice... but they don't actually handle the most common use-case for Client-Side UI Actions: prompting the user for input and then using this input in Server-Side code. Historically, this has been the stomping ground of what we'll call "AJAX UI Actions".

"AJAX" in the context of ServiceNow specifically refers to a type of Script Include which can be remotely triggered from Client-Side scripts via the GlideAjax API. It's the bog-standard approach to writing Server-Side code which can be remotely executed via Client-Side scripting.

Frustratingly, adding even a small amount of AJAX to a given UI Action can double or even triple total lines of code. Perhaps even more annoyingly: AJAX Script Includes are slow – UI AJAX Actions can be forced to wait for several seconds mid-execution while the Server thinks!

Despite these flaws, it is undeniable that AJAX Script Includes are incredibly useful tools whenever a requirement to dynamically interact back-and-forth with the Server based on user input arises...

Even so, isn't it kind of overkill if all that's needed is a one-way conversation that starts on the Client-Side and ends on the Server-Side? Why can't there be a happy middle with the simplicity of the "Combo UI Action" pattern for those usecases?

"One-Way" UI Actions: A New Way

We are proud to present a novel UI Action design pattern which achieves exactly this: the simplicity of "Combo UI Actions" + the Client/Server communication. A sort of "One-Way" connection which enables collecting user input on the Client-Side and then punts it over to the Server-Side for processing!

We've effectively extended the aforementioned "Combo UI Action" solution by exploiting the HTTP form submission as a medium for data transport. This tweak eliminates the single greatest limitation of the "Combo UI Action" and unlocks the ability to elegantly handle many User/Server interactions which were previously only possible via AJAX Script Includes!

As you've probably noticed, this new approach brings new limitations:

• Higher complexity than the traditional "Combo UI Action" pattern.
• Server-Side only starts after Client-Side ends – No back-and-forth.

In other words: this isn't a perfect solution – don't reach for it unless it fits the usecase! Some rules of thumb to consider:

• If it's not necessary to pass data from Client-Side to Server-Side, use the simpler "Combo UI Action" pattern.
• If it's necessary to make multiple request/interaction cycles within a single UI Action, use the more powerful "AJAX Script Include" design pattern.

Copyable Templates 🤓

The initial example presented is designed for maximum compatibility – it works regardless of whether the UI Action is present on a list or form page at the cost of extra boilerplate. The required boilerplate is halved if you don't need list compatibility!

Templates for common usecases such as Form-Only, List-Only, and Form+List are available for copying via this gist.

Most organizations have teams that support the infrastructure that keeps the actual servers up and running and often have event monitoring in place to ensure uptime and availability. However, it's always nice to have additional options and safeguards in place. Here are a few simplistic ways to keep tabs on your MID Server (most of which are already out-of-the-box and require minimal setup).

The ServiceNow instance sends a synthetic transaction via the Heartbeat probe to the MID Servers every five minutes. If the instance doesn’t detect a response from a MID Server, that server is marked as down. This will be important to keep in mind for the methods listed below. The heartbeat frequency can be adjusted by changing the scheduled job “MID Server Monitor.”

Here are some ways to keep tabs on your MID Server:

1. Notification: The MID Server table (ecc_agent) has a prebuilt notification that is out-of-the-box (OOB). All you need to do is provide a recipient. The notification fires when the MID Server status changes to "Down." This notification is already activated but doesn't know who to send it to. Simply navigate to it and provide a recipient.
2. Lifecycle Event [mid_server_event]: This recently introduced table tracks MID Server events such as up, down, upgrading, invalidated, validated, and removed. This table gives you more of a timeline view of the state (including dates/times) compared to the MID Server table (ecc_agent), which only provides the current status. Access this table via direct navigation (mid_server_event.list), the left navigation (MID Server > Profiles and Deployments > MID Server Lifecycle Events), or the UI action on a MID Server labeled "Lifecycle Events" in the Related Links section.
3. Resource Threshold Alerts: These alerts help monitor allocated CPU and memory. The configured alerts push data into the MID Server Issue (ecc_agent_issue) table. This method provides insight into potential issues before they impact your server’s performance.
4. Application Insights: While this feature is being prepared for future deprecation in Xanadu, it’s worth mentioning if you need to trigger flows based on ECC queue thresholds. Application Insights is the best way to do this. You can request and install it via the ServiceNow Store, but you will need to request MetricBase via Support in order to use Application Insights. Once installed, you can set up thresholds based on specific ECC metrics you’re concerned with. This is a more advanced type of monitoring because it does more than simple lifecycle event tracking.
5. Event Management: If you are licensed for ITOM Event Management, you can leverage its framework to monitor the MID Server and other areas of event management. Navigate to Event Management > Administration > Self-Health Monitoring. Many monitoring configurations exist out-of-the-box, but we are specifically going to look at the “MID Server Threshold Alerts.” These alerts create events and alerts based on how you’ve configured Event Management. You can use flows and other automations to create incidents or other ticket types based on your needs.

For any of the methods listed above that place data into a table, you can take a variety of approaches based on complexity to meet your monitoring needs:

1. Notifications
2. Business Rules, Flows, or Workflows
   a. Use these to trigger notifications
   b. Create incidents or create/update other ticket types
3. Dashboards

It works everywhere server-side code runs. Even in the Global scope without using the new "Turn on ECMAScript 2021 (ES12) mode" button.

How can this be??

Those of you following recent ServiceNow releases have probably already (correctly) intuited that this new development must be somehow related to the recent introduction of the new "ES12" JavaScript Mode. This is true... to an extent.

Internally, ServiceNow uses an ancient JavaScript engine known as Rhino. Rhino doesn't support most ES12 features, yet ServiceNow still somehow supports ES12... How is ServiceNow pulling off that magic trick? In short: Transpilation. Transpilers automatically convert modern code into legacy-compatible code – ServiceNow has a built-in auto-transpiler which automatically converts code wherever "ES12" mode has been enabled.

So, is that what's going on here? Did ServiceNow accidentally turn on their magic transpilation step everywhere and somehow never notice? Nope! That's definitely not the case because many other ES12 JavaScript features available remain unusable.

So... what's going on here, if not transpilation? The answer is actually rather simple: ServiceNow's version of Rhino has been upgraded to a newer release – first 1.7.12 in Washington, then 1.7.14 in Xanadu.

We can prove this by checking if Array.prototype.includes is available. This is a newer Array method which only gained support starting in Rhino version 1.7.12.

The proof is in the pudding. As you can see below: Rhino has gained native support for many new language features which were previously impossible!

This long-overdue engine update can be chalked up to a happy side-effect of ServiceNow's ongoing work on the new "ES12" JavaScript transpilation mode:
More engine features => Less transpilation => Better performance & accuracy

What's The Catch?

The catch is that Rhino is still an old engine without full ES12 support. Even if some new features have become available, >50% of all modern JavaScript features are still unavailable to Rhino. In other words: most modern features are still locked behind transpilation (i.e. "ES12" mode), Rhino upgrade notwithstanding.

How do I know what's newly available in my Instance?

Our research indicates two recent upgrades to the Rhino engine:

• Washington: Rhino 1.7.12
• Xanadu: Rhino 1.7.14

Consulting this table, search for any features which were red in 1.7R5 and now green in your instance's Rhino version (see directly above). Easy peasy!

Not so easy? Well, dear reader, this must be your lucky day because as a special gift just for you I've already compiled a list and snuck it in right below 😁

• Method Shorthand
  { foo(){ return 'foo!'; } } vs { foo: function(){ return 'foo!'; } }
• Arrow Functions
  (foo) => foo.explode()
• Template Literals (Xanadu+)
  `One plus one equals ${ 1 + 1 }. Two plus two equals ${ 2 + 2 }`
• Array.from
  Array.from('foo') // ['f', 'o', 'o']
• Array.of
  Array.of(1, 2, 3) // [1, 2, 3]
• Array.prototype.copyWithin
  [0, 1, 2, 3, 4, 5].copyWithin(2, 0, 2) // [0, 1, 0, 1, 2, 5]
• Array.prototype.includes
  [1, 2, 3].includes(2) // true
• Array.prototype.find
  [1, 2, 3, 4].find((x) => x > 2) // 3
• Array.prototype.findIndex
  ['a', 'b', 'c'].find((x) => x.startsWith('b')) // 1
• Array.prototype.fill
  [1, 2, 3, 4, 5, 6].fill('X', 2, 4) // [1, 2, 'X', 'X', 'X', 6]
• Math.cbrt
  Math.cbrt(64) // 4 (cube root)
• Math.clz32
  Math.clz32(1) // 31 (number of leading zeroes in 32-bit binary)
• Math.cosh
  Math.cosh(2) // 3.7621956910836314 (hyperbolic Math.cos)
• Math.acosh
  Math.acosh(2) // 1.3169578969248166 (hyperbolic Math.acos)
• Math.expm1
  Math.expm1(1) // 1.718281828459045 (Math.exp(X) - 1)
• Math.hypot
  Math.hypot(3, 4) // 5 (hypotenuse)
• Math.imul
  Math.imul(3, 3.5) // 9 (integer multiplication)
• Math.log10
  Math.log10(1000) // 3 (base-10 logarithm)
• Math.log2
  Math.log2(8) // 3 (base-2 logarithm)
• Math.sign
  Math.sign(-10) // -1
• Math.sinh
  Math.sinh(2) // 3.626860407847019 (hyperbolic Math.sin)
• Math.asinh
  Math.asinh(2) // 1.4436354751788103 (hyperbolic Math.asin)
• Math.tanh
  Math.tanh(1) // 0.7615941559557649 (hyperbolic Math.tan)
• Math.atanh
  Math.atanh(0.5) // 0.549306144334055 (hyperbolic Math.atan)
• Math.fround
  Math.fround(5.05) // 5.050000190734863 (round to single precision)
• Math.trunc
  Math.trunc (9.99) // 9
• Number.EPSILON (Xanadu+)
  Number.EPSILON // 2.220446049250313e-16
• Number.MAX_SAFE_INTEGER
  Number.MAX_SAFE_INTEGER // 9007199254740991
• Number.MIN_SAFE_INTEGER
  Number.MIN_SAFE_INTEGER // -9007199254740991
• Number.isFinite
  Number.isFinite(Infinity) // false
• Number.isInteger
  Number.isInteger(0.5) // false
• Number.isSafeInteger
  Number.isSafeInteger(Number.MAX_SAFE_INTEGER + 1) // false
• Number.isNaN
  Number.isNaN(NaN) // true
Number.isNaN('foo') // false (unlike global.isNaN)
• Number.parseFloat
  Number.parseFloat('123.456') // 123.456 (same as global.parseFloat)
• Number.parseInt
  Number.parseFloat('123') // 123 (same as global.parseInt)
• Object.assign
  var foo = { a: 1, b: 2 };
Object.assign(foo, { c: 3 }); // foo becomes { a: 1, b: 2, c: 3 };
• Object.is
  Object.is(-0, +0) // false, unlike a === check
• String.fromCodePoint (Xanadu+)
  String.fromCodePoint(9733) // '★'
• String.raw (Xanadu+)
  String.raw`¯\_(ツ)_/¯` // '¯\_(ツ)_/¯' (No escape necessary!)
• String.prototype.codePointAt
  '☃★♲'.codePointAt(1) // 9733
• String.prototype.includes
  'foobar'.includes('oba') // true
• String.prototype.normalize
  '\u00F1'.normalize('NFC') === '\u006E\u0303'.normalize('NFC') // true
• String.prototype.padStart
  '12345'.padStart(8, '0') // '00012345'
• String.prototype.padEnd
  '12345'.padEnd(8, '0') // '12345000'
• String.prototype.repeat
  'the end is never '.repeat(2) // 'the end is never the end is never'
• String.prototype.startsWith
  'foobar'.startsWith('foo') // true
• String.prototype.endsWith
  'foobar'.startsWith('bar') // true

While previously it was regarding the Oracle Cloud HCM - ServiceNow Integration Hub Spoke, this time it was the Key Management Framework. A customer had issues authenticating with their other tools after a clone down process, and we were on the hook to figure it out. ServiceNow Support had suggested running a Resource Exchange Request, and that's where we had most of our issues.

What is a Resource Exchange Request?

Since each instance uses a different encryption context, the data from Production can't be read by Dev or Test, until the Keys are exchanged from Prod (Source) to Dev or Test (Target).

If your instances are using the KMF, then you'll need to run this after each clone, if its not run automatically (based on the glide_encryption.auto_key_exchange.enabled property).

The steps in this article are missing some pertinent details, so this is my attempt to add some clarity.

Roles

• You need the "sn_kmf.cryptographic_manager" role in order to see the links the left hand nav
  • You can't give yourself the "sn_kmf.cryptographic_manager" role unless you have the "sn_kmf.admin" role.
    • You can't give yourself the "sn_kmf.admin" role unless you have the "security_admin" role.
      • Once you have the "security_admin" role, you need to click on the "Key Management Administration" LHN link to bring you to this role assignment page

Yes, even if you start off with security_admin, you still need to log in and out two more times.

Creating the Request (in the target instance)

• Exchange Frequency: Choose ad-hoc
• Crypto Specifications
  • We had 36 different ones. You can select them all on this one request form, but you do have to select them all individually.
• Once you're done, use this client-side snippet so you can keep the values for another instance
• copy(g_form.getValue("u_crypto_specification_list"))
• Do NOT right-click save. I couldn't figure out why these weren't sending until getting on the phone with ServiceNow Support. When you are creating these records you HAVE to click "Submit Request".

• Once the request is submitted, individual requests will be created for each specific Crypto Specifications.

Approving the Request (in the source instance)

• If there are a lot of requests, it may take some time for them to show up in the source instance.
  • Some Crypto specifications won't be found in the source instance, and that's ok. Those won't need to be approved. Here you'll only focus on the ones that are "Pending Approval'.
  • Out of the 36 that we requested, only 15 were found in the source instance.
• You'll need to approve each individual crypto specification.
• Similarly, when you approve the request you need to change the Status to "Request Approved" manually, and then click "Update Request". DO NOT click Update.

Confirming the Request (in the target instance)

• Once a request is approved in the source instance, you should see the request in the target instance also move to a status of Request Approved with a few minutes.
• Out of the 15 requests that were approved, we had one request that gave a status of "Error on Local Instance". But when we re-requested it again, it was able to be sent and approved successfully.

Other Options

If a key exchange isn't a viable option for you or your customer, then you can also have the option it rekey during the clone instead. Read more here.

The problem

Sometimes it is as easy as plugging in credentials, sometimes it's not. This time it was not. ServiceNow has great documentation, especially compared to other solutions. It's part of what makes them the king. But that's also what makes it so frustrating when they don't have documentation, or their documentation is missing a step. That's what made this integration so hard.

The client needed to integrate with Oracle Cloud HCM, and the ServiceNow Docs (Oracle HCM Cloud Spoke) didn't quite have the detail I needed.

• The set-up has a lot of complex steps, and some that we had to reply on another System Admin for
  • Create a keystore, upload it, create a password, send it to Oracle etc...
  • Give the oracle user the correct roles (like 20 of them)
• The steps referenced a JWT provider and Key, but didn't specifically mention them
• The iss/sub values also weren't specified

What was helpful

• Instead of using an entire flow, we tried testing with just a small part of it
  • The Get Oracle Cloud HCM Object Metadata action, using departments as the test object
• I also tried to use Rapid API (formerly Paw) as an additional option to debug
• I also love using diagrams to help step through ServiceNow's text documentation to ensure I didn't miss a step, and to also see where the output of one activity feeds into another
  • Whimsical is my tool of choice

What were the missing steps:

1. We had to create JWT Provider and Keys (in the Global scope), which wasn't mentioned in the docs
2. Use those values in the Connection configuration
3. Make sure that the provider has the correct iss (Issue entered into Oracle HCM) and sub (User name of account used to log into Oracle HCM) values
4. Make sure the names of the JWT Provider and JWT Keys are unique. They're only referenced by name, but there's some automation that's setting the and that the sn_oracle_hcm_spk.glide.hub.jwtprovidersysid property with a sys_id

Conclusion

Maybe this will help you, but maybe it won't. But I know that next time I encounter this, I would have forgotten everything I learned so that's why I'm writing it down.

Let me know if this did help you, or if you have any questions on this spoke or a similar one. You can reach me at toby@semaphorepartners.com

I am sure you have your own reasons for this type of report, but here are some potential uses:

1. Platform Hygiene
2. Removing fields with little adoption / use
3. Removing tables with little adoption / use
   

The reporting engine doesn't really allow for this type of reporting. But surely this must be possible - right?

The platform has a feature that has a slightly different intended use but can be leveraged to assist with this type of reporting.

Enter sys_column_stats_registry [Column Statistics Registry]. This table is where you specify which table, and which field(s) you want to generate a report for.

1. Specify the table name, if you are working with a table that is extended you will need to input both the parent and child class.
2. Specify a specific field name or use the wildcard * to scan all fields on the table
3. Submit the record and return to the list of records
4. Use the List Related Link: "Collect statistics now" which will invoke a progress worker.

5. Visit the sys_column_stats table to view the collected results. Depending on your table size, this could take some time for the progress worker to complete.

Results

On the sys_column_stats table the statistics are displayed:

Null count: fields with no value set

Not null count: fields with a value set

Cardinality: a count of distinct values in a table

I find it best to join this data with the dictionary data, this way you have access to the field type and the field label.

This is an excellent tool to have. Give it a try and I'd love to hear your use cases for this!

The calculation is actually pretty simple. Most of these sites utilize the adult average word per minutes to calculate the read time. I decided to whip together a quick widget.

HTML Template

I am using a basic bootstrap panel to match the Service Portal/Employee Center theme and styling.

<div class="panel panel-default b">
  <div class="panel-heading text-center">
    <h3>
    {{c.ttr_mins}} {{c.minsLabel}} {{c.readSuffix}}
  </h3>
  </div>
</div>

Client Script

Here is where the logic lives for the actual calculations

api.controller=function() {
  /* widget controller */
  var c = this;
	
	c.minsLabel = c.options.mins_label || "minute";
	c.readSuffix = c.options.read_label_suffix || "read";
	
	var wordsPerMinute = c.options.words_per_minute || 210;
	var kbText = angular.element('.kb-article-content').text();
	var words = kbText.trim().split(/\s+/g).length,
			wps = wordsPerMinute / 60,
			readingTimeSeconds = words / wps,
			mins = Math.floor(readingTimeSeconds / 60),
			seconds = Math.round(readingTimeSeconds % 60)
	
	c.ttr_mins = mins;

};

That is pretty much it, I would love to hear if this is useful or if you have any potential suggestions for improvements.

How to use

1. Download the widget XML and import it or copy paste the HTML & Client Script above.
2. Add the widget to your Knowledge page (typically kb_article or esc_kb_article) here is the link to the designer page /$spd.do#/esc/editor/esc_kb_article_view/6f2c780e1beb0e5000a00fe0604bcb95
3. The widget includes an option schema for changing the words per minute.

Result

Download

Our blog dives deep into the intricacies of ServiceNow, providing expert analysis, practical tips, and real-world case studies to help you navigate and maximize the platform's potential. Whether you're an administrator, developer, or ServiceNow professional, Relay offers valuable perspectives to enhance your ServiceNow journey.

Stay tuned to Relay for regular updates, industry news, and thought leadership that will keep you connected to the pulse of ServiceNow excellence.

Left Hand Navigation

table_name.do - new form in existing frame

table_name.form - new form in existing frame

table_name.list - list in existing frame

table_name.LIST - list in new window

table_name.FILTER - list in new window, but sysparm_filter_only=true

table_name.CONFIG - Configure All in new window

URL Navigation [Fulfiller view]

{TABLE}_list.do?nav_to.do?uri=sysparm_query={QUERY} - List View of a Table

{TABLE}_list.do?sysparm_query={QUERY} - List View of a Table

{TABLE}.do?sys_id={SYS_ID} - Record

{TABLE}.do?sys_id={NUMBER} - Works for most tasks (based on the display value)

URL Navigation [Portal view]

Navigation by Portal

Navigating by Portal Navigating by portal displays the portal including the header, footer, and theme defined by the portal.

{PORTAL_SUFFIX}?id={PAGE} [ex: tickets, sc_home, index]

{PORTAL_SUFFIX}?id={PAGE}&sys_id={RECORD ID} [ex: sc_category, sc_cat_item]

{PORTAL_SUFFIX}?id={PAGE}&sys_id={RECORD ID}&table{table}= [ex: ticket]

Navigating by Page

Navigating by the page excludes the header/footer and theme. This is useful for standalone widget pages.

$sp.do?id={PAGE}&param=1

Other URL Parameters

• sysparm_view use a specific view to load the list or form
• sysparm_filter_only (Do not fetch the list contents useful if the table is large and will take a while to be loaded ex: sys_log, sys_email, etc...)
• sysparm_order specifies field to sort by
• sysparm_order_direction specifies the sorting direction (desc, asc)
• sysparm_group_sort sort a list that is grouped (COUNT, COUNTDESC)

URL Navigation [Workspaces/Experiences]

Workspaces have a similar but slightly different pattern, additionally since pages and parameters are defined on page by page level, they differ between workspaces.

Base Workspace/Experience Suffix:

Workspaces created by ServiceNow will have the /now/ suffix appended after the instance URL.

/now/{WS_SUFFIX}/{PAGE_ID}/{TABLE}/{SYS_ID} [ex: /now/sow/record/interaction/a513653f1bcd0e1000a00fe0604bcbe2]

A way to easily join a related table into an existing query

Some examples

• Users with 1+ Open Incident
  • /sys_user_list.do?sysparm_query=RLQUERYincident.caller_id,>=1^active=true^ENDRLQUERY
• Users with 0 Active Incidents
  • /sys_user_list.do?sysparm_query=RLQUERYincident.caller_id,=0^active=true^ENDRLQUERY
• Users with >1 Computer Assigned to Them
  • /sys_user_list.do?sysparm_query=RLQUERYcmdb_ci_computer.assigned_to,>1^ENDRLQUERY

How do I get to them?

I’m not as familiar with the structure of them yet, so instead of writing them from memory, I usually build them in the Reporting module first and then copy and paste it wherever I need them.

1. Go to a list view, and jump from that query into the reporting module by clicking “Bar Chart” or “Pie Chart”
2. Once you’re there, expand the filter to show the “Related List Conditions” section
3. Run the report
4. Click on a bar to jump back into the list view
5. Right-click and copy the query and paste wherever you need it

active=true^RLQUERYincident.caller_id,>=1^active=true^ENDRLQUERY^active=1

How are they structured?

RLQUERY${RELATED_TABLE}.${RELATED_FIELD_NAME},${OPERATOR}${LIMIT}^ENDRLQUERY

Example:

RLQUERYincident.caller_id,>=1^active=true^ENDRLQUERY

RELATED_TABLE: The related table you’re looking to join from (ex: incident)

RELATED_FIELD_NAME: The table you’re looking to query from, this should point to the table you’re querying from (ex: caller_id)

OPERATOR: >, >= , =, <, <=

LIMIT: Can be any number

Do they work everywhere?

Kind of. They work via the URL, and they work in scripts. I’ve even used them in Performance Analytics Indicators and Indicator Sources.

However, I’ve had mixed success using them in Reference Qualifiers. As it turns out, if you’re using them in a Reference Qualifier you can ONLY use the Related List Query.

For example, this won’t work as a reference qualifier for the sys_user table. This would instead show all active users.

active=true^RLQUERYincident.caller_id,>=1^active=true^ENDRLQUERY

But this will work as a reference qualifier for the sys_user table

RLQUERYincident.caller_id,>=1^active=true^ENDRLQUERY^EQ

Out of box, there’s 17 different notifications for the incident table. What are they for? What do they look like? Who do they go to? When do they go out? Do you want to open all 17 pages and preview them one by one in 17 different tabs? Probably not!

This helper will show you all of them on one page so you can review them to ensure you have consistent content, triggers, links for all of your notifications.

What does it do?

• Previews multiple notifications from one page

What’s in it?

• Portal Page (ndoc)
• Widget (notification_doc)
• And all the other good stuff so that the Widget shows up on the Page
  • Instance
  • Container
  • Row
  • Column

How do I get it?

1. Install attached Update Set (Notification Helper 2024)
2. Navigate to it via URL: /sp_config?id=ndoc&q=QUERY
   1. For example: All Incident notifications that go to the Caller: /sp_config?id=ndoc&q=collection%3Dincident%5Eactive%3Dtrue%5Erecipient_fieldsLIKEcaller_id

Download