# Variable Management

> Complete guide to catalog variables including all types, reference qualifiers, cascading variables, and UI policies

- **Type:** Skill
- **Install:** `agentstack add skill-happy-technologies-llc-happy-platform-skills-variable-management`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Happy-Technologies-LLC](https://agentstack.voostack.com/s/happy-technologies-llc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Happy-Technologies-LLC](https://github.com/Happy-Technologies-LLC)
- **Source:** https://github.com/Happy-Technologies-LLC/happy-platform-skills/tree/main/skills/catalog/variable-management

## Install

```sh
agentstack add skill-happy-technologies-llc-happy-platform-skills-variable-management
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:** item_option_new, question_choice, catalog_ui_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 |
|------|-------------|
| one_to_one | Variables cloned per item (independent values) |
| one_to_many | 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-happy-technologies-llc-happy-platform-skills-variable-management
- Seller: https://agentstack.voostack.com/s/happy-technologies-llc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.