variable-management

サービスカタログの変数管理

概要

このスキルでは、カタログ変数の包括的な管理方法を説明します。

• すべての変数タイプと、それぞれの用途
• 変数の作成と設定
• 選択肢を絞り込むための参照修飾子
• 連動／依存変数
• 表示／非表示／必須のロジックに関する UI ポリシー
• 変数の選択肢（question_choice テーブル）
• 再利用可能な変数セット

使用する場面： カタログフォームの作成、動的なフォーム動作の実装、変数に関する問題のトラブルシューティングを行う場合です。

前提条件

• ロール： catalog_admin または admin
• アクセス権： item_option_new、question_choice、catalog_ui_policy テーブル
• 知識： カタログの基本的な構造
• 関連スキル： アイテムの完全な設定については catalog/item-creation

手順

Step 1: 変数タイプを理解する

重要： 変数タイプは、type フィールドに格納される数値です。

変数タイプの完全なリファレンス：

タイプ	値	用途	例
単一行テキスト	16	短いテキスト入力	名前、タイトル、コード
複数行テキスト	6	長いテキスト	説明、メモ、根拠
選択肢（ラジオボタン）	1	2～5 個の選択肢を同時に表示	優先度、はい／いいえ／どちらでもない
セレクトボックス（ドロップダウン）	5	6 個以上の選択肢、または長いラベル	部門、場所
参照	8	ServiceNow レコードへのリンク	ユーザー、CI、グループ
はい／いいえ	7	ブール値の切り替え	チェックボックス、切り替え
チェックボックス	7	「はい／いいえ」と同じ	承諾、同意
日付	9	日付ピッカー	開始日、期限
日時	10	日付と時刻のピッカー	会議の時刻、締め切り
メール	32	メールアドレスの検証	連絡先メールアドレス
URL	26	URL の検証	ウェブサイト、リンク
数値スケール	2	1～10 の評価	満足度、優先度
ルックアップセレクトボックス	21	絞り込まれた参照ドロップダウン	絞り込まれたユーザー／CI
コンテナー開始	19	変数を視覚的にグループ化	セクション見出し
コンテナー終了	20	コンテナーグループを終了	セクションのフッター
ラベル	11	表示専用テキスト	手順、警告
区切り	12	視覚的な区切り	改行
マクロ	14	UI マクロの実行	カスタムウィジェット
マスク	25	パスワード形式の入力	機密データ
HTML	17	リッチテキスト／HTML の表示	書式付き手順
ワイドテキスト	6	複数行テキストと同じ	レガシー
IP アドレス	27	IP アドレスの検証	ネットワーク設定
期間	29	時間の長さ	SLA の期間
添付ファイル	15	ファイルのアップロード	ドキュメント、画像
リストコレクター	22	複数選択可能な参照	複数のユーザー／グループ
ルックアップ複数選択	23	絞り込み可能な複数選択	複数の絞り込まれた参照

Step 2: 基本的な変数を作成する

単一行テキスト変数：

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

複数行テキスト変数：

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"

日付変数：

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: 選択肢変数を作成する

重要： カタログ変数の選択肢には sys_choice ではなく、question_choice テーブルを使用します！

タイプ 1 - 選択肢（ラジオボタン）： ユーザーが一度に確認する必要がある選択肢が 2～5 個の場合に最適です。

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

タイプ 5 - セレクトボックス（ドロップダウン）： 選択肢が 6 個以上の場合、または選択肢のラベルが長い場合に最適です。

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

変数に選択肢を追加する：

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

変数の選択肢をクエリする：

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: 参照変数を作成する

基本的な参照変数：

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

修飾子（フィルター）付き参照：

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

参照修飾子の例：

用途	参照修飾子
アクティブなユーザーのみ	active=true
特定のグループに属するユーザー	sys_idIN<group_members_subquery>
アクティブな CI	install_status=1
特定の CI クラス	sys_class_name=cmdb_ci_server
特定の場所にあるサーバー	location=[location_sys_id]^sys_class_name=cmdb_ci_server

動的な参照修飾子（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

ステップ 5：連動変数／依存変数を作成する

