CdmChangesetsApi

concept brazil Updated Sep 10, 2026 40 min read changesets-api.md
Raw file servicenow.com

The CdmChangesetsApi provides endpoints that enable you to manage changesets.

Using these endpoints you can:

  • Create new changesets.
  • Deploy changesets.
  • Retrieve lists of or individual changesets.
  • Retrieves the node changes within a changeset.
  • Retrieve a list of applications or deployables that are impacted by a changeset.
  • Delete changesets.
  • Return a list of shared components that are associated with a specified changeset.

The create changesets endpoints use an asynchronous queuing implementation. With this type of implementation, you first call the create changeset request endpoint. This endpoint queues your request and returns a commit identifier. You then use this commit identifier to call the appropriate status endpoint to obtain the status of the create request.

You must have one of the following roles to access this API:

  • Scripted REST CDM View ACL (sn_cdm.cdm.viewer)
  • Scripted REST CDM Editor ACL (sn_cdm.cdm_editor)

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

For additional information on changesets, see Changesets and version control in CDM.

Parent Topic:REST API reference

CdmChangesetsApi - DELETE /sn_cdm/changesets

Deletes a specified changeset.

The caller must have the CDM Editor role to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets

Default URL: /api/sn_cdm/changesets

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

changesetNumber

Required. Unique identifier of the associated changeset, such as "Chset-10".

Data type: String

Table: CDM Changeset [sn_cdm_changeset]
|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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

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
None

cURL request

The following code example shows how to remove a changeset.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets?changesetNumber=Chset-760" \ --request DELETE \ --header "Accept:application/json" \ --user 'username':'password'

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

Text
None - results defined by the HTTP status code

CdmChangesetsApi - GET /sn_cdm/changesets

Retrieves all changesets associated with a Configuration Data Management (CDM) application or a specified changeset record.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets

Default URL: /api/sn_cdm/changesets

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

appName

Required. Name of the CDM application whose changesets you want returned. This must be an active application.Data type: String

Table: CDM Application [sn_cdm_application]

number

Changeset number.If you pass this value, only the specified changeset is returned. It must be a changeset that is associated with the CDM application specified in the appName parameter.

Data type: String

Default: None - return all changesets associated with the CDM application or the ones specified by the state parameter.

Table: CDMChangeset [sn_cdm_changeset]

state

State of the changesets to return. Only return the changesets associated with the specified CDM application for the specified state.Valid values:

  • Blocked
  • Checking for conflict
  • Commit failed
  • Commit in progress
  • Committed
  • Open

Data type: String

Default: Return all changesets for all states
|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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

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

auto_validate

Flag that indicates whether the changesets created upon commit are validated.Valid values:

  • true: Validate the changesets.
  • false: Don't validate the changesets.

Data type: Boolean

cdm_application

Details of the CDM application associated with the changeset. Data type: Object

Text
"cdm_application": {  "link": "String",  "value": "String"}

cdm_application.link

Query to use to call the Table REST endpoint to retrieve the associated CDM application.Data type: String

cdm_application.value

Sys_id of the associated CDM application.Data type: String

Table: CDM Application [sn_cdm_application]

committed_at

Date and time that the changeset was last committed.Data type: String

Format: YYYY-mm-DD hh:mm:ss

committed_by

Details about the user that committed the changeset.Data type: Object

Text
"committed_by": {  "link": "String",  "value": "String"}

committed_by.link

Call to obtain the record of the user that committed the changeset using the REST Table API.Data type: String

committed_by.value

Sys_id of the user who committed the changeset.Data type: String

description

Brief description of the purpose of the changeset.Data type: String

error

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

Text
"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

last_conflict_detection_time

Amount of time since the last conflict detection was run. Conflict detection is performed whenever a changeset is committed.Data type: Number

Unit: Milliseconds

last_updated

Date and time when a change was made to the associated configuration data through this changeset.Format: YYYY-mm-DD hh:mm:ss

Data type: String

number

Unique changeset number.Data type: String

publish_option

Publish option for the associated configured snapshots.

Valid values:

  • publish_none: Don't publish any snapshots.
  • publish_valid: Publish only those snapshots that pass validation after the commit.

For additional information on publishing snapshots, see Publish or unpublish a snapshot.

Data type: String

Default: publish_none

state

Current state of the changeset.Possible values:

  • Blocked
  • Checking for conflict
  • Commit failed
  • Commit in progress
  • Committed
  • Open

Data type: String

sys_created_by

User name of the user that created the changeset. For example, able.tuter.Data type: String

