CdmPoliciesApi

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 15 minutes to read

    • The CdmPoliciesApi provides endpoints that enable you to manage policy mappings of deployables in Configuration Data Management (CDM). Policies that are properly mapped to a deployable are executed when a snapshot of the deployable is validated.

    You must have one of the following roles to access the endpoints in this API:
    • Scripted REST CDM View ACL
    • Scripted REST CDM Admin ACL

    In addition, the Configuration Data Management (CDM) plugin must be activated for this API to be available in an instance.

    For additional information on policy mappings, see Map policies to a deployable.

    CdmPoliciesApi - DELETE /sn_cdm/policies/mappings

    Deletes the mapping of a specified policy to a deployable.

    The caller of this endpoint must have the CDM Admin role.

    URL format

    Versioned URL: /api/sn_cdm/{api_version}/policies/mappings

    Default URL: /api/sn_cdm/policies/mappings

    Supported request parameters

    Table 1. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 2. Query parameters
    Name Description
    appName Required. Name of the Configuration Data Management (CDM) application for which to remove the mapping to the policy. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    deployableName Required. Name of the CDM deployable for which to remove the mapping to the policy. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    policyName Required. Name of the associated policy. Located in the Policy [sn_pace_policy] table.

    Data type: String
    Table 3. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. The policyName parameter passed is invalid.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    error If an error occurred during processing, the details about the error.

    Data type: Object

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail Additional information about the error.

    Data type: String
    error.message Error message that was generated while trying to process the request.

    Data type: String

    cURL request

    The following code example shows how to remove a policy mapping.

    curl "http://instance.servicenow.com/api/sn_cdm/policies/mappings?deployableName=Development_1&policyName=testALPolicy1&appName=testApp" \ 
--request DELETE \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    For a successful deletion of the mapping, no response is returned other than the HTTP status code.

    None - results defined by the HTTP status code

    CdmPoliciesApi - GET /sn_cdm/policies/mappings/inputs/resolved

    Returns the resolved inputs for a specified policy mapping of a deployable.

    For additional information on policy mappings, see Map policies to a deployable and Validating and correcting configuration data.

    The caller of this endpoint must have the CDM Viewer role.

    URL format

    Versioned URL: /api/sn_cdm/{api_version}/policies/mappings/inputs/resolved

    Default URL: /api/sn_cdm/policies/mappings/inputs/resolved

    Supported request parameters

    Table 7. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 8. Query parameters
    Name Description
    appName Required. Name of the Configuration Data Management (CDM) application associated with the deployable for which to return the resolved policy inputs. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    deployableName Required. Name of the CDM deployable for which to return the resolved policy. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    policyName Required. Name of the associated policy. Located in the Policy [sn_pace_policy] table.

    Data type: String
    Table 9. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 10. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 11. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. The policyName parameter passed is invalid.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    result Name-value pair list of all resolved inputs for the specified policy mapping.

    For example: {"input_name": "user_1", "input_password": "" }

    Data type: Object

    cURL request

    The following example shows how to use this endpoint to obtain the resolved policy inputs.

    curl "http://instance.servicenow.com/api/sn_cdm/policies/mappings/inputs/resolved?policyName=testALPolicy1&deployableName=Development_1&appName=testApp" \ 
