REST API: Configuration Manager

On this page:

1 URI structure
2 Step-by-step guide for using the API
- 2.1 Create a new snapshot*
- 2.2 Get snapshot metadata
- 2.3 Download a snapshot ZIP
- 2.4 Delete a snapshot
- 2.5 Start a deployment operation
- 2.6 Upload a snapshot ZIP file
- 2.7 Check the deployment status
3 Issue migration
4 Conflicting custom fields
5 Status code 500 while creating a snapshot
- 5.1 Error body

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.

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:

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:

http://localhost:2990/jira/rest/configuration-manager/api/1.6/snapshots

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

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. Learn more.
agileBoards	array of objects Optional	Includes the agile boards that match the provided `"boardId"`. Example: `"agileBoards" : [{ "boardId" : 1 }]`
includeProjectBoards	boolean Optional Default value: false	Includes all boards of the projects exported with the snapshot. Learn more.
includeAutomationRules	boolean Default value: true Optional	Includes all automation rules. Learn more.
dashboards	array of objects Optional	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. Example: `"appsWithGlobalData" : [ { "key": "com.botronsoft.jira.rollout.spi-test-plugin", "includeGlobalConfiguration": "true", "appDataIds": [ { "typeId" : "typeOneId", "objectIds" : ["id1", "id2", "id3"] }, { "typeId" : "typeTwoId", "objectIds" : ["id3"] } ] } ]`
filter Only applicable to the Project with issues scope.	string Optional	Includes only issues filtered by a JQL query. Example: `"filter":"issueType = Bug"`
includeOnlyArchivedIssues	boolean Optional Default value: false	Includes only archived issues.
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 specified or if the `"options"` parameter is not used. Example: `"options" : { "includeAttachmentFiles" : true, "checkCustomFieldValues" : true }`
PARAMETERS FOR SCOPE: SYSTEM
includeGlobalAppData	boolean Default value: false Optional	Includes the global configuration data of all Jira apps integrated with CMJ.
includeAllFilters	boolean Default value: false Optional	Includes all filters.
includeAllBoards	boolean Default value: false Optional	Includes all agile boards.
includeAllDashboards	boolean Default value: false Optional	Includes all dashboards.
includeAutomationRules	boolean Default value: true Optional	Includes all automation rules.

Unix/macOS request

curl -u admin:admin -i -H "Content-Type: application/json" -X POST <jira-base-url>/rest/configuration-manager/api/1.6/snapshots -d '
	{
		"name" : "My snapshot",
		"description" : "Very nice snapshot",
		"scope" : "system"
	}
	'

Windows request

Note that on Windows machines, single quotes around JSON might not work. Try escaping them like: "{\"name\":\"My snapshot\"...

curl -u admin:admin -i -H "Content-Type: application/json" -X POST <jira-base-url>/rest/configuration-manager/api/1.6/snapshots -d^
"{^
    \"name\" : \"My snapshot\",^
    \"description\" : \"Very nice snapshot\",^
    \"scope\" : \"system\"^
}"

Responses

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.

HTTP/1.1 201 Created
...
Location: <jira-base-url>/rest/configuration-manager/api/1.6/snapshots/1
Content-Type: application/json;charset=UTF-8
...
{
  "id" : 1,
  "objectCount" : 86
}

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.

Get snapshot metadata

GET /snapshots

This snapshot endpoint returns all snapshots' metadata attributes (i.e., no actual snapshot files, just the snapshot metadata).

Request

curl -u admin:admin -H "Content-Type: application/json" -X GET <jira-base-url>/rest/configuration-manager/api/1.6/snapshots

Responses

STATUS 200 application/json - Metadata successfully fetched.

STATUS 400 - Returned if the request is invalid.

STATUS 403 - Returned if the user does not have the necessary permissions to get all snapshots' metadata.

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

Parameter	Type	Description

Parameter

Type

Description

id

integer

Required

The id of the snapshot to be returned as a ZIP.

curl -u admin:admin -H "Content-Type: application/json" -X GET <jira-base-url>/rest/configuration-manager/api/1.6/snapshots/1 > snapshot.zip

Responses

STATUS 200 application/octet-stream - Returns as a ZIP containing a snapshot file in a binary format:

HTTP/1.1 200 OK
...
Content-Type: application/octet-stream
...
<?xml version="1.1" encoding="UTF-8"?>
<jiraconfiguration:JiraConfigurationRoot xmi:version="2.0" type="System" name="My snapshot">
...
</jiraconfiguration:JiraConfigurationRoot>

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

Parameter	Type	Description

Parameter

Type

Description

id

integer

Required

The id of the snapshot to be deleted.

curl -u admin:admin -i -H "Content-Type: application/json" -X DELETE <jira-base-url>/rest/configuration-manager/api/1.6/snapshots/1

Responses

STATUS 204 - Returned if successfully deleted.

HTTP/1.1 204 No Content
...

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

The query parameters vary based on the value of the "scope" parameter.

Parameter	Type	Description

Parameter	Type	Description
PARAMETERS FOR ALL SCOPES
scope	string Required	Accepted values: `"system"` and `"project"`.
PARAMETERS FOR SCOPE: PROJECT
mode	string Required	Accepted values: `"singleProject"` and `"multiProject"`. Value depends on the number of projects in the deployed snapshot. Learn more about deploying single-project and multi-project snapshots.
projectKey	string Required	Only applicable to `"singleProject"` mode. The key of the project with which to merge, usually the same as the project in the snapshot.
options	object Some of the objects are required for `singleProject` mode. Optional for `multiProject` mode.	Specifies the behavior during deployment. There are two main possibilities during deployment: merging the project(s) in the snapshot with the project(s) on target, or creating a new project (only applicable to `"singleProject"` mode) on target identical to the project in the snapshot. Available options: `"createNewProject"` - required when creating a new project in `"singleProject"` mode. Default value: false. `"newProjectKey"`/`"newProjectName"` - required if `"createNewProject"` = true. `"projectKey"` - required when merging the project in `"singleProject"` mode. This is the key of the project to merge into. `"modifyProjectVersions"` - optional. Default value: true. `"modifyProjectComponents"` - optional. Default value: true. `"modifyProjectRoles"` - optional. Default value: true. `"modifyProjectShortcuts"` - optional. Default value: true. `"attachmentFilesPath"` - optional. `"modifyFieldDefaultValues"` - optional. Default value: true. `"modifyFieldOptions"` - optional. Default value: true. `"modifyObjectDescriptions"` - optional. Default value: true. `"modifyObjectTranslations"` - optional. Default value: true. `"modifyStatusCategories"` - optional. Default value: true. `"modifyPriorityColors"` - optional. Default value: true. `"modifyAvatars"` - optional. Default value: true. `"skipReindexing"` - optional. Default value: false. `"modifyAutomationRules"` - optional. Default value: false. Learn more about the options in the Advanced Options document. Example: `"options" : { "createNewProject" : true, "newProjectKey" : "PRJ", "newProjectName" : "My Project", "modifyProjectVersions" : false, "modifyProjectComponents" : false, "modifyProjectRoles": true, "attachmentFilesPath" : "C:\\attachments" }`
PARAMETERS FOR SCOPE: SYSTEM
mode	string Required	Accepted values: `"systemRestore"` - replaces the configuration on target with the configuration in the deployed snapshot. `"systemMerge"` - keeps the configuration of objects on target that are not present in the snapshot. The value depends on the deployment strategy. Learn more about deploying system snapshots.
options	object Optional	Specifies the behavior during deployment. Available options: `"modifyProjectVersions"` - default value: true. `"modifyProjectComponents"` - default value: true.