ui-policies

カタログ UI ポリシー

概要

このスキルでは、サービスカタログアイテムの UI ポリシーの作成と管理について説明します。

• 条件付き UI ポリシーの作成
• 表示／非表示／必須／無効化のアクション
• スクリプトによる UI ポリシー条件
• UI ポリシーアクションとその REST API の制限事項
• バックグラウンドスクリプトを使用してアクションをリンクする回避策
• UI ポリシーのテストとデバッグ

使用する場面： フィールドの表示／非表示、ほかの選択内容に基づくフィールドの必須化、複雑な条件ロジックの実装が必要な動的なカタログフォームを作成する場合です。

対象ユーザー： 動的なフォーム動作を備えたサービスカタログアイテムを作成するカタログ管理者と開発者です。

前提条件

• ロール： catalog_admin または admin
• アクセス： catalog_ui_policy、catalog_ui_policy_action、item_option_new テーブル
• 知識： 基本的なカタログアイテムの構造、変数
• 関連スキル： 変数の作成については catalog/variable-management

カタログ UI ポリシーを理解する

UI ポリシーのコンポーネント

┌─────────────────────────────────────────────────────────┐
│                    Catalog UI Policy                     │
├─────────────────────────────────────────────────────────┤
│  Catalog Item: [reference to sc_cat_item]               │
│  Short Description: "Show approval fields for >$1000"   │
│  Conditions: amount>1000                                │
│  On Load: true    Reverse If False: true                │
│  Script True: [optional advanced logic]                 │
│  Script False: [optional reverse logic]                 │
├─────────────────────────────────────────────────────────┤
│                    UI Policy Actions                     │
├─────────────────────────────────────────────────────────┤
│  Action 1: manager_approval → visible=true, mandatory=true │
│  Action 2: justification → visible=true                    │
│  Action 3: cost_center → disabled=false                    │
└─────────────────────────────────────────────────────────┘

UI ポリシーの評価

User Opens Form
      │
      ▼
┌─────────────────┐
│  On Load = true?│───No──► Conditions evaluated only on change
      │
     Yes
      │
      ▼
┌─────────────────┐
│ Evaluate        │
│ Conditions      │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
  True      False
    │         │
    ▼         ▼
┌────────┐ ┌────────────────┐
│ Apply  │ │Reverse If False│───Yes──► Apply opposite actions
│Actions │ │    = true?     │
└────────┘ └───────┬────────┘
                   │
                  No
                   │
                   ▼
              Do nothing

手順

フェーズ 1：基本的な UI ポリシーを作成する

ステップ 1.1：UI ポリシーレコードを作成する

シンプルな条件ベースのポリシー：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show approval fields when amount exceeds $1000"
    active: true
    on_load: true
    reverse_if_false: true
    order: 100
    global: false
    run_scripts: false

結果： 作成された UI ポリシーの sys_id を返します（例：policy_sys_id）

ステップ 1.2：UI ポリシーのフィールドを理解する

フィールド	型	説明
catalog_item	参照	対象のカタログアイテム
short_description	文字列	ポリシー名／説明
active	ブール値	ポリシーを有効化／無効化します
on_load	ブール値	フォームの読み込み時に評価します
reverse_if_false	ブール値	条件が false の場合に逆の動作を適用します
order	整数	実行順序（数値が小さいほど先に実行）
global	ブール値	すべてのカタログアイテムに適用します
run_scripts	ブール値	Script True／Script False を有効にします
conditions	条件	変数に対するエンコード済みクエリ

フェーズ 2：UI ポリシー条件を追加する

ステップ 2.1：シンプルなフィールド条件

条件では、エンコード済みクエリ構文を使用して変数の値を比較します。

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

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show manager approval for external vendors"
    conditions: "vendor_type=external"
    active: true
    on_load: true
    reverse_if_false: true
    order: 100

条件構文の例：

条件	意味
priority=1	優先度が 1 と等しい
amount>1000	金額が 1000 より大きい
category=hardware^urgency=1	カテゴリが hardware で、緊急度が 1
department=IT^ORdepartment=Security	部門が IT または Security
requested_for.active=true	参照先のユーザーがアクティブ
descriptionISNOTEMPTY	説明に値が入力されている
quantityBETWEEN1@10	数量が 1 以上 10 以下

ステップ 2.2：複数の条件（AND／OR）

AND 条件：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Require justification for high-cost IT equipment"
    conditions: "department=IT^hardware_type=laptop^estimated_cost>2000"
    active: true
    on_load: true
    reverse_if_false: true
    order: 200

