Links Synchronizer

Dark Feature - Synchronizers are hidden by default

We recommend using Automation instead of Synchronizers. Automation is safer, provides additional functionality and flexibility, and uses fewer system resources.

To enable synchronizers, see Advanced Configuration and Dark Features.

The Links Synchronizer maintains issue links between parent issues and child issues.You can use this synchronizer to replicate the hierarchy in the structure with issue links, or to import a hierarchy that was previously created with links.

The Links synchronizer is available only when Links are enabled and there is at least one link type.

This synchronizer supports Resync in both directions (Import and Export) (more about resync). Incremental synchronization watches both structure changes and issue link changes and applies those change to the other side (unless the Reverse contradicting changes option is specified).

No matter how synchronizers are configured, they will only affect issues from the projects that are enabled for synchronization.

Synchronizers can add and remove Jira issue links based on the permissions of the user that installed the synchronizer.

Links Synchronizer Parameters

Link Type

The type of link to sync with. Links of other types will be ignored.

Link Direction

Defines which side of the link is the parent issue and which is the sub-issue.

Parent Issue Filter and Sub-Issue Filter

If set, these filters determine which issues and links can be affected by the synchronizer:

If a link's parent issue or sub-issue (as determined by Link Direction) doesn't pass the corresponding filter, then the link is ignored by the synchronizer. For example, if there are two issues that belong to the structure and pass the corresponding filters, but one of them falls out of its corresponding filter, the link will not be deleted.
If there is a parent issue and a sub-issue in the structure, and either of them doesn't pass the corresponding filter, the synchronizer will not create a link between them.

You can use saved filters or JQL queries.

Scope

Defines which issues are affected by the synchronizer, based on whether they are in the structure or not.

Synchronize issues that are already in the structure means that the synchronizer will affect only those issues that are already in the structure or reachable from it via issue links. Use this option when you need manual control over which of the linked issues appear in the structure.
- If Expand to sub-issues is selected, the synchronizer will add sub-issues to the structure if their parent issue is in the structure.
- If Expand to parent issues is selected, the synchronizer will add a parent issue to the structure if any of its sub-issues are in the structure.
Synchronize all issues that have links of selected type means that the synchronizer will affect all issues that have matching issue links and pass the Issue Filters. For example, you can use this option to import all issue relationships represented by links into an empty structure.

This setting also controls which issue links can be deleted during export, manual resync from structure, or incremental synchronization. For example, when you remove a sub-issue from the structure, the synchronizer will remove the corresponding link only if it could have added this sub-issue back (that is, when either Expand to sub-issues or Synchronize all issues is selected).

CAREFUL! Please be careful when using this synchronizer with Synchronize all issues option selected, because Exporting or Resyncing from Structure would delete all the existing links of the selected type between issues that are not in the corresponding positions in the structure.

Removal

Defines how the synchronizer treats a sub-issue that doesn't have a link to justify its position in the structure (for example, when a user deletes the link from its parent issue):

When Move upwards is selected, the synchronizer will move such an issue up the hierarchy until it's either at the top level of the structure or in a position that doesn't contradict the settings (for example, under an issue that does not pass the Parent Issue Filter).
When Remove is selected, the synchronizer will remove such an issue from the structure, together with all its sub-issues.

Primacy

By default, when a synchronizer is installed and enabled, it tracks changes made by users and applies them to the "other side":

When a user creates or deletes issue links, the synchronizer adjusts the structure accordingly.
When a user changes the structure, the synchronizer creates or removes the corresponding links.

You can use the Reverse contradicting changes option to override this behavior and specify the primary place where issue relationships are stored:

With Structure primacy, when a user creates or deletes a link that is within the scope of the synchronizer but contradicts the structure, that change will be reverted. One needs to change the structure to adjust issue relationships.
With Links primacy, the synchronizer reverts changes to the structure that contradict issue links. One needs to change the links to adjust an issue's position within the structure. Note that this does not apply to reordering issues without changing their parents.

Primacy does not apply during Export, Import or manual Resync.

Links Synchronizer Preserves Links Between an Added List of Issues

When a list of 2 or more issues is added to the structure, links between these issues are preserved, and the issues form a hierarchy according to these links. Such a situation may arise, for example, when moving several issues into the structure at one time.

This differs from the default behavior when the Reverse contradicting changes option is not selected: normally, if an issue A is added to the structure as a sub-issue B, and both of them pass the Issue Filters, Links synchronizer would establish a link between A and B and remove all other links of the corresponding type where B is on the sub-issue end of the link. When a list of issues is added, however, the synchronizer behaves as if Links primacy was selected.

Links Synchronizer Rules

When the synchronizer is enabled:
- Changes in the structure will be reflected by creating and removing links of the selected type.
- Links created or removed by the user will be automatically reflected in the structure.
Links created and removed by the synchronizer are not recorded in the issue history, and the issue update time is not changed (due to performance reasons).
Use Resync (from Structure to Links) or Export to update the links according to the structure.
- If Synchronize all issues is selected, all other links of the selected type will be deleted.
- Otherwise, the links that are reachable from the structure considering Expand to... options, but not represented in the structure, will be deleted.
Use Resync (from Links into Structure) or Import to add and rearrange the issues in the structure according to the existing links.
- If Synchronize all issues is selected, all issues with matching issue links will be added to the structure.
- Otherwise, only the issues reachable from the structure considering Expand to... options will be added.
Links that violate hierarchy restrictions are treated as follows:
- If a sub issue has more than one parent issue, the most recent issue link is used.
- If there is a sub-issue cycle, the oldest issue link is not used.
- There is an exception to the two preceding rules: Links synchronizer prefers to use links between an added list of issues, even if they are older than others.
- Unused links are deleted during incremental synchronization and ignored during Import or manual Resync.

Activity Stream

By default, changed made to links by the Link Synchronizer are not written to the activity stream, because doing so may affect Jira performance.

If you want these actions to be written to the activity stream, please perform the following steps:

Add a new Jira startup system property: -Dstructure.bulkLinkProcessor.useLinkManager=true
This page describes how to add JIRA startup properties.
Restart Jira