CdmVersionApi

  • Release version: Xanadu
  • Updated August 1, 2024
  • 10 minutes to read

    • The CdmVersionApi provides endpoints that enable you to publish, unpublish, and export versions (snapshots) in Configuration Data Management (CDM) for shared components under shared libraries.

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

    You must have one of the following roles to access this API:
    • Scripted REST CDM View ACL (sn_cdm.cdm.viewer)
    • Scripted REST CDM Editor ACL (sn_cdm.cdm_editor)

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

    For additional information on snapshots, see View snapshots.

    CdmVersionApi - GET /sn_cdm/versions/export

    Returns the configuration data for a specified shared component within a specified shared library for a specified published version.

    The CDM Editor role is required to access this endpoint.

    URL format

    Versioned URL: /api/sn_cdm/{api_version}/versions/export

    Default URL: /api/sn_cdm/versions/export

    Supported request parameters

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

    Data type: String
    Table 2. Query parameters
    Name Description
    dataFormat Required. Format of the configuration data.
    Valid values:
    • csv
    • ini
    • json
    • properties
    • raw
    • xml
    • yaml

    Data type: String
    decryptPassword Flag that indicates whether to show encoded or decrypted password values.
    Valid values:
    • true: Decrypt password and show decrypted value.
    • false: Show encrypted password value.

    Default: false
    sharedComponentName Required. Name of the shared component whose configuration data to export. Located in the CDM Shared Component [sn_cdm_shared_component] table.

    Data type: String
    sharedLibraryName Required. Name of the shared library that contains the component whose configuration data you want to return. Located in the CDM Application [sn_cdm_application] table. The specified application must have the type field set to "shared_library".

    Data type: String
    substituteVariables Flag that indicates whether to follow the variables. For information on following the variables, see Validating and correcting configuration data.
    Valid values:
    • true: Follow the variables.
    • false: Do not follow variables.

    Default: true
    Table 3. Request body parameters
    Name Description
    None

    Headers

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

    Table 4. Request headers
    Header Description
    Accept Data format of the response body.

    Supported types:

    • application/json
    • application/xml
    • text/xml

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

    Status codes

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

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. One of the follow problems may have occurred:
    • Shared library is not active.
    • Shared component is not active.
    • Version s not published.
    • Parameter is missing in 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

    Name Description
    result Configuration data in the specified format.
    error If an error occurred during processing, the details about the error.

    Data type: Object

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

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

    Data type: String
    status Error status of the request.

    Possible values: failure

    Data type: String

    cURL request

    The following code example shows how to export the configuration data of the "jdk8" component under the "JavaLib" shared library.

    curl "http://instance.servicenow.com/api/sn_cdm/shared_libraries/components/exports?sharedLibraryName=JavaLib&componentName=jdk8 
