CdmApplicationsApi

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

The CdmApplicationsApi provides endpoints that enable you to uploadzoominsoftware.io/utah-devops/configuration data to the component, collection, deployable, and component variable folders found in the DevOps Config Workspace UI. It also has endpoints that enable you to export deployable configuration data to your DevOps pipeline and manage shared components and shared applications.

The export and upload endpoints use an asynchronous queuing implementation. With this type of implementation, you first call the desired export or upload request endpoint. These endpoints queue your request and return a request identifier. You then use this request identifier to call the appropriate status endpoint, one for uploads and a different one for exports, to obtain the status of the upload/export. For export requests, once the export is complete, you can also request the content of the export.

This API does not provide endpoints that perform simple retrieval of application records. To retrieve these records, use the Table API.

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 Configuration Data Management and the DevOps Config Workspace UI, see Uploading your config data.

For additional information on shared components and shared libraries, see Sharing components among applications — Component libraries.

Parent Topic:REST API reference

CdmApplicationsApi - DELETE /sn_cdm/applications/deployables

Deletes a specified Configuration Data Management (CDM) deployable.

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

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables

Default URL: /api/sn_cdm/applications/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

appName

Required. Name of the CDM application to which the deployable is associated.Data type: String

Table: CDM Deployable [sn_cdm_deployable]

name

Name of the deployable to delete.Data type: String

Table: CDM Deployable [sn_cdm_deployable]
|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 deployable.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/deployables?appName=testApp&name=Dep-1" \ --request DELETE \ --header "Accept:application/json" \ --user 'username':'password1'

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

Text
None - results defined by the HTTP status code

CdmApplicationsApi - DELETE /sn_cdm/applications/shared_components

Removes the shared component usage reference from a specified Configuration Data Management (CDM) application.

The CDM Admin role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/shared_components

Default URL: /api/sn_cdm/applications/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

appName

Required. Name of the application from which to remove the specified shared component association. The specified application must have the type field set to "shared_library".Data type: String

Table: CDM Application [sn_cdm_application]

changesetNumber

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

Data type: String

Table: CDM Changeset [sn_cdm_changeset]

sharedComponentName

Required. Unique name of the shared component to remove from the specified application.Data type: String

Table: CDM Shared Component [sn_cdm_shared_component]
|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. Supported types: application/json or application/xml. Default: 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

result

Empty. The HTTP status code indicates the result of the call.

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

Error status of the request.Possible values: failure

Data type: String
### cURL request

The following code example shows how to delete the "paymentService-V1.1" shared component from the "App1" application.

Shell
curl "https://instance-name.service-now.com/api/sn_cdm/applications/shared_components?appName=App1&sharedComponentName=paymentService-V1.1&changesetNumber=Chset-25" \ --request DELETE \ --header "Accept:application/json" \ --user 'username':'password'

Response:

Text
""

CdmApplicationsApi - GET /sn_cdm/applications/deployables/exports/{export_id}/content

Returns the content associated with a specified configuration data export request.

Only call this endpoint once you have received a complete response from the CdmApplicationsApi - GET /sn_cdm/applications/deployables/exports/{export_id}/status endpoint. If you call this endpoint before the export is complete, a 400 status error is returned.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables/exports/{export_id}/content

Default URL: /api/sn_cdm/applications/deployables/exports/{export_id}/content

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

export_id

Unique identifier for the export request whose configuration data to return. This value is returned by the CdmApplicationsApi - POST /sn_cdm/applications/deployables/exports endpoint.
|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 (JSON or XML)

Name

Description

errors

Description of the errors encountered during export.Data type: String

export_id

Export request ID. Same as that passed into the endpoint.Data type: String

exporter_result

Content of the specified configuration data export.Data type:

  • JSON object: If the request was to export data in JSON format.
  • String: If the request was to export data in any other format.

request_id

Export request ID. Same as that passed into the endpoint.Data type: String

state

Current state of the specified export.Possible values:

  • completed
  • error
  • in_progress
  • new
  • ready

Data type: String

Table: In state column of the CDM Request Queue [sn_cdm_request_queue] table.
### cURL request

The following example requests the configuration data of an export request with the ID of 3ab14a7d53b1301096edddeeff7b12f.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/deployables/exports/3ab14a7d53b1301096edddeeff7b12f/content" \ --request GET \ --header "Accept:application/json" \--user 'username':'password'

The following shows the possible return results.

JavaScript
// Successful completion of the export request{   "result": {     "export_id": "3ab14a7d53b1301096edddeeff7b12f"     "exporter_result": "DEP1.COMP.cdi_1=cdi-1-value"   } }
// Response when an incorrect export_id is passed. Note: Status code is 200.{   "result": {     "request_id": "3ab14a7d53b1301096edddeeff7b12e",     "state": "error",     "errors": "Invalid requestId '3ab14a7d53b1301096edddeeff7b12fe'",     "export_id": "3ab14a7d53b1301096edddeeff7b12e"   } }

CdmApplicationsApi - GET /sn_cdm/applications/deployables/exports/{export_id}/status

Returns the current status of the specified configuration data export request.

Use the CdmApplicationsApi - POST /sn_cdm/applications/deployables/exports endpoint to make an export request.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables/exports/{export_id}/status

Default URL: /api/sn_cdm/applications/deployables/exports/{export_id}/status

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

export_id

Sys_id of the export request whose status to return. This value is returned by the CdmApplicationsApi - POST /sn_cdm/applications/deployables/exports endpoint.
|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 (JSON or XML)

Name

Description

errors

Description of the errors encountered during export.Data type: String

export_id

Export request ID. Same as that passed into the endpoint.Data type: String

exporter_result

Details about the associated error.Data type: Object

exporter_result.errors

Description of the error(s) encountered during export.Data type: Array

exporter_result.execution_id

Unique identifier for the exporter execution record.Data type: String

Table: CDM Exporter Execution [sn_cdm_exporter_execution]

exporter_result.state

Current state of the specified export.Possible values:

  • complete
  • error
  • in_progress
  • new

Data type: String

Table: CDM Exporter Execution [sn_cdm_exporter_execution]

request_id

Export request ID. Same as that passed into the endpoint.Data type: String

state

Current state of the specified export.Possible values:

  • completed
  • error
  • in_progress
  • new
  • ready

Data type: String

Table: In state column of the CDM Request Queue [sn_cdm_request_queue] table.
### cURL request

The following example requests the status of an export with the ID of 3ab14a7d53b1301096edddeeff7b12f.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/deployables/exports/3ab14a7d53b1301096edddeeff7b12f/status" \ --request GET \ --header "Accept:application/json" \--user 'username':'password'

The following are the possible return results.

JavaScript
// Successful completion of the export request{   "result": {     "state": "completed",     "export_id": "3ab14a7d53b1301096edddeeff7b12f0"   } }
// Response when an incorrect export_id is passed. Note: Status code is 200.{   "result": {     "request_id": "3ac8e1b05311301096edddeeff7b123c",     "state": "error",     "errors": "Invalid requestId '3ac8e1b05311301096edddeeff7b123c'",     "export_id": "3ac8e1b05311301096edddeeff7b123c"   } } 
// Response when the export encounters an error. The exporter_result array contains the error information. Note: Status code is 200.{   "result": {     "state": "completed",     "export_id": "24536c3353f9301096edddeeff7b12b1",     "exporter_result": {       "execution_id": "81536c3353f9301096edddeeff7b129e",       "state": "failure",       "errors": [         "Snapshot 'SNA-001-published-non_compliant' has not passed validation. All snapshots of deployable '/ApplicationA/deployables/DEP3' are required to pass validation"       ]     }   } }

