Issue Type Mappings (email/file exchange)

Issue Type Mappings define which issues are synchronized between instances.

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.

In a synchronization via email or file exchange, the master always creates the mappings first – once the master has created and published them, the slave configures them on their side. Issue types can be either mapped bi-directionally between master and slave, or uni-directionally from master to slave or slave to master. This guide will explain how to work with Issue Type Mappings on both the master and slave sides of the configuration.

Whenever a new issue is created in Jira, Jira will automatically assign an issue key which is not used. Since there might be different amounts of already existing issues, the issue keys will probably differ.

Issue type mappings – master

Create new field mappings at Edit Configuration > New Issue Type Mapping.

Firstly, you must decide which direction to map the issue type in. Each other maps the issue bi-directionally, First to Second maps it from your instance to the slave instance, and Second to First maps it from the slave instance to your instance.

When creating Issue Type mappings, you cannot directly map an issue type to a certain issue type on the partner side. This is because each partner controls their own side of the synchronization. Instead, you must assign the mapping a message alias, which is a label that determines how it is presented to the other synchronization Partner. The message should make it clear to the synchronization Partner which Issue Type they should map it to.

In most cases, this message alias should be the same as the issue type you map – this helps to avoid confusion.

Issue type mappings – slave

After the Issue Type Mappings have been created on the master side and published to the slave side, you need to assign the new Issue Type Mappings to issue types on your side of the configuration.

The message aliases assigned to the mappings should make it clear what issue types you should map them to. If this is unclear, contact your partner for clarification. Please map all the offered issue types by your partner to the corresponding issue types on your side via the edit action.

The slave does not have permission to create new field mappings, only to map ones created on the master side.

Limit the synchronized issues

Often it makes sense to only synchronize issues meeting a certain condition (e.g. with label ‘sync’). For this use case, you can further limit the set of synchronized issues by defining JQL filters. Backbone will scope this JQL so that only issues of this particular project are in it, so you don't accidentally select issues from other projects.

Read more about how to limit the synchronized issues in this help article: Limit the synchronized issues.

Both the master and slave synchronization partners can use this function.