UI ポリシー API - ServiceNow Fluent

  • リリースバージョン: Zurich
  • 更新日 2025年12月19日
  • 所要時間：12分

    • UI ポリシー API は、フォーム上の情報の動作を動的に変更し、タスクのカスタムプロセスフローを制御するユーザーインターフェイス (UI) ポリシー [sys_ui_policy] を定義します。

    UI ポリシーでは、特定の条件が満たされたときにフィールドを必須、読み取り専用、表示、非表示、またはクリアにすることができます。クライアントスクリプトを使用してこれらすべてのアクションを実行することもできますが、ロード時間を短縮するために、可能であれば UI ポリシーを使用してください。

    UI ポリシーに関する一般的な情報については、「 Using UI policies」を参照してください。

    UiPolicy オブジェクト

    UI ポリシー sys_ui_policy を作成して、フォームの動作を構成します。

    表 : 1. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    table 文字列 必須。変更するフォームのテーブル。
    shortDescription 文字列 必須。ポリシーとその目的の説明。
    アクティブ ブール ポリシーがフォームに適用されているかどうかを示すフラグ。

    デフォルト：true
    グローバル ブール

    ポリシーがどのフォームビューに適用されるかを示すフラグ。true の場合、ポリシーはテーブルのすべてのビューに適用されます。false の場合、ポリシーは ビュー プロパティで指定されたフォームビューに固有です。

    デフォルト：true
    onLoad ブール ポリシーがいつ実行されるかを示すフラグ。true の場合、条件が満たされていればフォームがロードされるたびにポリシーが実行されます。

    デフォルト：true
    reverseIfFalse ブール 条件が false と評価された場合にポリシーの動作を反転するかどうかを示すフラグ。true の場合、ポリシーの条件が false と評価されると、ポリシーアクションが取り消されます。

    デフォルト：true
    継承 ブール 現在のテーブルを拡張するテーブルがポリシーを継承するかどうかを示すフラグ。true の場合、拡張テーブルはポリシーを継承します。

    子テーブルに親テーブルから継承されたポリシーがある場合は、子テーブルのポリシーが最初に実行されます。このイベントは、ポリシーの順序に関係なく true です。

    デフォルト値：false
    isolateScript ブール 独立したスコープでスクリプトを実行するかどうかを示すフラグ。true の場合、スクリプトは独立したスコープで実行されます。このプロパティは、 runScripts が true に設定されている場合にのみ適用されます。

    デフォルト値：false
    条件 文字列 ユーザーがオブジェクトにアクセスするために true でなければならないフィールドと値を指定するフィルタークエリ。詳細については、「Operators available for filters and queries」を参照してください。 スクリプトを使用して条件を設定するには、代わりにクライアントスクリプトを使用します。

    ユーザーが手動でフォームのフィールドを変更した場合のみ、条件が再度確認されます。UI アクション、コンテキストメニューアクション、またはリストエディターによって変更が行われた場合、その変更は評価されません。
    runScript ブール true 条件と false 条件の両方に対して高度な動作をスクリプト化できるかどうかを示すフラグ。true の場合、 scriptTrue、 scriptFalse、 uiType、および isolateScript プロパティで定義されたスクリプトは、該当する場合に実行されます。

    デフォルト値：false
    scriptTrue 文字列 ポリシーの条件が満たされた場合に実行されるクライアント側スクリプト。このプロパティは、 runScripts プロパティが true に設定されている場合に必要です。

    形式: 関数 onCondition() {}

    デフォルト: 関数 onCondition() {\n\n}
    scriptFalse 文字列 ポリシーの条件が満たされず、 reverseIfFalse プロパティが true に設定されている場合に実行されるクライアント側スクリプト。このプロパティは、 runScripts プロパティが true に設定されている場合に必要です。

    形式: 関数 onCondition() {}

    デフォルト: 関数 onCondition() {\n\n}
    uiType 文字列 ポリシーが適用されるユーザーインターフェイスのタイプ。このプロパティは、 runScripts プロパティが true に設定されている場合に必要です。
    有効な値：
    • desktop:ポリシーはデスクトップインターフェイスに適用されます。
    • mobile-or-service-portal:ポリシーはモバイルおよび サービスポータル インターフェイスに適用されます。
    • all:ポリシーはすべてのインターフェイスに適用されます。

    デフォルト：desktop
    アクション アレイ 条件が満たされた場合に適用するフィールドアクションのリスト。詳細については、「アクション アレイ」を参照してください。
    relatedListAction アレイ 関連リストの可視化コントロールのリスト。詳細については、「relatedListActions アレイ」を参照してください。
    説明 文字列 ポリシーに関する追加情報。
    modelId 文字列 このポリシーが継承されるときにポリシーが適用される親 UI ポリシーのsys_id。このプロパティは、 model_table プロパティと連動して機能します。
    modelTable 文字列 UI ポリシーが親テーブルから継承されたときにポリシーが適用される親テーブルの名前。このプロパティは、 model_id プロパティと連動して機能します。
    順序 番号 複数のポリシーが条件に適合する場合にポリシーを適用する実行順序。

    継承された UI ポリシーの場合、拡張テーブルのポリシーが最初に実行されます。次に、ベーステーブルポリシーが実行されます。

    デフォルト：100
    setValues 文字列 (廃止)エンコードされた文字列形式を使用して設定するフィールド値。代わりに UI ポリシーアクション [sys_ui_policy_action] を使用してください。
    表示 参照または文字列 必須。適用される UI ビュー [sys_ui_view] の変数識別子または名前、またはデフォルトビュー。

    UI ビューを定義するには、「 レコード API - ServiceNow Fluent」を参照してください。

    デフォルトのビュー (default_view) を使用するには、次の方法でインポートする必要があります。
    import { default_view } from '@servicenow/sdk/core'
    		 
    import { UiPolicy } from '@servicenow/sdk/core';

