Building a review process with Jira Automation

 In this tutorial, you’ll learn how to use Jira Automation to build a review cycle into your Jira Cloud workflows, so that you can implement a compliant review process without the overhead of third-party apps and electronic signatures. You’ll find this feature helpful for bug triage, design reviews, and anywhere else an audit-ready review process required.

Configuration Steps

Note:  These instructions are written for company-managed projects.  Currently, team-managed projects do not support the read-only text fields used in these configurations.

Custom User Groups

Create a custom user group for each reviewer role that will be added to your review cycle.  (For example: ‘business-reviewers‘ and ‘technical-reviewers‘.)  The groups will be used to drive notifications and restrict transitions.

1. Go to Settings –> User Management –> Groups
2. Select Create Group.
3. Configure the new group:
   1. Group name:  Give the group a descriptive name
   2. (Optional) Group members:  Populate the group with an initial list of members
   3. (Optional) Group description:  Create a useful description.  Indicate the group is used to assign review permissions to users.
4. Repeat Steps 2 and 3 for each role that will be added to your review cycle.

Custom Fields

Create custom fields to capture the reviewer and timestamp details for each review task.

1. Go to Settings –> Issues –> Custom fields.
2. Select Create custom field.
3. Select Advanced –> Text Field (read only).
4. Press Next.
5. This field will contain name and user ID of the person completing the approval.  So give the field a name that indicates the meaning of the electronic approval you are implementing.   For example:  Business Reviewer, Technical Reviewer, QA Reviewer, etc.
6. (Optional) Provide a field description.
7. Press Create.
8. Select the issue types screens where this field should be displayed.
9. Press Update.
10. Repeat Steps 2 through 9 to create a corresponding timestamp field.  Give the field a name that corresponds with the name given to the first field.  For example:  Business Reviewed, Business Reviewed On, etc.
11. Repeat the above steps for each additional review role that will be added to your review cycle.  When you are finished, you should have two (2) fields for each review task.

Create a Comments Screen

1. Go to Settings –> Issues –> Screens.
2. Select Add screen.
3. Name the screen: Prompt for Comments Screen
4. (Optional) Provide a screen description.
5. Press Add.

Note:  No further configuration is necessary.  This screen will not contain any fields; it will only contain the default Add Comments section provided by Jira.

Workflow Configurations

Open Workflow for Editing

1. Go to Settings –> Issues –> Workflows.
2. Select to edit the workflow where you want to add the review cycle.

Add Statuses & Transitions

1. In Diagram view, insert a Pending Review status.   (Select to create a new status as needed.)
2. After the Pending Review status, insert a status for each review task.  For example: “Business Reviewed’ and “Technical Reviewed”.  (Select to create new statuses as needed.)
3. Create the following transitions.  Tailor the list of transitions to match the names and number of review tasks in your review cycle:
   1. Submit for review:  [Prior status] –> Pending Review
   2. Complete business review:  Pending Review –> Business Reviewed
      • Screen:  Prompt for Comments Screen
   3. Complete technical review:  Pending Review –> Technical Reviewed
      • Screen:  Prompt for Comments Screen
   4. Cancel review:  Pending Review –> [Prior status]
   5. Continue review cycle:
      1. Business Reviewed –> Pending Review
      2. Technical Reviewed –> Pending Review
   6. Complete review cycle:
      1. Business Reviewed –> [Post-review status]
      2. Technical Reviewed –> [Post-review status]

This is an example of a completed workflow.  Note that in this example “Initial Triage” is the prior status, and “To Do” is the post-review status.  The names of your statuses will likely differ.

Configure Transition Conditions

1. Select to view the properties of the first transition from Pending Review to a review task status.  (For example:  Pending Review –> Business Reviewed)
2. Select Conditions.
3. Select Add condition.
4. Select User is in group.  Press Add.
5. Select the user group that corresponds with the current review task.  (For example:  business-reviewers)
6. Press Add.
7. Repeat Steps 1 through 6 for each of the remaining review task transitions.  (For example:  Pending Review –> Technical Reviewed)
8. Select to view the properties of the first transition from Pending Review to the post-review status.  (For example:  Pending Review –> To Do)
9. Select Conditions.
10. Select Add condition.
11. Select Hide from user condition.
12. Press Add.
13. Repeat Steps 8 through 12 for each of the remaining transitions out of Business Reviewed, Technical Reviewed, etc.
14. When you are finished, only users in each reviewer group will be able to transition from Pending Review to reviewed, and only Jira Automation will be able to transition from reviewed back to Pending Review or forward to the post-review status.

