REST API: Configuration Manager

Owned by Rosen Marinkov
Last updated: May 07, 2024 by Stanley Neychev
9 min read

On this page:

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.

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:

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:

filters

array of objects

Optional

Includes the filters that match the provided "filterId".

Example:

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:

includeProjectBoards

boolean

Optional

Default value: false

Includes all boards of the projects exported with the snapshot.

Learn more.

dashboards

array of objects

Optional

Includes the dashboards that match the provided "dashboardId".

Example:

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:

filter
Only applicable to the Project with issues scope.

string

Optional

Includes only issues filtered by a JQL query.

Example:

 

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:

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.

Example from the latest REST API 1.6

 

Unix/macOS Request

Windows Request

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.

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

Responses

Delete a snapshot

DELETE /snapshots/{id}

This snapshot endpoint deletes a specified snapshot.

Request

Responses

Start a deployment operation

POST /deployments

Deployment is a two-step process:

  1. Meta information is provided.

  2. 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

Example from the latest REST API 1.6

Unix/macOS Request

Windows Request

Responses

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.

Request

Responses

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

Responses

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 first error in the body. To find all errors, use Integrity Check through the UI or REST API.

Error body