sys_created_on

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

Format: YYYY-mm-DD hh:mm:ss

sys_id

Sys_id of the changeset.Data type: String

Table: CDMChangeset [sn_cdm_changeset]

sys_updated_by

User name of the user that last updated the changeset. For example, able.tuter.Data type: String

sys_updated_on

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

Format: YYYY-mm-DD hh:mm:ss

title

Title of the changeset.Data type: String
### cURL request

This code example shows how to retrieve a specific changeset.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets?appName=testApp&changesetNumber=Chset-946&state=committed" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

Return results:

JSON
{   "result": [     {       "description": "Auto generated for deletion of CDM Deployable Dep-12022-06-29 13:09:46",       "cdm_application": {         "value": "62b517a953b70110a1d3ddeeff7b128c",         "link": "http://instance.servicenow.com/api/now/table/sn_cdm_application/62b517a953b70110a1d3ddeeff7b128c"       },       "sys_updated_on": "2022-06-29 13:09:47",       "title": "Auto generated for deletion of CDM Deployable Dep-12022-06-29 13:09:46",       "number": "Chset-946",       "sys_id": "955d6c0f53141110a1d3ddeeff7b1233",       "sys_updated_by": "admin",       "committed_at": "2022-06-29 13:09:46",       "sys_created_on": "2022-06-29 13:09:46",       "committed_by": {         "value": "6816f79cc0a8016401c5a33be04be441",         "link": "http://instance.servicenow.com/api/now/table/sys_user/6816f79cc0a8016401c5a33be04be441"       },       "state": "committed",       "auto_validate": true,       "publish_option": "publish_none",       "last_conflict_detection_time": "1656508187450",       "sys_created_by": "admin",       "last_updated": "2022-06-29 13:09:46"     }   ] }

CdmChangesetsApi - GET /sn_cdm/changesets/activity

Retrieves the node changes within a specified changeset.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/activity

Default URL: /api/sn_cdm/changesets/activity

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

changesetNumber

Required. Unique identifier of the associated changeset, such as "Chset-10".

Data type: String

Table: CDM Changeset [sn_cdm_changeset]

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
|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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

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

changeset_id

Details of the requested changeset. Data type: Object

Text
"changeset_id": { "link": "String", "value": "String"}

changeset_id.link

Query to use to call the Table REST endpoint to retrieve the associated changeset.Data type: String

changeset_id.value

Sys_id of the associated changeset.Data type: String

Table: CDM Changeset [sn_cdm_changeset]

conflict

Flag that indicates whether there is a conflict in the associated changeset.Valid values:

  • true: Conflict detected.
  • false: No conflict found.

Data type: Boolean

created

Date and time when the node was created.Format: YYYY-mm-DD hh:mm:ss

Data type: String

created_by

User name of the user that create the node. For example, able.tuter.Data type: String

error

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

Text
"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

name_path

Node path name.Data type: String

new_name

Current name of the node.Data type: String

new_value

Current value of the node. For leaf nodes and array literals.Data type: String

old_name

Previous name of the node.Data type: String

old_value

Previous value of the node. For leaf nodes and array literals.Data type: String

updated

Date and time when the node was last updated.Format: YYYY-mm-DD hh:mm:ss

Data type: String

updated_by

User name of the user that last updated the node. For example, able.tuter.Data type: String

secure

Flag that indicates whether the associated leaf node was secured.Valid values:

  • true: Node was secured.
  • false: Node was not secured.

Data type: Boolean

type

Node type.

Possible values:

  • sn_cdm_node_collection
  • sn_cdm_node_component
  • sn_cdm_node_folder
  • sn_cdm_node_cdi
  • sn_cdm_node_variable

Data type: String
### cURL request

This code example shows how to retrieve the node changes for a specific changeset.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/activity?changesetNumber=Chset-783" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

Return results:

JSON
{   "result": [     {       "sys_id": "ed5d6c0f53141110a1d3ddeeff7b1233",       "changeset_id": "955d6c0f53141110a1d3ddeeff7b1233",       "new_value": null,       "new_state": "Deleted",       "new_name": "Dep-1",       "new_type": "Deployable",       "new_encrypted": false,       "updated_on": "2022-06-29 13:09:46",       "updated_by": "admin",       "resolution_method": "",       "conflict": null,       "path": "deployables/Dep-1",       "created_by": null,       "created_on": null,       "old_value": null,       "old_state": "Superseded",       "old_name": "Dep-1",       "old_type": "Deployable",       "old_encrypted": false     } ] }

