Welcome to this Atlassian Skill Builder course on Customizing Jira Workflows.

Are your Jira

workflows plain or powerful, kludgy or classy? In this course, you'll learn about customizing
workflows in order to better match complex work processes, so teams can work more
effectively in Jira.

1 Customizing Jira Workflows

 To succeed with this course, you need:
• End-user experience with Jira
• Familiarity with the concepts of projects, issues, issue types, and boards
• Basic understanding of schemes, permissions, and notifications
• Basic familiarity with Jira Service Desk

2 Customizing Jira Workflows

 And here is what you will learn here:
• All the workflow-related concepts and terminology.
• Deep understanding of how to configure transitions in complex workflows, including where
the use of Marketplace apps may be appropriate by looking at specific examples of
business requirements. This is where we will spend the majority of our time.
• We will also see how workflows are edited and by whom.
• And finally, best practices and troubleshooting tips.

The course is developed primarily on Jira Software Server but much of the workflow concepts
and the workflow editor is the same or equivalent on other platforms and Jira applications.
However, some of the Marketplace app solutions may not be available for all combinations of
hosting options and applications.

Additionally, functionality specific to Jira Service Desk is covered in brief in its own module on
Service Desk Approvals and Automation. In the online assessment, questions about Jira
Service Desk will be specifically referenced.

3 Customizing Jira Workflows

 There are 8 modules in this course, as follows.
1. Workflow Basics
2. Default Workflows & Customizing
3. Configuring Transitions
4. Advanced Examples
5. Service Desk Approvals and Automation
6. Editing and Testing
7. Common Problems and Troubleshooting
8. Best Practices
So let’s start with workflow basics.

4 Customizing Jira Workflows

 Workflow defines the business process for completing different kinds of tasks. It defines the
stages that a task goes through from creation to completion. You can define different
workflows for different types of tasks. In the example we are about to look at, imagine that
you used Jira to track the process of building a house.

5 Customizing Jira Workflows

 Here is our example House-building Workflow. An issue represents a house to be built. Keep
in mind that it does not capture all of the complexity of an actual home-building project, but it
will suffice to help us review the different parts. Let’s begin with Statuses.

6 Customizing Jira Workflows

 Statuses represent where the issue is (or in our case, the house) within the process of being
built. In the diagram, Statuses are the colored boxes. We began with a New Plan. Then the
house can be In Design phase, In Estimation phase, In Construction phase or eventually, it will
be Completed. Along the way, house-building may be put On Hold. You might also have other
phases like Under Inspection, which is not shown here.

Note the different colors of each status. Each color represents a status category – To Do
(blue), In Progress (yellow), and Done (green). You’ll see these colors in all types of workflows.
These help you identify where issues are in their lifecycle, particularly in places where a large
number of issues are rolled up together.

7 Customizing Jira Workflows

 Transitions represent how that issue (or home-building task) moves from one status to
another. You Start Design, Start Estimate, Start Construction, Complete Construction, or
perhaps Cancel Project entirely.

8 Customizing Jira Workflows

 A transition can have these various parts configured:
1. Conditions can have permissions so that only some people are allowed to execute the
transition. For example, only Architects can Start Design.
2. Validators can require additional data before continuing. For example, you must enter the
Reason when putting a house-construction project On Hold.
3. Post Functions do additional processing as they occur. For example, you may create
additional tasks when Starting Estimate.
4. Triggers can automate transitions when certain events occur in a different system. In this
case, when the Supplier ships the construction materials, you can automate the process so
that the house-building task automatically goes from In Estimation to In Construction.

9 Customizing Jira Workflows

 Resolutions explain why an issue transitions from an Open or In-Progress type of status to a
Done type of status. In this case, the house-building task can go to the Completed Status
either because the project was cancelled or because the house was actually built. There may
be many other Resolutions in Jira; for example, Fixed or Cannot Reproduce in Software
workflows.

Resolution should always be set when an issue goes to its final status, and it should be cleared
when an issue is reopened again. In this workflow, the house-building task will never be
reopened.

It is crucial to remember that Jira considers an issue to be resolved if its Resolution field has a
value, regardless of the actual workflow status it is in. And Jira considers an issue to be
unresolved, if its Resolution field is empty.

10 Customizing Jira Workflows

 Workflow properties can further customize and enrich your workflow. You can use Step
Properties to restrict certain actions. For example, so that no more editing is allowed once the
house-building task is completed.

You can use transition properties to do things like translate buttons, so foreign companies can
estimate a house-building project.

11 Customizing Jira Workflows

 So let’s look again at the various aspects of a transition’s behavior; what they do and when
