On this page:
Table of Contents | ||||
---|---|---|---|---|
|
For details and examples, take a look at the REST API reference:
Documentation for REST API 1.6 - available with Configuration Manager 6.14.0 or later.
Expand | ||
---|---|---|
| ||
Documentation for REST API 1.5 - available with Configuration Manager 6.6.5 or later. Documentation for REST API 1.4 Documentation for REST API 1.3. Documentation for REST API 1.2. Documentation for REST API 1.1. Documentation for REST API 1.0. |
URI Structure
Configuration Manager's REST API provides means to manage snapshots via URI paths. URIs for Configuration Manager's REST API resource have the following structure:
Code Block |
---|
http://host:port/context/rest/configuration-manager/api/api-version/resource-name |
The current API version is 1.6.
For example, you would use the following path to access the snapshots' API on a locally run instance of Jira with a context path of /jira:
Code Block |
---|
http://localhost:2990/jira/rest/configuration-manager/api/1.6/snapshots |
Info |
---|
Context Path The example above specifies a context path of “/jira”. Keep in mind that the context path may be different or not present for your installation of Jira. |
Step-by-step guide for using the API
Create a new snapshot*
POST /snapshots
This snapshot endpoint creates a new snapshot.
Request
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example from the latest REST API 1.6
Unix/macOS Request
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Windows Request
Expand | ||||
---|---|---|---|---|
| ||||
|
Responses
Expand | |||||
---|---|---|---|---|---|
| |||||
STATUS 201 application/json - Returns a JSON representation of snapshot metadata (includes the id of the new snapshot and the count of objects). The Location header contains the URI pointing to the newly created snapshot.
STATUS 400 - Returned if a required parameter is not provided or a snapshot with the same name already exists. STATUS 403 - Returned if the user does not have permissions to create a snapshot. |
Download a snapshot ZIP
GET /snapshots/{id}
This snapshot endpoint returns a specified snapshot as a ZIP containing a snapshot file in a binary format.
Request
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Responses
Expand | |||||
---|---|---|---|---|---|
| |||||
STATUS 200 application/octet-stream - Returns as a ZIP containing a snapshot file in a binary format:
STATUS 400 - Returned if the request is invalid. STATUS 401 - Returned if authentication credentials are missing. STATUS 403 - Returned if the user does not have permissions to create a snapshot. STATUS 404 - Returned if no snapshot with the given id is found. STATUS 405 - Returned if the id parameter is not provided in the request body. |
Delete a snapshot
DELETE /snapshots/{id}
This snapshot endpoint deletes a specified snapshot.
Request
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Responses
Expand | |||||
---|---|---|---|---|---|
| |||||
STATUS 204 - Returned if successfully deleted.
STATUS 400 - Returned if the id parameter is not provided. STATUS 403 - Returned if the user does not have permissions to create a snapshot. STATUS 404 - Returned if no snapshot with the given id is found. |
Start a deployment operation
POST /deployments
Deployment is a two-step process:
Meta information is provided.
A snapshot file is uploaded.
A separate REST endpoint is used for tracking deployment progress.
The “Start a deployment operation” is the first step of the deployment process. The request parameters provide the meta information required.
Request
Expand | ||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||
|
Example from the latest REST API 1.6
Unix/macOS Request
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Windows Request
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Responses
Expand | |||||
---|---|---|---|---|---|
| |||||
STATUS 201 - Returns the id of the operation.
STATUS 400 - Returned if a requiredparameter is not provided. STATUS 403 - Returned if the user does not have permissions to create a snapshot. |
Upload a snapshot ZIP file
PUT /deployments/{id}/content
This endpoint uploads the snapshot content during deployment.
The snapshot content must be provided in a part named 'file' within a multipart/form-data body. After the content is successfully uploaded, the deployment process will start.
Info |
---|
Uploading a snaphot zip file is a required step after starting the deployment operation. |
Request
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Responses
Expand | ||
---|---|---|
| ||
STATUS 200 - Returned when the snapshot is successfully uploaded and parsed. STATUS 400 - Returned if the type of the snapshot does not match the type of deployment operation. STATUS 403 - Returned if the user does not have permissions to create a snapshot. |
Check the deployment status
GET /deployments/{id}
Returns the status of the deployment operation with the given id.
This "id"
is received as a response to the “Start a deployment operation” request.
Request
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Expand | |||||
---|---|---|---|---|---|
| |||||
|
Responses
Expand | |||||
---|---|---|---|---|---|
| |||||
STATUS 200 - Returns a status:
STATUS 400 - Returned if the id is not provided. STATUS 403 - Returned if the user does not have permissions to create a snapshot. STATUS 404 - Returned if no deployment operation with the given id is found. |
Note |
---|
Status: “waiting” You will receive the
Uploading a snapshot zip file is a required step in the deployment operation and the |
Issue Migration
In certain situations deploying a configuration snapshot may require migration of issues (e.g., when a workflow status is deleted and there are issues with this status). Note that this is different than deploying a snapshot with issues. This is not supported by the REST API, as migration requires user input. The following response will be returned:
Code Block |
---|
{ "id" : 1, "status" : "failed", "message" : "Data migration is required - automated deployment cannot continue." } |
In this case, the deployment will have to be performed through the user interface.
More information on issue migration can be found here.
Conflicting Custom Fields
Due to the fact that Jira allows the existence of multiple custom fields with the same name and type on a single system, it is not always possible to directly match custom fields on the snapshot to fields on the target system. More information on duplicate custom fields can be found here. CMJ allows these conflicts to be resolved from the GUI, as described here.
When using the REST API for deployment and such a case is detected, the deployment stops, and an error message is shown.
You can perform the deployment through the GUI and select the proper matching.
If you want to perform the deployment anyway, the error severity type can be reduced to a warning showing the same message, which doesn't stop the deployment. This is controlled by the General Settings' "Stop deployment in case of possible data loss".
The duplicate fields on the source Jira can be temporarily renamed before creating the snapshot. The duplicate fields on the target instance can be temporarily renamed before deploying the snapshot in order to get properly matched.
Status code 500 while creating a snapshot
If there are Integrity Check errors present, CMJ will return status code 500 with the first error in the body. To find all errors, use Integrity Check through the UI or REST API.
Error body
Code Block | ||
---|---|---|
| ||
{ "messages": [ "com.botronsoft.jira.rollout.integrity.IntegrityViolationException: Workflow <a href=\"/jira/secure/admin/workflows/ViewWorkflowSteps.jspa?workflowMode=live&workflowName=Sales+Workflow\" target=\"_blank\">'Sales Workflow'</a> refers to the missing custom field <b>customfield_10201</b>." ] } |