CdmChangesetsApi - GET /sn_cdm/changesets/commit-status/{commit_id}

Returns the current status of the specified changeset commit request.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/commit-status/{commit_id}

Default URL: /api/sn_cdm/changesets/commit-status/{commit_id}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

commit_id

Sys_id for the commit request whose status to return. This value is returned by the CdmChangesetsApi - POST /sn_cdm/changesets/{changeset_id}/commit endpoint.

Data type: String
|Name|Description| |----|-----------| |None| |
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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

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

commit_id

Commit request record sys_id. Same as that passed into the endpoint.Data type: String

errors

Description of the error(s) encountered during upload.Data type: String

output

Description of the uploaded data or if an error occurred during the upload, an error message describing the error that was encountered.Data type: Object

JSON
"output": {  "auto_validate": "String",  "cdm_application": "String",  "committed_at": "String",  "committed_by": "String",  "description": "String",  "last_conflict_detection_time": "String",  "number": "String",  "publish_option": "String",  "snapshot_description": "String",  "snapshot_name": "String",  "state": "String",  "sys_created_by": "String",  "sys_id": "String",  "title": "String"}

output.auto_validate

Indicates whether to invoke validation after the commit.Data type: String

output.cdm_application

Name of application under which the upload was performed.Data type: String

output.committed_at

Date and time that the uploaded content was committed.Data type: String

output.committed_by

Sys_id of the record of the entity that performed the commit.Data type: String

output.description

Not currently used.Data type: String

output.last_conflict_detection_time

Date and time conflict detection invocation.Data type: String

output.number

Unique number of the changeset.Data type: String

output.publish_option

Publish option for the associated configured snapshots.

Valid values:

  • publish_none: Don't publish any snapshots.
  • publish_valid: Publish only those snapshots that pass validation after the commit.

For additional information on publishing snapshots, see Publish or unpublish a snapshot.

Data type: String

Default: publish_none

output.snapshot_description

Description of the associated snapshot.Data type: String

output.snapshot_name

Name of the associated snapshot.Data type: String

output.state

State of the upload content.Possible values:

  • committed
  • completed
  • error
  • in_progress
  • new
  • ready

Data type: String

output.sys_created_by

Sys_id of the entity that created the record.Data type: String

output.sys_id

Sys_id of the record containing the changeset.Data type: String

output.title

Title of changeset created as part of the upload.Data type: String

processing_state

Current processing state of the commit request.Possible values:

  • NOT_PROCREED
  • PROCESSED

Data type: String

request_id

Request ID. Same as that passed into the endpoint and commit_id.Data type: String

state

Current state of the specified commit.Possible values:

  • completed
  • error
  • in_progress
  • new
  • ready

Data type: String

Table: Value from state column of the CDM Request Queue [sn_cdm_request_queue] table.

type

Type of request.Possible values:

  • commit
  • export
  • upload_and_commit

Data type: String
### cURL request

The following example shows how to call this endpoint to obtain the status of the specified commit.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/commit-status/bf506e69537c3010a1d3ddeeff7b12c0"\ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

The following shows examples of a success and error response.

JavaScript
// Successful response 
{   "result": {     "type": "commit",     "state": "completed",     "output": {       "sys_id": "4a4407e953124110da35ddeeff7b1235",       "number": "Chset-1207",       "title": "admin064407e953124110da35ddeeff7b1235",       "description": "A description of my changeset provided during creation",       "committed_at": "2022-03-17 22:19:33",       "committed_by": "6816f79cc0a8016401c5a33be04be441",       "sys_created_by": "admin",       "state": "committed",       "publish_option": "publish_none",       "auto_validate": false,       "snapshot_name": null,       "snapshot_description": null,       "cdm_application": "DemoApp",       "last_conflict_detection_time": null     },     "processing_state": "PROCESSED",     "commit_id": "9cd583e953124110da35ddeeff7b128a"   } } 
 
// Example of an error response 
{   "result": {     "state": "error",     "errors": "Invalid requestId '9cd583e953124110da35ddeeff7b128'",     "commit_id": "9cd583e953124110da35ddeeff7b128"   } }

CdmChangesetsApi - GET /sn_cdm/changesets/impacted-deployables

Returns the list of deployables that are associated with a specified changeset.

The CDM Viewer role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/impacted-deployables

Default URL: /api/sn_cdm/changesets/impacted-deployables

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

changesetNumber

Required. Unique identifier of the associated changeset, such as "Chset-10".

Data type: String

