Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
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:
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
The query parameters vary based on the value of the "scope" parameter.
Parameter
Type
Description
Parameter
Type
Description
PARAMETERS FOR ALL SCOPES
name
string
Required
The name of the snapshot.
scope
string
Required
Accepted values: "system", "project" or "projectWithIssues".
description
string
Optional
The description of the snapshot.
PARAMETERS FOR SCOPES: PROJECT, PROJECT WITH ISSUES
projectKey
array of strings
Required
Includes one or more selected projects.
Example:
For single-project snapshots:
"projectKey" : "PRJ"
For multi-project snapshots:
"projectKey" : [
"PRJA",
"PRJB"
]
filters
array of objects
Optional
Includes the filters that match the provided "filterId".
Example:
"filters" : [{
"filterId" : 1
}]
includeProjectFilters
boolean
Optional
Default value: false
Includes all filters referenced by the projects in the snapshot.
Includes the dashboards that match the provided "dashboardId".
Example:
"dashboards" : [{
"dashboardId" : 1
}]
appsWithGlobalData
array of objects
Optional
Includes the global configuration and/or data objects of all specified Jira apps integrated with the respective Service Provider Interface (SPI) integration points. Learn more.
Available objects:
"key" - specifies the app's key;
"includeGlobalConfiguration" -includes the global app configuration settings of the app specified by the "key" parameter. The app must be integrated with CMJ via the SPI global configuration integration point.
"appDataIds" - includes custom functionality of an app that extends standard Jira functions. The selected app must be integrated with CMJ via the SPI app data integration point.
"typeId" - specifies the app's selected types of objects (functionality);
"objectIds" - includes specific app data objects of the selected types.
filter Only applicable to the Project with issues scope.
string
Optional
Includes only issues filtered by a JQL query.
Example:
"filter":"issueType = Bug"
options
object
Optional
Specifies additional data that can be included in the snapshot.
Available options:
"includeAttachmentFiles" (only applicable to project with issues scope) - includes issue attachment files for the selected projects. If the value is false, during snapshot deployment there's an option to provide the path where the attachment files reside on the target system.
"checkCustomFieldValues" (only applicable to project scope)- includes custom fields with value in at least one issue in the project. If the value is false, only custom fields referenced by the project configuration will be included.
The default value of both options is false if not else specifiedor if the "options" parameter is not used.
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.
Uploading a snaphot zip file is a required step after starting the deployment operation.
Request
Parameter
Type
Description
Parameter
Type
Description
file
string
Required
The snapshot file to be uploaded.
id (URI Parameter)
integer
Required
The deployment operation id.
curl -u admin:admin -i -X PUT <jira-base-url>/rest/configuration-manager/api/1.6/deployments/1/content -F file=@snapshot.zip
Responses
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
Parameter
Type
Description
Parameter
Type
Description
id
integer
Required
The deployment operation id.
curl -u admin:admin -i -H "Content-Type: application/json" -X GET <jira-base-url>/rest/configuration-manager/api/1.6/deployments/1
Responses
STATUS 200 - Returns a status: "waiting", "running", "failed", "succeeded".
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.
Status: “waiting”
You will receive the "waiting" status as a response in the following cases:
the snapshot zip file you want to deploy is still uploading;
you haven’t uploaded a snapshot zip file.
Uploading a snapshot zip file is a required step in the deployment operation and the "waiting" status will not change until you provide a file.
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:
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 firsterror in the body. To find all errors, use Integrity Check through the UI or REST API.
Error body
{
"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>."
]
}