Status mapping
- Stanley Neychev
What is status mapping
Jira requires setting a mapping before deleting a status from an active workflow. To accommodate this, we facilitate a mapping process that allows you to select an alternative status mid-migration. The Cloud Migration Tool will then reassign affected issues to this new status during the migration process.
When is status mapping required
Cloud Migration Tool halts the migration during the Analyze changes phase if it identifies a status scheduled for deletion from an active workflow. In such instances, you will encounter the following error:
Status [statusname] will be removed from the destination workflow. To move the impacted issues, map this status to another mappable status using Customize mapping. See how to map statuses
It requires you to map the status scheduled for deletion to another status. You can choose a status already in the destination or one that the migration will create. For instructions on how to map statuses using a JSON file, please refer to the following sections.
Step-by-step guide to mapping statuses
Create a migration.
On the Analyze changes phase, click Download mapping on the top right.
You will get a JSON file with the default mapping for all projects, configuration elements, and users in the migration scope. This file will also include entries for statuses scheduled for deletion and a list of alternative statuses to which they can be mapped.Â
Modify the JSON file by entering alternative statuses for those scheduled for deletion. The section below, Guidelines for mapping statuses with a JSON file, details the required syntax for this task. Review the syntax and rules for customizing mappings for other configuration elements.
Click Customize mapping to upload the JSON file with the changes and review the result.
If no problems are reported, click Confirm to start applying the status mapping from the file. After that, the Cloud Migration Tool reanalyzes the configuration and finalizes applying the status mapping.
If any problems are reported, revisit the JSON file to correct the errors. No issues are migrated to the alternative status before resolving all problems reported.
After you resolve all reported problems, click Migrate at the bottom right to initiate the migration process. The Cloud Migration Tool will migrate affected issues to the alternative status.
Guidelines for mapping statuses with a JSON file
As detailed in the Step-by-step guide above, you can download a JSON mapping file that describes how the source configuration elements will be transferred to the destination. If the migration process involves deleting a status from an active workflow, the file will include a section for status mapping. In this section, you need to specify an alternative status to replace the one being deleted. After migration, any issues associated with the deleted status will be reassigned to the new status.
To configure the status mapping, modify the downloaded mapping file or create your own. Make sure any file you generate is in JSON format. Refer to the Guidelines to customize the configuration mapping document for additional instructions on using a JSON file.
Map statuses in a downloaded JSON file
You can manage the mapping between statuses by downloading the current mapping file, modifying it, and then uploading it back. When the migration includes deleting a status, the mapping file you download will include entries similar to the example below:
Status mapping records in a downloaded JSON file
"statusMapping" : {
"mappableStatuses" : [ "Build Broken", "To Do", "Done", "Review" ],
"statusMigrations" : [ {
"oldStatus" : "Completed"
} ]
}The mappableStatuses property enumerates all the statuses you can choose as alternatives to the status planned for deletion. You must select a status from this list to map any status scheduled to be deleted.
Records to map a status being deleted to another one
"statusMapping" : {
"mappableStatuses" : [ "Build Broken", "To Do", "Done", "Review" ],
"statusMigrations" : [ {
"oldStatus" : "Completed",
"newStatus" : "Done"
} ]
}Construct a JSON file with status mapping.
You can construct your own JSON file with status mapping entries and apply it to the migrated configuration. The example below shows the records needed in the file to map one status to an alternative one.
"statusMapping" : {
"statusMigrations" : [ {
"oldStatus" : "In Progress",
"newStatus" : "Developing"
} ]
}Set a mapping for more than one status
You might need to set mappings for multiple statuses scheduled for deletion. The example below shows how to structure your JSON entries to accommodate mappings for several statuses.
How Cloud Migration Tool determines the mappable statuses
Cloud Migration Tool determines the mappable statuses by analyzing all source workflows included in the migration and their statuses. It selects only the statuses common to all these workflows. This approach ensures that any status chosen for mapping is valid across all workflows in the migration scope.
For example, consider two workflows in a migration, WF1 and WF2, which require status mapping. Their statuses are Status1, Status2 for WF1 and Status2, Status3 for WF2. In this case, the mappableStatuses in the JSON file will only include Status2, the common status between the workflows.
No mappable statuses
You may encounter a scenario with no common statuses between the workflows in the migration.
When a universal status mapping applicable to all workflows isn't feasible, we suggest the following strategies:
Split the projects into smaller migrations: This is particularly useful if workflows from different projects have no common statuses.
Apply transformations: Specifically, consider renaming a workflow to add it as a new workflow to the destination. Post-migration, you will have to assign the renamed workflow to the same scheme the original was assigned to. Then, the workflow must become active.
Optimize workflows in the source Jira: Before the migration, modify your projects and workflows in the source Jira for a smoother process.