Variable Management

Service Catalog Variable Management

Overview

This skill covers comprehensive catalog variable management:

• All variable types and when to use each
• Creating and configuring variables
• Reference qualifiers for filtering options
• Cascading/dependent variables
• UI policies for show/hide/mandatory logic
• Variable choices (question_choice table)
• Variable sets for reusability

When to use: When building catalog forms, implementing dynamic form behavior, or troubleshooting variable issues.

Prerequisites

• Roles: catalog_admin or admin
• Access: itemoptionnew, questionchoice, catalogui_policy tables
• Knowledge: Basic catalog structure
• Related Skills: catalog/item-creation for full item configuration

Procedure

Step 1: Understand Variable Types

CRITICAL: Variable types are numeric values stored in the type field.

Complete Variable Type Reference:

| Type | Value | Use Case | Example | |------|-------|----------|---------| | Single Line Text | 16 | Short text input | Names, titles, codes | | Multi-Line Text | 6 | Long text | Descriptions, notes, justifications | | Choice (Radio) | 1 | 2-5 options, visible at once | Priority, Yes/No/Maybe | | Select Box (Dropdown) | 5 | 6+ options or long labels | Department, Location | | Reference | 8 | Link to ServiceNow record | User, CI, Group | | Yes/No | 7 | Boolean toggle | Checkboxes, toggles | | CheckBox | 7 | Same as Yes/No | Acceptance, agreement | | Date | 9 | Date picker | Start date, due date | | Date/Time | 10 | Date and time picker | Meeting time, deadline | | Email | 32 | Email validation | Contact email | | URL | 26 | URL validation | Website, link | | Numeric Scale | 2 | 1-10 rating | Satisfaction, priority | | Lookup Select Box | 21 | Filtered reference dropdown | Filtered users/CIs | | Container Start | 19 | Group variables visually | Section header | | Container End | 20 | End container group | Section footer | | Label | 11 | Display-only text | Instructions, warnings | | Break | 12 | Visual separator | Line break | | Macro | 14 | UI macro execution | Custom widgets | | Masked | 25 | Password-style input | Sensitive data | | HTML | 17 | Rich text/HTML display | Formatted instructions | | Wide Text | 6 | Same as Multi-Line | Legacy | | IP Address | 27 | IP address validation | Network config | | Duration | 29 | Time duration | SLA duration | | Attachment | 15 | File upload | Documents, images | | List Collector | 22 | Multi-select reference | Multiple users/groups | | Lookup Multiple Choice | 23 | Multi-select filtered | Multiple filtered refs |

Step 2: Create Basic Variables

Single Line Text Variable:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "employee_name"
    question_text: "Employee Full Name"
    type: 16
    order: 100
    mandatory: true
    active: true
    help_text: "Enter the employee's full legal name as it appears on their ID"
    example_text: "John A. Smith"
    default_value: ""

Multi-Line Text Variable:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "business_justification"
    question_text: "Business Justification"
    type: 6
    order: 200
    mandatory: true
    active: true
    help_text: "Explain why this request is needed for business operations"

Date Variable:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "required_by_date"
    question_text: "Required By Date"
    type: 9
    order: 300
    mandatory: true
    active: true

Step 3: Create Choice Variables

CRITICAL: Catalog variable choices use question_choice table, NOT sys_choice!

Type 1 - Choice (Radio Buttons): Best for 2-5 options that users need to see at once.

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "urgency_level"
    question_text: "Request Urgency"
    type: 1  # Radio buttons
    order: 400
    mandatory: true
    active: true

Type 5 - Select Box (Dropdown): Best for 6+ options or options with long labels.

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "department"
    question_text: "Department"
    type: 5  # Dropdown
    order: 500
    mandatory: true
    active: true
    include_none: false  # Don't show "-- None --" option

