Creating a Custom Workflow

Customised workflows are one of the key features within JIRA. Yet I often hear users mention that JIRA workflows are complex to implement and hard to understand. A lot of this sentiment stems from the sheer flexibility of JIRA's workflow functionality. As a JIRA QA Engineer, I can vouch that once you know how to use JIRA workflows, you will love them.

Creating a customised workflow allows JIRA to reproduce specific internal processes. At a very high level, workflows can be customised for different projects and issue types. You could for example have 'Support Requests' follow one custom workflow while 'Feature Requests' follow an entirely independent workflow. In this tutorial, I will be creating a copy of the default workflow of JIRA and customising it by adding some steps to it.

Whenever you implement a new customised workflow, it is always best to start by creating a visual representation of your workflow, ideally in the form of a flowchart. I am going to do this using Confluence, together with a diagramming plugin called Gliffy. You can see the flowchart I created here:

As you may have picked up, the workflow I am creating is for use in a software development team. In this example, I want to ensure that once development has checked-in their code, then we can conduct a 'Technical Review' (for conducting a code review in this case), and then move on to a 'Quality Review' (for testing by the quality assurance team). These are both going to be new steps within the existing default JIRA workflow.

Ensuring you have JIRA Administration privileges, head over to the JIRA Administration tab. Here you will see links to 'Workflows' and 'Workflow Schemes'. 'Workflows' let you define specific workflows whereas 'Workflow Schemes' allow you to map one or more specific workflows to certain issue types and in turn to certain projects.

To demonstrate the power of JIRA, I'm also going to add in some custom screens to display specific fields (including custom fields) within specific stages of the workflow. The tasks that I am going to focus on are:

• Add Custom Field: I'm going to add a custom field allowing us to select a specific user or 'Tester' to conduct our Quality Review.
• Add a Custom Screen: I'll create a new screen to ask users to select a user as the Tester, displaying the 'Tester' custom field we are adding.
• Add New Status: To reflect the new statuses our issue can be in, I'll add a status for 'Technical Review' and another for 'Quality Review'.

Step 1: Add Custom Field

Let's add our own customised 'User Picker' field called 'Tester' to allow us to select a specific person for testing in the QA step.

Click the 'Custom Fields' option under 'Issue Fields' in the 'Administration' tab.

