UI Builder Patterns for ServiceNow
UI Builder (UIB) is ServiceNow's modern framework for building Next Experience workspaces and applications.
UI Builder Architecture
Component Hierarchy
UX Application
└── App Shell
└── Chrome (Header, Navigation)
└── Pages
└── Variants
└── Macroponents
└── Components
└── Elements
Key Concepts
| Concept | Description | | ---------------- | -------------------------------------------- | | Macroponent | Reusable container with components and logic | | Component | UI building block (list, form, button) | | Data Broker | Fetches and manages data for components | | Client State | Page-level state management | | Event | Communication between components |
Page Structure
Page Anatomy
Page: incident_list
├── Variants
│ ├── Default (desktop)
│ └── Mobile
├── Data Brokers
│ ├── incident_data (GraphQL)
│ └── user_preferences (Script)
├── Client States
│ ├── selectedRecord
│ └── filterActive
├── Events
│ ├── RECORD_SELECTED
│ └── FILTER_APPLIED
└── Layout
├── Header (macroponent)
├── Sidebar (macroponent)
└── Content (macroponent)
Data Brokers
Types of Data Brokers
| Type | Use Case | Example | | ------------- | ----------------- | ------------------ | | GraphQL | Table queries | Incident list | | Script | Complex logic | Calculated metrics | | REST | External APIs | Weather data | | Transform | Data manipulation | Format dates |
GraphQL Data Broker
// Data Broker: incident_list
// Type: GraphQL
// Query
query ($limit: Int, $query: String) {
GlideRecord_Query {
incident(
queryConditions: $query
limit: $limit
) {
number { value displayValue }
short_description { value }
priority { value displayValue }
state { value displayValue }
assigned_to { value displayValue }
sys_id { value }
}
}
}
// Variables (from client state or props)
{
"limit": 50,
"query": "active=true"
}
Script Data Broker (ES5)
// Data Broker: incident_metrics
// Type: Script
;(function execute(inputs, outputs) {
var result = {
total: 0,
byPriority: {},
avgAge: 0,
}
var gr = new GlideRecord("incident")
gr.addQuery("active", true)
gr.query()
var totalAge = 0
while (gr.next()) {
result.total++
// Count by priority
var priority = gr.getValue("priority")
if (!result.byPriority[priority]) {
result.byPriority[priority] = 0
}
result.byPriority[priority]++
// Calculate age
var opened = new GlideDateTime(gr.getValue("opened_at"))
var now = new GlideDateTime()
var age = gs.dateDiff(opened, now, true)
totalAge += parseInt(age)
}
if (result.total > 0) {
result.avgAge = Math.round(totalAge / result.total / 3600) // hours
}
outputs.metrics = result
})(inputs, outputs)
Client State Parameters
Defining Client State
// Page Client State Parameters
{
"selectedIncident": {
"type": "string",
"default": ""
},
"filterQuery": {
"type": "string",
"default": "active=true"
},
"viewMode": {
"type": "string",
"default": "list",
"enum": ["list", "card", "split"]
},
"selectedRecords": {
"type": "array",
"items": { "type": "string" },
"default": []
}
}
Using Client State in Components
// In component configuration
{
"query": "@state.filterQuery",
"selectedItem": "@state.selectedIncident"
}
// Updating client state via event
{
"eventName": "NOW_RECORD_LIST#RECORD_SELECTED",
"handlers": [
{
"action": "UPDATE_CLIENT_STATE",
"payload": {
"selectedIncident": "@payload.sys_id"
}
}
]
}
Events and Handlers
Event Types
| Event | Trigger | Payload |
| --------------------------------- | --------------- | ----------------- |
| NOW_RECORD_LIST#RECORD_SELECTED | Row click | { sys_id, table } |
| NOW_BUTTON#CLICKED | Button click | { label } |
| NOW_DROPDOWN#SELECTED | Dropdown change | { value } |
| CUSTOM#EVENT_NAME | Custom event | Custom payload |
Event Handler Configuration
// Event: Record Selected
{
"eventName": "NOW_RECORD_LIST#RECORD_SELECTED",
"handlers": [
{
"action": "UPDATE_CLIENT_STATE",
"payload": {
"selectedIncident": "@payload.sys_id"
}
},
{
"action": "REFRESH_DATA_BROKER",
"payload": {
"dataBrokerId": "incident_details"
}
},
{
"action": "DISPATCH_EVENT",
"payload": {
"eventName": "INCIDENT_SELECTED",
"payload": "@payload"
}
}
]
}
Client Script Event Handler (ES5)
// Client Script for custom event handling
;(function (coeffects) {
var dispatch = coeffects.dispatch
var state = coeffects.state
var payload = coeffects.action.payload
// Custom logic
var selectedId = payload.sys_id
// Update multiple states
dispatch("UPDATE_CLIENT_STATE", {
selectedIncident: selectedId,
detailsVisible: true,
})
// Conditional dispatch
if (payload.priority === "1") {
dispatch("DISPATCH_EVENT", {
eventName: "CRITICAL_INCIDENT_SELECTED",
payload: payload,
})
}
})(coeffects)
Component Configuration
Common Components
| Component | Purpose | Key Properties |
| ----------------- | -------------- | --------------------- |
| now-record-list | Data table | columns, query, table |
| now-record-form | Record form | table, sysId, fields |
| now-button | Action button | label, variant, icon |
| now-card | Card container | header, content |
| now-tabs | Tab container | tabs, activeTab |
| now-modal | Modal dialog | opened, title |
Record List Configuration
{
"component": "now-record-list",
"properties": {
"table": "incident",
"query": "@state.filterQuery",
"columns": [
{ "field": "number", "label": "Number" },
{ "field": "short_description", "label": "Description" },
{ "field": "priority", "label": "Priority" },
{ "field": "state", "label": "State" },
{ "field": "assigned_to", "label": "Assigned To" }
],
"pageSize": 20,
"selectable": true,
"selectedRecords": "@state.selectedRecords"
}
}
Form Configuration
{
"component": "now-record-form",
"properties": {
"table": "incident",
"sysId": "@state.selectedIncident",
"fields": ["short_description", "description", "priority", "assignment_group", "assigned_to"],
"readOnly": false
}
}
Macroponents
Creating Reusable Macroponents
Macroponent: incident-summary-card
├── Properties (inputs)
│ ├── incidentSysId (string)
│ └── showActions (boolean)
├── Internal State
│ └── expanded (boolean)
├── Data Broker
│ └── incident_data (uses incidentSysId)
└── Layout
├── now-card
│ ├── Header: @data.incident.number
│ ├── Content: @data.incident.short_description
│ └── Footer: Action buttons
└── now-modal (if expanded)
Macroponent Properties
{
"properties": {
"incidentSysId": {
"type": "string",
"required": true,
"description": "Sys ID of incident to display"
},
"showActions": {
"type": "boolean",
"default": true,
"description": "Show action buttons"
},
"variant": {
"type": "string",
"default": "default",
"enum": ["default", "compact", "detailed"]
}
}
}
MCP Tool Integration
Available UIB Tools
| Tool | Purpose |
| ---------------------------------- | --------------------- |
| snow_create_uib_page | Create new page |
| snow_create_uib_component | Add component to page |
| snow_create_uib_data_broker | Create data broker |
| snow_create_uib_client_state | Define client state |
| snow_create_uib_event | Configure events |
| snow_create_complete_workspace | Full workspace |
| snow_update_uib_page | Modify page |
| snow_validate_uib_page_structure | Validate structure |
Example Workflow
// 1. Create workspace
await snow_create_complete_workspace({
name: "IT Support Workspace",
description: "Agent workspace for IT support",
landing_page: "incident_list",
})
// 2. Create data broker
await snow_create_uib_data_broker({
page_id: pageId,
name: "incident_list",
type: "graphql",
query: incidentQuery,
})
// 3. Add components
await snow_create_uib_component({
page_id: pageId,
component: "now-record-list",
properties: listConfig,
})
// 4. Configure events
await snow_create_uib_event({
page_id: pageId,
event_name: "NOW_RECORD_LIST#RECORD_SELECTED",
handlers: eventHandlers,
})
Best Practices
- Use Data Brokers - Never fetch data directly in components
- Client State for UI - Use for filters, selections, view modes
- Events for Communication - Decouple components via events
- Macroponents for Reuse - Create reusable building blocks
- GraphQL for Queries - More efficient than Script brokers
- Validate Structure - Use validation tools before deployment
- Mobile Variants - Create responsive variants
- Accessibility - Follow WCAG guidelines