Table: CDM Changeset [sn_cdm_changeset]

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
|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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

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

cdi_count

Number of configuration data items (CDIs) contained in the associated CDM application.Data type: Number (Integer)

cdi_usage

Percentage of the CDIs used by the deployable.Data type: Number (Integer)

cdm_app

CDM application object associated with the deployable.Data type: Object

Text
"cdm_app": {  "link": "String",  "value": "String"}

cdm_app.link

Call to use to access the CDM application record using the REST Table API. Data type: String

cdm_app.value

Sys_id of the associated CDM application record.Data type: String

Table: CDM Application [sn_cdm_application]

cdm_ci

Application service object associated with the deployable.Data type: Object

Text
"cdm_ci": {  "link": "String",  "value": "String"}

cdm_ci.link

Call to use to access the application service record using the REST Table API.Data type: String

cdm_ci.value

Sys_id of the associated application service record. Data type: String

Table: Configuration Item [cmdb_ci]

description

Description of the generated CDM deployable.Data type: String

environment_type

Environment type of the deployable.Possible values:

  • Development
  • Production
  • Test

Data type: String

error

Only returned if an error occurred during processing.Data type: Object

Text
"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

name

Name of the CDM deployable.Data type: String

node

Details about the deployable node.Data type: Object

Text
"node": {  "link": "String",  "value": "String"}

node.link

Call to use to access the deployable node record using the REST Table API. Data type: String

node.value

Sys_id of the deployable node record.Data type: String

Table: CDM Deployable [sn_cdm_deployable]

snapshot_version_counter

Number of snapshots created for the deployable.Data type: Number (Integer)

state

Current state of the deployable.Possible values:

  • active
  • deleted

Data type: String

sys_created_by

User name of the user that created the CDM deployable. For example, able.tuter.Data type: String

sys_created_on

Date and time when the CDM deployable was created.Data type: String

Format: YYYY-mm-DD hh:mm:ss

sys_id

Sys_id of the created deployable.Data type: String

Table: CDM Deployable [sn_cdm_deployable]

sys_updated_by

User name of the user that last updated the CDM deployable. For example, able.tuter.Data type: String

sys_updated_on

Date and time when the CDM deployable was last updated.Data type: String

Format: YYYY-mm-DD hh:mm:ss
### cURL request

The following code example shows how to retrieve the impacted deployables for a specified changeset.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/impacted-deployables?changesetNumber=Chset-783" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

Return results:

JSON
{   "result": [     {       "cmdb_ci": {         "value": "75c5d7a953b70110a1d3ddeeff7b12a2",         "link": "http://instance.servicenow.com/api/now/table/cmdb_ci_service_auto/75c5d7a953b70110a1d3ddeeff7b12a2"       },       "cdi_count": "2",       "snapshot_version_counter": "3",       "description": null,       "sys_updated_on": "2022-06-29 16:19:05",       "environment_type": "Development",       "node": {         "value": "a1c517a953b70110a1d3ddeeff7b129b",         "link": "http://instance.servicenow.com/api/now/table/sn_cdm_node/a1c517a953b70110a1d3ddeeff7b129b"       },       "sys_id": "6dc517a953b70110a1d3ddeeff7b129b",       "sys_updated_by": "admin",       "cdm_app": {         "value": "62b517a953b70110a1d3ddeeff7b128c",         "link": "http://instance.servicenow.com/api/now/table/sn_cdm_application/62b517a953b70110a1d3ddeeff7b128c"       },       "sys_created_on": "2022-05-31 13:03:23",       "cdi_usage": "0.02",       "name": "Development_1",       "state": "active",       "sys_created_by": "admin"     }   ] }

CdmChangesetsApi - GET /sn_cdm/changesets/impacted-shared-components

Returns a list of shared components that are associated with a specified changeset.

The CDM Viewer role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/impacted-shared-components

Default URL: /api/sn_cdm/changesets/impacted-shared-components

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

changesetNumber

Required. Unique identifier of the associated changeset, such as "Chset-10".

Data type: String

Table: CDM Changeset [sn_cdm_changeset]

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
|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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. The passed changeset does not exist.
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

cdm_shared__library

Sys_id of the shared library under which the component resides.Data type: String

description

Description of the CDM shared component.Data type: String

error

Only returned if an error occurred during processing.Data type: Object

Text
"error": {  "detail": "String",  "message": "String"}

error.detail

Details about the error that occurred.Data type: String

error.message

Message that provides an overview of the error.Data type: String

name

Name of the CDM shared component.Data type: String

