Workflow Mappings (email/file exchange)

With Backbone, you can define workflow mappings based on issue status, allowing you to define fine-grained distributed workflows between synchronized issues.

Are you on the right help page?

If you connect Jiras...
... via HTTP(S) (server/data center, cloud, local), check out this page instead.
... via email or file exchange (server/data center behind a firewall), you're in the right place.

This guide will demonstrate how to create a distributed workflow between two synchronized issues.

First steps

You must know the workflow status IDs of the partner project
You must assign your synchronization user the transition issues and administer projects JIRA permissions
You should know both projects' workflow structure

Choose the correct workflow editor

Backbone includes two workflow mapping editors – the default (visual) editor and the advanced (text-based) editor. When you start configuring workflow mappings, it's important to choose the correct one for your needs.

Name

Functionality

Recommended use case

Default editor

Lets you map workflow status between projects

All scenarios except when the advanced editor is recommended

Advanced editor

Lets you map the workflow status, and also select specific transitions

Two scenarios only:

If you have already configured workflow mappings for a project in Backbone versions 3.3 or earlier, and you don't want to lose them. This is because these earlier versions only used the advanced editor – and you cannot switch back to the default editor in a project without losing workflows created in the advanced editor.
There are certain transitions in your workflows that can be executed in multiple ways, and you need to define which exact path should be taken. This is because you can't select which transitions between states should be made in the default editor.

Find out your partner's workflow status IDs

When you create workflow mappings in a distributed configuration, you have to map the statuses to your partner's Status ID, rather than the status name. This means that each integration partner must find out their own workflow status IDs, and then give them to the integration partner.

The best way of finding out your own status IDs is by downloading the XML definition of your workflow, then opening it in a text editor and searching for the string jira.status.id. An xml snippet for a status named "open" may look like this. So you should provide as a Status ID the number 1.

CODE

<step id="1" name="Open">
	<meta name="jira.status.id">1</meta>
	<actions>
		<common-action id="4" />
		<common-action id="5" />
		<common-action id="2" />
	</actions>
</step>

Use the default editor

Let's create a workflow mapping with the default editor.

To get started, open the synchronization configuration and click Workflows > New workflow mapping;
If you see a different view (with two columns for the two projects), this means that you've already created workflow mappings for this project with the advanced editor – you won't be able to switch back to the simple editor without losing these.
Select which workflows you want to map, and what issue types you want to map the workflow for.
Now, you can use the editor to map what workflow status ID the partner project should be triggered to when your project sends them a certain workflow state.

You can't select specific workflow transitions

With the default editor, if there are two ways of executing a workflow transition, Backbone will always go for shortest path (if the paths are the same length, the choice is random).
The functionality to select specific transitions will be added in a future release: BAC-763
On the next screen, map what workflow status your project should transition to when the partner project sends a certain status ID. You can configure this in the same way as step 3.

Use the advanced editor

The advanced editor lets you map workflow states between projects, and also select specific transitions between those states.

If you need to use the advanced editor, switch by clicking ... > Switch to advanced view.

If you want to create a workflow mapping for all issue types belonging to a project's default workflow, then click Default workflow mapping +.
If you want to create a workflow mapping for (a) specific issue type/s, click + New workflow mapping.

To define a workflow mapping, simply click + then you can define transition rules for your project. When you define a transition rule, you can define what transition for project's workflow should be triggered when the workflow status ID in the partner project changes. The condition is always a combination of the local status and the status ID of the partner project. Whenever the status ID in the partner project changes, Backbone will search for a matching condition and perform the selected transition (or transitions). The list of transitions to select depends on the selected local status.