{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":48662,"path":"servicenow-platform/policy-as-code-engine-pace/pace-policy-structure.md","title":"Structure of a PaCE policy script","bundle":null,"doc_type":null,"release":"australia","body":"\n# Structure of a PaCE policy script\n\nThis section describes the structure of a PaCE policy script.\n\nWhen 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:\n\n\\[Omitted image \"pace-sample-script-new-names.jpg\"\\] Alt text: Sample script policy.\n\nTo debug the script, select the Debugger script icon \\[Omitted image \"pace-debug-icon.jpg\"\\] Alt text: Debugger icon. For more information, see [Script Debugger API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/scriptdebugger-api.md).\n\nThe following table lists the policy function parameters and how can they be used in your policy script.\n\n\n
\n\nVariable Name\n\n\n\nDescription\n\n
\n\nlogger\n\n\n\n`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\n- 2: debug\n- 3: warning\n- 4: error\n\n When a policy is invoked through the API, you can specify the desired log level. For example:The format is as follows:\n\n `logger.info(\"** snapshotId is: \"+snapshotId);`\n\n
\n\ncurrentRecord\n\n\n\n`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:\n\n- version number\n- last update date\n- the name of the user who updated the version\n- the number of times it was executed by the calling application\n- the number of times it was run in the test environment\n\nThe policy script can access this data during policy execution time by interacting with the `currentRecord` object passed to the policy.\n\n \\[Omitted image \"pace-version-details.jpg\"\\] Alt text: PaCE Version Details\n\n This example shows how a policy developer can access the properties of the policy version record:\n\n```\n(function(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output) {\n //retrieve the input values\n logger.info(currentRecord.getValue('name'));\n }\n )(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output);\n\n```\n\n
\n\ndocumentRecord\n\n\n\nThe `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.\n\n```\n{\n \"table\": \"sn_cdm_deployable\",\n \"sysId\": \"d1be8f5e87d80110eec7dbdd3fbb357d\"\n\t\t}\n```\n\nThis example shows how the documentRecord can be used in a policy script:```\n(function(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output) \n{\n//assuming that associated document has state field\n var documentState = documentRecord.getValue(“state”);\nif (documentState == “new”)\n …\nelse\n …\n}\n)(logger, currentRecord, documentRecord, apiVars, configParams, recordRefs, dataCollectors, childrenOutputs, output);\n\n```\n\n
\n\napiVars\n\n\n\nThe 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\n\n The [Sample policy script](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/policy-as-code-engine-pace/pace-policy-structure.md) shows how policies can be used to validate configuration data in the DevOps environment. In the sample script, the apiVars variable is defined as\n\n```\nvar snapshotId = apiVars.snapshotId;\n```\n\nwhere the specified `snapshotId` is mapped to the corresponding `snapshotId` of the DevOps Config deployable being validated based on specified criteria.\n\n 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.\n\n
\n\nconfigParams\n\n\n\nConfig Parameters are variables are passed when mapping the policy and includes all the Config Parameters variables defined for a specific version of the policy.\n\n The `configParams` variable is defined as follows in the [Sample policy script](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/servicenow-platform/policy-as-code-engine-pace/pace-policy-structure.md).\n\n```\nvar dbPort = configParams.dbPort;\n```\n\nThe 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.\n\n
\n\nrecordRefs\n\n\n\nRecord 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.\n\n
\n\ndataCollectors\n\n\n\nThe data collectors function collects input process data from ServiceNow or an external data source to provide an output.\n\n
\n\nchildrenOutputs\n\n\n\nNot supported in this version.\n\n
\n\noutputThis 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.\n\n This example shows a sample output with compliant and non\\_compliant decisions:\n\n```\n\n{\n \"decision\": \"compliant\",\n \"results\": [],\n \"warnings\": [],\n \"failures\": [],\n \"state\": \"complete\"\n}\n\n\n{\n \"decision\": \"non_compliant\",\n \"results\": [],\n \"warnings\": [],\n \"failures\": [“Failed to validate key”],\n \"state\": \"complete\"\n}\n\n```\n\n
\n\noutput.decision\n\n\n\nThe decision property can be set to:- Compliant: Determines that the policy complies with requirements.\n- Non-compliant: Determines that the policy does not comply with the requirements.\n- 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.\n\n The decision is returned in a JSON format back to the calling service.\n\n **Note:** 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.\n\n
\n\noutput.results\n\n\n\nThe `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.\n\n
\n\noutput.warnings\n\n\n\nThe `warnings` property can be used to pass data back to the calling service on any warnings that occurred during the policy validation phase.\n\n
\n\noutput.failures\n\n\n\nThe `failures` property can be used to pass data back to the calling service on any errors that occurred during the policy validation phase.\n\n
\n\n**Note:** The following fields are automatically filled in when the PaCE policy script is executed.\n\n
\n\noutput.name\n\n\n\nThe name \\(current version\\) of the policy being executed.\n\n
\n\noutput.state\n\n\n\nIt indicates the state of the policy invocation.- Complete: The invocation was completed successfully.\n- Pending: Indicates that the policy could not be successfully executed and is an incomplete state.\n\n
**Note:**\n\n- Auto-complete suggestions are available in the policy script editor for the `logger, callerInput` and `mappedInput` parameter.\n- To view additional information for a parameter, enter the parameter name and select one of the options as follows:\n\n \\[Omitted image \"pace-hover-text.jpg\"\\] Alt text: PaCE additional parameter details\n\n\n"}}