Structure of a PaCE policy script

This section describes the structure of a PaCE policy script.

When a policy is executed, a set of parameters is passed and the policy developer can use these parameters in this policy script to make a decision whether it is compliant, non-compliant, or compliant-exception and return this decision back to the calling service. The following image shows a sample script:

그림 1. Sample policy script

To debug the script, select the Debugger script icon . For more information, see Script Debugger API.

The following table lists the policy function parameters and how can they be used in your policy script.

Variable Name	Description
logger	Logger is an object that the policy coder can use to log messages. The log messages are stored in the sn_pace_execution_log table. You can review these log messages for debugging, tracking, or monitoring purposes. The log messages can be logged with one of the following levels: 1: info 2: debug 3: warning 4: error When a policy is invoked through the API, you can specify the desired log level. For example:The format is as follows: logger.info("** snapshotId is: "+snapshotId);
current Record	currentRecord is an object of the current version of the policy that is executed when the policy is used. To view the currentRecord details, navigate to the Versions tab on the Policy Home page and locate the policy whose version state is set to Current. In the image below, you can see that the current active version of the policy highlighted. It shows the following details: version number last update date the name of the user who updated the version the number of times it was executed by the calling application the number of times it was run in the test environment The policy script can access this data during policy execution time by interacting with the currentRecord object passed to the policy. This example shows how a policy developer can access the properties of the policy version record: (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	The documentRecord is used to map the policy to the relevant object (table and documentID) that is being validated. The documentRecord is a combination of the table_name and sysID. Based on the properties of the object, the policy logic is used to manage and interact with the object being validated to determine the right decision. For example: In the DevOps Config environment, a policy can be mapped to the deployable. When the API is invoked, a query is initiated on the document (deployable) table and the Sys ID of the deployable. { "table": "sn_cdm_deployable", "sysId": "d1be8f5e87d80110eec7dbdd3fbb357d" } This example shows how the documentRecord can be used in a policy script: (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);
apiVars	The apiVars is passed to the PaCE API when it is invoked. It includes all the API variables defined in the policy version. See <Defining Caller Inputs> section for details The Sample policy script shows how policies can be used to validate configuration data in the DevOps environment. In the sample script, the apiVars variable is defined as var snapshotId = apiVars.snapshotId; where the specified snapshotId is mapped to the corresponding snapshotId of the DevOps Config deployable being validated based on specified criteria. The policy developer can define logic in the policy script to use the apiVars values passed when the API is invoked to determine the decision. For example, the SnapshotID passed is used to identify key-values related to the specific snapshotID for a deployable passed in the documentRecord object.
configParams	Config Parameters are variables are passed when mapping the policy and includes all the Config Parameters variables defined for a specific version of the policy. The configParams variable is defined as follows in the Sample policy script. var dbPort = configParams.dbPort; The policy developer can define the logic in the policy script to use the values passed at mapping to determine the decision. For example, the dbPort number must be less than 30000, otherwise the policy is considered to be non_compliant.
recordRefs	Record references define queries to extract data from any ServiceNow® tables and use the data to configure the policy logic. There is an auto-completion function that can select the record reference in the Javascript editor.
dataCollectors	The data collectors function collects input process data from ServiceNow or an external data source to provide an output.
children Outputs	Not supported in this version.
output This parameter is used to pass the output of the policy execution that includes the decision back to the calling service. It provides a decision related to this policy, with additional information such as errors, warnings, and result details. This example shows a sample output with compliant and non_compliant decisions: { "decision": "compliant", "results": [], "warnings": [], "failures": [], "state": "complete" } { "decision": "non_compliant", "results": [], "warnings": [], "failures": [“Failed to validate key”], "state": "complete" }
output. decision	The decision property can be set to: Compliant: Determines that the policy complies with requirements. Non-compliant: Determines that the policy does not comply with the requirements. Compliant-exception: Determines that an exception to the policy has been approved and any policies that are non-compliant are set to the compliant-exception state. The decision is returned in a JSON format back to the calling service. 주: If a value is not specified in the output.decision field in the script, when the policy is executed, by default this field is set to compliant if there are no failures.
output. results	The results property can be used to pass data back to the calling service on decisions made during the policy validation phase. A list object with a list of results can be passed back to the calling service.
output. warnings	The warnings property can be used to pass data back to the calling service on any warnings that occurred during the policy validation phase.
output. failures	The failures property can be used to pass data back to the calling service on any errors that occurred during the policy validation phase.
주: The following fields are automatically filled in when the PaCE policy script is executed.
output. name	The name (current version) of the policy being executed.
output. state	It indicates the state of the policy invocation. Complete: The invocation was completed successfully. Pending: Indicates that the policy could not be successfully executed and is an incomplete state.

주:

• Auto-complete suggestions are available in the policy script editor for the logger, callerInput and mappedInput parameter.
• To view additional information for a parameter, enter the parameter name and select one of the options as follows: