The CdmSnapshotApi provides endpoints that enable you to publish, unpublish, and re-validate snapshots in Configuration Data Management (CDM).

You publish a snapshot so that it can be exported, enabling the Continuous Integration and Continuous Delivery (CICD) pipeline to access and use the associated configuration data. Exporters can only execute on published snapshots. When snapshots are no longer needed, you can unpublish them to reduce the confusion as to whether the snapshot is viable anymore.

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 snapshots, see View snapshots.

CdmSnapshotAPI - POST /sn_cdm/snapshots/{snapshot_id}/publish

Publishes a specified unpublished snapshot.

Before a snapshot can be published, it must be validated. You can use the CdmSnapshotAPI - POST /sn_cdm/snapshots/{snapshot_id}/validate endpoint to validate snapshots or have them automatically validated when you do a commit. A deployable must be connected to a service to publish its snapshots. Also, if the snapshot has already been published, the request will fail.

URL format

Versioned URL: /api/sn_cdm/{api_version}/snapshots/{snapshot_id}/publish

Default URL: /api/sn_cdm/snapshots/{snapshot_id}/publish

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

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
snapshot_id Sys_id of the snapshot record to process.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
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. Only supports application/json.
Content-Type Data format of the request body. Only supports 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. 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 (JSON or XML)

Example: cURL request

The following example shows how to publish the snapshot with the sys_id of 3a168d9dc342301054c1582e1340dd68.

curl "http://instance.servicenow.com/api/sn_cdm/snapshots/3a168d9dc342301054c1582e1340dd68/publish"\ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \
--user 'username':'password'

The following shows both a success and failure response to the publish request.

// Example of a successful response
{ 
  "" 
}

// Example of an error response
{
  "error": {
    "message": "Error: Unexpected error occurred in publish request.Error:Snapshot not found",
    "detail": ""
  },
  "status": "failure"
}

CdmSnapshotAPI - POST /sn_cdm/snapshots/{snapshot_id}/unpublish

Unpublishes a previously published snapshot.

URL format

Versioned URL: /api/sn_cdm/{api_version}/snapshots/{snapshot_id}/unpublish

Default URL: /api/sn_cdm/snapshots/{snapshot_id}/unpublish

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

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
snapshot_id Sys_id of the snapshot record to process.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
Table 8. Query parameters
Name Description
None
Table 9. Request body parameters (XML or JSON)
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. Only supports application/json.
Content-Type Data format of the request body. Only supports 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. 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 (JSON or XML)

Example: cURL request

The following example shows how to unpublish the snapshot with the sys_id of 3a168d9dc342301054c1582e1340dd68.

curl "http://instance.servicenow.com/api/sn_cdm/snapshots/3a168d9dc342301054c1582e1340dd68/unpublish"\ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \
--user 'username':'password'

The following shows both a success and failure response to the unpublish request.

// Example of a successful response
{ 
  "" 
}

// Example of an error response
{
  "error": {
    "message": "Error: Unexpected error occurred in publish request.Error:Snapshot not found",
    "detail": ""
  },
  "status": "failure"
}

CdmSnapshotAPI - POST /sn_cdm/snapshots/{snapshot_id}/validate

Validates a specified unpublished snapshot.

The validation is performed as an asynchronous process. Calling this endpoint only starts the validation process. The return results from this call only indicate whether the validation process started, not the results of the validation itself. To find out if the snapshot has validated, use the Table API to locate the snapshot and check its validation status.

Note: You cannot validate a published snapshot.

URL format

Versioned URL: /api/sn_cdm/{api_version}/snapshots/{snapshot_id}/validate

Default URL: /api/sn_cdm/snapshots/{snapshot_id}/validate

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

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
snapshot_id Sys_id of the snapshot record to process.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
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. The specified snapshot is already published or cannot be located.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Example: cURL request

The following example shows how to validate the snapshot with the sys_id of 3a168d9dc342301054c1582e1340dd68.

curl "http://instance.servicenow.com/api/sn_cdm/snapshots/3a168d9dc342301054c1582e1340dd68/validate"\ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \
--user 'username':'password'

The following shows both a success and failure response to the validate request.

// Example of a successful response
{ 
  "" 
}

// Example of an error response
{
  "error": {
    "message": "Invalid Snapshot id:test",
    "detail": ""
  },
  "status": "failure"
}

CdmSnapshotApi - PUT /sn_cdm/snapshots/publish

Publishes a specified unpublished snapshot.

Before a snapshot can be published, it must be validated. You can use the CdmSnapshotApi - PUT /sn_cdm/snapshots/validate endpoint to validate snapshots or have them automatically validated when you do a commit. A deployable must be connected to a service to publish its snapshots. Also, if the snapshot has already been published, the request will fail.

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

URL format

Versioned URL: /api/sn_cdm/{api_version}/snapshots/publish

Default URL: /api/sn_cdm/snapshots/publish

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

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
NameDescription
appName Required. Name of the Configuration Data Management (CDM) application for which to create the snapshot.

Data type: String

Table: CDM Application [sn_cdm_application]
deployableName Required. Name of the CDM deployable for which to create the snapshot.

Data type: String

Table: CDM Deployable [sn_cdm_deployable]
name Required. Name of the snapshot.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
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. 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

NameDescription
cdm_application_id Details about the CDM application associated with the snapshot.

Data type: Object

"cdm_application_id": {
  "link": "String",
  "value": "String"
}
cdm_application_id.link Call to use to access the CDM application record using the REST Table API.

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

Data type: String

Table: CDM Application [sn_cdm_application]
cdm_deployable_id Details about the CDM deployable associated with the snapshot.

Data type: Object

"cdm_deployable_id": {
  "link": "String",
  "value": "String"
}
cdm_deployable_id.link Call syntax for querying this deployable record using the Table REST API.

Data type: String
cdm_deployable_id.value Sys_id of the deployable record.

Data type: String

Table: CDM Deployable [sn_cdm_deployable]
changeset_id Details about the changeset associated with the snapshot.

Data type: Object

"changeset_id": {
  "link": "String",
  "value": "String"
}
changeset_id.link Call syntax for querying this changeset record using the Table REST API.

Data type: String
changeset_id.value Unique identifier of the changeset record.

Data type: String

Table: CDM Changeset [sn_cdm_changeset]
description Brief description of the snapshot.

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
last_published Date and time that the snapshot was last published.

Data type: String

Format: yyyy-mm-dd hh:mm:ss
last_validated Date and time that the snapshot was last validated.

Data type: String

Format: yyyy-mm-dd hh:mm:ss
name Name of the snapshot.

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

Data type: String
published Flag that indicates whether the snapshot was published.
Possible values:
  • true: Snapshot was published.
  • false: Snapshot wasn't published.

Data type: Boolean
sys_created_by Name of the user that created the snapshot.

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

Data type: String

Format: yyyy-mm-dd hh:mm:ss
sys_id Sys_id of the snapshot.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
sys_updated_by Name of the user that updated the snapshot.

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

Data type: String

Format: yyyy-mm-dd hh:mm:ss
validation Current validation state of the snapshot.
Possible values:
  • execution_error
  • failed
  • in_progress
  • not_validated
  • passed
  • passed_with_exception
  • requested

Data type: String

Example: cURL request

This code example shows how to publish a snapshot.

curl "http://instance.servicenow.com/api/sn_cdm/snapshots/publish?deployableName=Development_1&name=Development_1-v1.dpl&appName=testApp" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--user 'username':'password'

Return results:

 
{ 
  "result": { 
    "changeset_id": { 
      "value": "d4b9446e53001110a1d3ddeeff7b126c", 
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_changeset/d4b9446e53001110a1d3ddeeff7b126c" 
    }, 
    "cdm_deployable_id": { 
      "value": "6dc517a953b70110a1d3ddeeff7b129b", 
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_deployable/6dc517a953b70110a1d3ddeeff7b129b" 
    }, 
    "description": null, 
    "cdm_application_id": { 
      "value": "62b517a953b70110a1d3ddeeff7b128c", 
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_application/62b517a953b70110a1d3ddeeff7b128c" 
    }, 
    "published": true, 
    "sys_updated_on": "2022-06-30 12:57:02", 
    "last_published": "2022-06-30 12:57:02", 
    "number": "SNAP0001002", 
    "sys_id": "9017fc2e53801110a1d3ddeeff7b12d7", 
    "sys_updated_by": "admin", 
    "sys_created_on": "2022-06-15 14:19:38", 
    "name": "Development_1-v2.dpl", 
    "last_validated": "2022-06-30 12:56:07", 
    "validation": "passed", 
    "sys_created_by": "admin" 
  } 
}

CdmSnapshotApi - PUT /sn_cdm/snapshots/unpublish

Unpublishes a previously published snapshot.

URL format

Versioned URL: /api/sn_cdm/{api_version}/snapshots/unpublish

Default URL: /api/sn_cdm/snapshots/unpublish

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

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

Example: cURL request

This code example shows how to unpublish a snapshot.