OR 条件：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show security review for sensitive departments"
    conditions: "department=Finance^ORdepartment=Legal^ORdepartment=HR"
    active: true
    on_load: true
    reverse_if_false: true
    order: 300

フェーズ 3：UI ポリシーアクションを作成する

重要： ServiceNow の制限により、UI ポリシーアクションは REST API 経由では変数に完全にリンクできません。catalog_variable フィールドには特別な処理が必要です。

ステップ 3.1：制限事項を理解する

REST API 経由で catalog_ui_policy_action を作成すると：

• レコードは正常に作成されます
• catalog_variable フィールドは正しくリンクされません
• 手動で修正するか、バックグラウンドスクリプトで更新するまで、アクションは機能しません

この問題が発生する理由：

• catalog_variable フィールドは IO:[variable_sys_id] という特別な形式を必要とします
• REST API はこの参照型を正しく解決できません
• これは既知の ServiceNow プラットフォームの制限事項です

ステップ 3.2：アクションレコードを作成する（2 ステップ中の 1 ステップ目）

まず、UI ポリシーアクションレコードを作成します。

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: true
    disabled: false

結果： アクションの sys_id を返します（例：action_sys_id）

注： アクションは作成されますが、まだどの変数にもリンクされていません。

ステップ 3.3：アクションを変数にリンクする（2 ステップ中の 2 ステップ目）

必須： アクションを正しくリンクするには、バックグラウンドスクリプトを使用します。

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    // Link UI Policy Action to Catalog Variable
    var actionSysId = '[action_sys_id]';
    var variableSysId = '[variable_sys_id]';

    var gr = new GlideRecord('catalog_ui_policy_action');
    if (gr.get(actionSysId)) {
      // The catalog_variable field requires IO: prefix
      gr.setValue('catalog_variable', 'IO:' + variableSysId);
      gr.update();
      gs.info('Linked UI policy action ' + actionSysId + ' to variable ' + variableSysId);
    } else {
      gs.error('UI policy action not found: ' + actionSysId);
    }
  description: Link UI policy action to catalog variable

ステップ 3.4：複数のアクションをまとめてリンクする

複数のアクションをリンクする場合は、1 つのスクリプトにまとめます。

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    // Batch link UI Policy Actions
    var links = [
      { action: '[action1_sys_id]', variable: '[var1_sys_id]' },
      { action: '[action2_sys_id]', variable: '[var2_sys_id]' },
      { action: '[action3_sys_id]', variable: '[var3_sys_id]' }
    ];

    var success = 0;
    var failed = 0;

    links.forEach(function(link) {
      var gr = new GlideRecord('catalog_ui_policy_action');
      if (gr.get(link.action)) {
        gr.setValue('catalog_variable', 'IO:' + link.variable);
        gr.update();
        gs.info('Linked: ' + link.action + ' -> ' + link.variable);
        success++;
      } else {
        gs.error('Action not found: ' + link.action);
        failed++;
      }
    });

    gs.info('Batch link complete: ' + success + ' success, ' + failed + ' failed');
  description: Batch link UI policy actions to variables

フェーズ 4：UI ポリシーアクションの種類

ステップ 4.1：変数の表示／非表示

条件が真の場合に変数を表示する：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: false
    disabled: false

その後、バックグラウンドスクリプトを使用して変数にリンクします（ステップ 3.3）。

変数を非表示にする（reverse_if_false を使用）：

• アクションで visible: true を設定します
• ポリシーで reverse_if_false: true を設定します
• 条件が偽の場合、変数は非表示になります

ステップ 4.2：必須アクション

条件が真の場合に変数を必須にする：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: true
    disabled: false

一般的なパターン： 表示して必須にする：

• visible: true - フィールドを表示します
• mandatory: true - 値を必須にします
• reverse_if_false: true を指定すると、条件が偽の場合、フィールドは非表示になり、必須ではなくなります

ステップ 4.3：無効化／読み取り専用アクション

条件が真の場合に変数を読み取り専用にする：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy_sys_id]
    visible: true
    mandatory: false
    disabled: true

ユースケース： 計算フィールドや表示専用の値をロックします。

フェーズ 5：スクリプトによる UI ポリシー

ステップ 5.1：スクリプト実行を有効にする

単純なエンコード済みクエリでは表現できない複雑な条件の場合：