node

Sys_id of the shared component node.Data type: String

Table: CDM Node [sn_cdm_node]

node_main

Sys_id of the main_id of the shared component node record.Data type: String

Table: CDM Node Main [sn_cdm_node_main]

state

Current state of the shared component.Possible values:

  • active
  • deleted

Data type: String

sys_created_by

User name of the user that create the CDM shared component. For example, able.tuter.Data type: String

sys_created_on

Date and time when the CDM shared component was created.Format: YYYY-mm-DD hh:mm:ss

Data type: String

sys_id

Sys_id of the shared component.Data type: String

Table: CDM Shared Component [sn_cdm_shared_component]

sys_updated_by

User name of the user that last updated the CDM shared component. For example, able.tuter.Data type: String

sys_updated_on

Date and time when the CDM shared component was last updated.Format: YYYY-mm-DD hh:mm:ss

Data type: String

version_counter

Number of versions created for the shared component.Data type: Integer
### cURL request

The following code example shows how to retrieve the impacted shared components for changeset = "Chset-20".

Shell
curl "https://instance.servicenow.com/sn_cdm/changesets/impacted-shared-components?changesetNumber=Chset-20" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

Response:

JSON
{  "result": [    {      "version_counter": "1",      "description": null,      "cdm_shared_library": "acb905e097b3991052687b890353afcd",      "sys_updated_on": "2022-12-12 20:28:49",      "node": "3cb945e097b3991052687b890353af0d",      "sys_id": "34b945e097b3991052687b890353af20",      "sys_updated_by": "john.jones",      "node_main": "74b945e097b3991052687b890353af0d",      "sys_created_on": "2022-12-12 20:28:39",      "name": "logonService-V2.1",      "state": "active",      "sys_created_by": "john.jones"    },    {      "version_counter": "1",      "description": null,      "cdm_shared_library": "acb905e097b3991052687b890353afcd",      "sys_updated_on": "2022-12-12 20:28:49",      "node": "b0b945e097b3991052687b890353af11",      "sys_id": "30b945e097b3991052687b890353af21",      "sys_updated_by": "john.jones",      "node_main": "f8b945e097b3991052687b890353af10",      "sys_created_on": "2022-12-12 20:28:39",      "name": "logonService-V2.2",      "state": "active",      "sys_created_by": "john.jones"    },    {      "version_counter": "1",      "description": null,      "cdm_shared_library": "acb905e097b3991052687b890353afcd",      "sys_updated_on": "2022-12-12 20:28:49",      "node": "6cb905e097b3991052687b890353afd3",      "sys_id": "b4b945e097b3991052687b890353af21",      "sys_updated_by": "john.jones",      "node_main": "a4b905e097b3991052687b890353afd3",      "sys_created_on": "2022-12-12 20:28:39",      "name": "paymentService-V1.0",      "state": "active",      "sys_created_by": "john.jones"    },    {      "version_counter": "1",      "description": null,      "cdm_shared_library": "acb905e097b3991052687b890353afcd",      "sys_updated_on": "2022-12-12 20:28:49",      "node": "e0b905e097b3991052687b890353aff1",      "sys_id": "3cb945e097b3991052687b890353af21",      "sys_updated_by": "john.jones",      "node_main": "2cb905e097b3991052687b890353aff0",      "sys_created_on": "2022-12-12 20:28:39",      "name": "paymentService-V1.1",      "state": "active",      "sys_created_by": "john.jones"    }  ]}

CdmChangesetsApi - GET /sn_cdm/changesets/{changeset_id}/impacted-deployables

Returns the list of deployables that are associated with a specified changeset.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/{changeset_id}/impacted-deployables

Default URL: /api/sn_cdm/changesets/{changeset_id}/impacted-deployables

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

changeset_id

Sys_id of the changeset record to process.Data type: String

Table:CDM Changeset [sn_cdm_changeset]
|Name|Description| |----|-----------| |None| |
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.

Header Description
Accept Data format of the response body. Only supports application/json.
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.

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

changeset_id

Sys_id of the last changeset associated with the deployable node.Data type: String

conflict

Flag that indicates whether the associated deployable is in conflict.Possible values:

  • 0: Not in conflict.
  • 1: Conflicted - refer to the conflict_type return result for additional information.

Data type: Number

conflict_type

Type of deployable conflict.Possible values:

  • corrupted_node
  • deleted_node
  • duplicated_node
  • incomplete_deleted_parent
  • incomplete_deleted_ref
  • incomplete_renamed_ref
  • invalid_include
  • orphaned_descendant
  • related_conflict
  • unlinked_include
  • unrenamed_include
  • updated_node