they occur. This is really where the bulk of Jira workflow customization resides. You can
configure your workflow transitions with conditions, validators, post functions, and triggers.
These usually map to either a convenience (namely, “do the boring stuff for me”) or a
requirement (for example, “you can't close that without updating a field.”)
• A condition specifies a situation that must exist BEFORE something else is permitted.
Conditions control if a transition is visible, and therefore available, to be used.
• A validator checks that any input made DURING the transition is valid before the transition
is performed. If a validator fails, its post functions are not executed and the issue does not
progress to the destination status of the transition.
• A post function is an automated action AFTER a transition has been executed. It carries out
any additional processing.
• A trigger transitions a Jira issue when certain events occur in a connected development
tool, such as Atlassian's Bitbucket. It automates the transition, ignoring conditions and
validators, and just executes the post functions.
You can also add transition screens to gather required data. We'll look at all these elements in
much more depth.

12 Customizing Jira Workflows

 To use workflow, including moving an issue on a board, the user has to have certain
permissions.
• Browse Projects permission is needed in order to see the project. If they cannot see it, they
cannot use its workflow, or create and edit issues, for that matter.
• Transition Issues permission is needed to use workflow at all. If users do not have this
permission, they cannot see and use the workflow buttons on an issue nor move it on an
agile board.
• Users may need additional permissions, as specified in the transition conditions. For
example, non-simplified workflows require that users have the ‘Resolve Issues’ or the ‘Close
Issues’ permissions to resolve or close issues. Other conditions may require that the user
belongs to a particular group or project role, or that he is the Reporter or Assignee. If the
user does not meet these conditions, he will not see – and therefore will not be able to use
– that particular transition.
• Additionally, users need Jira Software Application access (to transition in boards), namely
to see an agile board and therefore to move issues from column to column. Note that the
Simplified Workflow does not have any conditions, so users can move issues freely
between columns.
• And users need Jira Service Desk Application access, namely to be Service Desk agents, in
order to transition issues in Service Desk projects.

13 Customizing Jira Workflows

 Workflows are not associated directly to projects. Instead, they are mapped to issue types
inside of a workflow scheme. And workflow schemes are associated with one or more
projects.

Here you see the Dev Workflow Scheme is associated with a single project, Space Programs.
There are four workflows used in this scheme. Bugs use the Bug Workflow. Stories use the
Story workflow. And both Tasks and Sub-tasks use the Task Workflow. All other issue types
available in this project, if any, are mapped to the Dev Workflow.

Notice that multiple issue types can be mapped to the same workflow.

An extra layer exists in Service Desk projects, where Request Types are first mapped to Issue
Types. We will explore this later.

14 Customizing Jira Workflows

 Jira ships with default workflows which can be used as is, out-of-the-box, but much of the
power of Jira lies in workflow customization.

15 Customizing Jira Workflows

 Each of the three Jira applications – Jira Core, Jira Software, and Jira Service Desk – ships
with project templates from which new projects can be created.

Each project which is newly created from a project template gets a set of schemes based on
the default schemes for its project template. Some of the associated schemes are shared with
other projects and some, including the Workflow Scheme, are unique to the project. This
means that they can be modified and the changes will not affect any other project.

Bottom line, when created from templates, projects get default workflows which are unique to
those projects. They are not shared with other projects unless later changed. Let’s look closer
at these defaults.

16 Customizing Jira Workflows

 Here you see the default business workflows for Jira Core project types. The Task
Management workflow just has two statuses, To Do and Done.
The Project Management workflow shown in the middle goes from To Do to In Progress to
Done. And there is also a Process Management workflow, as shown.

A set of default statuses are used by the default workflows, including To Do, Open, In
Progress, Under Review, Done, Closed, Cancelled, and others.

17 Customizing Jira Workflows

 Shown here are the default workflows for Software project types, which use the Simplified
Workflow by default. They all use global transitions, which allow any status in a workflow to
transition to any other status. And developers can freely drag issues between columns on a
board. The black label which reads “All” beside each status indicates that it is a global
transition. The Simplified Workflow is easy to work with but can only be used if a board
represents a single project.

18 Customizing Jira Workflows

 Jira Software boards are tied to the underlying workflow of their projects. The top shows the
sprint board in a Scrum project. The bottom shows the underlying workflow. The workflow
statuses are represented by (or mapped) to columns. Issue cards are moved from left to right
as they progress through the workflow. The goal is to transition from the leftmost column of
the board to the Done column.

Note the connection between columns and workflow statuses. Columns can have the same or
a different name than the mapped status. And multiple statuses can be mapped to the same
single column, as shown here, where both Resolved and Closed statuses are mapped to the
Done column.

It’s crucial that you map all statuses to columns. Otherwise issues in unmapped statuses will
be hidden from the board.

Board administrators can configure the columns. They can add, remove, rename, delete
columns and change the status mapping so it better represents the workflow and clearly
shows where in the process the work currently resides. To add a status to a board, the project
must be using the Simplified Workflow. Adding a status to a board adds a status to the
underlying workflow. We will discuss this later in the presentation.

19 Customizing Jira Workflows

 Meanwhile, the three Service Desk project types – Basic, Customer Service, and IT Service
Desk – offer their own set of default workflows. Here are two of them. We will discuss Service
Desk approvals and automation in a later module.

20 Customizing Jira Workflows

 As we have seen, there are many great default workflows to start with. But what if they don’t
meet the needs of your team? In that case, you can customize your project workflow.

Here are some examples of additional requirements:

• Only developers should be able to submit an issue for code review.
• When an issue is resolved, I want to see how long was spent in coding.
• I want the issue to show which developer implemented the change.

These requirements could be met by adding Conditions, Validators, and Post Functions to
various transitions in a custom workflow. And throughout this presentation, we will learn how
to do that.

21 Customizing Jira Workflows

 There are many conditions, validators, and post-functions available natively (out-of-the-box) in
Jira. But apps in the Atlassian Marketplace (formerly called add-ons) can greatly extend that
native functionality. They provide even more of these elements to satisfy complex business
requirements.

Different apps are available for Cloud, Server, and Data Center hosting options. Some apps
are free and others are paid.

Note that you need Jira System Administrators global permission (not just Jira Administrators
permission) to update or install an app.

22 Customizing Jira Workflows

 You can find and install new apps via the Manage Apps tab of the Jira administration menu.
Vendors often offer a free 30-day trial. You can search apps in various ways, such as by
highest rating, most popular or staff-picked, as well as by categories like admin tools, whether
it’s paid or free, or just by its name. This slide shows just a few of the many popular workflow
options.

This presentation mentions workflow solutions that rely on the use of Marketplace apps. We
will not be mentioning the vendors by name, since your requirement will differ and multiple
vendors sometimes offer similar functionality. So be sure to check out the Marketplace and
compare.

Note that you can also create your own conditions, validators, and post-functions by building
your own app, but we don’t cover it in this presentation.

23 Customizing Jira Workflows

 Now let’s dive deeper into configuring transitions.

24 Customizing Jira Workflows

 This section has several subsections, where we will learn about the various parts of a
transition, as shown in the menu. But first let’s see the types of transitions and how they are
created.

25 Customizing Jira Workflows

 Here is our example of the House-Building Workflow again. A regular transition is a link
between two statuses that enables an issue to move from one status to another. In order for an
issue to move between two statuses, a transition must exist. And it is a one-way link, so if an
issue needs to move back and forth between two statuses, two links need to be created.

In this example, Start Design transition goes from New Plan to In Design. If we wanted to go
back to New Plan, we would have to create a different transition.

26 Customizing Jira Workflows

 You can also reuse transitions and these are called common transitions. Notice that you can
Cancel the Project when In Design Phase. This sets the status to Completed. This transition
probably prompts the user for some input, like the reason for cancelling, comments, and sets
the resolution field to Project Cancelled. It may notify outside contractors and do other post-
processing.

But you also need the option to Cancel the Project when In Estimation phase. Instead of
creating a second transition with identical configurations, you can simply choose to reuse the
one configured earlier. This makes it easier to maintain in the future, and less error-prone
when business requirements change.

27 Customizing Jira Workflows

 If you want a particular transition that goes from every status to a certain status, you can
either reuse the same transition over and over, or you can create a Global Transition. Global
Transitions allow every other status in the workflow to transition to the selected status. In our
case, there is a global transition to On Hold status, so you can put a project on hold at any
time. Note the black All indicator beside the On Hold status, which indicates a global
transition. To create one, you select the option “Allow all statuses to transition to this one” in
the status panel.

28 Customizing Jira Workflows

 Finally, transitions don‘t have to change the status of an issue. They can simply loop back to
the same status. These are called Self-reflecting transitions or looping transitions. For
example, while In Estimation stage, you may need to Re-estimate multiple times through
different companies or (perhaps) due to budgetary constraints. No matter how many times
you estimate, the status should stay the same. You may have a transition screen pop-up during
this looping transition that allows the user to add, update, or delete various field values (like
the Total Cost), and add comments. To create such transitions, you simply make the From
status and To status the same.

One common use of such self-reflecting transitions is to allow only some users to edit one or
more restricted fields, which are available only on a transition screen which is hidden by a
permission condition. We will look at such an example once we learn more about conditions
and transition screens.

29 Customizing Jira Workflows

 So let’s learn more about Conditions.

30 Customizing Jira Workflows

 What do these requirements have in common?
• Only members of the QA team should be able to close issues.
• Only the current assignee should be able to start progress on an issue.
• No invoices should be sent until payment terms have been defined.
Let’s take a look at the answer.

31 Customizing Jira Workflows

 All these requirements, as shown especially in bold, are situations that must exist BEFORE a
transition can be executed. They are pre-requisites for the transition.

32 Customizing Jira Workflows

 A condition specifies a situation that must exist BEFORE something else is possible or
permitted. It’s a pre-requisite and controls if a transition is available to be used.

Conditions control either who performs a transition or under what circumstances. In this
example, Teams in Space want only developers to be able to send an issue for code review.
This can be achieved by adding a condition to the “Code Review” transition. So only the users
who are in the Developers role can see this transition. But remember that users also need the
'Transition Issues' permission to see and execute transitions at all.

If a condition fails, the user will not see the transition button when viewing the issue, and
therefore not be able to execute it.

33 Customizing Jira Workflows

 The most common use cases involve either something about the current user (the WHO) or
the current state of the issue (the WHAT).

Conditions can take into consideration whether the user is the reporter, assignee, or in a
particular project role or group. For example, you can restrict an approval transition to only
users who are in the approvers project role. Conditions can also check the user’s permissions.
For example, does the user have the Resolve Issues permission?

Conditions can also take into account something about the state of the issue. For example, has
code been committed against this issue? Or the status of the issue’s Sub-tasks. For example,
you can restrict the parent from transitioning to Done until all of its Sub-tasks have been
Resolved or Closed.

34 Customizing Jira Workflows

 In the previous slide, we saw that you can add either groups or project roles into workflow
conditions. In fact, both projects roles and groups can be used in many other places, including
permission and notification schemes, issue security levels, comment visibility, and the sharing
of filters and dashboards. So let’s explore their differences.

In short, groups are used across Jira, whereas roles fulfill particular functions within a project.
First, Jira administrators must create the project roles. But once created, project role
membership is project-specific whereas group membership is always global.

Project administrators can therefore manage membership (on a project by project basis), so
changes can be made quickly if membership changes. This takes the load off of Jira
administrators, because they are the only ones who can manage groups.

And finally, roles help to reduce the number of schemes because schemes can be more
generic and therefore shared.

35 Customizing Jira Workflows

 Let’s take a look at an example. Three HR projects – Hiring, PTO, and Expenses – share the
same workflow. In that workflow there are conditions and validators that use the project role
Approvers. Each project has different members in their Approvers role. As issues go through
the workflow in each project, the conditions and validators are checked against different sets
of users in this role. The workflow stays the same. Only the membership in the Approvers role
changes, on a project by project basis.

Groups are global across Jira, so unless you created different groups for each project you
couldn’t achieve the same flexibility. You might also have to create unique workflows.
Additionally, Project Administrators can modify membership in roles, but not in groups.

Bottom line, project roles are a much more flexible and sustainable. As a best practice, use
project roles instead of groups in workflow conditions and validators.

36 Customizing Jira Workflows

 You can also satisfy complex requirements by grouping and nesting conditions. And you can
toggle the logic for how the conditions in a group are applied between “All” and “Any.” In a
grouping of conditions, either all the conditions have to be met or any of the conditions have
to be met.

In this example, the only users who can execute this condition are EITHER the Reporter who is
also in the Managers project role OR members of the Sales group.

37 Customizing Jira Workflows

 Let’s put this all together and look at an example of how a transition with configured
conditions appears in Jira. This is the Start Progress transition. It has three configured
conditions. Let’s first look at the inner nested conditions. We see that “any of the following
conditions” must be met in the inner box. That means the user must be the Assignee or the
user must be in the Developers or Administrators project roles. Either of these must be true.

But then we look at the outer grouping which says that “all of the following conditions” must
be true. This means that in addition to the above, the third condition validates existing issue
links. If issue links of the specified link type exist, namely “is blocked by”, then Jira checks
whether they respect the constraint that their status must be in Resolved or Closed.

38 Customizing Jira Workflows

 Validators are next.

39 Customizing Jira Workflows

 What do these requirements have in common?
• When a support ticket is reopened the reason has to be stated in a comment.
• When closing a payment request, the payment data is mandatory.
• When the developer fixes a bug, a fix version has to be entered.
Let’s take a look at the answer.

40 Customizing Jira Workflows

 All these requirements define input that must be made DURING the workflow transition.

41 Customizing Jira Workflows

 A validator checks that any input made DURING the transition is valid before the transition is
performed. Input can be gathered from the user on a transition screen. If a validator fails,
workflow errors are presented to the user. The issue does not progress to the next status, and
the post functions are not executed.

The most common use case involves making fields or comments required on specific
transitions as the issue progresses through its lifecycle. Making the field required through field
configuration makes it required from the beginning, but some values are not known until a
later time. So that is why Fields Required validators are useful later in the workflow process.

In this example, the developer must enter the Time Spent on the issue when submitting an
issue for code review.

42 Customizing Jira Workflows

 Here are some examples of validators:
1. Fields Required – this is used to gather more information throughout the lifecycle of an
issue. For example, you must input the Root Cause Analysis field with detailed information
before resolving an Outage ticket. Or you must enter comments when rejecting an
approval request.
2. Regular Expression Check – This is useful when you need to validate that information has
been entered in a certain format. You might use this when validating that an email address
contains an @ symbol.
3. Date Compare – This is useful when you need to validate that an issue was created within
a certain date window. You might use it to validate that an issue’s Creation date < Due
date. Or you might require Start Date and End Date when moving to "Schedule" status and
at the same time, validate that the Start Date < End Date.

43 Customizing Jira Workflows

 Transition screens are used to capture information as an issue moves through a transition.
When a user clicks the transition, the transition screen allows the user to enter the needed
information. For example, when a manager rejects a request for a new mobile device, he may
enter the reason for the rejection and a comment.

These are not the only screens in Jira. Users interact with data when they create, edit, and
view issues, as well. These three issue operations (Create, Edit, View) are mapped to screens
via a Screen Scheme, and to an issue type via Issue Type Screen Scheme. But in this
presentation, we focus only on Transition Screens.

Jira supplies some transition screens built into the default workflows, for example, the
“Resolve Issue Screen” which is shared by all new Software projects and is used for all issue
types in the workflow.

Only Jira administrators can create custom transition screens, and associate them with
workflow transitions.

44 Customizing Jira Workflows

 Here are two examples of custom transitions screens. The one on the left only has the
Comment field and no other fields. Comment field is added automatically to every transition
screen, if a user has Comment permissions. If the user does not have Comment permissions,
the field will not be shown to that user. The screen on the right is a custom transition screen
called “Pay & Close” showing various other fields.

Note that you can actually use any screen as a transition screen. You could, for example, use
the Create Screen from a project as a transition screen. But as a best practice, you want to
include only the fields that should be entered or modified during that transition. Otherwise,
the transition screen becomes too cluttered and is frustrating to users.

45 Customizing Jira Workflows

 Now let’s go back to our house-building workflow for a moment and those self-reflecting
transitions, like the Re-estimate which is shown here.

One other common use case for these self-reflecting transitions is to restrict editing of some
fields to some users. For example, let’s say that the requirement is that only the Home Owner
should be allowed to edit the Budget field after the house-building request is created.
Everyone else should just view it. But everyone else should be able to edit the other fields.

Jira does not have field level permissions, so how can we achieve this requirement?

46 Customizing Jira Workflows

 Remember that transition screens can contain fields that don’t appear on other screens. We
can put fields for which we want to restrict editing only on a transition screen but not on the
Edit Issue screen. And then we can use a condition so that the transition, and hence the
transition screen, is only available to some users. Since we don’t really want the issue to
change statuses, we can utilize the self-reflecting transition.

Here is how to meet that requirement in more detail. The Budget field is placed on the Create
Issue and View Issue screens, but not on the Edit Issue screen. The Budget field is also placed
a transition screen. A self-reflecting transition called “Modify Budget” is created on the New
Plan status and it loops back to the same status. The transition has a condition that only the
Home Owner (i.e. the Reporter) can execute this transition.

The result is that only the Home Owner can see the transition and thus modify the Budget field
which is on the transition screen. Everyone else can just view the Budget Field. The only
purpose of the self-reflecting transition is to restrict the ability to edit the Budget field after
issue creation from everyone but the Reporter.

47 Customizing Jira Workflows

 There is a similar use case for validators and transition screens. The Resolution field is a
special system field. Whenever it appears on any screen, it is required. So you would not want
to place it on the Create screen. Instead, it appears on Resolve Issue Screen only at those
transition points in the workflow where you are ready to go to a Done status. And at that
point, it is required.

But you can put other fields on a Transition Screen and require them with a Validator.
Transition screens, plus validators, provide a way to make fields mandatory at any point in
your workflow, rather than at the time of issue creation. This also provides the flexibility to
clear field values on a certain transition and then make them mandatory again later in the
workflow. To make a field mandatory during a workflow transition, you use a validator and a
transition screen together.

48 Customizing Jira Workflows

 Let’s put this all together and look at an example of how a transition with configured validators
appears in Jira.
There are 4 validators configured in this example and a transition screen.
When the user clicks on this transition, he will first be presented with this screen in order to
update field values and possibly add comments.
When he clicks Review, the validators will be evaluated in top-down order. As soon as one of
them fails, Jira will stop further validation and return a message to the user.
The first validator checks that there is a Review Due Date. Second, that the Review Due Date
is within 7 days of the Final Due Date.
Third, Jira validates that only one Release was selected from a field which is presumably a
multi-value field, for example a Version Picker field.
Finally, the transition validates that the Assignee was modified. For example, that the user
changed from the person who worked on the issue to the person who will now review the
issue.
Notice that comment field is added automatically to the transition screen but it is not required.

49 Customizing Jira Workflows

 It’s time to look at Post Functions.

50 Customizing Jira Workflows

 What do these requirements have in common?
• Bugs should be automatically assigned to a QA Engineer as soon as they’re fixed.
• For reports, the current date needs to be captured automatically once a product has
shipped.
• When product support reopens a request, the resolution should be cleared automatically.
Let’s take a look at the answer.

51 Customizing Jira Workflows

 These are all automated actions that need to take place AFTER a transition has executed. This
can be achieved by using post functions.

52 Customizing Jira Workflows

 A post function is an automated action that happens after a transition has executed, assuming
that the conditions and validators have passed.

In this example, a post function clears the Resolution field after the Reopen transition has
executed, which moves the issue from Done back to To Do.

53 Customizing Jira Workflows

 Jira includes several optional post functions that can be added to transitions to meet business
requirements. One example is assigning issues, for example to the Reporter, Current User or
the project/component Lead Developer. You might assign an issue back to the reporter when
their holiday request has been rejected, for instance.
Another common post function is to update an issue's field. For example, setting the issue
Priority to Highest. Jira’s “Update Issue Field” post function allows you to update several
system fields: Assignee, Description, Environment, Priority, Summary, Resolution, Original
Estimate, Remaining Estimate, and Time Spent. Several Marketplace apps allow you to update
custom fields.

54 Customizing Jira Workflows

 One very important system field which should be updated is the Resolution field. Every
workflow should set the Resolution field when an issue is considered completed in it’s final
status, whether that is Resolved, Closed, Done, etc. To set the Resolution field, you can either
prompt the user to select it on a Transition Screen, as we have seen before, or you can update
the field directly through a post function via one or more transitions.

Here on the left, you see the first option. When going from In Progress to Done the user is
prompted to select the Resolution as either Duplicate, Fixed, or Won’t Do.
On the right, you see the second option. There are 3 outgoing transitions from the In Progress
status to 3 different statuses. Each one sets a different Resolution automatically. The
Resolution is set automatically to Duplicate when going to the status Resolved. It is set to
Fixed when going to Closed, and to Won’t Do when going to Cancelled.

Remember that Jira sees the Resolution field as a flag. If it has a value, then the issue is
considered resolved. If it's empty, then the issue needs some form of action, and is therefore
considered open. This is very important, because Jira uses Resolution on various gadgets and
reports. All transitions that resolve an issue should set a Resolution value, either automatically
via a post function or from user input via a transition screen.

55 Customizing Jira Workflows

 Likewise, the Resolution field needs to be cleared whenever an issue is being reopened.
Otherwise, it will still appear as being completed on Jira gadgets, reports, etc. You cannot
clear the Resolution via a Transition Screen because once it is on a screen, it is required. So
here, you see two transitions that reopen the issue by going back to the To Do status; one
from the Resolved status and the other from Done status. They both clear the Resolution, so in
Jira, it now shows as Unresolved. In the lower example, the issue is being transitioned from
Cancelled to Reopened. And it also clears the Resolution field. Not all workflows allow an
issue to be reopened, but if they do, they should clear the Resolution field. Note that clearing
the Resolution field also clears the Resolved Date.

56 Customizing Jira Workflows

 Whenever you create a new transition, you notice that 5 post functions are added by default.
These are called Essential Post Functions. They include setting the issue status properly,
adding a comment to the database if one was entered, updating change history, re-indexing,
and firing an event. When you create a new transition, the default event that is fired is the
Generic Event, as shown here. But Jira administrators can change this to another system or
custom event. We’ll learn about events in a moment.

These essential post functions cannot be deleted from a transition or reordered. However, you
can insert other (optional) post functions between them.

57 Customizing Jira Workflows

 The sequence of Post Functions matters. Notice in this example that the fourth post function
sets the Resolution to Duplicate, but that occurs after the third post function, which updates
change history. So the change in Resolution will not show up properly in the issue change
history. Lines 3 and 4 should be switched.

58 Customizing Jira Workflows

 Lines 3 and 4 have been switched in this screenshot. Make sure any post functions you add
are appropriately sequenced. Indexing, database update and firing events should be the final
post functions.

59 Customizing Jira Workflows

 Transitions always fire an event as the final of the default post functions. By default, when a
new transition is created, the Generic Event is fired. But custom events are commonly used in
workflow transitions to generate specific notifications not generally covered by other events.
Let’s take a look at an example of how you might configure a transition so that it fires a custom
event, rather than a system event, as its last post function.

Suppose you had a Tax project with a workflow to handle tax returns. In some cases, the
assignee will click a transition called “Audit Required” to move the issue from Under Review to
Pending Audit. This is the only time that auditors should be notified, and not every time that
returns are updated, commented, and so on.

Which event should be fired?

60 Customizing Jira Workflows

 It makes sense to add a custom event called “Pending Audit” which notifies only the Auditors
group, and only during this transition. The Auditors group would only be notified when this
particular event is fired, when clicking this particular transition.

Here is how the process works. First the Mail Listener picks up and processes the event.

61 Customizing Jira Workflows

 Then the Notification Scheme of Tax Project is checked.

62 Customizing Jira Workflows

 Finally, an email is sent to the “Auditors” group, as listed in the “Pending Audit” custom event
of the Notification Scheme.

It worth nothing that there is one more important step not pictured here. Before sending the
email, Jira must also check the permission scheme and the issue security scheme associated
with the project to make sure that Auditors group do actually have permissions to view the
issue.

63 Customizing Jira Workflows

 So, in summary, to use custom events, Jira administrators must first create the event, and
then the event can be selected by editing the last post function of a transition. And recipients
of that custom event should be entered into the project’s notification scheme.

64 Customizing Jira Workflows

 Let’s look a little closer at Jira’s internal events sub-system. Events are fired not just during
workflow transitions, but also as a result of other issue operations within the application. The
events sub-system detects various issue changes and fires off the event corresponding to that
change. Jira then looks up the notification scheme associated with the issue's project and
identifies the users associated with the fired event. It then sends an email notification to each
user. Notification schemes map events and email recipients.

There are 17 system events as shown on the left. These include Issue Created event, Issue
Updated, Issue Assigned, Issue Moved, Issue Deleted, and many others. On the right, you see
examples of custom events, such as Awaiting Response and Pending Audit which may be
added globally by Jira administrators. You don’t have to have custom events in a Jira instance,
but business requirements may warrant it, as we explored earlier.

65 Customizing Jira Workflows

 A post function can be used to trigger a Webhook. Webhooks are user-defined HTTP POST
callbacks. You can use Jira webhooks to notify a remote application when certain events
occur in Jira. You can trigger a webhook through a workflow transition, which we will focus on
here, or though changes to Jira issues (for example, when they are modified or deleted) or
even when boards are created or sprints started. There are numerous events to choose for
webhooks. And you can post all events to a specified URL, or a specific set of events for a
specific set of issues. Using webhooks means that remote applications don’t have to
periodically poll Jira to determine whether changes have occurred. Webhooks must first be
registered (i.e. created) either by a Jira administrator or via the Jira REST API.

In a workflow transition, you can add a post function called “Trigger a Webhook.” In the
example pictured here, when an audit is required, a webhook is triggered to automatically
assign tasks to Auditors in a remote auditing application.

If the webhook you choose is also configured to listen to events, then the webhook will be
triggered twice: once for the event and once for the workflow transition. For this reason, you
should always unselect all events from the webhook admin screen.

66 Customizing Jira Workflows

 Let’s put this all together and look at an example of how a transition with configured post
functions appears in Jira.
There are a total of 7 post functions configured in this example. There are 5 default ones, plus
2 additional ones.
The first one assigns the issue to whomever is currently listed in the Lead Auditor field.
The next one triggers a webhook to the remote Auditing Application so the right activity can
happen there.
The next few are the default post functions.
And the last row shows that a custom event, Pending Audit, is fired – so that other Auditors
can be notified.

67 Customizing Jira Workflows

 Triggers are next.

68 Customizing Jira Workflows

 What do these requirements have in common?
• Automatically transition Bug to In Progress when a branch is created in Bitbucket.
• Automatically transition issue when pull request is created.
• Automatically close the task when the review is closed in Crucible.
Let’s take a look at the answer.

69 Customizing Jira Workflows

 These are all automated actions that happen in Jira when events occur in development tools.

70 Customizing Jira Workflows

 A trigger transitions a Jira issue when certain events occur in a connected development tool,
such as Atlassian’s Fisheye/Crucible, Bitbucket and GitHub. It automates the transition.
Instead of relying upon developers to manually update the status of issues after committing
code, completing reviews, creating branches, etc., you can configure triggers in your
workflow to automatically transition issues when these events occur in your dev tools.

When a trigger is executed, the conditions and validators are ignored and only the post
functions are executed. This means that any permissions on who can transition the issue are
completely ignored.

You can still drag issues between columns on the agile board or update your status manually
using the workflow buttons in the issue. And in that case, permissions, conditions, and
validators are still respected.

Workflow automation triggers simply provide more options for how issues move from one
status to the next, as well as provide assurance that the current status reflects the actual state
of development. Before you can start using triggers, a Jira admin needs to connect your
development tools to Jira. Then configure triggers in Jira workflows that respond to events in
the linked dev tools.

71 Customizing Jira Workflows

 Here are some common triggers. But there are other triggers in these dev tools and in others.
In Bitbucket, when a developer creates a branch to start work on an issue or when he commits
code, and he references the Jira issue in the branch name or the commit message, that issue
can automatically be transitioned from To Do to In Progress.
When a pull request is created, the related issue can be automatically moved from In Progress
to In Review status. And when it is merged, the issue can automatically transition from In
Review to Done.
In Crucible, when a review is started, the related Jira issue can be automatically transitioned
from In Progress to In Review. And when the review is closed, a trigger can transition the Jira
issue to Done.
Additionally, triggers can be set up to stop progress on an issue (that is, to transition from In
Review back to In Progress) when a review is rejected or abandoned in Crucible.

72 Customizing Jira Workflows

 Do not configure triggers for global transitions, unless you are confident that you understand
exactly how the trigger will affect the behavior of the issue. Configuring triggers for global
transitions can often result in an issue unexpectedly transitioning to the target status for the
global transition. For example, consider if you configured a 'Commit created' trigger for the
global transition to the 'In Progress' status. Committing code can happen at many stages
during an issue's lifecycle (e.g. writing the initial code, changing code after a review, etc. This
could result in the issue incorrectly transitioning to 'In Progress' out of a number of other
statuses.

73 Customizing Jira Workflows

 In a workflow, you can have multiple transitions coming into the same status, as shown here.
One can be executed manually by end-users, named “Start Progress” here, and it may contain
permission-based conditions and validators.

Another transition, simply named Progress, can be invoked by a trigger from a dev tool. It
won’t have conditions and validators because they would be ignored anyway. In order not to
confuse users and keep it simple, you can use a condition to hide this particular transition
from the user, since it will only be triggered from a dev tool. There is a condition called “Hide
transition from user” which will hide it.

74 Customizing Jira Workflows

 Let’s look at an example of how a trigger appears when configured in Jira.

Notice the number 1 next to the Triggers tab on the transition. And there are no conditions or
validators. If there were, they would be ignored. The Branch created trigger automatically
transitions the issue when a related branch is created in a connected Bitbucket repository.

75 Customizing Jira Workflows

 Now let’s look at Properties.

76 Customizing Jira Workflows

 Workflow properties can further customize and enrich your workflow. You can use Step
Properties to restrict certain actions, like editing or commenting, in a certain status, and
possibly only to certain people, like members of a group.

Transition properties can be used to do certain things during a particular transition.

We will now look at some common examples. But use properties sparingly and only when
business requirements warrant them, as they’re hard to maintain and can easily confuse
inexperienced administrators.

77 Customizing Jira Workflows

 Here are two examples of step properties. The ‘editable’ property can prevent issues from
being edited when they are in a particular workflow status. In this case, that’s the Approved
status. The Property “jira.issue.editable” is set to false.

In the bottom example, you can restrict commenting when the issue is in the status Awaiting
Release by setting the property “jira.permission.comment.denied” as shown.

Using the ‘permission’ workflow property, you can restrict permissions at the status level. You
can restrict various permissions to a project role, group, user, and more when an issue is in
that status. You restrict WHO can do what to an issue and WHEN they can do it. The best
practice is to use project roles.

Workflow properties allow you more granular control of permissions than permission schemes
but they are also harder to maintain. Also note that you cannot use permission properties to
grant more permission than what is allowed by the permission scheme, instead you are further
limiting what is allowed by the permission scheme.

78 Customizing Jira Workflows

 Here are two examples of transition properties.

Using the ’opsbar-sequence’ property, as shown on the left, you can change the sequence of
available transitions when viewing an issue. It is more intuitive to have the most used transition
first, for example to see Approve transition before Reject or Cancel.

There is also a property that enables you to limit the resolutions on a workflow by workflow
basis. Instead of listing all nine default resolutions defined in Jira administration (or more, if
your system has grown over time), you can show just a few, or all except for one. Or only one
or two. Here you see the property “jira.field.resolution.exclude” excluding two of the available
Resolutions from being shown to the user on a transition screen.

You can also use i18n properties to translate the text of the buttons on screens for transitions.

79 Customizing Jira Workflows

 There is one final thing to learn before we end this section on configuring transitions. The
Create Transition, which is the initial transition of a workflow, is special.

80 Customizing Jira Workflows

 First of all, it is automatically created when a new workflow is created from scratch. It is
always present and is executed when a new issue is created. The initial transition cannot be
deleted.

The initial transition is called 'Create' (if you created a blank workflow) or 'Create Issue' (if you
copied the system workflow).

You do not have to begin a workflow in the Open status. You can simply redirect the Create
transition to go to a different initial status, such as New Candidate shown in the image on the
right.

81 Customizing Jira Workflows

 The second thing that makes it special is that the Create transition does not have conditions.

Notice that in the workflow editor, you do not see the Conditions tab, to the left of Validators.
The validator says that “Only users with Create Issues permission can execute this transition.”
Jira just looks at the Create Issues permission in the project’s Permission Scheme to
determine who is allowed to create any issues in the particular project which uses this
workflow.

Therefore, it is not normally possible to set create permissions per Issue Type in Jira. But there
is a workflow customization that can be done, via a Marketplace app, to work around this
limitation, by inserting a different validator in the "Create issue" transition. This is reviewed in
one of the requirements in the next section.

Also notice that there are 3 essential post functions that are specific to a workflow's initial
transition but additional optional post functions can also be added to an initial transition.

82 Customizing Jira Workflows

 Finally, you can add post functions to the initial Create transition. This can be useful if you
need to perform processing tasks when an issue is created, such as setting the value of a
particular field.

But Post function webhooks do not fire if added to the Create Issue workflow transition. We
recommend that you configure your web hook to fire from the issue_created event instead.

83 Customizing Jira Workflows

 Now let’s look at examples of advanced workflow configurations. You will have a chance to
think about business requirements and how to solve them. Almost all of the solutions
exemplified rely on apps from the Atlassian Marketplace. Recall that apps can greatly extend
native Jira functionality to satisfy complex business requirements. Different apps are available
for Cloud, Server, and Data Center hosting options. Some apps are free and others paid. We
will not be mentioning apps by name since your requirements will differ and multiple vendors
offer similar functionality. So be sure to check out the Marketplace for the latest offerings and
compare features. You can search apps in various ways, such as by highest rating, most
popular or staff-picked, as well as by categories like admin tools, or just by name. Let’s get
started.

84 Customizing Jira Workflows

 Let’s first review all the elements. This diagram shows a portion of a Dev Workflow, where we
see 3 statuses: To Do, In Progress, and In Review. We also see various parts of transitions.

There is a transition called “Start Progress” from To Do to In Progress.

• There is a Condition on this transition that only the Assignee or users in the Developers role
can see and click it.
• Once it is clicked, there is a Transition Screen presented to the user and a Validator
ensures that the Due Date and Fix Version/s fields contain a value. If not, the transition's
post functions are not executed and the issue does not progress to In Progress.
• If validation passes, the default post functions are executed and an additional configured
Post Function adds a Comment to all linked issues (which use the “blocked by” link type) to
say that work has been started on this blocker issue.

There is another transition called “Start Review”. There is a Trigger configured on this
transition. When a review is started in Crucible, the related Jira issue is automatically
transitioned from In Progress to In Review.

And finally, there is a Step Property configured on the In Review status so that no one can edit
while the code is being reviewed.

85 Customizing Jira Workflows

 And here is a portion of an HR workflow. The HR team uses Jira to track on-boarding user
access requests.

There is a transition called “Start Progress” from ONBOARD to STARTED.

• There is a Condition on this transition that only users in the HR project role can see and
click it.
• Once it is clicked, there is a Transition Screen presented to the user and a Validator
ensures that the Employee ID, Full Name, and Email contain a value. If not, the transition
presents an error and stops processing.
• If it passes, there is a Post Function configured to create multiple Sub-Tasks and assign
each issue to the resource owner during workflow transition. Resources are configured as
project component. Each resource owner is configured as a component lead.

86 Customizing Jira Workflows

 To make the process even more efficient, you can customize the HR Sub-task workflow.

You can add a Post Function there to Close the parent issue automatically once all Sub-tasks
are Resolved. When each Sub-task gets Resolved one by one, a post function checks the
status of sibling Sub-tasks. If they are all Resolved, then it can transition the parent issue
automatically to Done (using the Close transition on the parent).

87 Customizing Jira Workflows

 So now is your chance to think through business requirements, one at a time, and consider
whether it might be met with a Condition, Validator, or Post Function on a transition, or
perhaps even a workflow property.

Here is our first requirement. What if you want to force the user to modify some field (Due
Date) while rescheduling a Task, using the Reschedule transition. Do we need a Condition,
Validator, or Post Function here?

88 Customizing Jira Workflows

 This requirement needs a Validator because it must happen during the Reschedule transition.
Also, the user must change the field. This can be done with a Field has been modified validator
from a Marketplace app.

89 Customizing Jira Workflows

 Let’s take a look at the second requirement. After a ticket is closed, it’s duplicates should
inherit the Root Cause, and the final comments. This is useful for reporting purposes. We need
a way to copy the value of one field to another, between two related issues, such as an issue
link, Parent/Sub-Task or Epic/issues in Epic. In different requirements, we may need to copy
fields within the same issue.

Is this an example of using a Condition, Validator, or Post Function?

90 Customizing Jira Workflows

 Don’t be fooled by the word “while” which might again imply the use of a Validator. The point
is that you want this action to happen after everything else has happened. The user must first
enter the Root Cause and Comment on the current issue before that information can be
copied to its duplicate issues. So this is an example of using a Post Function, because it is
happening after other processing has completed. Different solutions can be found in
Marketplace to meet such needs, including:
• Copy field value to Sub-tasks from the parent or Copy field from parent to Sub-tasks.
• Copy field value to/from linked issues
• Copy value from field to field in same issue
Such post-functions are also often used on the create transition of Sub-task workflows when a
field value is dependent on the parent’s value.

91 Customizing Jira Workflows

 And what if we wish to actually close those Duplicates? We need a way to automatically
transition linked issues. What would we need?

92 Customizing Jira Workflows

 Again, we need a Post Function. There are several solutions of post functions from
Marketplace apps: Transition Issue, Transition parent issue and Transition linked issues.

Other use cases include transitioning all "Blocked By" issues to In Progress status when the
"Blocks" issue is Resolved. Or transitioning the parent issue to On Hold when a Sub-task is
placed On Hold. You can also trigger a transition on the current issue to move it one step
further in its own workflow.

93 Customizing Jira Workflows

 Here is another requirement. We shouldn’t allow users to start working on an upgrade task
until all of it’s prerequisites, or other dependencies, are completed.

Should this be a Condition, Validator, or Post Function? What do we need to check?

94 Customizing Jira Workflows

 The solution requires a Condition which, if not met, will not show the Start Progress transition
at all. If it is not visible, then it cannot be used to start the work. So we need to add a workflow
condition on the Start Progress transition which checks the status of that task’s linked issues –
based on the issue type, link type, and selected statuses. If the criteria matches, then the
transition will be available to the user. If not, the transition will be hidden. There is a Status of
Linked Issues condition which can accomplish this.

95 Customizing Jira Workflows

 Our next requirement. Allow only Auditors to edit issues in the In Review status.

Should this be a Condition, Validator, or Post Function?

96 Customizing Jira Workflows

 It should be none of those. This is actually a good example of using a Step Property. Step
Properties can restrict certain actions in a certain status, and only to certain people if desired.
In this case, we want to restrict so that only the members of the Auditors group should edit
issues in the In Review status. The Step Property would be configured as
jira.permission.edit.group.1=Auditors.

97 Customizing Jira Workflows

 What if the requirement is that only testers can create Bugs in a particular project, but anyone
else can create Tasks? Can you add a Condition on the Create transition?

98 Customizing Jira Workflows

 This one is a little tricky. Remember that there is no Condition on the Create Transition. And it
is not possible to set issue creation permissions per Issue Type in Jira. The Create Issues
permission in the Permission Scheme applies to all issue types in a project.

However, we can satisfy this requirement by inserting a validator on the initial Create
transition of a workflow.

Two different solutions are available from a Marketplace app.

• The validator Users in field are (not) in a project role is suitable when we have a different
workflows per issue type, or when we don't want to set different issue creation permissions
in the same workflow.
• Boolean validator with math, date-time or text-string terms is suitable when we share a
workflow among different issue types, and want to set different issue creation permissions
per Issue Type and Project Role in a same workflow.

99 Customizing Jira Workflows

 When Tests fail, let’s create new Bugs automatically and link them to the original issue, in
order to streamline the QA process and enhance collaboration between Testing and
Development teams.

Which transition element do we need?

100 Customizing Jira Workflows

 Again, don’t be fooled by the word “when” . This is not a Validator, but a Post Function
required because we need to do post processing – to create new issues in Jira.

To achieve this, we can add the Create a Linked Issue post function, which allows you the
create new issues, copy fields from the original to the new issue, and connect them with an
issue link.

Such a post function can also create issues related to each other, such as creating Sub-tasks,
or creating Issues in an Epic.

101 Customizing Jira Workflows

 Another requirement may come from purchasing. A request will require approval from
management only if the price exceeds $10,000. Otherwise, there is no approval required and
we can go to the next step in the workflow process. What do we need to configure?

102 Customizing Jira Workflows

 In this case, we can use a Condition that checks the value in the custom field Purchase Price.
If the purchase price is greater than the required amount, then show the Approve/Reject
transitions, otherwise, do not show them and go to the next step in the workflow process.
Another example is showing a special escalation transition if the Priority is Critical.

These are examples of using Field Value Conditions.

103 Customizing Jira Workflows

 Reporters should only be able to select a single component (for example Design or Security)
when creating Bugs, so that the right component lead can be assigned. How do we satisfy this
requirement?

104 Customizing Jira Workflows

 This requirement suggests the use of a Validator since the user needs to do something while
the transition is occurring. Normally, Components is a multi-value system field, so the user
could select multiple values during a transition, including the Create transition. But this
requirement says that he should select only one. This can be achieved with the Field has single
value validator, from a Marketplace app. Another common requirement is that developers
should only select a single version when resolving Bugs. Fix Version is likewise a multi-value
system field, but the user can be forced to select only one value through the use of this
Validator.

105 Customizing Jira Workflows

 This requirement says that only the requestor’s manager can approve a Change Request, and
that manager is listed on the request itself, hence it varies on an issue-by-issue basis.

106 Customizing Jira Workflows

 This is a conditional requirement. Only some people should be able to see and use the
Approve transition. So this needs a Condition. We can accomplish this requirement with the
User is in Custom Field Condition, from an app. Unless the user is listed in a particular custom
field (either a single User picker or a Group picker field), then they will not be able to see and
therefore execute the Approve transition. And you can also decide whether to allow only the
user in the field, or anyone except the user in the field.

107 Customizing Jira Workflows

 Here is our final example. Mark the fix versions field as required, but only when the resolution
is set to Fixed during the transition.

Remember that fields can be made required via the field configuration, but this will make them
always required, wherever and whenever they appear on screens. Another way is to use a
transition screen and a fields required validator. This will make the field required always
during that transition.

But here we want to make the Fix Version/s field conditionally required during a transition –
only when the resolution is set to the value Fixed.

So we need to require a field based on the value populated in another field. How can we
achieve this requirement?

108 Customizing Jira Workflows

 We solve that by using a server-side validator available through the behaviors functionality of
a Marketplace app. We can mark the Fix Version/s field as required, but only when the
resolution is Fixed, because it doesn’t make sense to require a Fix Version when the resolution
is Won’t Fix.

Some examples of behaviors are the following:

• Hide/show a certain field based on the value populated in another field during the
transition.
• Update the select list option based on the value of another custom field during the
transition.
• And as we see here, make another field required based on the value populated in another
field during the transition. And there are many other types of Behaviors.

That was our final advanced example of configuring transitions.

109 Customizing Jira Workflows

 Let’s now turn our attention briefly to Jira Service Desk Approvals and Automation. As we
have seen, we can build approval and automation-type functionality into any Jira workflow, by
adding conditions, validators, and post functions as needed. But Jira Service Desk specifically
ships with native approval functionality and automation rules which are powerful and easy to
configure. We will look at them in this module. These out-of-box features still allow for
workflow customization and extension. But it is good to be aware of the power of Service
Desk built-in features.

110 Customizing Jira Workflows

 First, let’s review workflow permissions related specifically to Jira Service Desk projects. To
use workflows in Jira Service Desk projects, users need:
• Browse Projects permission – to see the project at all.
• And they need Transition Issues permission to see any of the transitions. This is just like in
Jira Core and Jira Software.
• But specifically in Jira Service Desk, users also need Jira Service Desk Application access
to be able to see any transitions in Service Desk workflows and to see other features like
Queues, SLAs, etc. Namely, they have to be licensed agents.
• If users have Transition Issues permission, but not Service Desk Application access, they
will not see workflow buttons.
• Finally, in addition to the above, users need any other permission, groups, project roles as
required by workflow Conditions or Validators.

111 Customizing Jira Workflows

 Next, we need to understand the mapping of Request Types to Issues Types to Workflows to
Workflow Scheme in a Service Desk project.

JIRA Service Desk provides a set of default request types configured for each project
template. You can configure the default request types or add new ones as needed. Each
request type in a service desk is based on a Jira issue type.

Note that a single JIRA issue type can be the basis for many different request types. In this
example, “Get IT help” request type and “Set up VPN to the office” request type are both
mapped to the single Service Request issue type.

112 Customizing Jira Workflows

 And as we already know, issue types are mapped to workflows in a workflow scheme.

113 Customizing Jira Workflows

 And workflow schemes are associated with one or more projects.

In a Service Desk project, therefore, Request Types are mapped to Issue Types, Issue Types
are mapped to Workflows in a Workflow Schemes, and the Workflow Schemes are associated
with projects.

114 Customizing Jira Workflows

 There are default Service Desk workflows which feature native, out-of-the-box, approval
functionality, such as the two shown here. They make it easy to add approvals to certain
steps. Some Service Desk requests might need approval before your team can work on them.
For example, an IT manager might approve new system accounts. People don't need a Jira
Service Desk license to approve requests—they just have to be customers of the service desk
project.

Let’s see how Service Desk approvals are configured.

115 Customizing Jira Workflows

 Here's how approvals fit into the Service Desk request workflow:
• A person sends a request via the customer portal or email.
• When the request transitions to a status that needs approval, the approver is notified that
there's a pending approval. In this case, the workflow already begins with an approval
status called “Waiting for Approval.”
• In the customer portal, the approver approves or declines the request.
• The request transitions to the next status in the workflow, and the customer is notified
about any comments that the approver added.

Let’s see how each element is configured.

116 Customizing Jira Workflows

 To require approval for a request, you can add an approval to the workflow that the request
follows. You can choose when in the workflow approval is required. In the workflow shown,
the request goes to approvers right after it's created. The following steps are performed:
• Select the status you want to add an approval to. Here, it’s the Needs Approval status.
• Make sure the status you want to add the approval to has at least two transitions: one for
Approve and one for Decline. You might add another transition if you'd like an agent to be
able to transition the request without a response from an approver.
• Select Add approval.
• Complete the fields, then click Create.

Approval transitions don’t display screens on the Customer Portal, so a Resolution should be
set automatically if the request goes to a Done status.

117 Customizing Jira Workflows

 Here are the elements that must then be configured.

You must choose who can approve the request. You can have customers choose approvers
from a list, or you can send requests to a pre-set list of approvers. For example, the customer
can search for their manager in a list. Either way, a User Picker field used for approvers must
be added to the request form. By default, projects come with the Approvers field, but a
different field can also be created and configured. If the user is shown on the request type,
customer can choose approvers. But you must first ensure that customers can search for
them. Go to Project Settings > Customer permissions and make sure the setting “Who can
customers share request with?” is set to “Any customer or organization, by searching in this
project.” Or otherwise, you can set up a pre-set list of approvers by adding a user picker
custom field to the request and clicking Actions > Hide. Then enter the users who can approve
the request and click Set. The pre-set approvers will automatically display in the issue and be
notified when the request needs approval.

You also choose the required number of approvers - whether to consider the request
approved after all approvals or a certain number of approval(s).

Finally, you choose the approved and declined transitions. Note also that multiple approval
steps can be configured in a workflow.

118 Customizing Jira Workflows

 Service Desk ships with powerful automation rules that helps with repetitive tasks and the
sending of important notifications. The rules can be broken down into ones that Transition
Issues, Send Alerts, or Update Issues.

119 Customizing Jira Workflows

 There are two rules to transition issues. “Transition on comment” is used when a comment is
added to an issue. Then the rule automatically transitions the issue so it's clear who it's waiting
on.

For example, if the request is currently in the status Waiting For Customer, and the customer
adds a comment on the Customer Portal, then the request is automatically transitioned to
Waiting For Support.

The second rule is to “Re-open on customer comment.” When a comment is added to a

resolved issue – for example the Reporter notes that the resolution does not actually fix the
problem – then this rule will re-open the issue.

120 Customizing Jira Workflows

 There are three rules to send alerts. The first one is “Be aware of urgent issues.” This rule alerts
you to urgent issues when they are raised, so you can address them immediately. The second
one – “Keep on top of SLAs” – alerts you to at-risk SLAs – for example those that are about to
breach in 30 minutes – so you can stay on top of important issues. Finally, the rule “Set
customer expectations” lets customers know of expected resolution times when they raise a
request.

121 Customizing Jira Workflows

 And there are two rules to update issues. The first one is “Update when a linked issue
changes”. When the status of an issue changes, this rule will add a comment to its related
issues. You can customize this to resolve related issues, change which issues are updated, and
more.

The second one is “Triage requests sent by email.” It automatically sets the right request type
based on keywords in the requests sent by email.

122 Customizing Jira Workflows

 And finally you can create your own custom rule.

123 Customizing Jira Workflows

 Each rule works in a similar way; it performs actions based on specific events and conditions.
Rules consist of a set of When, If, Then configurations.
The When portion denotes events that trigger the rule, such as When a comment is added or
edited, When an issue is created or When the status is changed. You can have multiple
triggers in a rule.

124 Customizing Jira Workflows

 The If portion denotes optional conditions. That is, once the rule is triggered, check if certain
conditions are met. For example, If the issue matches certain fields (Status, Reporter, Priority)
or a JQL query. Or If the User Type is customer or agent, or not a customer or not an agent.
There are other conditions depending on the triggers selected. For example, if the comment
visibility is internal or external or if the comment contains a key phrase. Condition can have
branches (like “else if” statements). Each branch will have its own action (the Then).

125 Customizing Jira Workflows

 The final portion is Then which denotes the action. What happens when the rule is triggered
and the condition is met? The rule can transition an issue, add comments, alert users, edit the
request type, edit issue, send email or webhook, or auto approve or decline requests.

126 Customizing Jira Workflows

 Who configures rules? Either Jira Administrators or Project Administrators can configure
rules.
And rules can be configured to run as either a project default user – such as a Jira
Administrator or an agent – or as the user who triggered the rule.

127 Customizing Jira Workflows

 Now let’s look at why you might use automation instead of the type of workflow customization
we have discussed thus far.

In regular workflow customization, some things can be automated, such as triggering

transitions in Jira Software when events occur in Development tools. But the primary focus is
on what happens when the user presses the transition manually.

In contrast, much of the usefulness of automation is that it occurs behind-the-scenes without

user intervention. You don’t have to wait for the user to click a transition, it can occur
automatically based on the right set of conditions. Nor do you have to set up a saved filter and
a subscription in Jira to know when SLAs are about to breach. You can have an automation
rule do the heavy-lifting.

128 Customizing Jira Workflows

 Secondly, automation rules can easily be configured by project administrators. As we will see,
Project Administrators have limited workflow customization ability if the Extended Project
Administration permission is granted. We will look at that in the next module. But even if it is,
they still cannot do everything in the workflow – like add Conditions, Validators, Post
Functions, or Transition Screens. But with automation rules, Project Administrators have much
more power and control to actually create and maintain the rules.

129 Customizing Jira Workflows

 And finally, JSD automation provides a lot of rich out-of-box functionality – such as
transitioning issues, adding comments, and alerting users – which is easier to configure and
maintain. Though you may achieve the same goals by customizing Jira workflow, as we have
seen, this oftentimes involves the use of Marketplace apps, and the knowledge of how to set-
up and maintain all the transition configurations.

It’s worth noting that you can use both together – you can make customizations to default
Service Desk workflows, and also take advantage of automation rules, because not everything
can be achieved with Service Desk automation. Just be careful to understand what could
conflict. And of course, not all projects are Service Desk projects. But if you have a choice,
then try to use the automation rules.

Let’s now look at an example of how the same business requirements can be achieved both
ways – using customization or using automation.

130 Customizing Jira Workflows

 Let’s say that your Support process entailed creating an original support ticket and then
creating and linking all duplicates to it. Then, when the original ticket was being resolved, you
wanted to comment on and resolve all the duplicates. Here is how that would be done.

You would edit the workflow of the original issues and add a post function or two, from a
Marketplace app, in order to add a comment to all linked issues of a particular link type
(duplicates) and then to actually transition those duplicate issues to their resolved status. To
accomplish this, you need to be a Jira Administrator and have a Marketplace app, and it takes
quite a few steps to accomplish: first to create and then to maintain.

131 Customizing Jira Workflows

 Alternatively, with Jira Service Desk installed, you can set up an automation rule in a Service
Desk project. This automation rule is the equivalent of the previous workflow customization.
It’s based on the preset “Update when a linked issue changes” and modified to actually close
the duplicates. This is how to read it.

When a linked issue is transitioned (namely the original issue)

If that original issue now has a resolution (i.e. it is being resolved) AND the link type is
duplicates,
Then a comment is added to all the duplicate issues (saying that the original issue was
resolved) and the duplicate issues themselves are resolved.

The rule runs immediately when triggered. And you can further customize it, as well. It comes
natively in Service Desk and is easy to configure, modify, or disable in the future.

132 Customizing Jira Workflows

 So finally, let’s look at some automation best practices. Make sure the person configured to
run the rules has permission to complete all the actions taken by the rule. If the automation
rule is to transition issue and the transition in the workflow has conditions and validators,
make sure the user executing the rule meets the configurations in the workflow. Otherwise
the automation will fail to execute.

By default, rules can trigger other rules. You may need to disable this to prevent rules from
triggering each other, which could lead to infinite loops.

If business requirements can be satisfied by customizing a workflow or using Service Desk

automation out-of-box functionality, then use the latter instead.

And finally, test and evaluate the automation in a staging environment first before applying in
production. We’ll talk more about that in the upcoming module.

133 Customizing Jira Workflows

 So let’s move on to Editing and Testing of workflows.

134 Customizing Jira Workflows

 First, we need to know who can edit workflow and under what circumstances. Let’s look at
the first one.

135 Customizing Jira Workflows

 Jira Administrators have full access to everything that is workflow-related. They can create
new workflows, edit all the elements of a workflow (including conditions, validators, post
functions, triggers, transition screens, and properties). They can create and edit workflow
schemes and associate workflow schemes with projects. They can also create and delete
Statuses.

136 Customizing Jira Workflows

 Project Administrators have limited workflow editing capabilities – only when “Extended
Project Administration” permission is granted in the project’s permission scheme. First, let’s
see how this setting appears.

137 Customizing Jira Workflows

 Extended Project Administration appears under the Administer Projects permission in the
project’s permission scheme. It is enabled by default. But Jira administrators can disable it via
the checkbox. The setting allows project administrators limited editing of project workflows
and screens. So assuming that this permission is granted, let’s see what they can actually do.

138 Customizing Jira Workflows

 Here is a good summary. When Extended Project Administration is granted, then project
administrators can:
• Edit the workflow associated with their project (if its unshared)
• Create, update, delete transitions
• Add existing statuses to their workflow
• Delete statuses that aren’t used by their project’s issues
But they can’t:
• Edit shared workflows or the Jira default system workflow
• Select or update a transition screen
• Edit transition properties, conditions, validators, or post functions
• Create new statuses
• They also cannot create, change, delete, or associate workflow schemes with project.

139 Customizing Jira Workflows

 Finally, in Jira Software, Board Administrators who are also Project Administrators can affect
workflows by adding Statuses to agile boards which use the Simplified Workflow. When they
add a Status to the board, they are in effect adding it to the underlying workflow. Let’s look
closer.

140 Customizing Jira Workflows

 Remember that boards are tied to the underlying workflow. The top shows the sprint board and
the bottom shows the workflow. No matter which workflow is being used by the board, board
administrators can add, remove, or rename columns and change the status mapping. In this case,
the Board Administrator could add a new column called QA, for example, and map the existing
Resolved status to it, so that each column only displays one Status.

The Board Administrator does not have to be a Project Administrator to do this.

141 Customizing Jira Workflows

 But let’s say the team wants to add a new status which doesn’t currently exist in the workflow;
like the Testing status.

Board Administrators, who are also Project Administrators, can add Statuses to a board, if the
board is using the Simplified Workflow. They would add the status and map it to a column
accordingly.

142 Customizing Jira Workflows

 Adding a status to the board automatically adds that status to the underlying workflow, and to
the Jira instance itself, if it doesn’t already exist. So be watchful of users creating a lot of statuses.

Again, adding a Status to a board is only possible if the board uses the Simplified Workflow, and
the workflow cannot be shared. And once again, the Board Administrator must also be a Project
Administrator.

143 Customizing Jira Workflows

 Here is the summary of who can edit workflows, and under what circumstances.

144 Customizing Jira Workflows

 It is possible to switch the workflow of a board to the Simplified Workflow if:
(1) there is only one project being viewed by the board
(2) that project uses a Jira workflow scheme which only has one workflow for all issue types,
(3) the workflow only uses post functions, validators, and conditions that are provided by
Atlassian – and not by apps
(4) and the existing workflow has at least one outgoing transition for each status

145 Customizing Jira Workflows

 Now let’s look at building new workflows. It is easier to copy and customize an existing
workflow rather than creating one from scratch.

Aim to use a small set of standard workflows. For example, there’s no need to have twelve
software development workflows when most of your dev teams follow the same process.

Start simple and add on statuses, properties etc., only when the requirements warrant it.

146 Customizing Jira Workflows

 An active workflow is a workflow that is currently being used by one or more projects (in an
active workflow scheme). When you edit an active workflow, Jira first creates a draft that you
modify. When you've finished, you can publish your draft and, optionally, save your original
workflow as an inactive backup.

To edit workflows, you can use either diagram mode or text mode. Diagram mode is easier to
understand and work with, especially for beginners. Text mode is a bit more advanced and
shows the difference between steps and statuses. Either way you choose, you should finalize
the diagram for end-users, so it appears intuitive when they click on the View Workflow link
on an issue.

An inactive workflow is one that is not currently being used by any projects. It must first be
activated. Because there are no issues currently transitioning through an inactive workflow,
you can easily modify steps and statuses.

Inactive workflows need to be activated to use them in Jira. Activating is the process of
mapping the workflow to a workflow scheme, and then associating the workflow scheme with
a project. Issues will then need to be migrated, as we will see shortly. This is done by Jira
Administrators.

147 Customizing Jira Workflows

 There are some limitations to editing active workflows.
• You can only edit the description (not the name) of an active workflow.
• Workflow steps cannot be deleted in an active workflow.
• The associated Status of a step cannot be edited and the Step ID cannot be changed.
• And, if a step has no outgoing transitions (global transitions are not considered), it cannot
have any new outgoing transitions added.

148 Customizing Jira Workflows

 Let’s look at working with statuses. Statuses are global objects. Changing the name of a status
on one workflow also changes it in all other workflows that use that status.

Check before removing a status from a workflow, that it’s not being used in other places, like
filters and dashboards.

Removing a status from a copy of an active workflow will cause issue migration when the
modified workflow is associated with a project. At that time, Jira will check if there are issues
in the status that was removed. That means migrating issues.

149 Customizing Jira Workflows

 This diagram portrays migrating issues being mapped from statuses in the old workflow to
statuses in the new workflow. The Jira administrator is prompted to select which status in the
new workflow issues should be mapped to. And to select this for each issue type that will use
the new workflow in the project. If there are a lot of issues to migrate (in the thousands), it
could take some time. Before migrating, it’s a good idea to run the database integrity checker
and backups.

150 Customizing Jira Workflows

 It is always best to build and test workflows robustly on a test Jira environment (development
or staging) instead of working in a live Jira instance.
Alternatively, you can use a test project to test your workflows first in a production instance
before implementing the change in an active project. If you do this, you may need to create
test users and put them into project roles. Also ensure that permission scheme is set
appropriately and that notifications are disabled.
Always use caution when editing and publishing the draft of an active workflow to make sure
you understand the implications, especially if it’s shared.
And save a backup copy when publishing in production, so you can refer back to it later if
needed.

151 Customizing Jira Workflows

 If you are using a staging Jira instance, you can import and export your workflow between
instances as either XML or workflow format. You can also share on the Atlassian Marketplace.

But note that not all workflow functionality will be exported/imported, depending on the
format and use of apps. Importing XML workflows is supported for Server only.

152 Customizing Jira Workflows

 Finally, test everything thoroughly.

Step through each status and transition, checking if all Conditions, Validators, Transition
Screens, and Post Functions behave as expected. Check Triggers and their connected
Development Tools. And see if the right event was fired and the right notifications were sent.

You may need to use virtual users to test different permissions and memberships in groups
and project roles.

153 Customizing Jira Workflows

 Let’s review some Common Problems and Troubleshooting tips.

154 Customizing Jira Workflows

 There are many reasons a workflow could be behaving unexpectedly. Here are some
troubleshooting basics.
• Try to replicate the problem; preferably in a comparable staging instance.
• View the workflow in the workflow editor.
• This allows you to see all the statuses and transitions into and out of each status.
• Similarly, check validators, post functions, and triggers to see what is configured.
• Check step and workflow properties, if any.
• In Jira Service Desk, check automation rules and approval functionality, possibly adding
test users into the Approvers field.
• View the Audit Log for recent workflow changes.

155 Customizing Jira Workflows

 Permission-related problems are common in workflows. You may need to check the
permission scheme and project roles. Here are some examples.
• If the user cannot see any transitions, check the Transition Issues permission. In Jira Service
Desk projects, make sure the user has Service Desk Application Access.
• If the user cannot see one transition, check permissions or project roles in a condition.
• If the user cannot drag cards to a particular column on a board, then the transition
condition is probably not being met in the underlying workflow.
• If no one can edit Closed issues, check the Step Property “jira.issue.editable”
• If some users cannot comment in a particular status, check the Step Property
“jira.permission.comment.*”

156 Customizing Jira Workflows

 Here are some possible misconfiguration problems.
• If the user cannot add / update a required field during a transition, the field may not be on
the transition screen.
• If the user is not notified when a transition occurs, perhaps the wrong event is being fired or
the user is not listed as an event recipient in the project’s notification scheme.
• And if a saved filter or gadget is returning data errors, perhaps a workflow status was
removed or renamed.

157 Customizing Jira Workflows

 And finally, a look at administrator problems.
• If resolved issues are showing as Open, then the workflow might not be setting the
Resolution field.
• Conversely, if open issues are showing as Resolved, then the workflow may not be clearing
the Resolution field.
• If, after editing a workflow, other projects and issue types were affected, then the workflow
was probably shared and you may now need to undo the changes.
• If a board column shows no issues, perhaps the status was removed from the workflow but
the column was not.
• And if the workflow is returning strange errors in the logs, perhaps a Marketplace workflow
app is causing the issues.

158 Customizing Jira Workflows

 In this final module, let’s look at workflow best practices.

159 Customizing Jira Workflows

 • Check if workflow is shared before making changes, to ensure your customizations won’t
impact other projects and have unintended consequences.
• Explore Marketplace apps to extend workflow functionality.
• But use out-of-the-box features wherever possible, because things may break if the app is
disabled.
• Enable Extended Project Administration so project admins can help maintain their own
workflows.
• And document workflows. This helps training and troubleshooting without having to
provide access to workflow editing.

160 Customizing Jira Workflows

 • Add statuses only when you need them. Too many will confuse users. Reuse existing
statuses whenever possible and add new ones sparingly.
• Understand and limit who can add new statuses. For example, Board Administrators who
are also Project Administrators can add Statuses through the board if it is using the
Simplified Workflow.
• Use intuitive, more generic & reusable names.
• Make sure all statuses have outgoing transitions. Don’t create statuses that don’t transition
out, unless it is the final status and should not allow reopening.
• Ensure all statuses are mapped appropriately to columns on agile boards.

161 Customizing Jira Workflows

 • Add transitions only when needed; keep them simple and maintainable
• Use intuitive transition names
• Use common and global transitions which have the same configuration settings and are
therefore more scalable and maintainable.
• Ensure post functions are in the correct order
• Ensure each workflow sets and clears the Resolution field appropriately
• And finally, use project roles, rather than individual users or groups, in conditions and
validators.

162 Customizing Jira Workflows

 That’s it for this Skillbuilder course on Customizing Jira Workflows.

163 Customizing Jira Workflows