Tool: SN-Update-Record
Parameters:
  table_name: catalog_ui_policy
  sys_id: [policy_sys_id]
  data:
    run_scripts: true
    script_true: |
      // Runs when condition is TRUE
      // Access variables via g_form
      var amount = g_form.getValue('amount');
      var dept = g_form.getValue('department');

      if (parseFloat(amount) > 5000 && dept == 'IT') {
        // Additional client-side logic
        g_form.showFieldMsg('amount', 'Requires CIO approval', 'info');
      }
    script_false: |
      // Runs when condition is FALSE (optional)
      g_form.hideFieldMsg('amount');

ステップ 5.2：スクリプトの例

複雑な検証：

// script_true
var hardware = g_form.getValue('hardware_type');
var quantity = parseInt(g_form.getValue('quantity')) || 0;

// Show warning for bulk orders
if (hardware == 'laptop' && quantity > 10) {
  g_form.showFieldMsg('quantity', 'Bulk orders require procurement approval', 'warning');
}

// Dynamic mandatory based on multiple fields
if (hardware == 'other') {
  g_form.setMandatory('other_description', true);
}

日付の検証：

// script_true
var startDate = g_form.getValue('start_date');
var endDate = g_form.getValue('end_date');

if (startDate && endDate) {
  var start = new Date(startDate);
  var end = new Date(endDate);

  if (end < start) {
    g_form.showFieldMsg('end_date', 'End date must be after start date', 'error');
    g_form.setMandatory('end_date', true);
  }
}

フェーズ 6：UI ポリシーの完全な例

ステップ 6.1：完全な実装

シナリオ： 次の条件を満たすソフトウェアリクエストフォーム：

• ライセンスタイプが「Enterprise」の場合、コストセンターとマネージャーの承認を表示する
• 数量が 5 を超える場合、業務上の正当性を必須にする

ステップ 1：変数の sys_id を取得する：

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=[catalog_item_sys_id]
  fields: sys_id,name,question_text
  limit: 50

ステップ 2：ポリシー 1「Enterprise ライセンス」を作成する：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Show approval fields for Enterprise license"
    conditions: "license_type=enterprise"
    active: true
    on_load: true
    reverse_if_false: true
    order: 100
# Result: policy1_sys_id

ステップ 3：ポリシー 1 のアクションを作成する：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy1_sys_id]
    visible: true
    mandatory: true
    disabled: false
# Result: action1a_sys_id (for cost_center)

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy1_sys_id]
    visible: true
    mandatory: true
    disabled: false
# Result: action1b_sys_id (for manager_approval)

ステップ 4：アクションを変数にリンクする：

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    var links = [
      { action: '[action1a_sys_id]', variable: '[cost_center_var_sys_id]' },
      { action: '[action1b_sys_id]', variable: '[manager_approval_var_sys_id]' }
    ];

    links.forEach(function(link) {
      var gr = new GlideRecord('catalog_ui_policy_action');
      if (gr.get(link.action)) {
        gr.setValue('catalog_variable', 'IO:' + link.variable);
        gr.update();
        gs.info('Linked: ' + gr.sys_id);
      }
    });
  description: Link enterprise license policy actions

ステップ 5：ポリシー 2「一括注文」を作成する：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy
  data:
    catalog_item: [catalog_item_sys_id]
    short_description: "Require justification for bulk orders (>5)"
    conditions: "quantity>5"
    active: true
    on_load: true
    reverse_if_false: true
    order: 200
# Result: policy2_sys_id

ステップ 6：ポリシー 2 のアクションを作成してリンクする：

Tool: SN-Create-Record
Parameters:
  table_name: catalog_ui_policy_action
  data:
    ui_policy: [policy2_sys_id]
    visible: true
    mandatory: true
    disabled: false
# Result: action2_sys_id

Tool: SN-Execute-Background-Script
Parameters:
  script: |
    var gr = new GlideRecord('catalog_ui_policy_action');
    if (gr.get('[action2_sys_id]')) {
      gr.setValue('catalog_variable', 'IO:[justification_var_sys_id]');
      gr.update();
      gs.info('Linked bulk order justification action');
    }
  description: Link bulk order policy action

フェーズ 7：テストとデバッグ

ステップ 7.1：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,order,run_scripts
  limit: 50

ポリシーのすべてのアクションをクエリする：

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

ステップ 7.2：アクションリンクをデバッグする

catalog_variable が正しくリンクされているか確認する：

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

catalog_variable.name が空の場合、リンクに失敗しています。バックグラウンドスクリプトを再実行してください。

