Migrate app workflow rules from Jira server to cloud

Introduction

This tutorial shows app developers how to migrate app workflow rules from server to cloud. There are three steps to migrate app workflow rules:

1. Provide the app workflow rules to be migrated to cloud.
2. Retrieve the migrated workflow rules from your cloud app
3. Fix the configuration of migrated workflow rules.

Step 1: Provide the app workflow rules to be migrated

If your app is included in the migration plan, the Jira Cloud Migration Assistant (JCMA) will migrate the workflow rules that your app has claimed as part of product data migration. On your server app, add the interface JiraAppCloudMigrationListenerV1 on top of the class that implements DiscoverableListener to provide a map of the app workflow rules to be migrated.

Here's the method you'll have to implement:

1
2
public interface JiraAppCloudMigrationListenerV1 {

    Map<String, String> getSupportedWorkflowRuleMappings();

}

The method above returns a map of the server to cloud workflow rule mappings, where:

• key is class name of server workflow rule (ex: com.example.plugins.tutorial.jira.workflow.CloseParentIssuePostFunction)
• value is key of cloud workflow rule (ex: sample-cloud-workflow-post-function-key)

See an example

1
2
    @Override
    public Map<String, String> getSupportedWorkflowRuleMappings() {
        Map<String, String> map = new HashMap<>();
        map.put("com.vendor.impl.workflows.ParentIssueBlockingCondition", "parentIssueBlockingCondition-cloud");
        map.put("com.vendor.impl.workflows.CloseParentIssuePostFunction", "closeParentIssuePostFunction-cloud");
        map.put("com.vendor.impl.workflows.CloseIssueWorkflowValidator", "closeIssueWorkflowValidator-cloud");
        return map;
    }

Step 2: Retrieve the migrated workflow rules from your cloud app

1. Request mappings: Use the Get Mappings API with namespace jira/classic:workflowRule to retrieve the mappings for migrated workflow rules.
   

2. Filter the newly migrated workflow rules: Filter the migrated workflow rules that are yet to be processed by your cloud app from the mappings list retrieved in the previous (Request mappings) step. Your cloud app should store the cloud IDs of migrated workflows, workflow rules (i.e. {cloudWorkflowId}/{cloudWorkflowRuleID}) that are already processed by your app for the given cloud site to achieve this step.

Format of workflow rules ID Mapping

1
2
{
  {serverWorkflowRuleID}:{cloudWorkflowId}/{cloudWorkflowRuleID}
}

In the above code:

• serverWorkflowRuleID is the ID generated by JCMA (UUID) for server workflow rule.
• cloudWorkflowId is the entity ID of cloud workflow (UUID).
• cloudWorkflowRuleID is the ID of cloud workflow rule (UUID), which your apps can use to update workflow configuration.

See an example

1
2
{
  "b1357138-b7fd-4a7a-910f-a61d5adea551": "9674634a-c02f-4383-a4b6-fbb3ca228b23/d3a7c66e-c76b-4ac0-aa7c-a44e15a54c43",
  "c96282be-1f2f-4a28-94ce-5d6fe36ac4d8": "9674634a-c02f-4383-a4b6-fbb3ca228b23/e863d81d-fc90-41f6-afe4-271cef08a032",
  "dba809dd-433d-4ffa-9046-c1a41a17c8e4": "9674634a-c02f-4383-a4b6-fbb3ca228b23/9b2b1b87-4bfc-4197-9ee9-d5077765d4f0"
}

Step 3: Fix the configuration of migrated workflow rules

Use the new GET workflow details API to get the details of workflow rules which your cloud app retrieved in step 2 of this tutorial.

The code below shows you how the Jira Cloud Migration Assistant migrates server app workflow rule parameters to the cloud app workflow configuration.

Sample server workflow rule config

1
2
<condition type="class">
  <arg name="statuses">workflowMode,5,atl_token,descriptorTab</arg>
  <arg name="class.name">com.example.plugins.tutorial.jira.workflow.ParentIssueBlockingCondition</arg>
</condition>

Corresponding sample cloud workflow rule config

1
2
{
  "value": "{ \"statuses\": \"workflowMode,5,atl_token,descriptorTab\", \"class.name\":\"com.example.plugins.tutorial.jira.workflow.ParentIssueBlockingCondition\" }"
}

The screenshot below shows you how the migrated workflow rule configuration becomes available in the configuration field of ConnectWorkflowTransitionRule:

All the migrated app workflow rules migrates to cloud in a disabled state i.e. disabled property of the migrated workflow rule configuration will be set to true.

Your cloud app can use the cloudWorkflowRuleIds to do either of the following:

• Update/fix the workflow transition rule configuration
• Delete the workflow transition rule configuration