Child pages
  • Status Rollup Synchronizer

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

Skip to end of metadata
Go to start of metadata

Status Rollup synchronizer automatically aggregates statuses of the sub-issues and updates the status of the parent issue. For example, it can make parent issue Resolved if all sub-issues are Resolved.

Status Rollup Synchronizer Parameters

Enabled Projects

Only issues belonging to the selected projects are changed. It does not matter what project sub-issues belong to, as long as their parent belongs to the enabled project — every sub-issue counts with its status.

Enabled Issue Types

Same with types — you can select issues of which types may be changed by the synchronizer, and like with the enabled projects, only the parent issue type is checked.

Statuses Rolled Up

The selection and order of statuses that are used to calculate parent issue status. Parent issue status is set to the earliest status among its sub-issues. If a sub-issue has a status not selected in this parameter, the parent issue is not changed.

Allowed Transitions

For every status, you can select which transitions can the synchronizer make to move an issue to that status.

Resolution

Value to set to the Resolution field when workflow transition requires it. By default, a current or default value for Resolution is used.

The synchronizer is normally installed, resynced and used in the Incremental mode, tracking changes to issues and structure and updating issues. The synchronizer supports Exporting from Structure, changing statuses of the issues in the structure on one-time basis.

How Status Rollup Synchronizer Works

The synchronizer tracks updates to issues and to structure, and tries to make sure that the status of the parent issue corresponds to the aggregate status of its direct children.

When you configure Status Rollup, the most important parameter is the selected Statuses and their order:

Statuses that are not selected in the parameters are not recognized by the synchronizer. If a sub-issue has one of the unselected statuses, the synchronizer does not change the parent issue.

The order of the selected statuses should correspond to earliest-to-latest order of phases of the workflow. For example, the screenshot above shows configuration where Open is followed by Resolved, which is followed by Closed. With that configuration, once all sub-issues of an issue are Resolved, the synchronizer will try to make the issue Resolved too. Once all sub-issues are Closed, the issue will be made Closed. But if at least one sub-issue happens to be Open, the issue status will be set to Open — because it is the earliest status in the specified order.

On the screenshot above:

  • All sub-sub-issues and sub-issue 1 do not have sub-issues of their own, so the synchronizer does not change their status.
  • Sub-issue 3 has a single sub-issue, which has status Closed — so since all of its sub-issues are closed, it should be Closed too.
  • Sub-issue 2 has one Open sub-issue and one Resolved sub-issue — it should be Open because Open status comes before Resolved in the order specified earlier.
  • Parent Issue has sub-issues that have statuses Open, Resolved and Closed — so it should be Open for the same reason. Once all sub-issues are Resolved, Parent Issue will be automatically Resolved. Once all sub-issues are Closed, Parent Issue will automatically be Closed.

Remember, that whenever one of the sub-issues gets a status not listed in the synchronizer configuration, the synchronizer just skips the issue. For example, if we change the status of Sub-issue 2 above to In Progress, Parent Issue will not be updated. If we then change the status of Sub-issue 2 to Resolved, Parent Issue status will be updated to Resolved.

How Status is Changed

JIRA allows status to be changed only through a workflow transition, so the only way Status Rollup synchronizer can set the desired status on an issue is to apply a workflow transition. Therefore, when you select a status, you also need to select which transitions is synchronizer allowed to make.

So what the synchronizer does is:

  1. See what status does the issue currently have;
  2. Calculate what status should it have, based on the statuses of sub-issues;
  3. Find workflow transitions that can transfer the issue from the current status to the required status;
  4. Check which of those transitions are allowed by the configuration;
  5. Try to apply matching transition number one, if it fails - try the next one, and so on.

Note that all transitions are done under the account of the user who has installed the synchronizer.

Why Can a Workflow Transition Fail

It's not guaranteed that the synchronizer will be able to change the Status, because workflows are too flexible and there are many reasons that a given transition, which you have allowed in the configuration, can fail to execute. Here's some of the possible causes:

  • You (the user who has installed the synchronizer) do not have the required permissions to make the transition;
  • You are not the Assignee of the issue — required for In Progress status;
  • Some other pre-condition defined in the workflow fails;
  • Workflow transition requires a field to be set on an issue that has no default value.

As described above, it's possible that there are several possible transitions from one status to another. The synchronizer will try all of them unless one of them succeeds.

If the synchronizer fails to update the status, a warning message will be written into the server logs (subject to logging configuration).

Changing Resolution

You can set up a specific Resolution value to be set whenever a transition involves changing the resolution. If you don't specify this parameter, the default resolution or already existing resolution will be used.

In order to tell which issues have been automatically moved to a status like Resolved or Closed, you can set up a special resolution like Auto-Resolved.

Manually Changing Status of an Issue That Has Sub-Issues

Even if an issue has sub-issues and is subject to Status Rollup, you can manually change its status. Although the synchronizer will not be forced to recalculate the status of that issue immediately, it will recalculate the status if any of the sub-issues change – probably reversing your change, if it finds an allowed transition.

If you'd like the synchronizer to only move issues forward, that is, from Open to Resolved, but not vice versa, you can configure the allowed transitions accordingly.