Add Choices to Variable:

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]  # item_option_new sys_id
    text: "Engineering"
    value: "engineering"
    order: 100
    inactive: false

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]
    text: "Marketing"
    value: "marketing"
    order: 200
    inactive: false

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]
    text: "Finance"
    value: "finance"
    order: 300
    inactive: false

Query Variable Choices:

Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[variable_sys_id]
  fields: sys_id,text,value,order,inactive
  limit: 100

Step 4: Create Reference Variables

Basic Reference Variable:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "requested_for"
    question_text: "Request For (User)"
    type: 8  # Reference
    reference: sys_user  # Target table
    order: 100
    mandatory: true
    active: true

Reference with Qualifier (Filter):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "manager_approval"
    question_text: "Manager for Approval"
    type: 8
    reference: sys_user
    reference_qual: "active=true^rolesLIKEmanager"
    order: 200
    mandatory: true
    active: true

Reference Qualifier Examples: | Use Case | Reference Qual | |----------|---------------| | Active users only | active=true | | Users in specific group | sys_idIN | | Active CIs | install_status=1 | | Specific CI class | sys_class_name=cmdb_ci_server | | Servers in location | location=[location_sys_id]^sys_class_name=cmdb_ci_server |

Dynamic Reference Qualifier (JavaScript):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "team_member"
    question_text: "Team Member"
    type: 8
    reference: sys_user
    reference_qual: "javascript:new MyCatalogUtils().getTeamMembers(current.variables.department)"
    order: 300
    mandatory: true
    active: true

Step 5: Create Cascading/Dependent Variables

Cascading variables change based on another variable's selection.

Example: Department -> Team cascade

Step 1 - Create Parent Variable (Department):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "department"
    question_text: "Department"
    type: 5
    order: 100
    mandatory: true
    active: true
# Result: sys_id = "dept_var_id"

Step 2 - Create Child Variable (Team):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "team"
    question_text: "Team"
    type: 5
    order: 200
    mandatory: true
    active: true
    dependent_on_variable: "dept_var_id"  # Parent variable sys_id
# Result: sys_id = "team_var_id"

Step 3 - Add Choices with Dependencies:

# Engineering teams
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Frontend Engineering"
    value: "frontend"
    order: 100
    inactive: false
    depends_on: "engineering"  # Value of parent choice

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Backend Engineering"
    value: "backend"
    order: 200
    inactive: false
    depends_on: "engineering"

# Marketing teams
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Digital Marketing"
    value: "digital"
    order: 100
    inactive: false
    depends_on: "marketing"

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "team_var_id"
    text: "Brand Marketing"
    value: "brand"
    order: 200
    inactive: false
    depends_on: "marketing"

Step 6: Create UI Policies

UI policies control variable visibility, mandatory status, and read-only state based on conditions.

IMPORTANT: UI Policy Actions cannot be fully linked via REST API due to ServiceNow limitations. The catalog_variable field won't update through standard API calls.

Create UI Policy:

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show manager approval when cost > 1000"
    active: true
    on_load: true
    reverse_if_false: true
    script_false: ""
    script_true: ""
    order: 100

UI Policy Conditions: Conditions are evaluated against catalog item variables.

Create UI Policy with Conditions:

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show additional details for external vendors"
    conditions: "vendor_type=external"  # Variable name = value
    active: true
    on_load: true
    reverse_if_false: true
    order: 200

UI Policy Action Fields: | Action | Description | |--------|-------------| | visible | Show/hide the variable | | mandatory | Make variable required | | disabled | Make variable read-only |

Create UI Policy Action:

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [ui_policy_sys_id]
    catalog_variable: "IO:[variable_sys_id]"  # Must use IO: prefix
    visible: true
    mandatory: true
    disabled: false

Known Issue - UI Policy Action Linking: The catalog_variable field may not link properly via REST API.