Create a new custom field of type 'User Picker' and provide a 'Field Name' of 'Tester'. Leave other fields at their displayed defaults and click on 'Finish'. When presented with the 'Associate field Tester to screens' page, just click on 'Update' — do not select any screens at this stage (we're going to add a new screen in the next step). Let's repeat that process exactly but this time name this 'User Picker' custom field 'Reviewer'.

Step 2: Add New Screen:

We can now configure JIRA to create a screen for displaying our new field.

Click on 'Screens' link under "Issue Fields" in the JIRA Administration area.

Towards the bottom of the Screens page, within the 'Add Screen' dialog, specify a new screen named 'Assign to QA' and 'Add' it.

Now 'Assign to QA' is added in the screen list. Now click 'Configure' for that screen in the right most column named 'Operations'.

You will now be presented with the 'Configure Screen' page. Under 'Add Field', multi-select the fields named 'Fix Version' & 'Tester', and click 'Add'.

Repeat this process, specifying a new screen named 'Assign for Technical Review', configured to display the fields 'Fix Version' & 'Reviewer'.

Step 3: Add New Status:

We'll now add two new statuses that our issues can move through in our new workflow.

Click on 'Statuses' under 'Issue Settings' and 'Add new status' named 'Technical Review'. If you wish, you can change the icon for the new status by clicking on 'select image'. Let's repeat the process for our second status, this time, 'Add new status' named 'Quality Review'.

Step 4: Workflows:

We have now completed all the prerequisites for my workflow. We'll now create the new workflow that will incorporate all the changes we have made so far.

It's recommended, especially for new students of JIRA workflow configuration, that you copy an existing workflow and then start editing it, rather then creating one from scratch.

Click on the 'Workflows' link under 'Global Settings'. Find the jira workflow and select 'Copy' from the rightmost 'Operations' column. Edit the 'Workflow Name' to 'JIRA Quality Workflow' and edit the description to something appropriate.

We'll add two new steps, 'Technical Review' and 'Quality Review', and choose the appropriate status for each.

Click on 'Steps', again in the 'Operations' column. In the 'Add New Step' dialog, add a 'Step Name' called 'Technical Review' and select the matching 'Linked Status', 'Technical Review'. We'll repeat this process, this time adding a new step called 'Quality Review' with a matching 'Linked Status' of 'Quality Review'.

Our next step is to add/modify the transitions according to our original flowchart.

I will be adding a transition to the 'In Progress' step, to reflect the new options that will be available to a user from the In Progress step (moving to a Technical Review). While adding transitions you can specify a transition view also — a screen presented to the user when they click on a specific workflow action or 'transition'. We'll also add transitions to our 2 new steps ('Technical Review' & 'Quality Review').

For the 'In Progress' workflow, select 'Add Transition' under the 'Operations' column. Add a 'Transition Name' of 'Conduct Technical Review', leave the 'Description' field blank, specify a 'Destination Step' of 'Technical Review' and finally set the 'Transition Step' to 'Assign for Technical Review'.

Let's add two transitions for the Technical Review using these settings:

• Transition Name: More Work Required, Description: leave blank, Destination Step: In Progress, Transition View: No view for this transition
• Transition Name: Proceed to Quality Review, Description: leave blank, Destination Step: Quality Review, Transition View: Assign to QA

We'll also add two transitions for the Technical Review using these settings:

• Transition Name: More Work Required, Description: leave blank, Destination Step: In Progress, Transition View: No view for this transition
• Transition Name: Resolve Issue, Description: leave blank, Destination Step: Resolved, Transition View: Resolve Issue Screen

We'll also delete a workflow step, so you can see how that is done. Let's delete the 'Reopened' workflow step.

If you want to remove any of the steps from the workflow, you need to make sure it is not used as a transition for any other step. We'll need to remove the transitions to 'Reopened' from the 'Resolved' and 'Closed' issue steps.

Click on 'Delete Transitions' on both the 'Resolved' and 'Closed' steps and delete the 'Reopen Issue' transitions. You will now see a new 'Operation' called 'Delete Step' appear for the 'Reopened' step. Click on 'Delete Step' and confirm on the next screen by selecting 'Delete'.

Your workflow should now look like this:

Step 5: Specify Workflow Transition Conditions

Another powerful workflow feature of workflow transitions is their ability to support conditions/validators/Post Functions.

Suppose I want to add a condition that only the current assignee can move issues into 'Technical Review' or 'Quality Review'.

In the 'View Workflow Steps' of our current workflow, in the 'In Progress' step, click on the 'Conduct Technical Review' transition and click the 'Add' link on the 'Conditions' tab. Select the 'Only Assignee Condition' and click 'Add'. Go back to 'View workflow steps' and repeat this same procedure for the 'Proceed to Quality Review' transition on the 'Technical Review' step.

Step 6: Activate The Workflow

Now my workflow is ready to use — I just need to tell JIRA where I want to use it, based on the issue types and projects that I want to use this workflow in.

Workflow schemes define which issue types use what workflow. Let's configure that now.

Click on the 'Workflow Schemes' link under 'Schemes' in the JIRA Administration area. Click on 'Add workflow scheme' and add a workflow scheme named 'Software Development Workflow'.

We can now associate this workflow scheme with the relevant issue types for our 'Software Development' Project. In this case, I am going to assign this workflow scheme for use with all issues in our project. On the same Workflow Schemes page, on the 'Software Development Workflow', select 'Workflows' from the 'Operations' column. Under the 'Edit Workflows for Software Development Workflow' panel, select 'Assign a workflow'. On the next screen, under 'Add Workflow to Scheme' panel, specify the 'Issue Type' as 'All Unassigned Issue Types' and set the 'Workflow' to 'JIRA Quality Workflow'. Although in this case we are specifying the workflow for all issue types, this is where you could assign specific workflows to specific issue types.

We can now associate this issue workflow with an existing or new project. In this case, we'll create a new project. Firstly follow the steps outlined here to create your new project. Then go to the 'Projects' link under the 'Projects' section of JIRA's administration and click on the name of your new project. On the next screen, click on '( Select )' under Workflow Scheme. Next choose the 'Software Development Workflow' Scheme and finally click the 'Associate' button.

JIRA's flexible workflow engine makes almost anything possible and with great power comes great responsibility.