Page tree

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

Skip to end of metadata
Go to start of metadata
JIRA Agile (GreenHopper) Synchronizer lets you synchronize the position of issues in the structure and on an Agile board (such as a Scrum or Kanban board) using Rank synchronization, and synchronize an Epic field with the position of stories under epics in the structure.
JIRA Agile Synchronizer Parameters

Choose mode of operation (GreenHopper/JIRA Agile 6.1+ only):

  • Use Agile Board configuration (this feature is available only with JIRA Agile/Greenhopper 6.1+)
  • Use custom projects and fields configuration
 Agile Board mode (GreenHopper/JIRA Agile 6.1+ only) parameters:
Agile BoardJIRA Agile board to synchronize with. The issues matching Board query will be synchronized. The structure may contain other issues, they will not be affected. If Ranking is turned on by ORDER BY clause in the query, it can be used for synchronization.
Synchronize EpicsIf checked, epics will be synchronized with JIRA Agile epics.
Synchronize RankIf checked, and Ranking is enabled for Agile Board, it will be synchronized with Structure. For the details on the Consecutive and Independent ranking options please read below.
 Custom issue set mode and GreenHopper 6.0 and earlier parameters:


A project that JIRA Agile is used in. The structure may contain issues from other projects, they will not be affected. Multiple projects may be selected. The issues from all selected projects will be synchronized using the same Global Rank field.

Rank Field

The field of type "Rank" (managed by JIRA Agile) that holds the rank (backlog order) for the selected Project. If you do not wish to synchronize rank, select Don't synchronize.

Epic Field

The field holding the Epic that the story belongs to.

  • If you use epics on the Scrum boards in GreenHopper 6.1 and up, select "Scrum Board Epics" as the Epic field to synchronize them.
  • If you use the Classic Planning Board, pick the appropriate custom field of type "Labels", which is typically named "Epic/Theme".

    The synchronizer allows to select an Epic/Theme field even if it is applicable only to some of the available issue types. When the synchronizer should set a value to an Epic/Theme field, it will not make a change if the field is not applicable to the issue type of the changed issue.

  • If you do not wish to synchronize Epics content, select Don't synchronize.

Epic Type

Relevant only if an Epic Field is selected. Defines an issue type that is treated as Epic - typically named "Epic". All issues placed under an issue of this type in the structure will be updated to have Epic Field point to that issue.

Auto-add Subtasks

When turned on, sub-tasks will be automatically added to the structure and forced to stay under their respective parent issues. This works similarly to Sub-Tasks Synchronizer.

This synchronizer supports both Import and Export / Resync into/from Structure (more about resync). Incremental synchronization watches both structure changes and JIRA Agile's changes and applies the change to the other side.

CAREFUL! Please be careful when using this synchronizer, especially when you add multiple issues to the Structure, as this may lead to massive updates in the Agile ranks without undo.

JIRA Agile Synchronizer Rules

Common Rules
  • Issues that do not belong to the synchronized project(s) are not affected.
  • This synchronizer does not automatically add epics to the structure. You can use Filter synchronizer together with JIRA Agile synchronizer to automatically add epics.
  • Whether this synchronizer automatically adds stories or not, depends on your setup: 
    • if you select synchronization by an Agile Board, stories will be automatically added and placed under the corresponding epics. 
    • if you select synchronization by a project, stories will not be automatically added to the structure. To automatically add them, you can use Filter synchronizer.  
Sub-Tasks Synchronization
  • With Auto-Add Subtasks mode on, sub-tasks are added to the structure if their parent is in the structure.
  • The sub-tasks are forced to stay under their parent, so if you move a subtask somewhere else, it will jump back under the parent again. You can rearrange the order of the sub-tasks, which will be sync'ed to the Agile Rank if the Rank Field is configured.
Epic Synchronization
  • Placing an issue under an Epic in the structure will cause its Epic field to change to that Epic.
    • It does not matter at what level of depth is the sub-issue. A sub-sub-sub-issue of an Epic issue will also have its Epic field updated.
  • If you move an issue in the structure so that it's not under any epic, its Epic field will be cleared.
  • If you manually change Epic field (using JIRA Agile UI or otherwise) to point to a different Epic, the issue will be repositioned under that Epic in the structure.
    • An issue that has the Epic field pointing to an Epic in the structure will be automatically added to the structure.
  • If you clear Epic field or change it to point to an epic that is not in the structure, the issue will be moved up in the structure until it is no longer under any epic.
Rank Synchronization

Independent Ranking
Independent ranking is selected by default and in most cases is preferable as in this case the synchronizer updates issues rank the same way Agile board does.

  • On the Agile board you can arrange your Epics separately from your Stories and changing the order of Epics will not affect the order of Stories. The same will happen when you move issues in the structure.
  • When you move an Epic together with its Stories in a structure, only the Epics order changes to reflect this move. The order of the Stories is not updated.
  • If in your structure you have Epics or Stories arranged into a hierarchy of more than two levels (for example, you are using some Stories for grouping other Stories), the same logic will apply. Moving a Story that has other Stories under it, will only affect the order of Stories that are on the same level as this grouping Story and are under the same Epic.

Consecutive Ranking
Consecutive ranking was the only option in Structure 2.9 and older and has a few limitations, which may be useful in some scenarios, but can also be inconvenient, when used together with Epic synchronization.

  • With this option selected the rank of the Stories is updated, when their Epic is moved. For example, when you move an Epic with its stories above another Epic in the structure, the Stories are moved too and are placed above the Stories of the other Epic on the Agile board.
  • This may be convenient, when you want to change the priority of the Stories, whenever the priority of an Epic is changed, but this does not allow you to order Epics and Stories independently.
  • Also this means, that if you try to move a Story in the backlog of an Agile board above a Story from another Epic, this change will be reverted as this would require moving this story under another Epic in the structure.
How to Add Issues to Structure Sync'ed with JIRA Agile

When JIRA Agile synchronizer is enabled, it automatically updates Agile order in background when any Structure change happens. So if you carelessly add issues from the sync'ed project to the structure in some random order, their ranks will be updated according to that order.

To add issues to the structure without breaking the existing backlog order:

  • If adding manually on the Structure Widget, use JQL search and add order by Rank clause at the end of the query. Use the rank field that is used by the synchronizer. 
  • Select the position of the added issues carefully (best with drag-and-drop or copy/paste) - the order is likely to change unless you place issues under another issue without any other sub-issues (see Syncing Partial Orders below).
  • If using Saved Filter synchronizer to add issues, add order by Rank clause to the Saved Filter's query. However, the new issues that are added with the Saved Filter synchronizer will appear at the end of the structure and so will have the lowest ranking.