In this article by Patrick Li, author of the book Jira 7 Administration Cookbook – Second Edition, we will take a look at how Workflows are one of the core and most powerful features in JIRA. They control how issues in JIRA move from one stage to another as they are worked on, often passing from one assignee to another. For this reason, workflows can be thought of as the life cycle of issues.

In this article, we will cover:

• Setting up different workflows for your project
• Capturing additional information during workflow transitions
• Using common transitions
• Using global transitions
• Restricting the availability of workflow transitions
• Validating user input in workflow transitions
• Performing additional processing after a transition is executed

Unlike many other systems, JIRA allows you to create your own workflows to resemble the work processes you may already have in your organization. This is a good example of how JIRA is able to adapt to your needs without your having to change the way you work.

(For more resources related to this topic, see here.)

Setting up different workflows for your project

A workflow is similar to a flowchart, in which issues can go from one state to another by following the direction paths between the states. In JIRA’s workflow terminology, the states are called statuses, and the paths are called transitions. We will use these two major components when customizing a workflow.

In this recipe, we will create a new, simple workflow from scratch. We will look at how to use existing statuses, create new statuses, and link them together using transitions.

How to do it…

The first step is to create a new skeleton workflow in JIRA, as follows:

1. Log in to JIRA as a JIRA administrator.
2. Navigate to Administration > Issues > Workflows.
3. Click on the Add Workflow button and name the workflow Simple Workflow.
4. Click on the Diagram button to use the workflow designer or diagram mode.

The following screenshot explains some of the key elements of the workflow designer:

As of now, we have created a new, inactive workflow. The next step is to add various statuses for the issues to go through. JIRA comes with a number of existing statuses, such as In Progress and Resolved, for us to use:

1. Click on the Add status button.
2. Select the In Progress status from the list and click on Add.
   

   You can type the status name into the field, and JIRA will automatically find the status for you.

3. Repeat the steps to add the Closed status.

Once you add the statuses to the workflow, you can drag them around to reposition them on the canvas. We can also create new statuses, as follows:

1. Click on the Add status button.
2. Name the new status Frozen and click on Add.

JIRA will let you know if the status you are entering is new by showing the text (new status) next to the status name.

Now that we have added the statuses, we need to link them using transitions:

1. Select the originating status, which in this example is Open.
2. Click on the small circle around the OPEN status and drag your cursor onto the In PROGRESS status. This will prompt you to provide details for the new transition, as shown in the following screenshot:

3. Name the new transition Start Progress and select the None option for the screen.
4. Repeat the steps to create a transition called Close between the In PROGRESS and CLOSED statuses.

You should finish with a workflow that looks similar to the following screenshot:

At this point, the workflow is inactive, which means that it is not used by a project, and you can edit it without any restrictions. Workflows are applied on a project and issue-type basis. Perform the following steps to apply the new workflow to a project:

1. Select the project to apply the workflow to.
2. Click on the Administration tab to go to the project administration page.
3. Select Workflows from the left-hand side of the page.
4. Click on Add Existing from the Add Workflow menu.
5. Then, select the new Simple Workflow from the dialog and click on Next.
6. Choose the issue types to apply (for example, Bug) the workflow to and click on Finish.

After we apply the workflow to a project, the workflow is placed in the active state. So, if we now create a new issue in the target project of the selected issue type, our new Simple Workflow will be used.

Capturing additional information during workflow transitions

When users execute a workflow transition, we have an option to display an intermediate workflow screen. This is a very useful way to collect some additional information from the user. For example, the default JIRA workflow will display a screen for users to select the Resolution value when the issue is resolved.

Issues with resolution values are considered completed. You should only add the Resolution field to workflow screens that represent the closing of an issue.

Getting ready

We need to have a workflow to configure, such as Simple Workflow, which was created in the previous recipe. We also need to have screens to display; JIRA’s out-of-the-box Workflow screen and Result Issue screen will suffice, but if you create your own screens, those can also be used.

How to do it…

Perform the following steps to add a screen to a workflow transition:

1. Select the workflow to update, such as our Simple Workflow.
2. Click on the Edit button if the workflow is active. This will create a draft workflow for us to work on.
3. Select the Start Progress transition and click on the Edit link from the panel on the right-hand side.
4. Select the Workflow screen from the Screen drop-down menu and click on Save.
5. Repeat Step 3 and Step 4 to add the Resolve Issue screen to the Close transition.

If you are working with a draft workflow, you must click on the Publish Draft button to apply our changes to the live workflow.

