Continuous Integration and Continuous Delivery (CICD) Update Set API

The CICD Update Set API provides methods to create, retrieve, preview, commit, and back-out an update set.

This API is associated with the actions you can perform on system update sets and requires the sn_cicd.sys_ci_automation role and Continuous Integration and Continuous Delivery (CICD) REST API (com.glide.continuousdelivery) plugin to access it.

Parent Topic:REST API reference

CICD Update Set - POST /api/sn_cicd/update_set/retrieve

Retrieves an update set with a given sys_id and allows you to remove the existing retrieved update set from the instance.

URL format

Versioned URL: /api/sn_cicd/{api_version}/update_set/retrieve

Default URL: /api/sn_cicd/update_set/retrieve

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

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.

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.

Response body parameters (JSON or XML)

"links": {
  "progress": {Object}
}

"progress": {
  "id": "String",
  "url": "String"
}

cURL request

The following example retrieves a particular update set with a given sys_id and instance ID.

curl 
"https://instance.servicenow.com/api/sn_cicd/update_set/retrieve?update_set_id=2ce715950d619e10f87785462179bd67&update_source_id=e66613a49d011210f877036c70ae59f7" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'

Response body. Shows details about the update set's current status and execution progress.

{
  "result": {
    "links": {
      "progress": {
        "id": "e2ea3eedc92dde10f877184664aecd90",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/e2ea3eedc92dde10f877184664aecd90"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}   

CICD Update Set - POST /api/sn_cicd/update_set/commitMultiple

Commits multiple update sets in a single request according to the order that they're provided.

URL format

Versioned URL: /api/sn_cicd/{api_version}/update_set/commitMultiple

Default URL: /api/sn_cicd/update_set/commitMultiple

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

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.

Status codes

Response body parameters (JSON or XML)

"links": {
  "progress": {Object}
}

"progress": {
  "id": "String",
  "url": "String"
}

cURL request

The following example shows how to commit an update with a given sys_id.

curl 
"https://instance.servicenow.com/api/sn_cicd/update_set/commitMultiple?remote_update_set_ids=0a9f45ab9d415e10f877036c70ae5968%2Cc2e89999c9e19e10f877184664aecd40" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"force_commit\":\"true\"}" \
--user 'username':'password'

Response body.

{
  "result": {
    "links": {
      "progress": {
        "id": "3d174aa1c969de10f877184664aecdc0",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/3d174aa1c969de10f877184664aecdc0"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CICD Update Set - POST /api/sn_cicd/update_set/preview/{remote_update_set_id}

Previews an update set to check for any conflicts and retrieve progress information about the update set operation.

Note: If the update set you want to preview doesn't exist on the instance, you must first use the CICD Update Set - POST /api/sn_cicd/update_set/retrieve endpoint to retrieve the update set or manually in the UI.

URL format

Versioned URL: /api/sn_cicd/{api_version}/update_set/preview/{remote_update_set_id}

Default URL: /api/sn_cicd/update_set/preview/{remote_update_set_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

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.

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.

Response body parameters (JSON or XML)

"links": {
  "progress": {Object}
}

"progress": {
  "id": "String",
  "url": "String"
}

cURL request

The following example shows how to preview a remote update set using a given ID.

curl 
curl "https://instance.servicenow.com/api/sn_cicd/update_set/preview/8f4608d39d89da10f877036c70ae5998" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'

Response body.

{
  "result": {
    "links": {
      "progress": {
        "id": "54e9c665c969de10f877184664aecd72",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/54e9c665c969de10f877184664aecd72"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CICD Update Set - POST /api/sn_cicd/update_set/back_out

Backs out an installation operation that was performed on an update set with a given sys_id.

For more information about how the back out operation affects an update set, see Back out an update set.

URL format

Versioned URL: /api/sn_cicd/{api_version}/update_set/back_out

Default URL: /api/sn_cicd/update_set/back_out

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

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.

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.

Response body parameters (JSON or XML)

"links": {
  "progress": {Object}
}

"progress": {
  "id": "String",
  "url": "String"
}

cURL request

The following example shows how to roll back an installation operation on a specific update sys_id.

curl 
"https://instance.servicenow.com/api/sn_cicd/update_set/back_out?update_set_id=73dd24e39dcd1e10f877036c70ae59ae&rollback_installs=false" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'

Response:

{
  "result": {
    "links": {
      "progress": {
        "id": "036bf811c9619e10f877184664aecdcb",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/036bf811c9619e10f877184664aecdcb"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
} 

CICD Update Set - POST /api/sn_cicd/update_set/commit/{remote_update_set_id}

Commits an update set with a given sys_id.

When you have previewed an update set and have resolved any issues, you can commit the update set using this endpoint. Committing an update set applies all changes to the instance and creates a local copy of the update set that contains an update record for every change. For more information about committing an update set, see Commit an update set.

URL format

Versioned URL: /api/sn_cicd/{api_version}/update_set/commit/{remote_update_set_id}

Default URL: /api/sn_cicd/update_set/ commit/{remote_update_set_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

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.

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.

Response body parameters (JSON or XML)

"links": {
  "progress": {Object}
}

"progress": {
  "id": "String",
  "url": "String"
}

cURL request

The following example commits the update set with the associated sys_id.

curl 
"https://instance.servicenow.com/api/sn_cicd/update_set/commit/4ee89999c9e19e10f877184664aecd42" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'

Response body.

{
  "result": {
    "links": {
      "progress": {
        "id": "bf380a11c9e59e10f877184664aecd0e",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/bf380a11c9e59e10f877184664aecd0e"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CICD Update Set - POST /api/sn_cicd/update_set/create

Creates a new update set and inserts the new record in the Update Sets [sys_update_set] table.

URL format

Versioned URL: /api/sn_cicd/{api_version}/update_set/create

Default URL: /api/sn_cicd/update_set/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

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.

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.

Response body parameters (JSON or XML)

cURL request

The following example demonstrates how to create a new update set with the name Testupdateset and the scope set to sn_test.

curl 
"https://instance.servicenow.com/api/sn_cicd/update_set/create?update_set_name=Testupdateset&scope=sn_test" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'

Response body.

{
  "result": {
    "status": "2",
    "status_label": "",
    "status_message": "Successfully created update set: Test update set 1",
    "status_detail": "",
    "error": "",
    "update_set_id": "a9a485d1c9a19e10f877184664aecd11"
  }
}