--request GET \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Return result:

    { 
  "result": { 
    "key1": "someVal", 
    "additionalDeployablesInput": "[{\"id\":\"e7e34a531b501110636e0fe0604bcba9\",\"label\":\"testApp-Development_2\"}]" 
  } 
}

    CdmPoliciesApi - POST /sn_cdm/policies/mappings

    Maps a specified policy to a deployable.

    The caller of this endpoint must have the CDM Admin role.

    URL format

    Versioned URL: /api/sn_cdm/{api_version}/policies/mappings

    Default URL: /api/sn_cdm/policies/mappings

    Supported request parameters

    Table 13. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 14. Query parameters
    Name Description
    appName Required. Name of the Configuration Data Management (CDM) application for which to map the policy. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    deployableName Required. Name of the CDM deployable for which to map the policy. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    policyName Required. Name of the associated policy. Located in the Policy [sn_pace_policy] table.

    Data type: String
    returnFields List of fields to return as part of the response. Pass the record column names such as sys_id, sys_updated_by, or state.

    Data type: Array

    Default: All fields as determined by the endpoint
    Table 15. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 16. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 17. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. A bad request type or malformed request was detected.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    description Description of the mapping.

    Data type: String
    document Sys_id of the document.

    Data type: String
    document_ref Details of the document_ref record associated with the node.

    Data type: Object

    "document_ref": {
  "link": "String",
  "value": "String"
}
    document_ref.link Call syntax for querying the deployable record mapped to the policy using the Table REST API.

    PaCE uses this field to store the reference to the deployable that is mapped to a policy.

    Data type: String
    document_ref.sys_id Sys_id of the deployable record mapped to the policy.

    Data type: String
    error If an error occurred during processing, the details about the error.

    Data type: Object

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail Additional information about the error.

    Data type: String
    error.message Error message that was generated while trying to process the request.

    Data type: String
    exception If there's an exception while trying to perform the mapping, the link to the exception record.

    Data type: String
    exception_allowed Flag that indicates whether exceptions are allowed for the policy.
    Possible values:
    • true: Exceptions are allowed.
    • false: Exceptions aren't allowed.

    Data type: Boolean
    input_status Status of the inputs.
    Possible values:
    • invalid
    • valid

    Data type: String
    last_updated_by Details of the user that last updated the policy mapping.

    Data type: Object

    "last_updated_by": {
  "link": "String",
  "value": "String"
}
    last_updated_by.link Call syntax for querying the user record using the Table REST API.

    Data type: String
    last_updated_by.sys_id Sys_id of the user record. Located in the User [sys_user] table.

    Data type: String
    number Unique number that identifies the mapping. This value provides a human-readable identifier for the mapping.

    Data type: String
    policy Details of the policy record associated with the mapping.

    Data type: Object

    "policy": {
  "link": "String",
  "value": "String"
}
    policy.link Call syntax for querying the policy record mapped to the policy using the Table REST API.

    Data type: String
    policy.sys_id Sys_id of the policy record. Located in the Policy [sn_pace_policy] table.

    Data type: String
    reason Description of the reason for the current state.

    Data type: String
    state Current state of the mapping.
    Possible values:
    • active
    • inactive

    Data type: String
    sys_class_name Table name of the policy mapping.

    Data type: String
    sys_created_by Name of the user that created the mapping.

    Data type: String
    sys_created_on Date and time when the mapping was created.

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss
    sys_id Sys_id of the mapping. Located in the Policy Mapping [sn_pace_policy_mapping] table.

    Data type: String
    sys_updated_by Name of the user that updated the mapping.

    Data type: String
    sys_updated_on Date and time when the mapping was last updated.

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss

    cURL request

    This code example shows how to map a specific policy to a deployable.

    curl "http://instance.servicenow.com/api/sn_cdm/policies/mappings?appName=testApp&deployableName=Development_1&policyName=testALPolicy1" \ 
