Passing parameters to PaCE policies

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Passing parameters to PaCE policies

    Passing parameters to PaCE policies allows you to validate updates on objects such as tables and document IDs. This capability supports policy authoring in both low-code environments and JavaScript, enabling dynamic and flexible policy execution based on input values.

    Show full answer Show less

    Key Features

    • API Variables: These variables, formerly called Caller Inputs, are passed at the time a developer invokes the PaCE API. The only predefined and immutable API Variable is SnapshotId, which cannot be modified or deleted. No additional API Variables can be defined per policy. If the required API Variable is not provided when invoking the policy, the policy does not execute and no decision is made.
    • Config Parameters: Previously known as Mapped Inputs, these parameters are assigned when mapping policies to specific objects. Config Parameters allow you to define inputs such as expense limits that are used by the policy during invocation. Mandatory Config Parameters must have specified values; otherwise, the policy becomes inactive and does not execute. In the code editor, Config Parameters are accessed via configParams.
    • Record References: These define queries to extract and aggregate data from ServiceNow tables to support policy logic. Using record references, you can retrieve necessary additional data dynamically during policy execution. In code, they are accessed through recordRefs.
    • Data Collectors: Data collectors gather input data from ServiceNow or external sources to produce outputs that influence policy decisions. They can be created, edited, updated, and activated within the policy builder. In JavaScript, data collectors are accessed using the dataCollectors object. The platform provides auto-completion and dropdown menus to simplify access to available data collectors and their outputs, especially in low-code editing.

    Practical Application for ServiceNow Customers

    Understanding these parameter types enables ServiceNow customers to design PaCE policies that are flexible, context-aware, and maintainable. API Variables ensure required invocation context, Config Parameters allow policy customization per object mapping (such as different expense limits per employee group), and Record References enable dynamic data retrieval for complex validation scenarios. Data Collectors extend the policy’s ability to incorporate external or additional internal data sources, enhancing decision accuracy.

    By effectively leveraging these parameter inputs, customers can create robust policies that execute only when correctly configured and provide precise validation outcomes tailored to their organizational needs.

    Parameters can be passed to a PaCE policy to validate updates to an object (tables and document IDs). These variables apply to authoring in both low-code or JavaScript. Policy versions include three types of parameter inputs: API Variables, Config Parameters, and Record References.

    API Variables

    Previously known as Caller Inputs, the API Variables is passed to the PaCE API at the time of invocation by a developer. The API Variable is a variable that enables you to pass the value to the policy whenever the policy is invoked. Specify a value for this API Variable when calling the API, otherwise the policy is not executed and no decision is reached. In the code editor, the variable name is apiVars.

    For each PaCE policy, there is only one pre-defined API Variable called SnapshotId. This API Variable is Immutable and cannot be modified or deleted. You cannot define any additional API Variables for a policy.

    Config Parameters

    Previously known as Mapped Inputs, the Config Parameters can be passed when mapping policies to an object (tables and document IDs). When you define a Config Parameter, you are creating a parameter that enables you to pass values to the policy whenever the policy is mapped. If you define mandatory inputs, you must specify values for these inputs when mapping the policy. If the inputs you define are not mandatory, the policy is not executed (the status is set to inactive) and no decision is reached. In the code editor, the variable name is configParams.

    For example, for a travel expenses policy you can add variables to define the limits of different types of expenses. The limits are specified when mapping the policy, and set the limits on the expense when the policy is invoked on this object. The breakfast expense limit for one group of employees could be $25, and for a different group of employees the limit could be $50. Each time the policy is invoked, the expenses are validated by the policy according to the limits specified in the mapping.

    Record References

    Record references define queries to extract data from any ServiceNow® tables and use the data to configure the policy logic. This feature enables you to retrieve additional data that may be required while defining the policy. You can define a query to perform aggregate functions for a record reference. In the code editor, the variable name is recordRefs.

    Data Collectors

    The data collectors function collects input process data from ServiceNow or an external data source to provide an output. The output can be used in the policy logic to make a decision. You can define and manage data collectors by creating, editing, updating, and activating them to your policy builder.

    Data collectors can be accessed by using the dataCollectors object in JavaScript.
    Note:
    Auto-completion lists all possible outputs and data collectors that are available to use.

    While editing a policy in low-code, an output of the configured data collectors is available under the drop-down menu.