Data type: String

description

Description of the deployable node.Data type: String

effective_from

Timestamp when the node is valid. This value is null until you commit a changeset in which the node was created.Data type: Number

effective_to

Timestamp when the node is no longer valid. If this value is null, the node stays in affect until it is replaced with a new version.Data type: Number

error

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

Text
"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

level

Depth of the node starting from the application level, which is 0.Data type: Number

linked_to

ID of the reference node within a collection and component.For example, the following node snippet shows a link between the collection collA and the component compA. For this example, the linkedTo value is 1:

CSS
{ components : {compA:{} //MainId: 1}, 
Collections : { collA : {     compA :{} //Include, linkedTo: 1     }   } }

Data type: String

main_id

Unique identifier of the deployable node. This value is generated when the node is created and used to identify the deployable node.Data type: Number

main_id_encoded

Encoded value of the mainId return results, using Radix 57 string representation.Data type: String

name

Name of the deployable.Data type: String

node_classifier

Node classification, such as Development, Production, or Test. In the format:

  • /application/deployables/env:Development
  • /application/deployables/env:Production
  • /application/deployables/env:Test

Data type: String

position

Deployable node position. Only applicable to arrays.For example, for the array:

Text
node1:{  arrayNode: [{}, "literal1", "literal2", []] }

{} is position 1000,

"literal1" is position 2000,

"literal2" is position 3000,

[] is position 4000

Data type: Number

previous_version

Sys_id of the previous version of the associated deployable node.Data type: String

restricted_to

List of sys_ids of the users that are allowed to access the associated deployable node. This value is null if all groups can access the deployable.Data type: String

Table: CDM Restricted Groups [sn_cdm_restricted_groups]

secure_value

Secure value of the CDI or variable. Only returned for leaf nodes and array literals. This is the same as the value return result, but is encrypted.Data type: String

status

Status of deployable node or the status of a failed request.Possible values:

  • deleted
  • failure (passed if endpoint call fails.)
  • new
  • superseded
  • updated
  • valid

Data type: String

system_folder

Flag that indicates whether the associated folder is a system folder.Possible values:

  • 0: Not a system folder.
  • 1: System folder.

Data type: Number

sys_id

Sys_id of the impacted deployable.Data type: String

type

Node type, such as sn_cdm_node_deployable. This value enables you to determine whether the node is a component, config data item (CDI), or deployable. This value is generated when the node is created.Data type: String

value

Value of the CDI or variable. Only returned for leaf nodes and array literals. If this information is encrypted, it is returned in the secure_value return result.For example, if this node is the CDI nodeA:{cdi1: 1}, the value return result is 1. If it is an array node such as node1: {arrayNode: [{}, "literal1", "literal2", []]}, the value return result is literal1.

Data type: String
### cURL request

The following example shows how to request the deployables that are associated with the changeset whose sys_id is bf506e69537c3010a1d3ddeeff7b12c0.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/bf506e69537c3010a1d3ddeeff7b12c0/impacted-deployables"\ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

The following shows both a successful and an error response for this endpoint.

JavaScript
// Successful response{  "result": [    {      "sys_id": "833527a953924110da35ddeeff7b12c1",      "type": "sn_cdm_node_deployable",      "main_id": "150",      "main_id_encoded": "&M",      "node_path": "!&@!&D!&M",      "level": 2,      "status": "valid",      "node_classifier": "/application/deployables/env:Development",      "position": null,      "restricted_to": null,      "changeset_id": "cb3527a953924110da35ddeeff7b12c0",      "previous_version": "e8946f6953924110da35ddeeff7b1264",      "effective_from": "1647563806950",      "effective_to": null,      "name": "Development_1",      "description": "dev deployable decription",      "value": null,      "secure_value": null,      "system_folder": "0",      "linked_to": null,      "conflict": "0",      "conflict_type": null    },    {      "sys_id": "a245e7a953924110da35ddeeff7b1223",      "type": "sn_cdm_node_deployable",      "main_id": "153",      "main_id_encoded": "&P",      "node_path": "!&@!&D!&P",      "level": 2,      "status": "valid",      "node_classifier": "/application/deployables/env:Test",      "position": null,      "restricted_to": null,      "changeset_id": "ea45e7a953924110da35ddeeff7b1222",      "previous_version": "9505ef6953924110da35ddeeff7b121a",      "effective_from": "1647563821422",      "effective_to": null,      "name": "Test_1",      "description": "test deployable decription",      "value": null,      "secure_value": null,      "system_folder": "0",      "linked_to": null,      "conflict": "0",      "conflict_type": null    }  ]} 
// Example of an error response{  "error": {    "message": "Error: Unexpected error occurred in create request.Error:Application not found",    "detail": ""  },  "status": "failure"}

CdmChangesetsApi - POST /sn_cdm/changesets/{changeset_id}/commit

Commits the specified changeset. Once committed, the changeset is persisted into the CDM tables within the associated instance.

The system updates the application to persist the changes to the configuration data within the changeset. The changeset state changes to Committed. The system then generates a snapshot of each deployable that is affected by the changeset.

This endpoint returns the ID of the commit request. Use this ID to call the CdmChangesetsApi - GET /sn_cdm/changesets/commit-status/{commit_id} endpoint to obtain the current status of the changeset commit.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/{changeset_id}/commit

Default URL: /api/sn_cdm/changesets/{changeset_id}/commit

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

changeset_id

Sys_id of the changeset record to process.Data type: String

Table:CDM Changeset [sn_cdm_changeset]

Name

Description

autoValidate

Flag that indicates whether the snapshots created upon commit are validated, meaning any associated policies are run against the snapshot.Valid values:

  • true: Validate the snapshots.
  • false: Do not validate the snapshots.

Default: false

publishOption

Publish option for the associated configuration snapshots. Valid values:

  • publish_none: Do not publish any snapshots.
  • publish_valid: Publish only those snapshots that pass validation after the commit.

Note: This option is only available if the value for the autoCommit parameter is true.

For additional information on publishing snapshots, see Publish or unpublish a snapshot.

Data type: String

Default: publish_none
|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.

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.
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.

Status code

Description

200

Successful. The request was successfully processed.

400

Bad Request. Error: <Error message>Validate that the changeset_id parameter that you passed in was correct.

Ensure that you have the required roles to access this endpoint.

500

Internal Server Error Error: Invalid boolean value.If you passed in the autoValidate parameter, verify that it is a boolean value.
### Response body parameters

Name

Description

commit_id

Sys_id of the commit request. Use this ID when calling the CdmChangesetsApi - GET /sn_cdm/changesets/commit-status/{commit_id} endpoint to check the status of the commit request.

Data type: String

error

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

Text
"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

status

Status of the commit. Only returned when an error occurs.Possible values: failure

Data type: String
### cURL request

The following example shows how to call this endpoint to commit a changeset record.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/29e24001533030104bacddeeff7b120c/commit?publishOption=publish_valid"\ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \--user 'username':'password'

The following shows the response for a successful changeset commit request.

JavaScript
// Successful response{   "result": {     "commit_id": "64b5f79f5379301096edddeeff7b12eb"   } }
// Example of an error response{  "error": {    "message": "Error: Unexpected error occurred in commit request.Error:Failed to insert request in queue",    "detail": ""  },  "status": "failure"}

CdmChangesetsApi - POST /sn_cdm/changesets/create

Creates a new changeset in the open state for a specified CDM application or shared library.

The CDM Editor role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/create/

Default URL: /api/sn_cdm/changesets/create/

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

appName

Required. Name of the CDM application or shared library to associate with this changeset. This must be an active application or shared library.Data type: String

description

Changeset description. Enter something that will allow others to understand the purpose of the changeset.Data type: String

Default: None

returnFields

Comma separated list of fields in the CDM Changeset [sn_cdm_changeset] table to return as part of the response.Data type: String
|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.

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.
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.

Status code

Description

200

Successful. The request was successfully processed.

400

Bad Request. Error: <Error message>Ensure that the specified CDM application or shared library exists and in the active state.

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

auto_validate

Flag that indicates whether auto validation was performed.

Possible values:

  • true: Auto validation was performed.
  • false: Auto validation was not preformed.

Data type: Boolean

cdm_application

Details about the CDM application associated with the changeset.Data type: Object

Text
"cdm_application": {  "link": "String", "value": "String"}

For example: {"value": "<sysId>", "link": "http://localhost:8081/api/now/table/*’}"

cdm_application.link

URL of the associated CDM application.Data type: String

cdm_application.value

Sys_id of the associated CDM application.Data type: String

committed_at

Date and time that the changeset was committed to the associated repository.Data type: String

committed_by

Sys_id of the entity that created the changeset.Data type: String

description

Description of the changeset as passed when the endpoint was called.Data type: String

error

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

Text
"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

last_conflict_detection_time

Last time conflict detection ran.Data type: Number

Unit: Milliseconds

number

Unique identifier for the new changeset.Data type: String

publish_option

Publish option for the associated configured snapshots.

Valid values:

  • publish_none: Don't publish any snapshots.
  • publish_valid: Publish only those snapshots that pass validation after the commit.

For additional information on publishing snapshots, see Publish or unpublish a snapshot.

Data type: String

Default: publish_none

snapshot_description

Description of the snapshot associated with the changeset.Data type: String

state

State of the changeset creation.Possible values:

  • Blocked
  • Checking for conflict
  • Commit failed
  • Commit in progress
  • Committed
  • Open

Data type: String

status

Status of the changeset creation. Only returned when an error occurs.Possible values: failure

Data type: String

sys_created_by

Sys_id of the entity that created the changeset record.Data type: String

sys_id

Sys_id of the new changeset.Data type: String

title

Title of the changeset associated with the application. Typically auto-generated by the system.Data type: String
### cURL request

The following example shows how to create a changeset associated with the App Service1 CDM application.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/create?appName=App%20Service1&description=Sample%20Description \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \--user 'username':'password'

The following shows the response for a successful creation of the changeset.

JavaScript
// Example of a successful response{   "result": {     "sys_id": "42748779c370301054c1582e1340ddcd",    "number": "Chset-8",    "title": "admin2021-06-18 10:06:46",    "description": null,    "committed_at": "",    "committed_by": null,    "sys_created_by": "admin",    "state": "open",    "publish_option": "publish_none",    "auto_validate": false,    "snapshot_name": null,    "snapshot_description": null,    "cdm_application": "App%20Service1"   } }
// Example of an error response{  "error": {    "message": "Error: Unexpected error occurred in create request.Error:Application not found",    "detail": ""  },  "status": "failure"}

cURL request

The following example shows how to create a changeset for the shared library "javalib".

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/create?sharedLibraryName=javalib&description=description of changeset" \ --request POST \ --header "Accept:application/json" \ --user 'username':'password'

Response:

Text

CdmChangesetsApi - PUT /sn_cdm/changesets/commit

Updates and commits a specified changeset.

The system updates the application to persist the changes to the configuration data within the changeset. The changeset state changes to Committed. The system then generates a snapshot of each deployable that is affected by the changeset.

This endpoint returns the ID of the commit request. Use this ID to call the CdmChangesetsApi - GET /sn_cdm/changesets/commit-status/{commit_id} endpoint to obtain the current status of the changeset commit.

URL format

Versioned URL: /api/sn_cdm/{api_version}/changesets/{changeset_id}/commit

Default URL: /api/sn_cdm/changesets/{changeset_id}/commit

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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

Name

Description

autoValidate

Flag that indicates whether the snapshots created during the commit are validated, meaning any associated policies are run against the snapshot.Valid values:

  • true: Validate the snapshots.
  • false: Don't validate the snapshots.

Data type: Boolean

Default: false

changesetNumber

Required. Unique identifier of the associated changeset, such as "Chset-10".

Data type: String

Table: CDM Changeset [sn_cdm_changeset]

publishOption

Publish option for the associated configured snapshots.

Valid values:

  • publish_none: Don't publish any snapshots.
  • publish_valid: Publish only those snapshots that pass validation after the commit.

For additional information on publishing snapshots, see Publish or unpublish a snapshot.

Data type: String

Default: publish_none
|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.

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.
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.

Status code

Description

200

Successful. The request was successfully processed.

400

Bad Request. Error: <Error message>Validate that the changeset_id parameter that you passed in was correct.

Ensure that you have the required roles to access this endpoint.

500

Internal Server Error: Invalid boolean value.If you passed in the autoValidate parameter, verify that it is a boolean value.
### Response body parameters

Name

Description

commit_id

Sys_id of the commit request. Use this ID when calling the CdmChangesetsApi - GET /sn_cdm/changesets/commit-status/{commit_id} endpoint to check the status of the commit request.

Data type: String

error

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

Text
"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

status

Status of the commit. Only returned when an error occurs.Possible values: failure

Data type: String
### cURL request

The follow code example shows how to use this endpoint to update a changeset.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/changesets/commit?changesetNumber=Chset-146" \ --request PUT \ --header "Accept:application/json" \ --user 'username':'password'

Return results:

JSON
{   "result": {     "commit_id": "cca8190f53141110a1d3ddeeff7b129e"   } }
Search documentation
Search document titles and file paths on the brazil branch