Operations API

On this page:

1 SPI API reference
2 Invoke the Operations API
3 Report results and progress
- 3.1 Report results
- 3.2 Report progress
4 Map configuration elements
- 4.1 referenceKey property
5 Open API spec

SPI API reference

If you need more technical information on the latest SPI OpenAPI specs, please read the complete API reference.

Invoke the Operations API

The Operations API is the REST API that CMJ Cloud provides and can be invoked by apps implementing the SPI for various services.

When CMJ Cloud calls an app endpoint, it starts an operation. This process is explained in detail here. Each operation has a unique id sent to the app in the request body and can then be used to call the Operations API.

Currently, the Operations API provides the following endpoints:

Reporting results and progress
Mapping of configuration elements

Report results and progress

CMJ Cloud works with apps asynchronously - an operation is started, and then the app must call back CMJ via the Operations API to notify that it is done.

Report results

The API for reporting the result of the operation:

POST https://spi.cmj.botronsoftcloud.com/operations/<operation id>/result

To report the migration result, you have two options:

Return a result HTML report (resultHtml) with the warnings and errors encountered during the migration.
Return a result link (resultLink) to a custom report generated and hosted by you.

info The resultHtml option is suitable for small reports (up to a few megabytes). For larger reports, we recommend using the reportLink instead.

Below, you can see examples of how to implement the two approaches for the migration result report.

HTML report

{
   "resultHtml":"<!doctype html>
                 <meta charset=utf-8>
                 <title> Migration Report (suitable for small html reports) </title>"
                 <body> Successfully migrated 3/4 post functions, 3/5 conditions, 2/2 validators for workflow "Workflow name"</body>"
}

Link to a custom report

{
   "resultLink":"https://www.link-to-custom-hosted-report.com/report.html"
   "problems":[
      {
         "message":"Some warning",
         "severity":"WARNING"
      },
      {
         "message":"Some error",
         "severity":"ERROR"
      }
   ]
}

Report progress

It is highly recommended but optional for apps to report progress during the operation. This can be done via the API for reporting progress:

Map configuration elements

When configuration and data are moved between different instances of Jira, the IDs of the different configuration elements change. The same applies to migrations to Jira Cloud. The data exported by your app may contain references to configuration elements that need to be updated with the new IDs.

To retrieve the mapping of IDs between source and target, an app may invoke the mappings resource from the CMJ Cloud’s Operations API.

The API is paginated, and the mappings will be returned in the following format:

referenceKey property

The referenceKey property returned in the Operations API is the key property of a configuration element in the Server API’s ConfigurationReferenceCollector.

For example, in your Server SPI implementation, you might be referring to a user by their username. However, in the Cloud, you need to know the ID of that user. You can use the Operations API’s output to match the user’s key and id.

Open API spec

The Open API spec for the Operations API can be found here.