REST API: Configuration Manager

On this page:

 

For details and examples refer to the following articles:

Documentation for REST API 1.5 - available with Configuration Manager 6.11.0 or later.

Documentation for REST API 1.4 - available with Configuration Manager 6.6.5 or later.

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:

1 http://host:port/context/rest/configuration-manager/api/api-version/resource-name

The current API version is 1.5.

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:

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

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

  • Creating a new snapshot*

    Unix/MacOS Request

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

     

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



    Windows Request

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



    Response

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



  • Downloading a snapshot ZIP

    Request

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

    The snapshot will be saved in snapshot.zip file in the current directory

    Response

    1 2 3 HTTP/1.1 200 OK ... Content-Type: application/octet-stream



  • Deleting a snapshot

    Request

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



    Response

    1 2 HTTP/1.1 204 No Content ...



  • Snapshot deployment

    Deployment is a two step process - first meta information is provided and then a snapshot file is uploaded. The operation is asynchronous, a separate REST endpoint is used for tracking deployment progress.

    1. Starting a deployment operation

      Unix/MacOS Request

      1 2 3 4 5 6 curl -u admin:admin -i -H "Content-Type: application/json" -X POST <jira-base-url>/rest/configuration-manager/api/1.5/deployments -d ' { "scope" : "system", "mode" : "systemRestore" } '


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



      Windows Request

      1 2 3 4 5 curl -u admin:admin -i -H "Content-Type: application/json" -X POST <jira-base-url>/rest/configuration-manager/api/1.5/deployments -d^ "{^ \"scope\" : \"system\",^ \"mode\" : \"systemRestore\"^ }"



      Response

      1 2 3 4 5 6 7 8 HTTP/1.1 201 Created ... Location: <jira-base-url>/rest/configuration-manager/api/1.5/deployments/1 Content-Type: application/json;charset=UTF-8 ... { "id" : 1 }



    2. Uploading a snapshot ZIP file

      Executed from the directory where the snapshot.zip snapshot file is. Note that the ID of the deployment operation needs to be provided (in this case "1").

      Request

      1 curl -u admin:admin -i -X PUT <jira-base-url>/rest/configuration-manager/api/1.5/deployments/1/content -F file=@snapshot.zip



      Response

      1 2 HTTP/1.1 200 OK ...



    3. Checking the deployment status

      Request

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



      Response

      1 2 3 4 5 6 7 8 HTTP/1.1 200 OK ... Content-Type: application/json;charset=UTF-8 ... { "id" : 1, "status" : "succeeded" }



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:

1 2 3 4 5 6 { "id" : 1, "status" : "failed", "message" : "Data migration is required - automated deployment cannot continue." }  

In this case the deployment will have to 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 unequivocally match custom fields from 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 case is detected by default 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 can be reduced to warning with 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 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
1 2 3 4 5 { "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>." ] }