--request POST \  
--header "Accept:application/json" \   
--user 'username':'password'

    Response:

    {  
"result": {  
    "sharedComponentA": { "cdi": "val" } 
 }  
}

    CdmVersionApi - PUT /sn_cdm/versions/publish

    Publishes a version of a shared component under a specified shared library.

    The CDM Editor role is required to access this endpoint.

    Note:
    Snapshots and versions are synonymous in meaning for this implementation.

    URL format

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

    Default URL: /api/sn_cdm/versions/publish

    Supported request parameters

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

    Data type: String
    Table 8. Query parameters
    Name Description
    name Required. Name of the version of the shared component to publish. Located in the CDM Shared Component [sn_cdm_shared_component] table.

    Data type: String
    returnFields Comma-separated list of fields in the CDM Snapshot [sn_cdm_snapshot] table to return as part of the response.

    Data type: String

    Default: Returns all non-system fields.
    sharedComponentName Required. Name of the shared component to publish. Located in the CDM Shared Component [sn_cdm_shared_component] table.

    Data type: String
    sharedLibraryName Required. Name of the shared library in which the specified component resides. Located in the CDM Application [sn_cdm_application] table. The type field in the associated record must be set to "shared_library".

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

    Headers

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

    Table 10. Request headers
    Header Description
    Accept Data format of the response body.

    Supported types:

    • application/json
    • application/xml
    • text/xml

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

    Status codes

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

    Table 12. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. Error occurred during publishing.
    Possible issues:
    • Version name not found.
    • Component version is already published.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    cdm_application_id Details about the CDM application associated with the snapshot.

    Data type: Object

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

    Data type: String
    cdm_application_id.value Sys_id of the associated CDM application record. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    cdm_deployable_id Details about the CDM deployable associated with the snapshot.

    Data type: Object

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

    Data type: String
    cdm_deployable_id.value Sys_id of the deployable record. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    changeset_id Details about the changeset associated with the snapshot.

    Data type: Object

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

    Data type: String
    changeset_id.value Unique identifier of the changeset record. Located in the CDM Changeset [sn_cdm_changeset] table.

    Data type: String
    description Brief description of the snapshot.

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

    Data type: Object

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

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

    Data type: String
    last_published Date and time that the snapshot was last published.

    Data type: String

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

    Data type: String

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

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

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

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

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

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss
    sys_id Sys_id of the snapshot. Located in the CDM Snapshot [sn_cdm_snapshot] table.

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

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

    Data type: String

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

    Data type: String

    cURL request

    This code example shows how to publish the shared component "Development" with the version name of "Development-v1.shc".

    curl "http://instance.servicenow.com/api/sn_cdm/versions/publish?sharedLibraryName=LibraryJdk&componentName=Development&name=Development-v1.shc" \  