--request POST \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Return results:

    { 
  "result": { 
    "exception": null, 
    "reason": null, 
    "exception_allowed": "--", 
    "document": "0be34a531b501110636e0fe0604bcb21", 
    "input_status": "valid", 
    "description": null, 
    "sys_updated_on": "2022-06-30 14:07:37", 
    "sys_class_name": "sn_cdm_pace_policy_mapping", 
    "sys_id": "ea24469f1b101110636e0fe0604bcbed", 
    "number": "MAP0001001", 
    "last_updated_by": { 
      "value": "48630e131b501110636e0fe0604bcb53", 
      "link": "https://instance.servicenow.com/api/now/table/sys_user/48630e131b501110636e0fe0604bcb53" 
    }, 
    "sys_updated_by": "admin", 
    "sys_created_on": "2022-06-30 14:07:37", 
    "document_ref": { 
      "value": "0be34a531b501110636e0fe0604bcb21", 
      "link": "https://instance.servicenow.com/api/now/table/sn_cdm_deployable/0be34a531b501110636e0fe0604bcb21" 
    }, 
    "state": "active", 
    "sys_created_by": "admin", 
    "policy": { 
      "value": "12a3c2531b501110636e0fe0604bcb9b", 
      "link": "https://instance.servicenow.com/api/now/table/sn_pace_policy/12a3c2531b501110636e0fe0604bcb9b" 
    } 
  } 
}

    CdmPoliciesApi - PUT /sn_cdm/policies/mappings/inputs/additional-deployables

    Updates the additionalDeployablesInput input variable of a Configuration Data Management (CDM) policy mapping.

    The additionalDeployablesInput input variable contains the additional deployables you can assign to an existing policy mapping. They are similar to mapping inputs, but they have a specific array structure.

    For additional information on policy mappings, see Map policies to a deployable.

    The caller of this endpoint must have the CDM Admin role.

    URL format

    Versioned URL: /api/sn_cdm/{api_version}/policies/mappings/inputs/additional-deployables

    Default URL: /api/sn_cdm/policies/mappings/inputs/additional-deployables

    Supported request parameters

    Table 19. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 20. Query parameters
    Name Description
    additionalDeployables Required. List of deployables to add to the additionalDeployablesInput input variable.

    Data type: Array of Objects

    "additionalDeployables": [
  {
    "appName": "String", 
    "deployableName": "String"
  }
]
    additionalDeployables.appName Required. Name of the CDM application to which the deployable is associated. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    additionalDeployables.deployableName Required. Name of the CDM deployable to add to the additionalDeployablesInput input variable. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    appName Required. Name of the CDM application for which to update the additionalDeployablesInput input variable. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    deployableName Required. Name of the CDM deployable for which to update the additionalDeployablesInput input variable. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    policyName Required. Name of the associated policy. Located in the Policy [sn_pace_policy] table.

    Data type: String
    returnFields List of fields to return as part of the response. Pass the record column names such as sys_id, sys_updated_by, or state.

    Data type: Array

    Default: All fields as determined by the endpoint
    Table 21. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 22. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 23. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 24. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. The policyName parameter passed is invalid.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    io_definition Details about the associated PaCE IO definition record.

    For additional information on PaCE, see Administering policies in DevOps Config.

    Data type: Object

    "io_definition": {
  "link": "String",
  "value": "String"
}
    io_definition.link Call syntax for querying this PaCE IO definition record using the Table REST API.

    Data type: String
    io_definition.value Sys_id of the PaCE IO definition record. Located in the IO Mapping [sn_pace_io_mapping] table.

    Data type: String
    is_unused Flag that indicates whether the mapping input variable is unused.
    Possible values:
    • true: Associated mapping input variable isn't currently used.
    • false: Associated mapping input variable is currently used.

    Data type: Boolean
    mapped_value Current value of the mapping input variable.

    Data type: Array of Objects or String
    policy_mapping Details about the PaCE policy-mapping record.

    For additional information on PaCE, see Administering policies in DevOps Config.

    Data type: Object

    "policy_mapping": {
  "link": "String",
  "value": "String"
}
    policy_mapping.link Call syntax for querying the policy mapping record using the Table REST API.

    Data type: String
    policy_mapping.value Sys_id of the PaCE policy-mapping record. Located in the Policy Mapping [sn_pace_policy_mapping] table.

    Data type: String
    sys_created_by Name of the user that created the mapping input variable.

    Data type: String
    sys_created_on Date and time when the mapping input variable was created.

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss
    sys_id Sys_id of the associated mapping record. Located in the IO Mapping [sn_pace_io_mapping] table.

    Data type: String
    sys_updated_by Name of the user that updated the mapping input variable.

    Data type: String
    sys_updated_on Date and time when the mapping input variable was last updated.

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss

    cURL request

    The following example shows how to add deployables to an additionalDeployablesInput input variable.

    curl "https://instance.servicenow.com/api/sn_cdm/policies/mappings/inputs/additional-deployables?additionalDeployables=%5B%7B%22appName%22%3A%20%22testApp%22%2C%20%22deployableName%22%3A%22Development_2%22%7D%5D&policyName=testALPolicy1&deployableName=Development_1&appName=testApp" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--user 'admin':'admin

    Return result:

    { 
  "result": { 
    "sys_id": "6bb746171b501110636e0fe0604bcb1c", 
    "policy_mapping": { 
      "value": "6bb746171b501110636e0fe0604bcb1b", 
      "link": "https://instance.servicenow.com/api/now/table/sn_cdm_pace_policy_mapping/6bb746171b501110636e0fe0604bcb1b" 
    }, 
    "sys_updated_by": "ameya", 
    "sys_created_on": "2022-06-30 14:23:15", 
    "io_definition": { 
      "value": "4d0b061b1b501110636e0fe0604bcb2f", 
      "link": "https://instance.servicenow.com/api/now/table/sn_pace_io_definition/4d0b061b1b501110636e0fe0604bcb2f" 
    }, 
    "mapped_value": "[{\"id\":\"e7e34a531b501110636e0fe0604bcba9\",\"label\":\"testApp-Development_2\"}]", 
    "sys_updated_on": "2022-06-30 14:53:21", 
    "sys_created_by": "ameya", 
    "is_unused": false 
  } 
}

    CdmPoliciesApi - PUT /sn_cdm/policies/mappings/inputs

    Updates a specified input variable for a Configuration Data Management (CDM) policy mapping.

    For additional information on policy mappings, see Map policies to a deployable.

    The caller of this endpoint must have the CDM Admin role.

    URL format

    Versioned URL: /api/sn_cdm/{api_version}/policies/mappings/inputs

    Default URL: /api/sn_cdm/policies/mappings/inputs

    Supported request parameters

    Table 25. Path parameters
    Name Description
    api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

    Data type: String
    Table 26. Query parameters
    Name Description
    appName Required. Name of the CDM application for which to update the policy mapping inputs. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    deployableName Required. Name of the CDM deployable for which to update the policy mapping inputs. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    inputName Required. Name of the input variable to update. The available input variables are defined in the IO Mapping [sn_pace_io_mapping] table.

    Data type: String
    inputValue Required. Value to assign to the input variable.

    Data type: Dependant on the input variable. You can find the data type in the IO Mapping [sn_pace_io_mapping] table.
    policyName Required. Name of the associated policy. Located in the Policy [sn_pace_policy] table.

    Data type: String
    returnFields List of fields to return as part of the response. Pass the record column names such as sys_id, sys_updated_by, or state.

    Data type: Array

    Default: All fields as determined by the endpoint
    Table 27. Request body parameters
    Name Description
    None

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 28. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Content-Type Data format of the request body. Only supports application/json.
    Table 29. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 30. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. The policyName parameter passed is invalid.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    io_definition Details about the associated PaCE IO definition record.

    For additional information on PaCE, see Administering policies in DevOps Config.

    Data type: Object

    "io_definition": {
  "link": "String",
  "value": "String"
}
    io_definition.link Call syntax for querying this PaCE IO definition record using the Table REST API.

    Data type: String
    io_definition.value Sys_id of the PaCE IO definition record. Located in the IO Mapping [sn_pace_io_mapping] table.

    Data type: String
    is_unused Flag that indicates whether the mapping input variable is unused.
    Possible values:
    • true: Associated mapping input variable isn't currently used.
    • false: Associated mapping input variable is currently used.

    Data type: Boolean
    mapped_value Current value of the mapping input variable.

    Data type: Array of Objects or String
    policy_mapping Details about the PaCE policy-mapping record.

    For additional information on PaCE, see Administering policies in DevOps Config.

    Data type: Object

    "policy_mapping": {
  "link": "String",
  "value": "String"
}
    policy_mapping.link Call syntax for querying the policy mapping record using the Table REST API.

    Data type: String
    policy_mapping.value Sys_id of the PaCE policy-mapping record. Located in the Policy Mapping [sn_pace_policy_mapping] table.

    Data type: String
    sys_created_by Name of the user that created the mapping input variable.

    Data type: String
    sys_created_on Date and time when the mapping input variable was created.

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss
    sys_id Sys_id of the associated mapping record. Located in the IO Mapping [sn_pace_io_mapping] table.

    Data type: String
    sys_updated_by Name of the user that updated the mapping input variable.

    Data type: String
    sys_updated_on Date and time when the mapping input variable was last updated.

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss

    cURL request

    The following example shows how to update the key1 input variable associated with the testALPolicy.

    curl "http://instance.servicenow.com/api/sn_cdm/policies/mappings/inputs?policyName=testALPolicy1&appName=testApp&inputValue=value1&inputName=key1&deployableName=Development_1" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Return results:

    { 
  "result": { 
    "sys_id": "631b861b1b501110636e0fe0604bcb6f", 
    "policy_mapping": { 
      "value": "6bb746171b501110636e0fe0604bcb1b", 
      "link": "https://instance.servicenow.com/api/now/table/sn_cdm_pace_policy_mapping/6bb746171b501110636e0fe0604bcb1b" 
    }, 
    "sys_updated_by": "admin", 
    "sys_created_on": "2022-06-30 14:38:00", 
    "io_definition": { 
      "value": "fe1b061b1b501110636e0fe0604bcb90", 
      "link": "https://instance.servicenow.comm/api/now/table/sn_pace_io_definition/fe1b061b1b501110636e0fe0604bcb90" 
    }, 
    "mapped_value": "someVal", 
    "sys_updated_on": "2022-06-30 14:39:21", 
    "sys_created_by": "admin", 
    "is_unused": false 
  } 
}