CdmApplicationsApi - GET /sn_cdm/applications/shared_components

Returns the list of shared components used by a specified application. You can also specify to only return those shared components that have a new version available.

The CDM Admin role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/shared_components

Default URL: /api/sn_cdm/applications/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

appName

Required. Name of the application whose list of shared components you want returned. The type field of the application must be set to shared_library.Data type: String

Table: CDM Application [sn_cdm_application]

withUpdatesOnly

Flag that indicates whether to only return shared components that have a new updated version available.Valid values:

  • true: Only return shared components that have a new updated version available.
  • false: Return all shared components used by the specified application.

Default: false
|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. Supported types: application/json or application/xml. Default: 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

currentVersion

Current version of the CDM application. Data type: Number (Integer)

currentVersionName

Name of shared component version currently in use.Data type: String

description

Description of shared component.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

Unique name of the shared component.Data type: String

sharedLibraryName

Name of shared library to which the shared component belongs.Data type: String

status

Error status of the request.Possible values: failure

Data type: String

updateVersionName

Name of shared component version available for update.Data type: String
### cURL request

The following code example shows how to call this endpoint to retrieve the shared components that have a new version used by "App1".

Shell
curl "https://instance-name.service-now.com/api/sn_cdm/applications/shared_components?updatesOnly=true&appName=App1" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

Response:

