PaCE ポリシースクリプトの構造

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

    • このセクションでは、PaCE ポリシースクリプトの構造について説明します。

    ポリシーが実行されると、一連のパラメーターが渡されます。ポリシー開発者は、このポリシースクリプトでこれらのパラメーターに基いて、準拠、非準拠、または準拠例外のいずれであるかを判断し、この決定を呼び出しサービスに返すことができます。次の画像は、サンプルのスクリプトを示しています。
    図 : 1. サンプルポリシースクリプト
    サンプルスクリプトポリシー。

    スクリプトをデバッグするには、デバッガスクリプトアイコン デ バッガアイコンを選択します。詳細については、「Script Debugger API」を参照してください。

    次の表に、ポリシーの関数パラメーターと、それらをポリシースクリプトで使用する方法を示します。

    変数名 説明
    logger Logger は、ポリシーコーダーがメッセージをログに記録するために使用できるオブジェクトです。ログメッセージは sn_pace_execution_log テーブルに保存されます。これらのログメッセージは、デバッグ、追跡、または監視の目的で確認できます。ログメッセージは、次のいずれかのレベルで記録できます。
    • 1：info (情報)
    • 2：debug (デバッグ)
    • 3：warning (警告)
    • 4：error (エラー)

    API を介してポリシーを呼び出すときに、目的のログレベルを指定できます。例でば、次のような形式で使用します。

    logger.info("** snapshotId is: "+snapshotId);
    current

    Record

    		 currentRecord は、ポリシーの使用時に実行されるポリシーの現在バージョンを示すオブジェクトです。currentRecord の詳細を表示するには、ポリシーのホームページの [バージョン] タブに移動し、バージョンステータスが [現在] に設定されているポリシーを特定します。
    下の画像では、ポリシーの現在アクティブなバージョンが強調表示されていることがわかります。次の詳細が表示されます。
    • バージョン番号
    • 最終更新日
    • バージョンを更新したユーザーの名前
    • 呼び出し元アプリケーションによって実行された回数
    • テスト環境で実行された回数
    ポリシースクリプトは、ポリシーに渡された currentRecord オブジェクトとの対話により、ポリシーの実行中にこのデータにアクセスできます。

    PaCE バージョンの詳細
    次の例は、ポリシー開発者がポリシーバージョンレコードのプロパティにアクセスする方法を示しています。 
    (function(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output) {
     //retrieve the input values
     logger.info(currentRecord.getValue('name'));
  }
 )(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output);
    document

    Record

    		 documentRecord は、検証対象の関連オブジェクト (テーブルと documentID) にポリシーをマップするために使用されます。documentRecord は、table_name と sysID の組み合わせです。ポリシーロジックは、オブジェクトのプロパティに基づいて、検証対象のオブジェクトの管理と操作を行い、正しい決定を下すために使用されます。
    例えば、DevOps コンフィグ 環境では、ポリシーを展開可能項目にマッピングできます。API を呼び出すと、ドキュメント (展開可能項目) テーブルと展開可能項目の Sys ID に対してクエリが開始されます。 
    {
           "table": "sn_cdm_deployable",
           "sysId": "d1be8f5e87d80110eec7dbdd3fbb357d"
		}
    次の例は、ポリシースクリプトで documentRecord を使用する方法を示しています。
    (function(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output) 
{
//assuming that associated document has state field
  var documentState = documentRecord.getValue(“state”);
if (documentState == “new”)
   …
else
   …
}
)(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output);

    apiVar

    apiVars は、PaCE API が呼び出されたときに渡されます。これには、ポリシーバージョンで定義されているすべての API 変数が含まれます。詳細については、「発信者入力の定義」のセクションを参照してください。

    サンプルポリシースクリプト は、ポリシーを使用して DevOps 環境で構成データを検証する方法を示しています。サンプルスクリプトでは、apiVars 変数は次のように定義されています。 
    var snapshotId = apiVars.snapshotId;
    ここで、指定された snapshotId は、指定された基準に基づいて検証される DevOps コンフィグ展開可能項目の対応する snapshotId にマップされます。

    ポリシー開発者は、ポリシースクリプトでロジックを定義して、API が呼び出されたときに渡される apiVars 値を使用して決定を下すことができます。たとえば、渡された SnapshotID は、documentRecord オブジェクトで渡された展開可能項目の特定の snapshotID に関連するキー値を識別するために使用されます。
    configParams

    構成パラメーターは、ポリシーのマッピング時に渡される変数で、特定のバージョンのポリシーに対して定義されたすべての 構成パラメーター変数が含まれます。

    configParams 変数は、サンプルポリシースクリプト では以下のように定義されています。
    var dbPort = configParams.dbPort;
    ポリシー開発者は、ポリシースクリプトでロジックを定義し、マッピング時に渡された値を使用して決定を下すことができます。たとえば、dbPort 番号は 30000 未満である必要がありますが、それ以外の場合、ポリシーは非準拠と見なされます。
    recordRefs レコード参照は、ServiceNow® テーブルからデータを抽出するクエリを定義し、そのデータを使用してポリシーロジックを設定します。オートコンプリート機能があり、Javascript エディターでレコード参照を選択する際に使用できます。
    dataCollectors データコレクター機能は、ServiceNow または外部データソースから入力プロセスデータを収集して出力します。
    children

    Outputs

    		 このバージョンではサポートされていません。
    output

    このパラメーターは、決定を含むポリシー実行の出力を、呼び出しサービスに返すために使用されます。このポリシーに関連する決定と、エラー、警告、結果の詳細などの追加情報を提供します。

    次の例は、準拠決定と非準拠決定を含む出力を示しています。
    
