Hold an Issue, Seek Clarification, Then Proceed

In this recipe, you will learn how to sidetrack an issue from the overall workflow in order to put it on hold; this can represent a blocked status where an external problem must be resolved before proceeding, or a scenario where clarification is needed before work can continue. 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!

Alternately, you could use this setup to hide an issue from your Kanban board by setting up the “on hold” status under a status that is not included in the board (for example, a status under the To Do category).

This setup can be used for a variety of scenarios. For example:

Requesting more information before continuing work (this Recipe)
Blocking an issue that cannot proceed, for any reason
Pausing work on an issue that needs to be delayed, reassigned, or moved to a future sprint

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 Waiting for Clarification - the “on hold” status.
All ingoing transitions to Waiting for Clarification use the same transition - a transition named Request Clarification).
Outgoing transitions from Waiting for Clarification 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 labelled differently, or you may have additional statuses that need to be connected to the “on hold” status. Or 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 status.

You are viewing the documentation for Jira Cloud.

Requirements

Jira Administrator login
Jira Misc Workflow Extensions for Jira Cloud
An updated workflow that includes an on-hold status such as Waiting for Clarification (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 recipe uses a standard short text custom field and a post-function that creates a concatenated field 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 Waiting for Clarification:

In Progress → (Transition) Request Clarification → Waiting for Clarification

The return transition from Waiting for Clarification 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:

Waiting for Clarification → (Transition) Return to In Progress → In Progress

Workflow configuration

Consider the workflow shown in Figure 1, right.

Waiting for Clarification is a status available to several points in the workflow - specifically to any status under the In Progress category (blue status nodes in the workflow). This configuration was chosen because at any point in the development process it may be necessary to sidetrack an issue while waiting for clarification on questions or problems.

1. Create custom field for tracking original 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 issue from a hold.

Log into your Jira Server 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

To edit a workflow:

Log into your Jira Server instance as an Administrator.
Click on the Settings icon ⚙️ in the upper right corner.
Select Issues.
In the left-hand panel, click Workflows.
Click Actions ( ) for the workflow you want to edit and select Edit.

3. Add Waiting for Clarification status and transitions

In the following section you will add the Waiting for Clarification 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: https://support.atlassian.com/jira-cloud-administration/docs/configure-statuses-resolutions-and-priorities/.

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 Waiting for Clarification, and click Add.
In the upper-left hand corner of the workflow editor, click Add Transition
On the New Transition tab (Point 1, Figure 3, right), set the following options (Point 2, Figure 3, right):
1. From status - Select In Progress.
2. To status - Select Waiting for Clarification.
3. Name - Enter “Request Clarification”.
Add the Request Clarification transition from Code Review to Waiting for Clarification. In the Add Transition window, select the Reuse a Transition tab and select Request Clarification.
Add the Request Clarification transition from Testing to Waiting for Clarification. In the Add Transition window, select the Reuse a Transition tab and select Request Clarification.
Repeat Step 4, above, to add a transition from Waiting for Clarification to In Progress. Name the transition “Return to In Progress”.
Repeat Step 4, above, to add a transition from Waiting for Clarification to Code Review. Name the transition “Return to Code Review”.
Repeat Step 4, above, to add a transition from Waiting for Clarification to Testing. Name the transition “Return to Testing”.

4. Add a Set issue fields post-function to the “Request Clarification” 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 Waiting for Clarification status.

In your workflow, add a post-function to the Request Clarification transition:
1. 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.
2. 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:
1. Target issue(s) (Point 1, Figure 4, right) - Set to Current issue.
2. Add field(s) (Point 2, Figure 4, right)- Select Return Transition.
3. Options - Leave all options unchecked.
4. Value (Point 3, Figure 4, right) - Enter {{ ["Return to ", transition.from_status] | join }}
5. Click Add (Point 4, Figure 4, right).
6. Send notifications - Configure as needed.
7. Conditional execution - Configure as needed.
8. Run as - It is recommended to leave this set to Addon user.
9. Delayed execution - Configure as needed.
Click Add.

5. Add a 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:
1. 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.
2. 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.
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.