Workaround - Background Script:

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    var gr = new GlideRecord('catalog_ui_policy_action');
    gr.get('[action_sys_id]');
    gr.setValue('catalog_variable', 'IO:[variable_sys_id]');
    gr.update();
    gs.info('Updated UI policy action: ' + gr.sys_id);
  description: "Link UI policy action to catalog variable"

Step 7: Configure Variable Sets

Variable sets group reusable variables across multiple catalog items.

Create Variable Set:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new_set
  data:
    title: "Standard Requester Information"
    description: "Common requester fields used across all hardware requests"
    active: true
    type: "one_to_one"  # Each item gets unique variable instances
    order: 100

Variable Set Types: | Type | Description | |------|-------------| | onetoone | Variables cloned per item (independent values) | | onetomany | Variables shared across items (same record) |

Add Variables to Variable Set:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    variable_set: [variable_set_sys_id]  # Instead of cat_item
    name: "cost_center"
    question_text: "Cost Center"
    type: 16
    order: 100
    mandatory: true
    active: true

Associate Variable Set with Catalog Item:

Tool: SN-Create-Record
Parameters:
  table_name: io_set_item
  data:
    sc_cat_item: [catalog_item_sys_id]
    variable_set: [variable_set_sys_id]
    order: 100

Step 8: Advanced Variable Configuration

Hidden Variable (for workflow data):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "internal_tracking_id"
    question_text: "Tracking ID"
    type: 16
    order: 9999
    mandatory: false
    active: true
    hidden: true  # Not visible to users
    read_only: true

Read-Only Variable (display only):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "calculated_cost"
    question_text: "Estimated Cost"
    type: 16
    order: 800
    mandatory: false
    active: true
    read_only: true
    default_value: "$0.00"

Variable with Attributes:

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "quantity"
    question_text: "Quantity"
    type: 16
    order: 600
    mandatory: true
    active: true
    attributes: "min=1,max=100,step=1"  # HTML5 validation

List Collector (Multi-Select Reference):

Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: [catalog_item_sys_id]
    name: "additional_users"
    question_text: "Additional Users for Access"
    type: 22  # List Collector
    reference: sys_user
    reference_qual: "active=true"
    order: 700
    mandatory: false
    active: true

Step 9: Query and Verify Variables

Get all variables for a catalog item:

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=[catalog_item_sys_id]
  fields: sys_id,name,question_text,type,order,mandatory,active,reference
  limit: 100

Get choices for a variable:

Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[variable_sys_id]
  fields: sys_id,text,value,order,depends_on,inactive
  limit: 100

Get UI policies for catalog item:

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy
  query: catalog_item=[catalog_item_sys_id]^active=true
  fields: sys_id,short_description,conditions,on_load,reverse_if_false
  limit: 50

Get variable sets for catalog item:

Tool: SN-Query-Table
Parameters:
  table_name: io_set_item
  query: sc_cat_item=[catalog_item_sys_id]
  fields: sys_id,variable_set.title,order
  limit: 50

Complete Example: Hardware Request Form

# 1. Create container for requester info
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "requester_section"
    question_text: "Requester Information"
    type: 19  # Container Start
    order: 100
    active: true

# 2. Requested For
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "requested_for"
    question_text: "Requested For"
    type: 8
    reference: sys_user
    reference_qual: "active=true"
    order: 110
    mandatory: true
    active: true

# 3. Department (dropdown)
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "department"
    question_text: "Department"
    type: 5
    order: 120
    mandatory: true
    active: true
# Result: sys_id = "dept_id"

# Add department choices
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "dept_id"
    text: "Engineering"
    value: "eng"
    order: 100

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "dept_id"
    text: "Sales"
    value: "sales"
    order: 200

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "dept_id"
    text: "Finance"
    value: "fin"
    order: 300

# 4. End requester section
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "request

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Happy-Technologies-LLC](https://github.com/Happy-Technologies-LLC)
- **Source:** [Happy-Technologies-LLC/happy-platform-skills](https://github.com/Happy-Technologies-LLC/happy-platform-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.