{
    "decision": "compliant",
    "results": [],
    "warnings": [],
    "failures": [],
    "state": "complete"
}


{
    "decision": "non_compliant",
    "results": [],
    "warnings": [],
    "failures": [“Failed to validate key”],
    "state": "complete"
}
    output.

    decision

    		 decision プロパティは次のいずれかに設定されます。
    • 準拠：ポリシーが要件に準拠していると判断します。
    • 非準拠：ポリシーが要件に準拠していないと判断します。
    • 準拠例外 (Compliant-exception)：ポリシーの例外が承認され、準拠していないポリシーが準拠例外ステータスに設定されると判断します。

    決定は、呼び出しサービスに JSON 形式で返されます。

    注:
    スクリプトの output.decision フィールドに値が指定されていない場合、ポリシーが実行されたときにエラーがなければ、このフィールドはデフォルトで [準拠] に設定されます。
    output.

    results

    results プロパティを使用すると、ポリシーの検証フェーズ中に行われた決定について、呼び出しサービスにデータを返すことができます。結果のリストを含むリストオブジェクトを、呼び出しサービスに返すことができます。
    output.

    warnings

    warnings プロパティを使用すると、ポリシーの検証フェーズ中に発生した警告について、呼び出しサービスにデータを返すことができます。
    output.

    failures

    failures プロパティを使用すると、ポリシーの検証フェーズ中に発生したエラーについて、呼び出しサービスにデータを返すことができます。
    注:
    次のフィールドは、PaCE ポリシースクリプトが実行されると自動的に入力されます。
    output.

    name

    		 実行されているポリシーの名前 (現在のバージョン)。
    output.

    state

    		 これは、ポリシー呼び出しのステータスを示します。
    • Complete：呼び出しは正常に完了しました。
    • Pending：ポリシーを正常に実行できず、未完了のステータスであることを示します。
    注:
    • ポリシースクリプトエディターでは、logger、callerInput、および mappedInput パラメーターで、オートコンプリートによる提案を使用できます。
    • パラメーターの追加情報を表示するには、パラメーター名を入力し、次のいずれかのオプションを選択します。
      PaCE 追加パラメーターの詳細