Page tree

This documentation relates to an older version 2.10 of the Structure Plugin for JIRA. View the current documentation home.

Skip to end of metadata
Go to start of metadata

Links Synchronizer maintains issue links between parent issue and children 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.

Links synchronizer is available only when Links are enabled and there's 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 the change to the other side (unless Reverse contradicting changes option is specified, see below).

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

When synchronizer adds or removes JIRA issue links, it has the same permissions as the user that installed the synchronizer.

Links Synchronizer Parameters
Link Type

The type of the 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, as if it didn't exist.
    In particular, if there are two issues that belong to the structure and pass the corresponding filters, and 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.


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 is 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.


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.


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.

Please note that this option does not apply during Export, Import or manual Resync.

Links Synchronizer Preserves Links Between Added List of Issues

There is a special case: when a list of 2 or more issues is added to the structure, links between these issues are preserved, and they form a hierarchy according to these links. Such a situation may arise, for example, when searching outside the structure and moving a bunch of issues into the structure.

This differs from the default behaviour when 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 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 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 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.