--request PUT\  
--header "Accept:application/json" \  
--user 'username':'password

    Response:

    {
  "result": {
    "changeset_id": {
      "value": "1a2bd15c7764a1109ac0cf0bbb5a99fc",
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_changeset/1a2bd15c7764a1109ac0cf0bbb5a99fc"
    },
    "cdm_deployable_id": null,
    "cdm_shared_component_node_id": {
      "value": "fe2b155c7764a1109ac0cf0bbb5a995d",
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_node/fe2b155c7764a1109ac0cf0bbb5a995d"
    },
    "cdm_shared_component_id": {
      "value": "362b155c7764a1109ac0cf0bbb5a9970",
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_shared_component/362b155c7764a1109ac0cf0bbb5a9970"
    },
    "description": null,
    "cdm_application_id": {
      "value": "122bd15c7764a1109ac0cf0bbb5a99fa",
      "link": "http://instance.servicenow.com/api/now/table/sn_cdm_application/122bd15c7764a1109ac0cf0bbb5a99fa"
    },
    "published": true,
    "sys_updated_on": "2023-01-18 14:15:44",
    "last_published": "2023-01-18 09:53:37",
    "sequence_number": "1",
    "number": "SNAP0001110",
    "sys_id": "df2b155c7764a1109ac0cf0bbb5a9949",
    "sys_updated_by": "admin",
    "sys_created_on": "2023-01-18 09:53:36",
    "name": "logonService-V2.1-v1.shc",
    "last_validated": "",
    "validation": "passed",
    "sys_created_by": "admin"
  }
}

    CdmVersionApi - PUT /sn_cdm/versions/unpublish

    Unpublishes a version of a shared component under a specified shared library.

    The CDM Editor role is required to access this endpoint.

    Note:
    Snapshots and versions are synonymous in meaning for this implementation.

    URL format

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

    Default URL: /api/sn_cdm/versions/publish

    Supported request parameters

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

    Data type: String
    Table 14. Query parameters
    Name Description
    name Required. Name of the version of the shared component to unpublish. Located in the CDM Shared Component [sn_cdm_shared_component] table.

    Data type: String
    returnFields Comma-separated list of fields in the CDM Snapshot [sn_cdm_snapshot] table to return as part of the response.

    Data type: String

    Default: Returns all non-system fields.
    sharedComponentName Required. Name of the shared component to unpublish. Located in the CDM Shared Component [sn_cdm_shared_component] table.

    Data type: String
    sharedLibraryName Required. Name of the shared library in which the specified component resides. Located in the CDM Application [sn_cdm_application] table. The type field in the associated record must be set to "shared_library".

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

    Headers

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

    Table 16. Request headers
    Header Description
    Accept Data format of the response body.

    Supported types:

    • application/json
    • application/xml
    • text/xml

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

    Status codes

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

    Table 18. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. Error occurred during unpublishing.
    Possible issues:
    • Version name not found.
    • Component version is already published.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters

    Name Description
    cdm_application_id Details about the CDM application associated with the snapshot.

    Data type: Object

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

    Data type: String
    cdm_application_id.value Sys_id of the associated CDM application record. Located in the CDM Application [sn_cdm_application] table.

    Data type: String
    cdm_deployable_id Details about the CDM deployable associated with the snapshot.

    Data type: Object

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

    Data type: String
    cdm_deployable_id.value Sys_id of the deployable record. Located in the CDM Deployable [sn_cdm_deployable] table.

    Data type: String
    changeset_id Details about the changeset associated with the snapshot.

    Data type: Object

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

    Data type: String
    changeset_id.value Unique identifier of the changeset record. Located in the CDM Changeset [sn_cdm_changeset] table.

    Data type: String
    description Brief description of the snapshot.

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

    Data type: Object

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

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

    Data type: String
    last_published Date and time that the snapshot was last published.

    Data type: String

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

    Data type: String

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

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

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

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

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

    Data type: String

    Format: yyyy-mm-dd hh:mm:ss
    sys_id Sys_id of the snapshot. Located in the CDM Snapshot [sn_cdm_snapshot] table.

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

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

    Data type: String

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

    Data type: String

    cURL request

    The following code example shows how to unpublish the "paymentService-V1" shared component from the "OracleG-Library-10" shared library.

    curl "https://instance-name.service-now.com/api/sn_cdm/versions/unpublish?sharedLibraryName=OracleG-Library-10&sharedComponentName=paymentService-V1.1&name=paymentService-V1.1-v1.shc" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--user 'username':'password'

    Response:

    {
  "result": {
    "changeset_id": {
      "value": "1a2bd15c7764a1109ac0cf0bbb5a99fc",
      "link": "http://192.168.0.129:8080/api/now/table/sn_cdm_changeset/1a2bd15c7764a1109ac0cf0bbb5a99fc"
    },
    "cdm_deployable_id": null,
    "cdm_shared_component_node_id": {
      "value": "fe2b155c7764a1109ac0cf0bbb5a995d",
      "link": "http://192.168.0.129:8080/api/now/table/sn_cdm_node/fe2b155c7764a1109ac0cf0bbb5a995d"
    },
    "cdm_shared_component_id": {
      "value": "362b155c7764a1109ac0cf0bbb5a9970",
      "link": "http://192.168.0.129:8080/api/now/table/sn_cdm_shared_component/362b155c7764a1109ac0cf0bbb5a9970"
    },
    "description": null,
    "cdm_application_id": {
      "value": "122bd15c7764a1109ac0cf0bbb5a99fa",
      "link": "http://192.168.0.129:8080/api/now/table/sn_cdm_application/122bd15c7764a1109ac0cf0bbb5a99fa"
    },
    "published": false,
    "sys_updated_on": "2023-01-18 14:15:44",
    "last_published": "2023-01-18 09:53:37",
    "sequence_number": "1",
    "number": "SNAP0001110",
    "sys_id": "df2b155c7764a1109ac0cf0bbb5a9949",
    "sys_updated_by": "admin",
    "sys_created_on": "2023-01-18 09:53:36",
    "name": "logonService-V2.1-v1.shc",
    "last_validated": "",
    "validation": "passed",
    "sys_created_by": "admin"
  }
}