---

name: ui-builder-patterns description: This skill should be used when the user asks to "create workspace", "UI Builder", "UIB", "workspace page", "macroponent", "data broker", "UX page", "configurable workspace", or any ServiceNow UI Builder and Next Experience development. license: Apache-2.0 compatibility: Designed for Snow-Code and ServiceNow development metadata: author: groeimetai version: "1.0.0" category: servicenow tools:

• snow_workspace_create
• snow_query_table
• snow_find_artifact
• snow_execute_script_with_output

---

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

CopyUX Application
└── App Shell
    └── Chrome (Header, Navigation)
        └── Pages
            └── Variants
                └── Macroponents
                    └── Components
                        └── Elements

Key Concepts

Page Structure

Page Anatomy

CopyPage: 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

GraphQL Data Broker

Copy// 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)

Copy// 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

Copy// 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

Copy// 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 Handler Configuration

Copy// 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)

Copy// 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

Record List Configuration

Copy{
  "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

Copy{
  "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

CopyMacroponent: 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

Copy{
  "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

Example Workflow

Copy// 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

1. Use Data Brokers - Never fetch data directly in components
2. Client State for UI - Use for filters, selections, view modes
3. Events for Communication - Decouple components via events
4. Macroponents for Reuse - Create reusable building blocks
5. GraphQL for Queries - More efficient than Script brokers
6. Validate Structure - Use validation tools before deployment
7. Mobile Variants - Create responsive variants
8. Accessibility - Follow WCAG guidelines