連動変数は、別の変数の選択内容に応じて値が変わります。

例：部門 → チームの連動

ステップ 1 - 親変数（部門）を作成する：

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"

ステップ 2 - 子変数（チーム）を作成する：

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"

ステップ 3 - 依存関係を設定して選択肢を追加する：

# 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"

ステップ 6：UI ポリシーを作成する

UI ポリシーは、条件に基づいて変数の表示状態、必須状態、読み取り専用状態を制御します。

重要： ServiceNow の制限により、UI ポリシーアクションは REST API では完全に関連付けられません。catalog_variable フィールドは、標準の API 呼び出しでは更新されません。

UI ポリシーを作成する：

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 ポリシーの条件： 条件はカタログアイテムの変数に対して評価されます。

条件付き UI ポリシーを作成する：

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 ポリシーアクションのフィールド：

アクション	説明
visible	変数を表示／非表示にします
mandatory	変数を必須にします
disabled	変数を読み取り専用にします

UI ポリシーアクションを作成する：

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

既知の問題 - UI ポリシーアクションの関連付け： catalog_variable フィールドは、REST API では正しく関連付けられない場合があります。

回避策 - バックグラウンドスクリプト：

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"

ステップ 7：変数セットを設定する

変数セットは、複数のカタログアイテムで再利用できる変数をグループ化します。

変数セットを作成する：

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

変数セットのタイプ：

タイプ	説明
one_to_one	アイテムごとに変数を複製します（値は独立）
one_to_many	アイテム間で変数を共有します（同じレコード）

変数セットに変数を追加する：

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

変数セットをカタログアイテムに関連付ける：

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

ステップ 8：変数の詳細設定

非表示変数（ワークフローデータ用）：

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

読み取り専用変数（表示のみ）：

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"

属性付き変数：

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

リストコレクター（複数選択の参照）：

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

ステップ 9：変数を照会して確認する

カタログアイテムのすべての変数を取得する：

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

変数の選択肢を取得する：

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

カタログアイテムの UI ポリシーを取得する：

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

カタログアイテムの変数セットを取得する：

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

完全な例：ハードウェアリクエストフォーム

# 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: "requester_section_end"
    question_text: ""
    type: 20  # Container End
    order: 190
    active: true

# 5. Hardware type (radio - 3 options)
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "hardware_type"
    question_text: "Hardware Type"
    type: 1  # Radio buttons
    order: 200
    mandatory: true
    active: true
# Result: sys_id = "hw_type_id"

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "hw_type_id"
    text: "Laptop"
    value: "laptop"
    order: 100

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "hw_type_id"
    text: "Desktop"
    value: "desktop"
    order: 200

Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: "hw_type_id"
    text: "Monitor"
    value: "monitor"
    order: 300

# 6. Business justification
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "justification"
    question_text: "Business Justification"
    type: 6  # Multi-line
    order: 300
    mandatory: true
    active: true

# 7. Required by date
Tool: SN-Create-Record
Parameters:
  table_name: item_option_new
  data:
    cat_item: "hardware_item_id"
    name: "needed_by"
    question_text: "Required By"
    type: 9  # Date
    order: 400
    mandatory: true
    active: true

変数タイプの選択ガイド

Text Input:
├── Short answer (< 100 chars)?
│   └── Type 16: Single Line Text
├── Long answer (> 100 chars)?
│   └── Type 6: Multi-Line Text
└── Sensitive/password?
    └── Type 25: Masked

Selection (from list):
├── 2-5 options, visible at once?
│   └── Type 1: Choice (Radio)
├── 6+ options OR long labels?
│   └── Type 5: Select Box
├── Single ServiceNow record?
│   └── Type 8: Reference
├── Multiple ServiceNow records?
│   └── Type 22: List Collector
└── Filtered reference list?
    └── Type 21: Lookup Select Box

Boolean:
└── Yes/No or Checkbox?
    └── Type 7: Yes/No

Date/Time:
├── Date only?
│   └── Type 9: Date
└── Date and time?
    └── Type 10: Date/Time

