Workflows are controlled and managed centrally from the JIRA administration console, so you need to be an administrator to create and configure workflows. To manage workflows, perform the following steps:
- Log in to JIRA as a JIRA administrator.
- Browse to the JIRA administration console.
- Select the Issues tab and then the Workflows option. This will bring up the View Workflows page:
From the View Workflows page, you will be able to see a list of all the available workflows. You can also create new workflows and manage existing ones. The page is divided into two sections, Active and Inactive. Active workflows are being used by projects, and inactive ones are not. By default, the Inactive section is collapsed, so the page will only display active workflows. The preceding screenshot shows the Inactive section being expanded.
JIRA comes with a default read-only workflow called jira. This workflow is applied to projects that do not have any specific workflow applied. For this reason, you cannot edit or delete this workflow. With JIRA 7, this is mostly used to remain backward compatible with existing projects. New projects will have their own workflows created based on the template selected. These project-specific workflows will have their names start with the project key, followed by the project's template, such as HD: Task Management Workflow.
In a JIRA workflow, an issue status represents a state in the workflow for an issue. It describes the current status of the issue. If we compare it to a flow chart, the statuses will be the rectangles and in the diagram they indicate the current status of the issue along the process. Just as a task can only be in one stage of a business process, an issue can be in only one status at any given time, for example, an issue cannot be both open and closed at the same time.
There is also a term called step, which is the workflow terminology for statuses. Since JIRA has simplified its workflow administration, step and status can be used interchangeably. For consistency, we will be using the term status in this book, unless a separation needs to be made in special cases.
Statuses represent stages in a workflow; the path that takes an issue from one status to the next is known as a transition. A transition links two statuses together. A transition cannot exist on its own, meaning it must have a start and finish status and can only have one of each. This means that a transition cannot conditionally split off to different destination statuses. Transitions are also one way only. This means that if a transition takes an issue from status A to status B, you must create a new transition if you want to go back from status B to status A.
Transitions have several components. They are as follows:
- Conditions: Criteria must be met before the transition is available (visible) for users to execute. It is usually used to control permissions around how users can execute the transition.
- Validators: These are the verifications that must pass before the transition can be executed. They are usually used together with Transition Screens.
- Post Functions: These are additional functions to be performed as part of the transition process.
- Transition Screen: This is an optional screen to be displayed when a user is executing the transition. It is usually used to capture additional information as a part of the transition.
- Triggers: If you have integrated JIRA with other development tools such as Stash or GitHub, triggers can automatically execute the transition when an event happens, such as the creation of a new branch or when someone makes a code commit.
Each of the first three components defines the behavior of the transitions, allowing you to perform pre-and post-validations, as well as post-execution processing on the transition execution. We will discuss these components in depth in the following sections.
As described earlier, JIRA needs to be integrated with one of the following systems before you can start using triggers:
- Atlassian Stash
- Atlassian FishEye/Crucible
- Atlassian Bitbucket
- GitHub
Triggers will listen for changes from the integrated development tools, such as code commits, and when these happen, the trigger will automatically execute the workflow transition. Note that all permissions are ignored when this happens.
Sometimes, you might want to have control over who can execute a transition or when a transition can be executed. For example, a transition to authorize an issue should be restricted to users in the managers group so normal employees will not be able to authorize their own requests. This is where conditions come in.
Conditions are criteria that must be fulfilled before the user is allowed to execute the transition. If the conditions on transitions are not met, the transition will not be available to the user when viewing the issue. The following table shows a list of conditions that are shipped with JIRA:
|
Condition |
Description |
|
Code Committed Condition |
This allows the transition to execute only if code has/has not (depending on configuration) been committed against this issue. |
|
Hide transition from user |
This will hide the transition from all users, and it can only be triggered from post functions. This is useful in situations where the transition will be triggered as part of an automated process rather than manually by a user. |
|
No Open Reviews Condition |
This allows a transition to execute only if there are no related open crucible reviews. |
|
Only Assignee Condition |
This only allows the issue's current assignee to execute the transition. |
|
Only Reporter Condition |
This only allows the issue's reporter to execute the transition. |
|
Permission Condition |
This only allows users with the given permission to execute the transition. |
|
Sub-Task Blocking Condition |
This blocks the parent issue transition depending on all its subtasks' statuses. |
|
Unreviewed Code Condition |
This allows transition to execute only if there are no unreviewed change sets related to this issue. |
|
User Is In Group |
This only allows users in a given group to execute the transition. |
|
User Is In Group Custom Field |
This only allows users in a given group custom field to execute a transition. |
|
User Is In Project Role |
This only allows users in a given project role to execute a transition. |
Validators are similar to conditions as they validate certain criteria before allowing the transition to complete. The most common use case for validators is to validate the user input during transition. For example, you can validate if the user has entered data for all fields presented on the workflow screen.
The following table shows a list of validators that come shipped with JIRA:
|
Validator |
Description |
|
Permission Validator |
This validates that the user has the selected permission. This is useful when checking whether the person who has executed the transition has the required permissions. |
|
User Permission Validator |
This validates that the user has the selected permission where the |
As the name suggests, post functions are functions that occur after (post) a transition has been executed. This allows you to perform additional processes once you have executed a transition. JIRA heavily uses post functions internally to perform a lot of its functions. For example, when you transition an issue, JIRA uses post functions to update its search indexes so your search results will reflect the change in issue status.
If a transition has failed to execute (for example, failing validation from validators), post functions attached to the transition will not be triggered. The following table shows a list of post functions that come shipped with JIRA:
|
Post function |
Description |
|
Assign to Current User |
This assigns the issue to the current user if the current user has the assignable user permission. |
|
Assign to Lead Developer |
This assigns the issue to the project/component lead developer. |
|
Assign to Reporter |
This assigns the issue to the reporter. |
|
Create Perforce Job Function |
This creates a perforce job (if required) after completing the workflow transition. |
|
Notify HipChat |
This sends a notification to one or more HipChat rooms. |
|
Trigger a Webhook |
If this post function is executed, JIRA will post the issue content in JSON format to the URL specified. |
|
Update Issue Field |
This updates a simple issue field to a given value. |