Return results:

CdmSnapshotApi - PUT /sn_cdm/snapshots/validate

Validates a specified unpublished snapshot against its mapped policies.

The validation is performed as an asynchronous process. Calling this endpoint only starts the validation process. The return results from this call only indicate whether the validation process started, not the results of the validation itself. To find out if the snapshot has validated, use the Table API to locate the snapshot and check its validation status.

Note: You cannot validate a published snapshot.

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

URL format

Versioned URL: /api/sn_cdm/{api_version}/snapshots/validate

Default URL: /api/sn_cdm/snapshots/validate

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

Table 31. 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 32. Query parameters
NameDescription
appName Required. Name of the Configuration Data Management (CDM) application for which to create the snapshot.

Data type: String

Table: CDM Application [sn_cdm_application]
deployableName Required. Name of the CDM deployable for which to create the snapshot.

Data type: String

Table: CDM Deployable [sn_cdm_deployable]
name Required. Name of the snapshot.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
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 33. 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 34. 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 35. 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 36. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. The specified snapshot is already published or cannot be located.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters

NameDescription
cdm_application_id Details about the CDM application associated with the snapshot.

Data type: Object

"cdm_application_id": {
  "link": "String",
  "value": "String"
}
cdm_application_id.link Call to use to access the CDM application record using the REST Table API.

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

Data type: String

Table: CDM Application [sn_cdm_application]
cdm_deployable_id Details about the CDM deployable associated with the snapshot.

Data type: Object

"cdm_deployable_id": {
  "link": "String",
  "value": "String"
}
cdm_deployable_id.link Call syntax for querying this deployable record using the Table REST API.

Data type: String
cdm_deployable_id.value Sys_id of the deployable record.

Data type: String

Table: CDM Deployable [sn_cdm_deployable]
changeset_id Details about the changeset associated with the snapshot.

Data type: Object

"changeset_id": {
  "link": "String",
  "value": "String"
}
changeset_id.link Call syntax for querying this changeset record using the Table REST API.

Data type: String
changeset_id.value Unique identifier of the changeset record.

Data type: String

Table: CDM Changeset [sn_cdm_changeset]
description Brief description of the snapshot.

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
last_published Date and time that the snapshot was last published.

Data type: String

Format: yyyy-mm-dd hh:mm:ss
last_validated Date and time that the snapshot was last validated.

Data type: String

Format: yyyy-mm-dd hh:mm:ss
name Name of the snapshot.

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

Data type: String
published Flag that indicates whether the snapshot was published.
Possible values:
  • true: Snapshot was published.
  • false: Snapshot wasn't published.

Data type: Boolean
sys_created_by Name of the user that created the snapshot.

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

Data type: String

Format: yyyy-mm-dd hh:mm:ss
sys_id Sys_id of the snapshot.

Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
sys_updated_by Name of the user that updated the snapshot.

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

Data type: String

Format: yyyy-mm-dd hh:mm:ss
validation Current validation state of the snapshot.
Possible values:
  • execution_error
  • failed
  • in_progress
  • not_validated
  • passed
  • passed_with_exception
  • requested

Data type: String

Example: cURL request

This code example shows how to validate a snapshot.

curl "http://instance.servicenow.com/api/sn_cdm/snapshots/validate?name=Development_1-v2.dpl&deployableName=Development_1&appName=testApp" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--user 'username':'password'

Return results:

{ 
  "result": { 
    "changeset_id": { 
      "value": "d4b9446e53001110a1d3ddeeff7b126c", 
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_changeset/d4b9446e53001110a1d3ddeeff7b126c" 
    }, 
    "cdm_deployable_id": { 
      "value": "6dc517a953b70110a1d3ddeeff7b129b", 
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_deployable/6dc517a953b70110a1d3ddeeff7b129b" 
    }, 
    "description": null, 
    "cdm_application_id": { 
      "value": "62b517a953b70110a1d3ddeeff7b128c", 
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_application/62b517a953b70110a1d3ddeeff7b128c" 
    }, 
    "published": false, 
    "sys_updated_on": "2022-06-30 12:57:02", 
    "last_published": "2022-06-30 12:57:02", 
    "number": "SNAP0001002", 
    "sys_id": "9017fc2e53801110a1d3ddeeff7b12d7", 
    "sys_updated_by": "admin", 
    "sys_created_on": "2022-06-15 14:19:38", 
    "name": "Development_1-v2.dpl", 
    "last_validated": "2022-06-30 12:56:07", 
    "validation": "passed", 
    "sys_created_by": "admin" 
  } 
}