So, let's take a look at how to create and set up a new workflow in JIRA. To create a new workflow, all you need is a name and description:
- Browse to the View Workflows page.
- Click on the Add Workflow button.
- Enter a name and description for the new workflow in the Add Workflow dialog.
- Click on the Add button to create the workflow.
The newly created workflow will only contain the default create and open status, so you will need to configure it by adding new statuses and transitions to make it useful. Let's start with adding new statuses to the workflow using the following steps:
- Click on the Add status button.
- Select an existing status from the drop-down list. If the status you need does not exist, you can create a new status by entering its name and pressing the Enter key on your keyboard.
- Check the Allow all statuses to transition to this one option if you want users to be able to move the issue into this status regardless of its current status. This will create a global transition, which is a convenient option, so you do not have to manually create multiple transitions for the status.
- Click on the Add button to add the status to your workflow. You can repeat these steps to add as many statuses as you want to your workflow:
Now that the statuses are added to the workflow, they need to be linked with transitions so that issues can move from one status to the next. There are two ways to create a transition:
- Click on the Add transition button
- Select the originating status and then click and drag the arrow to the destination status
Both options will bring up the Add Transition dialog, as shown in the following screenshot:
From the preceding screenshot, you can choose to either create a new transition with the New Transition tab or use an existing transition with the Reuse a transition tab.
When creating a new transition, you will need to configure the following:
- From status: This is the originating status. The transition will be available when the issue is in the selected status.
- To status: This is the destination status. Once the transition is executed, the issue will be put into the selected status.
- Name: This is the name of the transition. This is the text that will be displayed to users. It is usually a good idea to name your transitions starting with a verb, such as
Close Issue. - Description: This is an optional text description showing the purpose of this transition. This will not be displayed to users.
- Screen: This is an optional intermediate screen to be displayed when users execute the transition. For example, you display a screen to capture additional data as part of the transition. If you do not select a screen, the transition will be executed immediately. The following screenshot shows a workflow screen:
If you want to reuse an existing transition, simply click on the Reuse a transition tab, the From and To statuses, and the Transition to reuse, as shown in the following screenshot:
You might be wondering when you should create a new transition and when you should reuse an existing transition. The big difference between the two is that when you reuse a transition, all instances of the reused transition, also known as common transition, will share the same set of configurations, such as conditions and validators. Also, any changes made to the transition will be applied to all instances. A good use case for this is when you need to have multiple transitions with the same name and setup, such as Close Issue; instead of creating separate transitions each time, you can create one transition and reuse it whenever you need a transition to close an issue. Later on, if you need to add a new validator to the transition to validate additional user input, you will only need to make the change once, rather than multiple times for each Close Issue transition.
Another good practice to keep in mind is to not have a dead end state in your workflow, for example, allowing closed issues to be reopened. This will prevent users from accidentally closing an issue and not being able to correct the mistake.
One thing people often overlook is, you can change the status an issue is transitioned to when it is first created. By default, an issue is placed in the Open status as soon as it is created. While this makes sense for most cases, you can actually change that. For example, you might want all your issues to be in a Waiting status and transition to Open only after someone has reviewed it. You can also make changes to the default Create Issue transition. By doing so, you can influence the issue creation process. For example, you can add a validator to it to add additional checking before an issue is allowed to be created, or add a post function to perform additional tasks as soon as an issue is created.
Now that we have seen how to add new statuses and transitions to a workflow, let's look at adding triggers, conditions, validators, and post functions to a transition.
You can only add triggers to transitions if JIRA is integrated with at least one of the supported development tools. To add triggers, perform the following steps:
- Select the transition you want to add triggers to.
- Click on the Triggers link.
- Click on the Add trigger button. If you do not have any integrated development tools, this button will be disabled:
- Select the trigger you want to add and click on the Next button.
- Confirm the trigger source detected and click on the Add trigger button.
New transitions do not have any conditions by default. This means that anyone who has access to the issue will be able to execute the transition. JIRA allows you to add any number of conditions to the transition:
- Select the transition you want to add conditions to.
- Click on the Conditions link.
- Click on the Add condition link. This will bring you to the Add Condition To Transition page, which lists all the available conditions you can add:
- Select the condition you want to add.
- Click on the Add button to add the condition.
- Depending on the condition, you may be presented with the Add Parameters To Condition page where you can specify the configuration options for the condition. For example, the User Is In Group condition will ask you to select the group to check against, shown as follows:
Newly added conditions are appended to the end of the existing list of conditions, creating a condition group. By default, when there is more than one condition, logical AND is used to group the conditions. This means that all conditions must pass for the entire condition group to pass. If one condition fails, the entire group fails, and the user will not be able to execute the transition. You can switch to use the logical OR condition, which means only one of the conditions in the group needs to pass for the entire group to pass. This is a very useful feature as it allows you to combine multiple conditions to form a more complex logical unit.
For example, the User Is In Group condition lets you specify a single group, but with the AND operator, you can add multiple User Is In Group conditions to ensure that the user must exist in all the specific groups to be able to execute the transition. If you use the OR operator, then the user will only need to belong to one of the listed groups. The only restriction to this is that you cannot use both operators for the same condition group.
Like conditions, transitions, by default, do not have any validators associated. This means that transitions are completed as soon as they are executed. You can add validators to transitions to make sure that executions are only allowed to be complete when certain criteria are met. Use the following steps to add a validator to a transition:
- Select the transition you want to add conditions to.
- Click on the Validators link.
- Click on the Add validator link. This will bring you to the Add Validator To Transition page, which lists all the available validators you can add:
- Select the validator you want to add.
- Click on the Add button to add the validator.
- Depending on the validator, you may be presented with the Add Parameters To Validator page where you can specify configuration options for the validator. For example, the Permissions validator will ask you to select the permission to validate against, shown as follows:
Similar to conditions, when there are multiple validators added to a transition, they form a validator group. Unlike conditions, you can only use the logical AND condition for the group. This means that in order to complete a transition, every validator added to the transition must pass its validation criteria. Transitions cannot selectively pass validations using the logical OR.
The following screenshot shows a validator (the Field required validator from JIRA Suite Utilities, refer to the Extending workflow with workflow add-ons section) being placed on the transition, which validates whether the user has entered a value for the Resolution Details field:
Transitions, by default, are created with several post functions. These post functions provide key services to JIRA's internal operations, so they cannot be deleted from the transition. These post functions perform the following:
- Set the issue status to the linked status of the destination workflow step
- Add a comment to an issue if one is entered during a transition
- Update the change history for an issue and store the issue in the database
- Re-index an issue to keep indexes in sync with the database
- Fire an event that can be processed by the listeners
As you can see, these post functions provide some of the basic functions such as updating a search index and setting an issue's status after transition execution, which are essential in JIRA. Therefore, instead of letting users manually add them in and risk the possibility of leaving one or more out, JIRA adds them for you automatically when you create a new transition:
- Select the transition you want to add post functions to.
- Click on the Post Functions link.
- Click on the Add post function link and select the post function you want to add:
- Click on the Add button to add the post function.
- Depending on the post function, you may be presented with the Add Parameters To Function page where you can specify configuration options for the post function. The following screenshot shows an example from the Update Issue Field post function:
Just like conditions and validators, multiple post functions form a post function group in a transition. After a transition is executed, each post function in the group is executed sequentially as it appears in the list, from top to bottom. If any post function in the group encounters an error during processing, you will receive an error, and the remaining post functions will not be executed.
Since post functions are executed sequentially and some of them possess the ability to modify values and perform other tasks, often, their sequence of execution becomes very important. For example, if you have a post function that changes the issue's assignee to the current user and another post function that updates an issue field's value with the issue's assignee, obviously the update assignee post function needs to occur first, so you need to make sure that it is above the other post function.
You can move the position of post functions up and down along the list by clicking on the Move Up and Move Down links. Note that not all post functions can be repositioned.