Hold an issue, proceed when clear
- Daniel Barrow
Goal | Place an issue on hold, and return it to its original status when ready |
|---|---|
Scenario | You need to place issues in a holding status ('Blocked', for example) when work can not proceed. Additionally, when work is ready to restart you need to guarantee that the issue returns to its original status before being placed on hold. |
Components | Set issue fields post function, Build-your-own (scripted) condition |
Baseline |
|
This setup can be used for a variety of scenarios. For example:
Blocking an issue that cannot proceed for any reason (this use case)
Requesting more information before continuing work
Pausing work on an issue that needs to be delayed, reassigned, or moved to a future sprint
Alternatively, you could use this setup to hide an issue from your Kanban board by setting up the “on hold” status value under a status that is not included in the board.
In this example, the workflow is configured so that:
Only statuses that are in the In Progress category (blue status nodes in Figure 1, below) have transitions to a status labeled Blocked - the “on hold” status.
All incoming transitions to Blocked use the same transition - a transition called Blocked.
Outgoing transitions from Blocked use the formula “Return To” and the name of the original status (e.g. “Return to In Progress”)
In your Jira instance, the status values may be labeled differently, or you may have additional statuses that need to be connected to the “on hold” status. You may have multiple “on hold” status values (such as both Blocked and Waiting for Clarification). If you have different values, just substitute your status values in the steps below. If you need more than one “on hold” status, just repeat the steps below for each holding status.
You are viewing the documentation for Jira Cloud.
On This Page |
|---|
Requirements
Jira Administrator login
An updated workflow that includes an on-hold status such as Blocked (Figure 1, right), or a workflow that can have this status added.
Note: The configuration requires a custom field that will store the name of the transition that should be used when the issue leaves the “on hold” status. This use case uses a standard short text custom field and a post function that creates a concatenated value that enables transition names to be more clear. For example, you will create a standard transition from the In Progress status to the hold status Blocked:
In Progress → (Transition) Blocked → Blocked
The return transition from Blocked to In Progress uses the original status value of “In Progress” to store a transition name that will return the issue to its original status:
Blocked → (Transition) Return to In Progress → In Progress
Workflow configuration
Blocked is a status available at several points in the workflow - specifically to any status under the In Progress category (blue status nodes). This configuration was chosen because, at any point in the development process, it may be necessary to sidetrack an issue while waiting for the resolution of questions or problems.
1. Create a custom field for tracking return status
Before updating your workflow, you need to add a custom field to your Jira instance; this custom field will store the name of the transition that should be used when removing the hold from an issue.
Log into your Jira instance as an Administrator.
Click on the Settings icon in the upper right corner.
Select Issues.
In the left-hand panel, click Custom fields and click Create custom field in the upper right corner.
From the list of Standard fields, select
Short text (plain text only). Click Next.For the name, enter “Return Transition” (Figure 2, right). Enter a description if desired.
Click Create.
Associate the custom field with any screens that are used in the workflow being updated.
Click Update.
2. Open the workflow
3. Add Blocked status and transitions
In the following section you will add the Blocked status, if it does not already exist. Additionally, you will add all necessary transitions to and from this status. If you need to create an new status, see this page: Configure statuses, resolutions, and priorities | Atlassian Support.
Open your workflow using the steps above, then follow these steps:
In the upper-left hand corner of the workflow editor, click Add Status.
Select Blocked, and click Add.
In the upper-left hand corner of the workflow editor, click Add Transition
On the New Transition tab, set the following options (Figure 3, right):
From status - Select In Progress.
To status - Select Blocked.
Name - Enter “Blocked”.
Add the Blocked transition from Code Review to Blocked. In the Add Transition window, select the Reuse a Transition tab and select Blocked.
Add the Blocked transition from Testing to Blocked. In the Add Transition window, select the Reuse a Transition tab and select Blocked.
Repeat Step 4, above, to add a transition from Blocked to In Progress. Name the transition “Return to In Progress”.
Repeat Step 4, above, to add a transition from Blocked to Code Review. Name the transition “Return to Code Review”.
Repeat Step 4, above, to add a transition from Blocked to Testing. Name the transition “Return to Testing”.
4. Add a Set issue fields post function to the Blocked transition
In this section you will add a JMWE post-function to the Request Clarification transition. The Set issue fields post function will update the issue being transitioned with the name of the transition that should be used when moving the issue out of the Blocked status.
In your workflow, add a post function to the Blocked transition:
When viewing the Workflow in Diagram view, select the Transition and click the Post Functions link. Click Add post function at the top of the list of existing post functions.
When viewing the Workflow in Text view, click the name of the Transition then select the Post Functions tab. Click Add post function at the top of the list of existing post functions.
Select Set issue fields (JMWE app) from the list and click Add.
Configure the post function as follows:
Target issue(s) (Point 1, Figure 4, right) - Set to Current issue.
Under Fields to update click Add (Point 2, Figure 4, right).
For Field, select Return Transition (Point 3, Figure 4, right).
New Value (Point 4, Figure 4, right) - Enter the following script:
{{ ["Return to ", transition.from_status] | join }}Click Add (Point 5, Figure 4, right).
Additional options - Leave blank.
Click Add.
5. Add a Build-your-own (scripted) Condition to each outgoing transition
The last step in this configuration is to add a condition to each of the outgoing transitions from Waiting for Clarification. These conditions will guarantee that only the transition back to the original status is available.
In your workflow, add a condition to the Return to In Progress transition:
When viewing the Workflow in Diagram view, select the Transition and click the Conditions link. Click Add condition at the top of the list of existing conditions.
When viewing the Workflow in Text view, click the name of the Transition then select the Conditions tab. Click Add condition at the top of the list of existing post functions.
Select Build-your-own (scripted) Condition (JMWE app) from the list and click Add.
Give your condition a description, if desired.
Under Choose type select Jira Expression.
In the Jira Expression editor (Figure 5, right), click the Issue Fields tab of the Help section (Point 1, Figure 5, right).
From the Select a field pulldown menu (Point 2, Figure 5, right), select Return Transition.
Click the first box under Testing the field’s value (Point 3, Figure 5, right) to insert the code into the editor.
Replace
"A string"with"Return to In Progress".Click Add.
Repeat steps 1 through 7 for the Return to Code Review and Return to Testing transitions, replacing
“A string"in the code editor with the name of the transition.
Congratulations!
You can now place issues in a holding status while awaiting resolution or information from outside your team. Because Jira does not natively support Blocked issues, the addition of an “on hold” status can be a powerful tool, especially when combined with dedicated columns or swimlanes in your Kanban board. This can provide distinct visual cues to the issues that require attention!