Configuring Jira Automation

1. Navigate to your project.
2. Go to Project Settings –> Automation. 
   
   (Note: If you have Jira Premium, you can go to Settings –> System –> Global Automation.)

Configure Rule — Notify Reviewers

1. Select Create rule.
2. Under New Trigger, select Issue transitioned.
3. Configure the From status and To status to match the transition from the pre-review status into Pending Review
4. Press Save.
5. Select to add a New action.
6. Under New Action, select Send email.
7. Configure the email:
   1. To:  Select the first review group that should be notified.
   2. Subject:  Configure a meaningful subject.  Consider using Jira Smart Values.  For example:
      Bug {{issue.key}} is pending technical review
   3. Content:  Configure helpful content.  Consider using Jira Smart Values, especially issue.url for embedding a hyperlink to the issue in Jira.  For example:
      The following bug is ready for technical review:{{issue.key}}: {{issue.summary}}{{issue.description}}{{issue.url}}
8. Press Save.
9. Repeat Steps 5 through 8 for each email notification that should be sent.  (Typically, one per reviewer group.)
10. Provide a name for your new automation.  For example, “Notify Reviewers“.
11. Press Turn in on.
12. Select Return to list.

 Here’s an example of a completed notifications rule:

Configure Rules — Set Reviewers

1. Select Create rule.
2. Under New Trigger, select Issue transitioned.
3. Configure the From status to be blank and the To status to one of your reviewed status (ex:  Business Reviewed).
4. Press Save.
5. Select to add a New action.
6. Under New Action, select Edit issue.
7. Select to edit the two review info fields associated with the current status (example:  Business Reviewer and Business Reviewed).
8. For the user name and ID field (ex: Business Reviewer), enter the following value (learn more):
   {{initiator.displayName}} (ID: {{initiator.emailAddress}})
9. For the timestamp field (ex: Business Reviewed), enter the following value (learn more):
   {{now.longDateTime}}
10. Press Save.
11. Select to add a New condition.
12. Under New condition, select lf / else block.
13. Configure the If block:
    1. Run actions if:  All conditions match
    2. Conditions: 
       1. Issue fields condition
          1. Field:  Technical Review (for example)
          2. Condition:  does not equal
          3. Value:  —
       2. Add additional field conditions for any other reviewer fields (if you have more than two reviewers in your review cycle).
    3. Press Save.
14. Select to add a New action to the If block.
15. Select the Transition issue action.
16. Select the post-review status (ex:  To Do) as the Destination status.
17. Press Save.
18. Select to add a New action to the else block.
19. Select the Transition issue action.
20. Select Pending Review as the Destination status.
21. Press Save.
22. Provide a name for your new automation.  For example, “Set Business Reviewers“.
23. Press Turn in on.
24. Select Return to list.
25. Repeat Steps 1 through 24 for each review task in your review cycle.

 Here’s an example of a completed notifications rule:

Configure Rule – Clear Reviewers

1. Select Create rule.
2. Under New Trigger, select Issue transitioned.
3. Configure the From status to be blank and the To status to match pre-review status (for example: Initial Triage).
4. Press Save.
5. Select to add a New action.
6. Under New Action, select Edit issue.
7. Select to edit all the reviewer fields by setting them to:  —
   1. Example: 
      1. Business Review:  —
      2. Business Reviewed:  —
      3. Technical Review:  —
      4. Technical Reviewed:  —
   2. Note:  Due to a limitation of Jira, you cannot clear these fields with an empty string or null value.  You must specify a non-zero-length string, or the automation will fail to update the field.
8. Press Save.
9. Provide a name for your new automation.  For example, “Clear Reviewer Fields“.
10. Press Turn in on.

Here is an example of a completed rule:

Related Tutorials

• Creating Workflow-based Approvals using Jira Automation

More Information

Find more strategies like this in my Quick Start Guide for Jira Cloud:  https://www.agile-innovations.tech/part-11

For more information about Jira automation, checkout Atlassian’s documentation:   

• Jira Cloud automation: https://support.atlassian.com/cloud-automation/docs/jira-cloud-automation/
• Smart values:  https://support.atlassian.com/cloud-automation/docs/smart-values-in-jira-automation/