If you do not see your changes reflected, it is most likely that you forgot to publish your draft workflow.

Using common transitions

Often, you will have transitions that need to be made available from several different statuses in a workflow, such as the Resolve and Close transitions. In other words, these are transitions that have a common destination status but many different originating statuses.

To help you simplify the process of creating these transitions, JIRA lets you reuse an existing transition as a common transition if it has the same destination status.

Common transitions are transitions that have the same destination status but different originating statuses.

A common transition has an additional advantage of ensuring that transition screens and other relevant configurations, such as validators, stay consistent. Otherwise, you would have to constantly check the various transitions every time you make a change to one of them.

How to do it…

Perform the following steps to create and use common transitions in your workflow:

1. Select the workflow and click on the Edit link to create a draft.
2. Select the Diagram mode.
3. Create a transition between two steps—for example, Open and Closed.
4. Create another transition from a different step to the same destination step and click on the Reuse a transition tab.

5. Next, select the transition created in Step 3 from the transition to reuse the drop-down menu and click on Add.
6. Click on Publish Draft to apply the change.

See also

Refer to the Using global transitions recipe.

Using global transitions

While a common transition is a great way to share transitions in a workflow and reduce the amount of management work that would otherwise be required, it has the following two limitations:

• Currently, it is only supported in the classic diagram mode (if running on older JIRA versions)
• You still have to manually create the transitions between the various steps

As your workflow starts to become complicated, explicitly creating the transitions becomes a tedious job; this is where global transitions come in.

A global transition is similar to a common transition in the sense that they both share the property of having a single destination status. The difference between the two is that the global transition is a single transition that is available to all the statuses in a workflow.

In this recipe, we will look at how to use global transitions so that issues can be transitioned to the Frozen status throughout the workflow.

Getting ready

As usual, you need to have a workflow you can edit. As we will demonstrate how global transitions work, you need to have a status called Frozen in your workflow and ensure that there are no transitions linked to it.

How to do it…

Perform the following steps to create and use global transitions in your workflow:

1. Select and edit the workflow that you will be adding the global transition to.
2. Select the Diagram mode.
3. Select the Frozen status.
4. Then, check the Allow all statuses to transition to this one option.
5. Click on Publish Draft to apply the change.

   The following screenshot depicts the preceding steps:

6. Once you create a global transition for a status, it will be represented as an All transition, as shown in the following screenshot:

After the global transition is added to the Frozen status, you will be able to transition issues to Frozen regardless of its current status.

You can only add global transitions in the Diagram mode.

See also

Refer to the Restricting the availability of workflow transitions recipe on how to remove a transition when an issue is already in the Frozen status.

Restricting the availability of workflow transitions

Workflow transitions, by default, are accessible to anyone who has access to the issue. There will be times when you would want to restrict the access to certain transitions. For example, you might want to restrict access to the Freeze Issue transition for the following reasons:

• The transition should only be available to users in specific groups or project roles
• As the transition is a global one, it is available to all the workflow statuses, but it does not make sense to show the transition when the issue is already in the Frozen status

To restrict the availability of a workflow transition, we can use workflow conditions.

Getting ready

For this recipe, we need to have the JIRA Suite Utilities add-on installed. You can download it from the following link or install it directly from Universal Plugin Manager:

https://marketplace.atlassian.com/plugins/com.googlecode.jira-suite-utilities

How to do it…

We need to create a new custom field configuration scheme in order to set up a new set of select list options. Perform the following steps for this:

1. Select and edit the workflow to configure.
2. Select the Diagram mode.
3. Click on the Frozen global workflow transition.
4. Click on the Conditions link from the panel on the right-hand side.
5. Click on the Add condition, select the Value Field condition (provided by JIRA Suite Utilities) from the list, and click on Add.
6. Configure the condition with the following parameters:
   • The Status field for Field
   • The Not equal != for Condition
   • Frozen for Value
   • String for Comparison Type

     This means that it should only show the transition if the issue’s status field’s value is not Frozen.

7. Click on the Add button to complete the condition setup.
   

   At this point, we added the condition that will make sure the Freeze Issue transition is not shown when the issue is already in the Frozen status. The next step is to add another condition to restrict the transition and is only available to users in the Developer role.

8. Click on the Add condition again and select the User in the Project Role condition.
9. Then, select the Developer project role and click on Add.
10. Click on Publish Draft to apply the change.

After you apply the workflow conditions, the Frozen transition will no longer be available if the issue is already in the Frozen status and/or the current user is not in the Developer project role.

There’s more…

