Filter 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 Filter Synchronizer automatically adds issues to a structure or removes issues from a structure based on a Saved Filter or a JQL query.
This powerful synchronizer lets you control the contents of the structure with an issue filter (either a Saved Filter or an arbitrary JQL Query). It can be configured to automatically add or remove issues from a structure, or both.
Filter Synchronizer Parameters
Filter | This is where you determine the Saved Filter or JQL Query to sync with. Click Select to choose a saved filter or switch to JQL query and enter the JQL. When this synchronizer is enabled and runs in background, it "listens" to Jira events about issues being changed. If the result of a query change without an issue being changed, the synchronizer will not detect the change and will not update the structure - for example, if you use JQL query |
Add | Turns on Add Mode: the synchronizer will make sure that all issues from the filter's result are present in the structure. |
Place added issue at the top level | If this is selected, the newly discovered issues from the filter result are placed at the top level, at the end of the structure. |
Place added issue as a sub-issue of ... | Allows you to selecte an issue key (like PROJECT-123) of an issue that will serve as the parent for any newly discovered issues from the filter. These new issues will be placed as children of the selected issue, at the end of the current children list. If the specified issue is not present in the structure, newly discovered issues will not be added to the structure. |
Allow move | This option is only available if you select the "Place added issue as a sub-issue of..." option. This tells the synchronizer what to do if a matching issue is already added to the structure but located under a different parent issue. If the option is on, the synchronizer will move the issue (with all its possible sub-issues) under the specified parent issue. If the option is off, the issue will be left alone where it now resides. |
Remove | Turns on Remove Mode: the synchronizer will remove issues from the structure when they no longer are present in the filter result. However, if an issue to be removed contains sub-issues that should stay in the structure, it will not be removed. CAREFUL! If Remove mode is enabled and another synchronizer is adding issues (for example, a Sub-tasks synchronizer), it could result in an endless cycle. Structure has safeguards in place to protect against this, but it is best practice to avoid this situation whenever possible. See Protection from Synchronizer Cycles for more details. |
Remove only from where added issues are placed | Additional flag to remove issues only if they are either at the top level or under the issue where they were initially placed by the synchronizer. If this option is enabled, and you move an automatically added issue somewhere else, it will not be removed, even if it is no longer present in the search result. |
This synchronizer only supports Import / Resync into Structure (more about resync).
If the Saved Filter used in the configuration is later deleted, or if you lose permissions to run it, the synchronizer will not work.
No matter how synchronizers are configured, they will only affect issues from the projects that are enabled for synchronization.
Filter Synchronizer Rules
- The synchronizer adds issues from its filter's result to structure and/or removes issues that no longer are in the filter's result.
- Whenever an issue changes, a query is run to see if it matches the filter. On resync, all issues are checked.
- With Add mode on, an issue will be added to the structure if it matches the filter - even if the user has manually removed it from there. If the issue is already in the structure, it will not be affected, unless Allow Move is on - in which case it will be relocated under the specified parent issue.
- With Remove mode on, an issue will be removed from the structure if it does not match the filter - even if a user manually added it to the structure.
- When adding issues on Resync or Import, the synchronizer places them at the end of the structure (or under the specified parent issue), in the order that corresponds to the filter's order. However, if only part of the filter result is added (for example, because other issues are already in the structure), the final sequence of issues may be different from the filter result.