Cloud workflows SPI

On this page:

1 SPI API reference
2 Integration endpoint for migrating workflow configuration from server to cloud
3 Migration process
4 Cloud SPI descriptor
5 App REST endpoint

SPI API reference

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

Integration endpoint for migrating workflow configuration from server to cloud

The Atlassian Connect platform allows apps to introduce new workflow elements. This means apps can introduce their types of workflow conditions, validators, and post-functions.

The Cloud Workflows SPI is our Service Provider Interface for workflows. This interface offers a way to migrate apps' conditions, validators, and post-functions from Jira Server/DC to the Cloud. For this purpose, apps need to implement the Cloud Workflows SPI. Then, the app users will be able to migrate Server/Data Center workflow elements to their equivalent elements in Jira Cloud.

Migration process

The server-to-cloud migration process for workflow elements includes the following steps:

Data is exported from the server via the CMJ Server SPI.
For each workflow element, CMJ Cloud looks for a cloud app with the same key in Jira Cloud.
If an app that provides a Cloud SPI descriptor is found, CMJ Cloud will look for a migration path in the descriptor’s ruleMappings (check the Cloud SPI Descriptor example in the next section).
If a migration path is found, CMJ Cloud creates the workflow rule, equivalent to the server workflow element.
CMJ Cloud creates a new migration operation and invokes the app REST endpoint that will handle the configuration transfer.
The app may query CMJ Cloud for mapping data and report the progress of the operation via the CMJ Cloud Operations API.

Cloud SPI descriptor

Here is an example of what the Cloud SPI descriptor looks like for the Workflows SPI:

{
  "baseUrl": "https://your-app-domain.com",
  "appKey": "com.botronsoft.cmj.cloud.spi.spi-test-app",
  "endpoints": [
    {
      "path": "/cmjspi/workflow/importFromServer",
      "apiVersion": 1,
      "type": "WORKFLOW_IMPORT_FROM_SERVER",
      "ruleMappings": [
        {
          "serverRule": "com.botronsoft.cmj.cloud.spi.spiservertestapp.workflow.participants.SampleJiraWorkflowCondition",
          "cloudRule": "sample-workflow-condition"
        },
        {
          "serverRule": "com.botronsoft.cmj.cloud.spi.spiservertestapp.workflow.participants.SampleJiraWorkflowPostFunction",
          "cloudRule": "sample-workflow-post-function"
        },
        {
          "serverRule": "com.botronsoft.cmj.cloud.spi.spiservertestapp.workflow.participants.SampleJiraWorkflowMissingPostFunction",
          "cloudRule": "non-existent-workflow-post-function-key",
          "disabled": true
        },
        {
          "serverRule": "com.botronsoft.cmj.cloud.spi.spiservertestapp.workflow.participants.SampleJiraWorkflowValidator",
          "cloudRule": "sample-workflow-validator"
        }
      ]
    }
  ],
  "authentication": "JWT"
}

If a Jira Server/DC app rule does not have a direct counterpart on Cloud, you can disable the server-cloud mapping by:

Passing a non-existent key for the Cloud rule mapping and
Turning off the rule by setting "disabled": true.

This way, you can still handle the server rule’s configuration during import. Remember that this strategy applies to all rule types - conditions, validators, and post-functions.

For more implementation details, you can check the missing post-function SampleJiraWorkflowMissingPostFunction in the Cloud SPI descriptor example above.

App REST endpoint

The app REST endpoint that handles the workflow rules transfer must accept POST requests and body in application/JSON format.

POST https://your-app-domain.com/cmjspi/workflow/importFromServer

Here is what the request for starting a workflow import operation looks like:

{
  "migrationMetadata": {
    "migrationId": "bf4c34b0-fc29-4fc9-a2a8-8e0b64ac075b",
    "migrationName": "my super migration",
    "operationId": "74c62a8d-32b9-4071-ba89-5c1b2bd5820d",
    "jwtToken": "AQICAHg2WvAsAq1udQglhZmIC4Z7tXwr39T1xTaDnB8fZgwj7AFRVg99eXmbKdRpRXPXNbgLAAABKDCCASQGCSqGSIb3DQEHBqCCARUwggERAgEAMIIBCgYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAz5pcrUyuO3MKyxBBgCARCAgdwJoV7CfDTIIK88Dz3TkuMtZn3nQb8kjE_RWzjBglweyCZ0N05QF_pDxgDClv2s_BQFd9Hf5QT6pfH6aWEy6J1Ox-RUjaxGb6-ZNz4N78oiEq-iKf_srxTAxOnoolCk-UP4tY9nW_4s80WSvdaJx1XmoJ89TxE63vxNW54PLXC0Czot7SqvPScLWK6UfaXOllthq-wCMBMc9mXGwWRZaPJd9in0n2wkfhbQZJ6U4ZMZZ-_2MrbSxv5zzs8jE5HRPn3kkHgPdYDPaRdf4jCnCZsTK8744QxYBH9oGHvp"
  },
  "sourceJiraMetadata": {
    "origin": "SERVER",
    "appVersion": "0.0.14-CMJC-2386-SNAPSHOT",
    "jiraVersion": "9.0.0",
    "jiraClientKey": null,
    "jiraHostUrl": null
  },
  "targetJiraMetadata": {
    "origin": "CLOUD",
    "appVersion": "1.0",
    "jiraVersion": "CLOUD",
    "jiraClientKey": "c297f40f-302f-3d8f-a486-7ad08da4bbc2",
    "jiraHostUrl": "https://botron-ci-test-16.atlassian.net"
  },
  "context": {
    "workflowId": "testWorkflowPostFunctionDifferentProps",
    "workflowRules": [
      {
        "id": "b7dd45e6-fde6-4c3c-b55c-2f1368419eb4",
        "key": "sample-workflow-post-function",
        "transitionId": "id-of-the-transition-the-rule-belongs-to"
        "type": "POST_FUNCTION",
        "configuration": {
          "class.name": "com.botronsoft.cmj.cloud.spi.spiservertestapp.workflow.participants.SampleJiraWorkflowPostFunction",
          "customFieldId": "customfield_10001",
          "statusId": "10002",
          "statusName": "CustomStatus"
        }
      }
    ]
  }
}