export const securityIncidentPolicy = UiPolicy({
  $id: Now.ID['security_incident_policy'],
  table: 'incident',
  shortDescription: 'Lock critical fields for security incidents',
  active: true,
  onLoad: true,
  conditions: 'category="security"',
  actions: [
    {
      field: 'security_notes',
      mandatory: true,
      visible: true
    },
    {
      field: 'caller_id',
      readOnly: true  // Lock caller field when category is security
    },
    {
      field: 'assignment_group',
      readOnly: true  // Lock assignment group when category is security
    },
    {
      field: 'priority',
      readOnly: true  // Lock priority when category is security
    }
  ],
  relatedListActions: [
    {
      // Using plain GUID for system relationships 
      list: 'b9edf0ca0a0a0b010035de2d6b579a03', // Attachments
      visible: false
    },
    {
      // Using table.field format for reference fields
      list: 'x_snc_17sepapp1_expenseitem.expensereport', // Example reference field
      visible: true
    }
  ]
})

    アクション アレイ

    UI ポリシーがフィールドで実行するアクション [sys_ui_policy_action] を構成します。

    UiPolicy オブジェクト内の actions アレイを使用します。アクションは、アレイに表示される順序で処理されます。アレイ内の各アクションには、 表示、 読み取り専用、 必須、または クリアされた プロパティの少なくとも 1 つを指定する必要があります。

    表 : 2. プロパティ
    名前 タイプ 説明
    フィールド 文字列 必須。アクションが適用されるフィールドの名前。
    注:
    指定されたフィールドがフォーム上に見つからない場合、UI ポリシーは同じ名前の変数に対してアクションを実行します。
    visible ブール値または文字列 フィールドの可視化を制御するオプション。
    有効な値：
    • true:フィールドは表示されます。
    • false:フィールドは非表示です。
    • 'ignore':フィールドは変更されません。

    デフォルト:ignore
    readOnly ブール値または文字列 フィールドを編集するためのアクセスを制御するオプション。
    有効な値：
    • true:フィールドは読み取り専用です。
    • false:フィールドは編集可能です。
    • 'ignore':フィールドは変更されません。

    デフォルト:ignore
    必須 ブール値または文字列 フィールドを必須にするかどうかを制御するオプション。
    有効な値：
    • true:フィールドは必須です。
    • false:フィールドはオプションです。
    • 'ignore':フィールドは変更されません。

    デフォルト:ignore
    クリア ブール ポリシーの条件が満たされた場合にフィールドをクリアするかどうかを示すフラグ。

    デフォルト値：false
    テーブル 文字列 ポリシーによって指定されたテーブルを上書きする、アクションが適用されるテーブル。空の場合は、ポリシーで指定されたテーブルが適用されます。
    値 文字列 ポリシー条件が満たされた場合にフィールドに設定する値。
    フィールドメッセージ 文字列 ポリシー条件が満たされた場合にフィールドについて表示するメッセージ。
    フィールドメッセージタイプ 文字列 フィールドメッセージの表示方法を決定するメッセージタイプ。
    有効な値：
    • error
    • 情報
    • 警告
    • なし

    デフォルト：none
    値アクション 文字列 フィールド値に対して実行するアクション。
    有効な値：
    • set_value
    • clear_value
    • 無視

    デフォルト:ignore

    		 
    actions: [
        {
            field: 'assignment_group',
            mandatory: true,
            value: 'Critical Response Team', // Set default value
            fieldMessage: 'This incident requires immediate attention from the Critical Response Team',
            fieldMessageType: 'error' // Show as error message
        },
        {
            field: 'urgency',
            value: '1', // Set to High urgency
            fieldMessage: 'Urgency has been automatically set to High',
            fieldMessageType: 'info'
        },
        {
            field: 'impact',
            value: '1', // Set to High impact
            fieldMessage: 'Impact has been automatically set to High',
            fieldMessageType: 'warning'
        }
    ]

    relatedListActions アレイ

    UI ポリシーのフォームでの関連リスト [sys_ui_policy_rl_action] の可視化を構成します。

    UiPolicy オブジェクト内の relatedListActions アレイを使用します。関連リストアクションは、アレイに表示される順序で処理されます。リストまたは表示プロパティのいずれかを、アレイ内の関連リストアクションごとに指定する必要があります。

    表 : 3. プロパティ
    名前 タイプ 説明
    list 文字列 フォーム上の関連リストへの参照。空の場合、アクションはすべての関連リストに適用されます。このプロパティは、 表示プロパティ が設定されていない場合に必要です。
    Format (形式)：
    • sys_ID:リストのsys_ID。この形式は、カスタムクエリ、添付ファイル、およびシステム定義の関連リストに使用します。
    • table.field:「 incident.caller_id」など、リストに関連付けられたテーブルとフィールドの名前。この形式は、参照フィールドベースの関係に使用します。
    visible ブール値または文字列 関連リストの可視化を制御するオプション。このプロパティは、 リスト プロパティが設定されていない場合に必要です。
    有効な値：
    • true:関連リストが表示されます。
    • false:関連リストは非表示です。
    • 'ignore':関連リストは変更されません。

    デフォルト:ignore

    		 
     relatedListActions: [
    {
      // Using plain GUID for system relationships 
      list: 'b9edf0ca0a0a0b010035de2d6b579a03', // Attachments
      visible: false
    },
    {
      // Using table.field format for reference fields
      list: 'x_snc_17sepapp1_expenseitem.expensereport', // Example reference field
      visible: true
    }
  ]