Using the Value Field condition (that comes with the JIRA Suite Utilities add-on) is one of the many ways in which we can restrict the availability of a transition based on the issue’s previous status. There is another add-on called JIRA Misc Workflow Extensions (this is a paid add-on), which comes with a Previous Status condition for this very use case. You can download it from https://marketplace.atlassian.com/plugins/com.innovalog.jmwe.jira-misc-workflow-extensions.

When you have more than one workflow condition applied to the transition, as in our example, the default behavior is that all the conditions must pass for the transition to be available.

You can change this so that only one condition needs to pass for the transition to be available by changing the condition group logic from All of the following conditions to Any of the following conditions, as shown in the following screenshot:

Validating user input in workflow transitions

For workflow transitions that have transition screens, you can add validation logic to make sure what the users put in is what you are expecting. This is a great way to ensure data integrity, and we can do this with workflow validators.

In this recipe, we will add a validator to perform a date comparison between a custom field and the issue’s create date, so the date value we select for the custom field must be after the issue’s create date.

Getting ready

For this recipe, we need to have the JIRA Suite Utilities add-on installed. You can download it from the following link or install it directly using Universal Plugin Manager:

https://marketplace.atlassian.com/plugins/com.googlecode.jira-suite-utilities

As we will also do a date comparison, we need to create a new date custom field called Start Date and add it to the Workflow screen.

How to do it…

Perform the following steps to add validation rules during a workflow transition:

1. Select and edit the workflow to configure.
2. Select the Diagram mode.
3. Select the Start Progress transition and click on the Validators link on the right-hand side.
4. Click on the Add validator link and select Date Compare from the list.
5. Configure the validator with the following parameters:
   • The Start Date custom field for This date
   • The Greater than > for Condition
   • Created for Compare with
6. Click on Add to add the validator.

7. Then, click on Publish Draft to apply the change.

After we add the validator, if we now try to select a date that is before the issue’s create date, JIRA will prompt you with an error message and stop the transition from going through, as shown in the following screenshot:

How it works…

Validators are run before the workflow transition is executed. This way, validators can intercept and prevent a transition from going through if one or more of the validation logics fail.

If you have more than one validator, all of them must pass for the transition to go through.

Performing additional processing after a transition is executed

JIRA allows you to perform additional tasks as part of a workflow transition through the use of post functions. JIRA makes heavy use of post functions internally; for example, with the out-of-the-box workflow, when you reopen an issue, the resolution field value is cleared automatically.

In this recipe, we will look at how to add post functions to a workflow transition. We will add a post function to automatically clear out the value stored in the Reason for Freezing custom field when we take it out of the Frozen status.

Getting ready

By default, JIRA comes with a post function that can change the values for standard issue fields, but as Reason for Freezing is a custom field, we need to have the JIRA Suite Utilities add-on installed.

You can download this from the following link or install it directly using Universal Plugin Manager:

https://marketplace.atlassian.com/plugins/com.googlecode.jira-suite-utilities

How to do it…

Perform the following steps to add processing logic after a workflow transition is executed:

1. Select and edit the workflow to configure.
2. Select the Diagram mode.
3. Click on the Frozen global workflow transition.
4. Next, click on the Post functions link on the right-hand side.
5. Click on Add post function, select Clear Field Value post function from the list, and click on Add.
6. Select the Reason for Freezing field from Field and click on the Add button.
7. Now, click on Publish Draft to apply the change.

With the post function in place, after you execute the transition, the Reason for Freezing field will be cleared out. You can also note from the issue’s change history as a part of the transition execution that where the Status field is changed from Frozen to Open, the change for the Reason for Freezing field is also recorded.

How it works…

Post functions are run after the transition is executed. When you add a new post function, you might notice that the transition already has a number of post functions preadded; this is shown in the screenshot that follows.

These post functions are system post functions that carry out important internal functions, such as keeping the search index up to date. The order of these post functions is important.

Always add your own post functions at the top of the list.

For example, any changes to issue field values, such as the one we just added, should always happen before the Reindex post function, so by the time the transition is completed, all the field indexes are up to date and ready to be searched.

Summary

In this article, you learned about not only how to create workflows with the new workflow designer but also how to use workflow components, such as conditions and validators, to add additional behavior to your workflows. We also looked at many different add-ons that are available to expand the possibilities of what you can do with workflows.

Resources for Article:

---

Further resources on this subject:

• JIRA Agile for Scrum [article]
• JIRA – an Overview [article]
• Gadgets in JIRA [article]

---