Shell
{   "result": [    {      "name": "Component_Name",      "description": "”,      "sharedLibraryName": "Shared Library",      "currentVersion": "2",      "currentVersionName": "Component_A-v2.shc",      "updateVersionName": "Component_A-v3.shc"    }   ]}

CdmApplicationsApi - GET /sn_cdm/applications/shared_libraries/components/applications

Returns a map of shared components and the applications that use them that are within a specified library.

The CDM Admin role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/shared_libraries/components/applications

Default URL: /api/sn_cdm/applications/shared_libraries/components/applications

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

sharedComponentName

Required. Name of the shared component to include in the map.Data type: String

Table: CDM Shared Component [sn_cdm_shared_component]

sharedLibraryName

Required. Name of the shared library to include in the map. The specified application must have the type field set to "shared_library".Data type: String

Table: CDM Application [sn_cdm_application]
|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. Supported types: application/json or application/xml. Default: 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

description

Description of application using shared component 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

managed_by_group

Comma-separated list of sys_ids of the groups that can manage the application.Data type: String

name

Unique name of the application using the component.Data type: String

status

Error status of the request.Possible values: failure

Data type: String

sys_id

Sys_id of the application utilizing the shared component.Data type: String
### cURL request

The following code example shows how to call this endpoint to retrieve the map that shows the applications in the "OracleG-Library-10" shared library that use the "paymentService-V1.1" shared component.

Shell
curl "https://instance-name.service-now.com/api/sn_cdm/applications/shared_libraries/components/applications?sharedLibraryName=OracleG-Library-10&sharedComponentName=paymentService-V1.1" \ --request GET \ --header "Accept:application/json" \ --user 'username':'password'

Response:

JSON
{  "result": {    "component_name": [      {         "name": "App Name",        "description": "desc",        "managed_by_group": null,        "sys_id": "4e7808bb1b371110636e0fe0604bcb08"      },       {        "name": "Config App",        "description": "desc",        "managed_by_group": null,        "sys_id": "55a75cfb1b771110636e0fe0604bcb5c"      },      {        "name": "Database App",        "description": "desc",        "managed_by_group": null,        "sys_id": "2eb7503f1b771110636e0fe0604bcb06"      }    ]  } }

CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id}

Returns the current status of the specified configuration data upload request.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/upload-status/{upload_id}

Default URL: /api/sn_cdm/applications/upload-status/{upload_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

upload_id

Sys_id of the upload request whose status to return. This value is returned by the various CdmApplications upload request endpoints.
|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 (JSON or XML)

Name

Description

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: Array of String

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

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

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:

  • blocked
  • checking_for_conflict
  • commit_failed
  • commit_in_progress
  • committed
  • open

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 upload request.Possible values:

  • NOT_PROCESSED
  • PROCESSED

Data type: String

state

Current state of the upload request.Possible values:

  • completed
  • error
  • in_progress
  • new
  • ready

type

Type of upload request.Possible values:

  • commit
  • upload_and_commit

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following example show requesting the status for an upload with the ID of 5560a6895326301096edddeeff7b1230.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/upload-status/5560a6895326301096edddeeff7b1230" \ --request GET \ --header "Accept:application/json" \--user 'username':'password'

The following are the possible return results.

JavaScript
// Successful completion of the upload request{   "result": {     "type": "upload_and_commit",     "state": "completed",     "output": {       "sys_id": "be681dc95362301096edddeeff7b12ba",       "number": "Chset-102",       "title": "admin2021-09-10 08:09:07",       "description": null,       "committed_at": "2021-09-10 20:23:37",       "committed_by": "6816f79cc0a8016401c5a33be04be441",       "sys_created_by": "admin",       "state": "committed",       "publish_option": "publish_none",       "auto_validate": false,       "snapshot_name": null,       "snapshot_description": null,       "cdm_application": "Demo_App1631126164773",       "last_conflict_detection_time": "1631305417894"     },     "processing_state": "PROCESSED",     "upload_id": "5560a6895326301096edddeeff7b1230"  } }
// Response when an incorrect upload_id is passed. Note: Status code is 200.{   "result": {     "state": "error",     "errors": "Invalid requestId '5560a6895326301096edddeeff7b1240'",     "upload_id": "5560a6895326301096edddeeff7b1240"   } } 
// Response when the upload encounters an error. The exporter_result array contains the error information. Note: Status code is 200.{   "result": {     "type": "upload_and_commit",     "state": "error",     "output": "Error encountered during execution of request.\nError: Node 'dbSettings' of type 'sg_cdm_node_component' cannot create child 'dbSettings' of type 'sg_cdm_node_folder'",     "processing_state": "PROCESSED",     "upload_id": "272f8a415326301096edddeeff7b1232"   } }

CdmApplicationsApi - POST /sn_cdm/applications/deployables

Creates a new deployable and automatically connects it to a specified Configuration Data Management (CDM) application.

You can create a deployable for any one of three environment types: Development, Test, or Production.

To access this endpoint the caller must have the CDM Admin role.

If you need to create multiple deployables, use the CdmApplicationsApi - POST /sn_cdm/applications/deployables/create endpoint.

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.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables

Default URL: /api/sn_cdm/applications/deployables

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 an existing, active CDM application to associate with the deployable.Data type: String

Table: CDM Application [sn_cdm_application]

envType

Required. Environment type for the deployable.

Valid values (case-sensitive):

  • Development
  • Production
  • Test

Note: The deployable environment type can't be changed after creation.

Data type: String

name

Required. Name of the CDM deployable.Should not be more than 255 chars. Default allowed characters are 0-9, A-Z, a-z, _,-,., %, $, whitespace, :, #.

Data type: String

Maximum length: 255 characters

Allowable characters: 0-9, A-Z, a-z, _, -, ., %, $, whitespace, :, and #

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.
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. 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 create and associate a deployable to a CDM application.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/deployables?name=Dep-1&returnFields=name%2Csys_id%2Cstate&appName=testApp&envType=Test" \ --request POST \ --header "Accept:application/json" \ --user 'username':'password1'

Return results:

JSON
{   "result": [     {       "cmdb_ci": {         "value": "f5b9e00b53901110a1d3ddeeff7b12b8",         "link": "http://192.168.0.233:8080/api/now/table/cmdb_ci_service_auto/f5b9e00b53901110a1d3ddeeff7b12b8"       },       "cdi_count": "0",       "snapshot_version_counter": "0",       "description": null,       "sys_updated_on": "2022-06-29 12:53:57",       "environment_type": "Test",       "node": {         "value": "7db9e00b53901110a1d3ddeeff7b12b6",         "link": "http://192.168.0.233:8080/api/now/table/sn_cdm_node/7db9e00b53901110a1d3ddeeff7b12b6"       },       "sys_id": "39b9e00b53901110a1d3ddeeff7b12b7",       "sys_updated_by": "admin",       "cdm_app": {         "value": "62b517a953b70110a1d3ddeeff7b128c",         "link": "http://192.168.0.233:8080/api/now/table/sn_cdm_application/62b517a953b70110a1d3ddeeff7b128c"       },       "sys_created_on": "2022-06-29 12:53:57",       "cdi_usage": "0",       "name": "Dep-2",       "state": "active",       "sys_created_by": "admin"     }   ] }

CdmApplicationsApi - POST /sn_cdm/applications/deployables/create

Creates one or more new deployables.

You can create one of two types of deployables:

  • Deployables that must be manually connected to an Application Model (CI Service).
  • Deployables that are automatically connected to new, dynamically created Application Models (CI Services).

You can create a deployable for any one of three environment types: Development, Test, or Production. When creating multiple deployables, the auto-generated names of the deployables follow the pattern: DeployableType_Number, where Number is a running sequence number based on the creation of a new deployable. For example, if you create three deployables of type Test in an endpoint call, they are named Test_1, Test_2, and Test_3. If you then call the endpoint again, and create a different Test deployable, its auto-gen'd name is Test_4. These numbers are never reused, even if a deployable is deleted.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables/create

Default URL: /api/sn_cdm/applications/deployables/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

appSysId

Required. Sys_id of an active CDM Application to associate with the deployables.Data type: String

autoConnect

Required. Flag that determines whether to automatically connect the newly created deployables to dynamically generated Application Models.Valid values:

  • true: Connect the newly created deployables to dynamically generated Application Models.
  • false: Just create the deployables. These deployables must be manually mapped to Application Models using the UI.

Data type: Boolean

envType

Required. Environment type for the deployable.

Valid values (case-sensitive):

  • Development
  • Production
  • Test

Note: The deployable environment type can't be changed after creation.

Data type: String

quantity

Required. Number of deployables to create.Data type: Number
|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.
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

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

result

Sys_ids of the created deployables.Data type: Array

status

Error status of the request.Possible values: failure

Data type: String
### cURL request

The following example shows how to create a single deployable and associate it with and existing CDM application.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/deployables/create?envType=Production&appSysId=5e118055b712011054c1e5a6ce11a9d4&quantity=5&autoConnect=true" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \--user 'username':'password'

The following shows the possible responses to this call, both as a success and an error.

JavaScript
// Successful completion of the upload request{  "result": [    "8ba43a3db7d6011054c1e5a6ce11a9a4",    "93a47a3db7d6011054c1e5a6ce11a90d",    "dba47a3db7d6011054c1e5a6ce11a91d",    "6fa47a3db7d6011054c1e5a6ce11a921",    "efa47a3db7d6011054c1e5a6ce11a925"  ]} 
// Error response{  "error": {    "message": "Error: CDM Application with SysID 5e118055b712011054c1e5a6ce11a9d1 was not found. (sys_script_include.8cf0fbf453626010a1d3ddeeff7b12fe.script; line 211)",    "detail": ""  },  "status": "failure"}

CdmApplicationsApi - POST /sn_cdm/applications/deployables/exports

Submits a request to export the current snapshot for a specified application and one or more deployables into the CDM Exporter Cache [sn_cdm_exporter_cache] table.

This endpoint returns a unique identifier for the request, which you then use to call the CdmApplicationsApi - GET /sn_cdm/applications/deployables/exports/{export_id}/status endpoint to retrieve the status of the export. Once the export is complete, you can use the CdmApplicationsApi - GET /sn_cdm/applications/deployables/exports/{export_id}/content endpoint to retrieve the associated application's configuration data.

A snapshot is the complete data model of a deployable at the time a configuration change is committed. This includes any included components, collections, and vars, as well as deployable-specific vars and overrides. For additional information on deployables, see Create and update a deployable.

Note: Snapshots cannot exceed 10,000 configuration data items (CDIs) per deployable or 100,000 CDIs per application.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables/exports

Default URL: /api/sn_cdm/applications/deployables/exports

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

additionalDeployables

Non-primary deployables to export.Data type: Array of Objects

Text
"additionalDeployables": [  {    "app_name": "String",    "deployable_name": "String"  }]

For example: [{'app_name':'TestApp', "deployable_name:'DEP-1'}]

Default: Empty array - []

additionalDeployables.app_name

Required if additionalDeployables array is specified. Name of the application associated with the deployable whose configuration data you want to export.Data type: String

additionalDeployables.deployable_name

Required if additionalDeployables array is specified. Name of the non-primary deployable whose configuration data you want to export.Data type: String

appName

Required. Name of the application whose configuration data you want to export.Data type: String

args

A JSON object containing key-value pairs for custom arguments.Data type: Object

dataFormat

Output format of the exported data.Valid values (case-sensitive):

  • ini
  • json
  • properties
  • raw (Data is returned in String format)
  • xml
  • yaml

Data type: String

Default: json

deployableName

Required. Name of the deployable whose configuration data you want to export.Data type: String

exporterName

Required. Name of the exporter to use to export the snapshot data. Exporters are custom to the implementer. For details on creating a custom exporter, see Create a custom exporter.Data type: String

restrictExport

Flag that indicates whether the endpoint validates snapshots when exporting the data.Valid values:

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

Data type: Boolean

Default: false

snapshotName

Name of the snapshot to export. This can only be one of the snapshot names associated with the deployable as specified in the deployableName or additionalDeployables.deployable_name parameters. Default: The endpoint exports the latest published snapshot. If there is not a published snapshot, the system throws the error “Failed to find latest published snapshot for deployable '{0}'”
|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. A bad request type or malformed request was detected.Possible error messages:

  • Error: Missing required param 'appName'
  • Error: User does not have necessary permission to create Export request
  • Error: Invalid Boolean value (<xyz>).

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

Details about the error that occurred.Data type: Array

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

export_id

Unique identifier of the export request. Use this ID when calling the CdmApplicationsApi - GET /sn_cdm/applications/deployables/exports/{export_id}/status endpoint to check the current status of the export request.Data type: String

status

Error status of the request.Possible values: failure

Data type: String
### cURL request

The following example requests the export of the configuration data for the following: application name = TestAppA, deployable name = DEP, using the exporter = exporter-1-primary_deployable.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/deployables/exports?appName=TestAppA&args=%7B%22arg_A_required%22%20%3A%20%22value%20A%22%7D&exporterName=exporter-1-primary_deployable&deployableName=DEP1" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \--user 'username':'password'

Returns the unique identifier of the export request.

JSON
{   "result": {    "export_id": "64b5f79f5379301096edddeeff7b12eb"   } }

CdmApplicationsApi - POST /sn_cdm/applications/shared_components

Associates the specified shared component to the application within a specified changeset.

The CDM Admin role is required to access this endpoint.

Note: The specified shared component must have an associated published version (snapshot).

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/shared_components

Default URL: /api/sn_cdm/applications/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

appName

Required. Name of the application to associate with the shared component.Data type: String

changesetNumber

Required. Unique identifier of the changeset associated with the component.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

sharedComponentName

Required. Name of the shared component to associate with the specified application.Data type: String

Table: CDM Shared Component [sn_cdm_shared_component]

sharedLibraryName

Required. Name of the shared library under which to create the component. The shared library must have the following fields defined as follows:- state = active

  • available = true
  • type = shared_library

Data type: String

Table: CDM Application [sn_cdm_application]
|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. Supported types: application/json or application/xml. Default: 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 doesn't exist.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters

The response fields depend on what fields were specified in the returnFields parameter in the request. The following describes some of the more important fields.

Name

Description

changeset_id

Details of the changeset record associated with the node. Data type: Object

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

Description of the CDM node.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

linked_to

ID of the main node associated with the shared component.Data type: String

linked_to_version

Details of the CDM snapshot record associated with the node. Data type: Object

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

linked_to_version.link

Call syntax for querying this version record using the Table REST API.Data type: String

linked_to_version.value

Sys_id of the version record.Data type: String

main

Flag that indicates whether the associated snapshot was published.

Valid values:

  • true: Snapshot was published.
  • false: Snapshot wasn't published.

main_id

Unique ID of the newly created main node.Data type: String

main_id_encoded

Encoded ID of the newly created main node.Data type: String

name

Name of the CDM node.Data type: String

node

Sys_id of the shared component node.Data type: String

node_path

Path to the new linked node created when adding the shared component. Data type: String

status

Status of the node.Possible values: New

Data type: String

sys_created_by

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

sys_created_on

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

Data type: String

sys_id

Sys_id of the node.Data type: String

Table: CDM Node [sn_cdm_node]

sys_updated_by

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

sys_updated_on

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

Data type: String

type

Node type.Data type: String
### cURL request

The following example shows how to call this endpoint to associate the application "App1" with the shared component "paymentService-V1.1" under the shared library "OracleG-Library-10" within the "Chset-20" changeset.

Shell
curl "https://instance.servicenow.com/api/sn_cdm/applications/shared_components?appName=App1&changesetNumber=Chset-20&sharedLibraryName=OracleG-Library-10&sharedComponentName=paymentService-V1.1" \ --request POST \ --header "Accept:application/json" \ --user 'username':'password'

Response:

JSON
{   "result": {     "changeset_id": {       "value": "74b7ff6fc33711100c257e2cc840dd6b",       "link": "http://instance.servicenow.com/api/now/table/sn_cdm_changeset/74b7ff6fc33711100c257e2cc840dd6b"     },     "node_path": "!,0!,1!/D",     "description": null,     "sys_updated_on": "2022-12-22 17:07:29",     "type": "sn_cdm_node_linked_shared_component",     "sys_class_name": "sn_cdm_node",     "sys_id": "ff8b37ebc3b711100c257e2cc840ddba",     "sys_updated_by": "admin",     "previous_version": null,     "sys_created_on": "2022-12-22 17:07:29",     "value": null,     "effective_from": null,     "linked_to": "210",     "sys_created_by": "admin",     "restricted_to": null,     "linked_to_version": {       "value": "581fc3e9c3b311100c257e2cc840dd17",       "link": "http://instance.servicenow.com/api/now/table/sn_cdm_snapshot/581fc3e9c3b311100c257e2cc840dd17"     },     "level": "2",     "conflict_type": null,     "main_id": "483",    "effective_to": null,    "secure_value": null,     "node_classifier": "/application/components",     "main_id_encoded": "/D",    "name": "LIB2_C",    "position": null,    "reason_for_conflict": null,    "system_folder": false,    "status": "new",    "conflict": false  } }

CdmApplicationsApi - POST /sn_cdm/applications/uploads/components

Submits a request to upload the passed-in configuration data for a specific component, within the system components folder, for the specified application.

This endpoint returns the ID of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.

Note: The maximum default upload content size is 2 MB. You can modify this default by updating the property sn_cdm.max_allowed_upload_file_size.

The following image shows an example of where the component configuration data is uploaded in reference to the ServiceNow DevOps Config UI. Assumes the component is dbComponent and the application is paymentSvc.

[Omitted image "apps-uploads-components_data.png"] Alt text: Example configuration content location within UI

Note: This upload method cannot be used to modify nodes. Use the alternative CdmApplicationsApi - POST sn_cdm/applications/uploads/components/file method to modify nodes.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/uploads/components

Default URL: /api/sn_cdm/applications/uploads/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

appName

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoDelete

Flag that indicates whether the existing nodes, that aren’t part of the upload content, are deleted after the processing is complete.Valid values:

  • true: Automatically delete existing nodes.
  • false: Don't automatically delete existing nodes.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

dataFormat

Required. Format of the configuration data.Valid values:

  • csv
  • ini
  • json
  • properties
  • raw
  • xml
  • yaml

Data type: String

dataFormatAttributes

Only supported when the dataFormat parameter is set to csv. Attributes that define the CSV data format. For additional information, see Parsing of CSV files in CDM.Data type: Object

JavaScript
"dataFormatAttributes" {  "containsHeader": Boolean,  "delimeter": "String"  "headers": [Array],  "securedHeaders": [Array]}

dataFormatAttributes.containsHeaders

Flag that indicates whether the data contains a header row.Valid values:

  • true: Data contains a header row. The first row in the data is considered the header row.

[Omitted image "cdm_header_row_example.png"] Alt text: Header row example

  • false: Data doesn't contain a header row. You must pass the header information in the dataFormatAttributes.headers parameter.

Data type: Boolean

Default: false

dataFormatAttributes.delimeter

Character to use to delineate fields within the data.Data type: String

Default: Comma ","

dataFormatAttributes.headers

Required if dataFormatAttributes.containsHeaders parameter is false. Fields in the data that comprise the header. These headers are converted to the key names of the CDIs in the JSON format. The number of headers must match the number of record fields.Data type: Array

Default: Empty array

dataFormatAttributes.securedHeaders

Fields in the data that are secure fields and must be encrypted in the data uploaded to CDM. The name of the secured headers must match the name of the headers in the headers attribute or data file. These fields are stored in a column of type Password (2 Way Encrypted).Note: You can only secure fields using this attribute. You can't unsecure the secured fields.

Data type: Array

Default: Empty array

deleteRedundantOverrides

Flag that indicates whether to create an override where redundant values are present.Valid values:

  • true: If redundant values are present, an override isn’t created.
  • false: If redundant values are present, proceeds with an override.

Default: true

fileName

Name of the file to upload. This name can differ from than the actual file name and contain the file extension. For example, .txt/.scv/.jar. The fileName value is applied when downloading the file.Data type: String

fileNodeName

Name of the file node. This file name is used in the configuration data when exporting it. This name doesn’t require a file extension nor does it affect the download.Data type: String

identifierKeys

List of names that indicate which key in an array child to use to identify the same node.For example, if you’re uploading:

Shell
[  {"name" : "Allan, "city" : "Paris"},   {"name" : "Karen, "city" : "Sydney"}]

in the following existing model:

Shell
[  {"name" : "Karen, "city" : "Manila"},  {"name" : "Allan, "city" : "Brussels"}]

and you set identifierKeys to name, it produces the following output:

Shell
[  {"name" : "Karen, "city" : "Sydney"},  {"name" : "Allan, "city" : "Paris"}]

Otherwise, it produces the following output:

Shell
[  {"name" : "Karen, "city" : "Manila"},  {"name" : "Allan, "city" : "Brussels"},  {"name" : "Allan, "city" : "Paris"},  {"name" : "Karen, "city" : "Sydney"}]

Data type: Array of Strings

ignoreAttributes

Flag that indicates whether the given data format supports attributes (currently only XML).Valid values:

  • true: If the given data format supports attributes, any attributes in the input data are skipped during the upload.
  • false: If the given data format supports attributes, any attributes in the input data are included in the upload.

Data type: Boolean

Default: false

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String

sharedLibraryName

Required. Name of the shared library where the component to delete is located.Data type: String

Table: CDM Application [sn_cdm_application]
|Name|Description| |----|-----------| |Variable upload data|Configuration data to upload. This can be any data in the format defined by the **dataFormat** parameter of the query parameters.|

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. Supported types: text/plain and application/x-www-form-urlencoded.Default: text/plain
|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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following example shows an upload request for the application Demo_App1631126164773.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/components?namePath=%2FSettings%2FdbSettings&dataFormat=json&appName=Demo_App1631126164773&changesetNumber=Chset-8&autoCommit=false&publishOption=publish_none&autoValidate=false&autoDelete=true" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "{  \"dbIPAddress\": \"10.10.10.110\",  \"dbPort\": \"8080\",  \"dbConnectionString\": \"admin:admin server1.xyz.com:8080 dbName_payments\",  \"dbConnectionStringBackup\": \"admin:admin server2.xyz.com dbName_payments_backup\"}" \ --user 'username':'password'

The following return results show both a successful and an error response for this request.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "ec1f71f45322301096edddeeff7b12b3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Size of uploaded data:6853632.0(bytes) is greater than max allowed upload limit of 2097152.0(bytes)",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - POST sn_cdm/applications/uploads/components/file

Uploads files as part of the Configuration Data Model (CDM) to the components folder.

Use this method to upload to a components file node.

URL format

Versioned URL: POST /api/sn_cdm/{api_version}/applications/uploads/components/file

Default URL: POST /api/sn_cdm/applications/uploads/components/file

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

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

fileName

Name of the file to upload. This name can differ from than the actual file name and contain the file extension. For example, .txt/.scv/.jar. The fileName value is applied when downloading the file.Data type: String

fileNodeName

Name of the file node. This file name is used in the configuration data when exporting it. This name doesn’t require a file extension nor does it affect the download.Data type: String

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String

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

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

Name

Description

Variable upload data

Configuration data to upload. By default, file size uploads are limited to 5 MB. For information about how to adjust your upload file sizes and type, see this Now Support article.Data type: String/stream
### Headers

Header

Description

Accept

Data format of the response body. Supported types: application/json or application/xml. Default: application/json

Content-Type

Data type of the file to be uploaded. Supported types: application/zip, text/plain, application/json.Default: 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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following example shows how to upload a content to a text file.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/components/file?autoValidate=true&appName=testApp&namePath=testComponent%2FfilesFolder&fileName=testFileNodeName.txt&publishOption=publish_valid&changesetNumber=Chset-108&autoCommit=true&fileNodeName=testFile.txt" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "This is sample content that will be uploaded to a plain text file."\ --user 'username':'password'

The following return results show both a successful and an error response for this request.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "ec1f71f45322301096edddeeff7b12b3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Could not find active application with name: ‘testApp’ of type application",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - POST /sn_cdm/applications/uploads/components/vars

Submits a request to upload the passed-in configuration data under the vars folder, within the system components folder, for the specified application.

The following image shows an example of where the component's vars configuration data is uploaded in reference to the ServiceNow DevOps Config Workspace UI. Assumes the application is paymentSvc.

[Omitted image "apps-uploads-comp-vars_data.png"] Alt text: Upload vars directory

Note: The maximum default upload content size is 2 MB. You can modify this default by updating the property sn_cdm.max_allowed_upload_file_size.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/uploads/components/vars

Default URL: /api/sn_cdm/applications/uploads/components/vars

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

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoDelete

Flag that indicates whether the existing nodes, that aren’t part of the upload content, are deleted after the processing is complete.Valid values:

  • true: Automatically delete existing nodes.
  • false: Don't automatically delete existing nodes.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

dataFormat

Required. Format of the configuration data.Valid values:

  • ini
  • json
  • properties
  • raw
  • xml
  • yaml

Data type: String

deleteRedundantOverrides

Flag that indicates whether to create an override where redundant values are present.Valid values:

  • true: If redundant values are present, an override isn’t created.
  • false: If redundant values are present, proceeds with an override.

Default: true

fileName

Name of the file to upload. This name can differ from than the actual file name and contain the file extension. For example, .txt/.scv/.jar. The fileName value is applied when downloading the file.Data type: String

fileNodeName

Name of the file node. This file name is used in the configuration data when exporting it. This name doesn’t require a file extension nor does it affect the download.Data type: String

identifierKeys

List of names that indicate which key in an array child to use to identify the same node.For example, if you’re uploading:

Shell
[  {"name" : "Allan, "city" : "Paris"},   {"name" : "Karen, "city" : "Sydney"}]

in the following existing model:

Shell
[  {"name" : "Karen, "city" : "Manila"},  {"name" : "Allan, "city" : "Brussels"}]

and you set identifierKeys to name, it produces the following output:

Shell
[  {"name" : "Karen, "city" : "Sydney"},  {"name" : "Allan, "city" : "Paris"}]

Otherwise, it produces the following output:

Shell
[  {"name" : "Karen, "city" : "Manila"},  {"name" : "Allan, "city" : "Brussels"},  {"name" : "Allan, "city" : "Paris"},  {"name" : "Karen, "city" : "Sydney"}]

Data type: Array of Strings

ignoreAttributes

Flag that indicates whether the given data format supports attributes (currently only XML).Valid values:

  • true: If the given data format supports attributes, any attributes in the input data are skipped during the upload.
  • false: If the given data format supports attributes, any attributes in the input data are included in the upload.

Data type: Boolean

Default: false

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String

sharedLibraryName

Required. Name of the shared library where the component to delete is located.Data type: String

Table: CDM Application [sn_cdm_application]
|Name|Description| |----|-----------| |Variable upload data|Configuration data to upload. This can be any data in the format defined by the **dataFormat** parameter of the query parameters.|

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. Supported types: text/plain and application/x-www-form-urlencoded.Default: text/plain
|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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following example shows a vars upload request for the application Demo_App1631126164773.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/components/vars?changesetNumber=Chset-102&autoValidate=false&autoDelete=true&publishOption=publish_none&appName=Demo_App1631126164773&namePath=%2FSettings%2FdbSettings&autoCommit=false&dataFormat=json" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "{   \"dbSettings\": {     \"dbIPAddress\": \"10.10.10.110\",     \"dbPort\": \"8080\",     \"dbConnectionString\": \"username:password server1.xyz.com:8080 dbName_payments\",     \"dbConnectionStringBackup\": \"username:password server2.xyz.com dbName_payments_backup\"  } }"--user 'username':'password'

The following return results show both a successful and an error response for this request.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "d21f71f45322301096eccceaff7b1ce3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Size of uploaded data:6853632.0(bytes) is greater than max allowed upload limit of 2097152.0(bytes)",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - POST /sn_cdm/applications/uploads/collections

Submits a request to upload the passed-in configuration data for a specific collection, within the system collections folder, for the specified application.

This endpoint returns the ID of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.

Note: The maximum default upload content size is 2 MB. You can modify this default by updating the property sn_cdm.max_allowed_upload_file_size.

The following image shows an example of where the configuration data is uploaded in reference to the ServiceNow DevOps Config Workspace UI. Assumes the collection is db0Release1.0 and the application is paymentSvc.

[Omitted image "apps-uploads-collections_data.png"] Alt text: Collections upload folder

Note: This upload method cannot be used to modify nodes. Use the alternative CdmApplicationsApi - POST /sn_cdm/applications/uploads/collections/file method to modify nodes.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/uploads/collections

Default URL: /api/sn_cdm/applications/uploads/collections

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

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoDelete

Flag that indicates whether the existing nodes, that aren’t part of the upload content, are deleted after the processing is complete.Valid values:

  • true: Automatically delete existing nodes.
  • false: Don't automatically delete existing nodes.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

collectionName

Required. Name of the collection under which to store the uploaded payload. Note: If the specified namePath does not exist under this collection, the system automatically creates the component(s) under this collection and then uploads the configuration content. For example, if you want to upload the collection collA, with the path compA/comp/compC, the data is uploaded under /collA/collections/compa/compB/compC.

If compA exists but not compB and compC, then the endpoint creates these components and uploads the data under compC.

Data type: String

dataFormat

Required. Format of the configuration data.Valid values:

  • csv
  • ini
  • json
  • properties
  • raw
  • xml
  • yaml

Data type: String

dataFormatAttributes

Only supported when the dataFormat parameter is set to csv. Attributes that define the CSV data format. For additional information, see Parsing of CSV files in CDM.Data type: Object

JavaScript
"dataFormatAttributes" {  "containsHeader": Boolean,  "delimeter": "String"  "headers": [Array],  "securedHeaders": [Array]}

dataFormatAttributes.containsHeaders

Flag that indicates whether the data contains a header row.Valid values:

  • true: Data contains a header row. The first row in the data is considered the header row.

[Omitted image "cdm_header_row_example.png"] Alt text: Header row example

  • false: Data doesn't contain a header row. You must pass the header information in the dataFormatAttributes.headers parameter.

Data type: Boolean

Default: false

dataFormatAttributes.delimeter

Character to use to delineate fields within the data.Data type: String

Default: Comma ","

dataFormatAttributes.headers

Required if dataFormatAttributes.containsHeaders parameter is false. Fields in the data that comprise the header. These headers are converted to the key names of the CDIs in the JSON format. The number of headers must match the number of record fields.Data type: Array

Default: Empty array

dataFormatAttributes.securedHeaders

Fields in the data that are secure fields and must be encrypted in the data uploaded to CDM. The name of the secured headers must match the name of the headers in the headers attribute or data file. These fields are stored in a column of type Password (2 Way Encrypted).Note: You can only secure fields using this attribute. You can't unsecure the secured fields.

Data type: Array

Default: Empty array

deleteRedundantOverrides

Flag that indicates whether to create an override where redundant values are present.Valid values:

  • true: If redundant values are present, an override isn’t created.
  • false: If redundant values are present, proceeds with an override.

Default: true

ignoreAttributes

Flag that indicates whether the given data format supports attributes (currently only XML).Valid values:

  • true: If the given data format supports attributes, any attributes in the input data are skipped during the upload.
  • false: If the given data format supports attributes, any attributes in the input data are included in the upload.

Data type: Boolean

Default: false

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String
|Name|Description| |----|-----------| |Variable upload data|Configuration data to upload. This can be any data in the format defined by the **dataFormat** parameter of the query parameters.|

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. Supported types: text/plain and application/x-www-form-urlencoded.Default: text/plain
|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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

This example shows how to upload JSON-formatted dbSettings configuration date into the collections folder for the application Demo_App1631126164773.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/collections?dataFormat=json&autoValidate=false&changesetNumber=Chset-102&appName=Demo_App1631126164773&autoDelete=true&namePath=%2FSettings%2FdbSettings&collectionName=release-1.0&autoCommit=false&publishOption=publish_none" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "{   \"dbSettings\": {     \"dbIPAddress\": \"10.10.10.110\",     \"dbPort\": \"8080\",     \"dbConnectionString\": \"admin:admin server1.xyz.com:8080 dbName_payments\",     \"dbConnectionStringBackup\": \"admin:admin server2.xyz.com dbName_payments_backup\"   } }" \ --user 'username':'password'

The following shows the possible responses to this call, both as a success and an error.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "ec1f71f45322301096edddeeff7b12b3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Size of uploaded data:6853632.0(bytes) is greater than max allowed upload limit of 2097152.0(bytes)",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - POST /sn_cdm/applications/uploads/collections/file

Uploads a file to the collections folder in the Configuration Data Model (CDM).

URL format

Versioned URL: POST /api/sn_cdm/{api_version}/applications/uploads/collections/file

Default URL: POST /api/sn_cdm/applications/uploads/collections/file

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

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

collectionName

Required. Name of the collection under which to store the uploaded payload.Note: If the specified namePath does not exist under this collection, the system automatically creates the component(s) under this collection and then uploads the configuration content. For example, if you want to upload the collection collA, with the path compA/comp/compC, the data is uploaded under /collA/collections/compa/compB/compC. If compA exists but not compB and compC, then the endpoint creates these components and uploads the data under compC.

Data type: String

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

fileName

Name of the file to upload. This name can differ from than the actual file name and contain the file extension. For example, .txt/.scv/.jar. The fileName value is applied when downloading the file.Data type: String

fileNodeName

Name of the file node. This file name is used in the configuration data when exporting it. This name doesn’t require a file extension nor does it affect the download.Data type: String

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String

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

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

Name

Description

Variable upload data

Configuration data to upload. By default, file size uploads are limited to 5 MB. For information about how to adjust your upload file sizes and type, see this Now Support article.Data type: String/stream
### Headers

Header

Description

Accept

Data format of the response body. Supported types: application/json or application/xml. Default: application/json

Content-Type

Content Type of the file to be uploaded. Examples: application/zip, text/plain, 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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following call uploads a plain text file to the CDM collections folder.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/collections/file?autoValidate=true&collectionName=collA&appName=testApp&namePath=testComponent%2FfilesFolder&fileName=testFileNodeName.txt&publishOption=publish_valid&changesetNumber=Chset-108&autoCommit=true&fileNodeName=testFile.txt" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "This is sample content that will be uploaded to a plain text file."\ --user 'username':'password'

The following return results show both a successful and an error response to this request.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "ec1f71f45322301096edddeeff7b12b3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Could not find active application with name: ‘testApp’ of type application",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - POST /sn_cdm/applications/uploads/deployables

Submits a request to upload the configuration content for a specific deployable within the deployables system folder of a specified application.

This endpoint returns the ID of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.

Note: The maximum default upload content size is 2 MB. You can modify this default by updating the property sn_cdm.max_allowed_upload_file_size.

The following image shows an example of where the deployable configuration data is uploaded in reference to the ServiceNow DevOps Config UI. Assumes the deployable is Development_1 and the application is paymentSvc.

[Omitted image "apps-uploads-deployables_data.png"] Alt text: Deployables config data location in UI

Note: This upload method cannot be used to modify nodes. Use the alternative CdmApplicationsApi - POST /sn_cdm/applications/uploads/deployables/file method to modify nodes.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/uploads/deployables

Default URL: /api/sn_cdm/applications/uploads/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

appName

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoDelete

Flag that indicates whether the existing nodes, that aren’t part of the upload content, are deleted after the processing is complete.Valid values:

  • true: Automatically delete existing nodes.
  • false: Don't automatically delete existing nodes.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

dataFormat

Required. Format of the configuration data.Valid values:

  • csv
  • ini
  • json
  • properties
  • raw
  • xml
  • yaml

Data type: String

dataFormatAttributes

Only supported when the dataFormat parameter is set to csv. Attributes that define the CSV data format. For additional information, see Parsing of CSV files in CDM.Data type: Object

JavaScript
"dataFormatAttributes" {  "containsHeader": Boolean,  "delimeter": "String"  "headers": [Array],  "securedHeaders": [Array]}

dataFormatAttributes.containsHeaders

Flag that indicates whether the data contains a header row.Valid values:

  • true: Data contains a header row. The first row in the data is considered the header row.

[Omitted image "cdm_header_row_example.png"] Alt text: Header row example

  • false: Data doesn't contain a header row. You must pass the header information in the dataFormatAttributes.headers parameter.

Data type: Boolean

Default: false

dataFormatAttributes.delimeter

Character to use to delineate fields within the data.Data type: String

Default: Comma ","

dataFormatAttributes.headers

Required if dataFormatAttributes.containsHeaders parameter is false. Fields in the data that comprise the header. These headers are converted to the key names of the CDIs in the JSON format. The number of headers must match the number of record fields.Data type: Array

Default: Empty array

dataFormatAttributes.securedHeaders

Fields in the data that are secure fields and must be encrypted in the data uploaded to CDM. The name of the secured headers must match the name of the headers in the headers attribute or data file. These fields are stored in a column of type Password (2 Way Encrypted).Note: You can only secure fields using this attribute. You can't unsecure the secured fields.

Data type: Array

Default: Empty array

deleteRedundantOverrides

Flag that indicates whether to create an override where redundant values are present.Valid values:

  • true: If redundant values are present, an override isn’t created.
  • false: If redundant values are present, proceeds with an override.

Default: true

deployableName

Required. Name of the deployable under which to store the uploaded payload. Note: If the specified namePath does not exist under this deployable, the system automatically creates the component(s) under this deployable and then uploads the configuration content.

identifierKeys

List of names that indicate which key in an array child to use to identify the same node.For example, if you’re uploading:

Shell
[  {"name" : "Allan, "city" : "Paris"},   {"name" : "Karen, "city" : "Sydney"}]

in the following existing model:

Shell
[  {"name" : "Karen, "city" : "Manila"},  {"name" : "Allan, "city" : "Brussels"}]

and you set identifierKeys to name, it produces the following output:

Shell
[  {"name" : "Karen, "city" : "Sydney"},  {"name" : "Allan, "city" : "Paris"}]

Otherwise, it produces the following output:

Shell
[  {"name" : "Karen, "city" : "Manila"},  {"name" : "Allan, "city" : "Brussels"},  {"name" : "Allan, "city" : "Paris"},  {"name" : "Karen, "city" : "Sydney"}]

Data type: Array of Strings

ignoreAttributes

Flag that indicates whether the given data format supports attributes (currently only XML).Valid values:

  • true: If the given data format supports attributes, any attributes in the input data are skipped during the upload.
  • false: If the given data format supports attributes, any attributes in the input data are included in the upload.

Data type: Boolean

Default: false

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String

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

Note: This option is only available if the value for the autoCommit parameter is true.
|Name|Description| |----|-----------| |Variable upload data|Configuration data to upload. This can be any data in the format defined by the **dataFormat** parameter of the query parameters.|

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. Supported types: text/plain and application/x-www-form-urlencoded.Default: text/plain
|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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following example shows an upload request for the application Demo_App1631126164773.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/deployables?deployableName=TST-1&autoValidate=false&dataFormat=json&autoDelete=false&changesetNumber=Chset-102&appName=Demo_App1631126164773&publishOption=publish_none&autoCommit=true&namePath=%2FSettings%2FdbSettings" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "{  \"dbIPAddress\": \"10.10.10.110\",  \"dbPort\": \"8080\",  \"dbConnectionString\": \"admin:admin server1.xyz.com:8080 dbName_payments\",  \"dbConnectionStringBackup\": \"admin:admin server2.xyz.com dbName_payments_backup\"}" \ --user 'username':'password'

The following return results show both a successful and an error response for this request.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "ec1f71f45322301096edddeeff7b12b3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Size of uploaded data:6853632.0(bytes) is greater than max allowed upload limit of 2097152.0(bytes)",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - POST /sn_cdm/applications/uploads/deployables/file

Uploads files to the deployables folder in the Configuration Data Model (CDM).

URL format

Versioned URL: POST /api/sn_cdm/{api_version}/applications/uploads/deployables/file

Default URL: POST /api/sn_cdm/applications/uploads/deployables/file

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

Name of the application to associate with the configuration data. This application must be in the active state.Data type: String

Table: CDM Application [sn_cdm_application]

autoCommit

Flag that indicates whether the changeset identified in the changesetNumber parameter is committed to the data model after upload.Valid values:

  • true: Changeset is committed after upload.
  • false: Changeset isn't committed after upload.

Data type: Boolean

Default: false

autoValidate

Flag that indicates whether the snapshots created when committed are validated.Valid values:

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

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

Data type: Boolean

Default: false

changesetNumber

String that uniquely identifies the changeset associated with the application, such as Chset-102. This changeset must be in the "Open" state.Data type: String

Default: Creates a changeset to use. The changeset details are returned as part of the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} results.

Table: CDM Changeset [sn_cdm_changeset]

deployableName

Required. Name of the CDM deployable for which to map the policy.Data type: String

Table: CDM Deployable [sn_cdm_deployable]

fileName

Name of the file to upload. This name can differ from than the actual file name and contain the file extension. For example, .txt/.scv/.jar. The fileName value is applied when downloading the file.Data type: String

fileNodeName

Name of the file node. This file name is used in the configuration data when exporting it. This name doesn’t require a file extension nor does it affect the download.Data type: String

namePath

Path of the targeted node under which the configuration data should be uploaded. This path is relative to the components, collection, or deployable folder (depending on the endpoint being called).You can pass the name path in any of the following formats. For example, to define the name path for the node testApp/deployables/Development1/cdi1:

  • Backslash format: testApp/deployables/Development1/cdi1

Note: If your node name contains a backslash ("/"), you can’t use this format.

  • Backend name path with replacement characters: testApp�deployables�​Development1​�​cdi1
  • Array: ['testApp','deployables','Development1','cdi1']

Note: If the specified component doesn't exist at the specified path, the system automatically creates the component at the specified path and then uploads the data.

Data type: String

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

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

Name

Description

Variable upload data

Configuration data to upload. By default, file size uploads are limited to 5 MB. For information about how to adjust your upload file sizes and type, see this Now Support article.Data type: String/stream
### Headers

Header

Description

Accept

Data format of the response body. Supported types: application/json or application/xml. Default: application/json

Content-Type

Data type of the file to be uploaded. Supported types: application/zip, text/plain, application/json.Default: 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.Upload request has been rejected.

Possible issues:

  • Size of configuration payload is greater that the allowed maximum - 2 MB by default.
  • Required parameters are missing from the call.

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\)

Name

Description

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

Error status of the request.Possible values: failure

Data type: String

upload_id

Sys_id of the upload request. Use this ID to call the CdmApplicationsApi - GET /sn_cdm/applications/upload-status/{upload_id} endpoint to obtain the status of the upload.Data type: String
### cURL request

The following request uploads a plain text file to the deployables folder of the CDM application.

Shell
curl "http://instance.servicenow.com/api/sn_cdm/applications/uploads/deployables/file?autoValidate=true&deployableName=depA&appName=testApp&namePath=testComponent%2FfilesFolder&fileName=testFileNodeName.txt&publishOption=publish_valid&changesetNumber=Chset-108&autoCommit=true&fileNodeName=testFile.txt" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:text/plain" \ --data "This is sample content that will be uploaded to a plain text file."\ --user 'username':'password'

The following return results show both a successful and an error response to this request.

JavaScript
// Successful completion of the upload request{   "result": {     "upload_id": "ec1f71f45322301096edddeeff7b12b3"   } } 
// Error response. Payload is too large.{   "error": {     "message": "Could not find active application with name: ‘testApp’ of type application",     "detail": ""   },  "status": "failure"}

CdmApplicationsApi - PUT /sn_cdm/applications/deployables

Updates the specified shared component in an application within a specified changeset.

Allows an update to the following fields:

  • Name
  • Description
  • Application Service\Dynamic CI Group
  • Deployable identifier

The CDM Admin role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/deployables

Default URL: /api/sn_cdm/applications/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

appName

Required. Name of the CDM Application.Data type: String

name

Required. Name of the CDM Deployable.Data type: String

newDescription

Optional. A description for the CDM Deployable.Data type: String

newServiceId

Optional. The ID of the desired Application Service/Dynamic CI Group. In the cURL request, provide '’ to disconnect the Deployable from the service.

newIdentifier

Optional. The identifier of the Deployable.Data type: Choice (Development/Test/Production

newName

Optional. The new name of the Deployable.Data type: String

returnFields

Optional. Comma-separated list of fields to be returned as part of the response.
|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. Supported types: application/json

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 (JSON or XML)

Name

Description

sys_id

CDM deployable sys_Id.

name

Name of the CDM Deployable.

node

Deployable node object.{ ‘value’: ‘<sysId>’, ‘link’: ‘http://localhost:8081/api/now/table/*’}

description

CDM deployable description.

identifier

An identifier for the deployable.

cmdb_ci

The app service object which is connected to a deployable.{ ‘value’: ‘<sysId>’, ‘link’: ‘http://localhost:8081/api/now/table/*’}

cmdb_app

The CDM application object.{ ‘value’: ‘<sysId>’, ‘link’: ‘http://localhost:8081/api/now/table/*’}

snapshot_version_counter

The count of snapshots created for a deployable.

cdi_count

The number of CDIs contained in this CDM deployable.

cdi_usage

The CDI usage percentage.

environment_type

The environment type. Possible values: - development

  • production
  • test

state

The active or deleted state . Possible values: - active

  • deleted

sys_created_by

CDM deployable created by <username>.

sys_created_on

CDM deployable creation timestamp in the format of <yyyy-MM-dd hh:mm:ss>.

sys_updated_by

CDM deployable updated by <username>.

sys_updated_on

CDM deployable updated by timestamp in the format of <yyyy-MM-dd hh:mm:ss>.
### cURL request
Shell
curl "http://localhost:8080/api/sn_cdm/applications/deployables?appName=testApp&name=Dep-1" \ --request PUT\ --header "Accept:application/json" \ --user 'cdm_admin':'password1!'

Output:

JSON
{   "result": {     "identifier": "identiy1",     "cmdb_ci": {       "value": "f5b9e00b53901110a1d3ddeeff7b12b8",       "link": "http://192.168.0.233:8080/api/now/table/cmdb_ci_service_auto/f5b9e00b53901110a1d3ddeeff7b12b8"     },     "cdi_count": "3",     "snapshot_version_counter": "1",     "description": "cdcds",     "sys_updated_on": "2022-07-27 13:40:13",     "environment_type": "Test",     "node": {       "value": "30c00d4053015110a1d3ddeeff7b12bf",       "link": "http://192.168.0.233:8080/api/now/table/sn_cdm_node/30c00d4053015110a1d3ddeeff7b12bf"     },     "sys_id": "39b9e00b53901110a1d3ddeeff7b12b7",     "sys_updated_by": "admin",     "cdm_app": {       "value": "62b517a953b70110a1d3ddeeff7b128c",       "link": "http://192.168.0.233:8080/api/now/table/sn_cdm_application/62b517a953b70110a1d3ddeeff7b128c"     },     "sys_created_on": "2022-06-29 12:53:57",     "cdi_usage": "0.03",     "name": "Dep-2",     "state": "active",     "sys_created_by": "admin"   } }

CdmApplicationsApi - PUT /sn_cdm/applications/shared_components

Updates the specified shared component in an application within a specified changeset.

The CDM Admin role is required to access this endpoint.

URL format

Versioned URL: /api/sn_cdm/{api_version}/applications/shared_components

Default URL: /api/sn_cdm/applications/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 changeset associated with the component.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

sharedComponentName

Required. Name of the shared component associated with the specified application.Data type: String

Table: CDM Shared Component [sn_cdm_shared_component]

sharedLibraryName

Required. Name of the shared library under which the component resides. The shared library must have the following fields defined as follows:- state = active

  • available = true
  • type = shared_library

Data type: String

Table: CDM Application [sn_cdm_application]

version

Required. Version name associated with the shared component.Data type: String

Table: CDM Snapshot [sn_cdm_snapshot]
|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. Supported types: application/json or application/xml. Default: 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

The response fields depend on what fields were specified in the returnFields parameter in the request. The following describes some of the more important fields.

Name

Description

changeset_id

Details of the changeset record associated with the node. Data type: Object

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

Description of the CDM node.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

linked_to

ID of the main node associated with the shared component.Data type: String

linked_to_version

Details of the CDM snapshot record associated with the node. Data type: Object

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

linked_to_version.link

Call syntax for querying this version record using the Table REST API.Data type: String

linked_to_version.value

Sys_id of the version record.Data type: String

main

Flag that indicates whether the associated snapshot was published.

Valid values:

  • true: Snapshot was published.
  • false: Snapshot was not published.

main_id

Unique ID of the newly created main node.Data type: String

main_id_encoded

Encoded ID of the newly created main node.Data type: String

name

Name of the CDM node.Data type: String

node

Sys_id of the shared component node.Data type: String

node_path

Path to the new linked node created when adding the shared component. Data type: String

status

Status of the node.Possible values: New

Data type: String

sys_created_by

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

sys_created_on

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

Data type: String

sys_id

Sys_id of the node.Data type: String

Table: CDM Node [sn_cdm_node]

sys_updated_by

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

sys_updated_on

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

Data type: String

type

Node type.Data type: String
### cURL request

The following example shows how to call this endpoint to update the application "App1" with the shared component "paymentService-V1.1" under the shared library "OracleG-Library-10" within the "Chset-20" changeset.

Text
"https://instance-name.service-now.com/api/sn_cdm/applications/shared_components?sharedComponentName=paymentService-V1.1&sharedLibraryName=OracleG-Library-10&changesetNumber=Chset-20&versionName=sComp3-v2.shc&appName=App1" \ --request PUT \ --header "Accept:application/json" \ --user 'username':'password'

Response:

Shell
"result": {  "changeset_id": {    "value": "7343d0f71b771110636e0fe0604bcb0b",    "link": "https://instance-name.service-now.com/api/now/table/sn_cdm_changeset/7343d0f71b771110636e0fe0604bcb0b"  },  "node_path": "!2!3!&`",  "description": null,  "sys_updated_on": "2022-12-22 18:52:38",  "type": "sn_cdm_node_linked_shared_component",  "sys_class_name": "sn_cdm_node",  "sys_id": "339314b71b771110636e0fe0604bcba3",  "sys_updated_by": ”admin",  "previous_version": {    "value": "a9ce80bf1b371110636e0fe0604bcb10",    "link": "https://instance-name.service-now.com/api/now/table/sn_cdm_node/a9ce80bf1b371110636e0fe0604bcb10"   },  "sys_created_on": "2022-12-22 18:52:38",  "value": null,  "effective_from": null,  "linked_to": "146",   "sys_created_by": ”admin",  "restricted_to": null,  "linked_to_version": {    "value": "54115c371b771110636e0fe0604bcb77",    "link": "https://instance-name.service-now.com/api/now/table/sn_cdm_snapshot/54115c371b771110636e0fe0604bcb77"  },  "level": "2",  "conflict_type": null,  "main_id": "166",  "effective_to": null,  "secure_value": null,  "node_classifier": "/application/components",  "main_id_encoded": "&`",  "name": "Component_A",  "position": null,  "reason_for_conflict": null,  "system_folder": false,  "status": "updated",  "conflict": false}
Search documentation
Search document titles and file paths on the brazil branch