ステップ 7.3：テストチェックリスト

テスト前：

• すべての UI ポリシーが有効になっている
• すべてのポリシーアクションに変数がリンクされている（catalog_variable が空ではない）
• 順序番号が正しく設定されている（競合がない）
• reverse_if_false が適切に設定されている

テストシナリオ：

1. 読み込み時： フォームを新しく開き、初期状態の表示を確認する
2. 真の条件： 条件が真になるよう値を設定し、アクションが適用されることを確認する
3. 偽の条件： 条件が偽になるよう値を変更し、逆の動作を確認する
4. 複数のポリシー： 条件の組み合わせをテストする
5. スクリプトポリシー： スクリプトがエラーなく実行されることを確認する

ステップ 7.4：一般的なデバッグコマンド

リンクされていないアクションを検索する：

Tool: SN-Query-Table
Parameters:
  table_name: catalog_ui_policy_action
  query: ui_policy.catalog_item=[catalog_item_sys_id]^catalog_variableISEMPTY
  fields: sys_id,ui_policy.short_description
  limit: 50

名前から変数の sys_id を取得する：

Tool: SN-Query-Table
Parameters:
  table_name: item_option_new
  query: cat_item=[catalog_item_sys_id]^name=manager_approval
  fields: sys_id,name

ツール使用の概要

操作	MCP ツール	備考
UI ポリシーの作成	SN-Create-Record	catalog_ui_policy テーブル
UI ポリシーアクションの作成	SN-Create-Record	catalog_ui_policy_action テーブル
アクションを変数にリンク	SN-Execute-Background-Script	必須 — REST API の制限
ポリシーのクエリ	SN-Query-Table	catalog_ui_policy
アクションのクエリ	SN-Query-Table	catalog_ui_policy_action
ポリシーの更新	SN-Update-Record	script_true/script_false 用

ベストプラクティス

• わかりやすい名前： デバッグしやすいよう、明確で短い short_description を使用します
• 順序を慎重に設定： 数値が小さいほど先に実行されます。競合を避けてください
• reverse_if_false を使用： 反対のポリシーを 2 つ作成するよりも簡潔です
• 両方の状態をテスト： 真と偽の両方の条件を必ずテストします
• スクリプトを最小限にする： 可能な場合は条件を使用します。スクリプトは実行が遅くなります
• ロジックを文書化： 複雑な条件は description フィールドにコメントを記載します
• アクションをまとめてリンク： 複数のリンクには単一のバックグラウンドスクリプトを使用します
• リンクを確認： catalog_variable に値が設定されていることを必ずクエリで確認します

トラブルシューティング

UI ポリシーが実行されない

症状： 変数の表示設定／必須設定が変わらない 原因：

1. ポリシーが無効になっている
2. 条件の構文エラー
3. アクションが変数にリンクされていない 解決策：

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

active=true を確認し、条件の構文を検証してください。

アクションがリンクされていない（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('Fixed action link');
  description: Fix unlinked UI policy action

reverse_if_false が機能しない

症状： 条件が false の場合も、変数が表示されたまま／必須のままになる 原因：

1. reverse_if_false が有効になっていない
2. on_load が有効になっていない（変更時にのみ評価される） 解決策：

Tool: SN-Update-Record
Parameters:
  table_name: catalog_ui_policy
  sys_id: [policy_sys_id]
  data:
    on_load: true
    reverse_if_false: true

スクリプトエラー

症状： フォームの読み込み時にコンソールエラーが発生し、スクリプトが実行されない 原因： script_true または script_false に JavaScript の構文エラーがある 解決策：

1. ブラウザーのコンソールでエラーを確認します
2. JavaScript の構文を検証します
3. まずブラウザーのコンソールでスクリプトをテストします

複数のポリシーが競合する

症状： 変数の動作が予測できない 原因： 同じ変数に影響する複数のポリシーで、アクションが競合している 解決策：

1. その変数に影響するすべてのポリシーを検索します
2. 順序番号を調整します
3. 複雑な条件を持つ単一のポリシーへの統合を検討します

関連スキル

• catalog/variable-management - 変数の作成と設定
• catalog/item-creation - カタログアイテムの完全なセットアップ
• catalog/approval-workflows - 承認の設定
• admin/script-execution - バックグラウンドスクリプトのパターン

参考資料

• ServiceNow カタログ UI ポリシー
• UI ポリシーアクション
• クライアントスクリプトと UI ポリシーの比較