Migrating issues when modifying workflows (Jira Cloud)

Notice: this article is relevant for Jira Cloud environments only. Search for "Migrating issues when modifying workflow schemes (Jira Data Center)" to get the relevant instructions for Jira Data Center environments.

When modifying an existing Jira workflow, an issue migration might be necessary. This happens when there are existing issues with statuses that do not appear in the modified workflow. When migrating issues, users have to choose a new status for each issue type and current status.

When using Salto to deploy a change to a workflow which requires migration, you will get the following warning: "Workflow change requires status migration". This means that you have to specify some NACL code which instructs Salto how to do the migration.

To do this, edit the target workflow scheme element NACL (using the "Edit" button during deployments from environments) and add this code at the top of the element (below the jira.WorkflowConfiguration <instanceName> line):

statusMappings = [
  {
    issueTypeId = jira.IssueType.instance.Epic
    projectId = jira.Project.instance.helpdesk@s
    statusMigrations = [
      {
        oldStatusReference = jira.Status.instance.done
        newStatusReference = jira.Status.instance.<statusName>
      },
    ]
  },
  {
    issueTypeId = jira.IssueType.instance.Bug
    projectId = jira.Project.instance.helpdesk@s
    statusMigrations = [
      {
        oldStatusReference = jira.Status.instance.done
        newStatusReference = jira.Status.instance.<statusName>
      },
    ]
  },
  {
    issueTypeId = jira.IssueType.instance.HelpRequest
    projectId = jira.Project.instance.helpdesk@s
    statusMigrations = [
      {
        oldStatusReference = jira.Status.instance.done
        newStatusReference = jira.Status.instance.<statusName>
      },
    ]
  },
]

Each {} object specifies how Jira should migrate issues: transform all issues from a specific projectId and issueTypeId, which are in a specific status oldStatusReference, to the new status newStatusReference which should be in the new workflow.

You should only complete the missing newStatusReference values.