Special:
├── Email address?
│   └── Type 32: Email
├── URL/link?
│   └── Type 26: URL
├── IP address?
│   └── Type 27: IP Address
├── File upload?
│   └── Type 15: Attachment
├── Rating (1-10)?
│   └── Type 2: Numeric Scale
└── Time duration?
    └── Type 29: Duration

Display Only:
├── Instructions/info?
│   └── Type 11: Label
├── Rich HTML content?
│   └── Type 17: HTML
└── Visual separator?
    └── Type 12: Break

Layout:
├── Start section?
│   └── Type 19: Container Start
└── End section?
    └── Type 20: Container End

ツールの使用概要

操作	MCP ツール	テーブル
変数を作成	SN-Create-Record	item_option_new
選択肢を作成	SN-Create-Record	question_choice
UI ポリシーを作成	SN-Create-Record	catalog_ui_policy
UI ポリシーアクションを作成	SN-Create-Record	catalog_ui_policy_action
変数セットを作成	SN-Create-Record	item_option_new_set
変数セットをリンク	SN-Create-Record	io_set_item
変数を照会	SN-Query-Table	item_option_new
選択肢を照会	SN-Query-Table	question_choice

ベストプラクティス

• 選択肢が 6 個以上の場合はタイプ 5 を使用： ドロップダウンは、ラジオボタンよりも長いリストを扱いやすくなります
• 選択肢が 2～5 個の場合はタイプ 1 を使用： ラジオボタンを使うと、ユーザーはすべての選択肢を一度に確認できます
• sys_choice ではなく question_choice を使用： カタログ変数には必ず question_choice を使用します
• 100 刻みで順序を設定： 後から変数を挿入できます（100、200、300...）
• 意味のある変数名： lowercase_with_underscores 形式の名前を使用します
• ヘルプテキスト： 複雑なフィールドには必ず補足説明を記載します
• コンテナーでグループ化： 関連するフィールドの整理にはタイプ 19／20 を使用します
• 参照修飾子： 参照フィールドを関連するレコードのみに絞り込みます
• UI ポリシーをテスト： 表示／非表示のロジックが両方向で機能することを確認します

トラブルシューティング

選択肢が表示されない

症状： ドロップダウンまたはラジオボタンに選択肢が表示されません 原因： 選択肢が question_choice ではなく sys_choice に作成されています 解決策：

# Verify choices are in question_choice
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[variable_sys_id]
  fields: text,value,order,inactive

# If empty, create choices in correct table
Tool: SN-Create-Record
Parameters:
  table_name: question_choice
  data:
    question: [variable_sys_id]
    text: "Option 1"
    value: "opt1"
    order: 100

連動変数で絞り込まれない

症状： 親変数の選択内容にかかわらず、子変数にすべての選択肢が表示されます 原因： depends_on の値が親変数の選択肢の値と一致していません 解決策：

# Check parent choices
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[parent_variable_sys_id]
  fields: text,value

# Verify child choices have matching depends_on values
Tool: SN-Query-Table
Parameters:
  table_name: question_choice
  query: question=[child_variable_sys_id]
  fields: text,value,depends_on

UI ポリシーが機能しない

症状： 条件に基づいて変数が表示または非表示になりません 原因：

1. UI ポリシーが無効になっています
2. 条件の構文が正しくありません
3. UI ポリシーアクションが関連付けられていません 解決方法：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy
  query: catalog_item=[item_sys_id]
  fields: short_description,conditions,active,reverse_if_false

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy_action
  query: ui_policy=[policy_sys_id]
  fields: catalog_variable,visible,mandatory,disabled

参照修飾子の構文エラー

症状： 参照フィールドにエラーが表示されるか、結果が表示されません 原因： reference_qual のエンコード済みクエリ構文が無効です 解決方法： まずリストフィルターでクエリをテストし、まったく同じ構文を使用してください

関連スキル

• catalog/item-creation - 完全なカタログアイテムの作成
• catalog/approval-workflows - 承認の設定
• catalog/request-fulfillment - 送信されたリクエストの処理
• development/client-scripts - 動的なフォームの動作

参考資料

• ServiceNow の変数タイプ
• カタログ UI ポリシー
• 変数セット