Jira Strategy Admin Workbook - Templates For The Application Administrator To Set Up, Clean Up, and Maintain Jira (PDFDrive)

JIRA Strategy
Admin Workbook
Templates for the application administrator to set up,
clean up, and maintain JIRA
Rachel Wright
JIRA Strategy Admin Workbook
Templates for the application administrator to set up, clean up, and maintain JIRA
jirastrategy.com
Copyright @ 2016 by Industry Templates, LLC
Cover Photo and Design by: Rachel Wright

The cover photo was taken during a visit to the Big Cypress National Preserve in southern Florida.
ISBN-13: 978-1539090229
ISBN-10: 1539090221
Download the worksheets, templates, and companion materials for this book from the JIRA Strategy
Store at: jirastrategy.com/store.
Copyright
All rights reserved. No part of this book may be reproduced or transmitted in any form or by any
means without the prior written permission of the publisher, except in the case of brief quotations
embedded in articles or reviews.
Trademarks
JIRA Strategy Admin Workbook, the publisher logo, and the cover image are trademarks of Industry
Templates, LLC.
Any trademarks, service marks, product names, or named features are assumed to be the property
of their respective owners. They are used only for reference and there is no implied endorsement.
The author and publisher are not associated with any product or provider mentioned in this book.
Notice of Liability
The information in this book is distributed on an "As Is" basis, without warranty. The publisher and
the author assume no responsibility for errors or omissions, or for damages resulting from the use of
the information contained in this book. Use of the information and instructions contained in this
work is at your own risk.
Format
The content is published in a number of formats. Some content that appears in print may not be
available in electronic formats and vice versa.
I dedicate my first book to Chris, who changed the trajectory of my life forever.
About the Author
Rachel Wright is an entrepreneur, process engineer, and Atlassian
Certified JIRA Administrator. She started using JIRA in 2011 and
became a JIRA administrator in 2013. She is the owner and founder
of Industry Templates, which helps companies grow, get organized,
and develop their processes.
In 2013, Rachel founded the Northern Virginia Atlassian User Group.
In 2016, she moved on to assist the User Group program as a

volunteer consultant and as a member of the User Group Leader
Council. Also in 2016, she participated on the Atlassian Summit
Program Selection Committee, helping to select conference sessions
for the "Extend & Scale" and "Team & Culture" tracks.
Atlassian Awards
Atlassian Certified JIRA Administrator
jirastrategy.com/link/cert-badge
March 2016
Winner, "Community Champion"

Atlassian User Group Leader Award
November 2015
Winner, Atlassian User Group "Founder's" Award

November 2015
Winner, "Play, as a Team" Atlassian

User Group Leader Award
September 2014
Winner, Atlassian User Group Summit

Registration Competition
September 2014
Editors
The wonderful reviewers and editors who vetted my recommendations, clarified my thoughts, and
helped make this book a useful resource are:
Matt Doar
Chief Toolsmith at ServiceRocket and author of Practical JIRA
Administration (jirastrategy.com/link/practical-admin)
My favorite thing about JIRA is it’s better than spreadsheets and much
better than email for keeping track of what you and the team are doing.
The best thing about JIRA is the community.
I’ve made plenty of configuration mistakes; enough to fill a book in fact! I

see things in JIRA each week that make me smile (or groan). The funniest
thing however is the credits screen. In JIRA Server go to the bottom of
any screen, click “About JIRA” then click “Roll Credits.” It’s quite
unexpected and fun.
André Lehmann
Certified JIRA Administrator, Evangelist
My favorite thing about JIRA is its flexibility and usability.
I once upgraded my test server and forgot to change the database

connection. This unintentionally upgraded the production database. Since
this occurred in the middle of the workday, I had to upgrade the
production application immediately.
Gregory Van Den Ham

Information Technology Manager, Chicago Atlassian User Group Leader
My favorite thing about JIRA is that it allows me to centrally manage the

work for my teams. I’m able to judge workload, prioritize and coordinate
across teams. I can give accurate estimates and easily negotiate timeline
impacting conflicts.
My most interesting experience was when I realized workflow steps were

shared across workflows. I didn’t realize statuses were linked to unique id
numbers. I renamed the “Open” status in production one Saturday, and
quickly changed it back after receiving a few support calls.
Susan Hauth
JIRA Queen
My favorite thing about JIRA is how it can be easily deployed to all teams
in your organization, including software teams, HR, Finance or
Marketing. JIRA is the most user friendly tool I have ever worked with.
I was told that the JIRA Expense Claim system I created was too
complicated. But then I watched the Sales team (our least technical user
group) use it quickly to process their claims. There’s nothing like expense
reimbursement to motivate people!
Billy Poggi
Servant Leader, Adventurer, Northern Virginia Atlassian User Group Leader
My favorite part of JIRA is what it accomplishes. It enables teams to build

the world changing future through synergizing teams and their abilities.
Using JIRA, I enabled the flow of information from chaos into an organized
and referenced source for a fast paced research project full of talented
people. JIRA, and its abilities to integrate with many systems, brought
light to the great efforts of the teams and helped turn research into
solutions!
Kimmoy Matthews
Master of making things easy to understand
I always ask my potential clients what do they use to manage their

projects and track bugs. When they tell me they use spreadsheets or
something other than JIRA, I know I’m up for a bigger challenge than
expected.
I can hear the cheers from everyone in the JIRA community when I
express that one of my favorite quotes is “If you can’t explain it simply,
you don’t understand it well enough.” ~ Albert Einstein
Sheri Breault
Master of making things look good
My favorite part of JIRA is the organization and structure it provides. It’s

exciting how many non-technical things you can track with it.
JIRA appeals to my eye for design and this book to my instructional

materials and organizational background. As for the book itself, as
technical as it is, it's fairly easy to read and chocked full of funny insights.
Special Thanks
Additionally, I’d like to thank:
• Jobin Kuruvilla author of the Jira 7 Development Cookbook (jirastrategy.com/link/jira7-dev-
cookbook) for encouraging me to write this book and answering all my first time author
questions.
• Hatim Khan, Technical Architect at The College Board, and Mariano Goldman Senior Java
Developer at Atlassian, for introducing me to JIRA.
• My cat Lynx, who caused the mistake featured in the “Announcement Banners” section.
Pledge 1%
Pledge 1% is a corporate philanthropy movement dedicated to making the
community a key stakeholder in every business. As a proud member of this
program, Industry Templates, LLC annually donates 1% of sales, product, and
employee time to help the community. As the owner and founder of Industry
Templates, LLC, I'm happy to have built a company that makes community
involvement a priority. My mother taught me that there is a right way to do
things. She taught me to be thankful for what I have and use my skills to help
others. I want to help and to motivate others to do the same.
Pledge 1% is an effort spearheaded by Atlassian, Rally for Impact, Salesforce

and Tides to accelerate their shared vision around integrating philanthropy into businesses around
the world. They believe pledging a small portion of future success today can have a huge impact on
tomorrow. Pledge 1% offers companies turnkey tools and best practices, making it accessible for
any company to incorporate philanthropy into their business model. To learn more or to take the
pledge, visit: pledge1percent.org.
Are you part of a non-profit who needs JIRA help? Contact Industry Templates, LLC at:
info@industry-templates.com.
Table of Contents
How I Fell in Love with JIRA ........................................................ 1

Introduction: A Tale of Three Companies ............................................ 2
Who This Book Is For........................................................................... 2
What You'll Need ................................................................................. 3
Book Structure .................................................................................... 3
Terminology ....................................................................................... 4
Conventions ....................................................................................... 5
Worksheets, Templates & Companion Materials .................................. 5
Errata .................................................................................................. 6
Comments, Feedback, and Questions .................................................. 6
Part 1: Setting the Foundation .................................................... 7

Establish an Advisory Board ................................................................ 7
Ideal Board Makeup ............................................................................. 8
Role of the Board ................................................................................ 8
Establish Standards ............................................................................. 8
Handle Sensitive Information ................................................................ 9
Support Metrics ................................................................................... 13
Sample JIRA Support Project Set Up ................................................... 15
Customer Satisfaction Survey ............................................................... 19
Sample Workflow: JIRA Support ........................................................... 21
Appoint Ambassadors .......................................................................... 23
User Access Strategies ........................................................................ 23
User Types ......................................................................................... 24
Test Users .......................................................................................... 24
Define Admin Users ............................................................................. 25
Project Leads ...................................................................................... 27
External Users .................................................................................... 33
Character Users ................................................................................... 35
Roles and Groups ................................................................................. 38
User Management ................................................................................ 40
Other Users ......................................................................................... 43
Single Sign-On .................................................................................... 43
Shared Access ..................................................................................... 44
Part 2: Project Configuration ....................................................... 45

Name Your Schemes ............................................................................ 45
JIRA Terminology ................................................................................. 46
Projects ................................................................................................ 47
Strategy for Creating New Projects ......................................................... 47
Name Your Project ............................................................................... 50
Project Categories ................................................................................ 51
Share Project Schemes and Assets ......................................................... 52
Establish Scheme Defaults .................................................................... 53
Project Configuration Strategy ............................................................... 53
Configure Your Project .......................................................................... 59
Issue Types .......................................................................................... 66
Best Practices ...................................................................................... 66
Issue Type Schemes............................................................................. 67
Name Your Issue Types and Schemes ..................................................... 69
Statuses ............................................................................................... 70
Best Practices ...................................................................................... 70
Status Categories................................................................................. 71
Resolutions .......................................................................................... 72
What is a Resolution? ........................................................................... 72
Bulk Update Resolutions ....................................................................... 73
Priorities .............................................................................................. 76
Best Practices ...................................................................................... 76
Workflows ............................................................................................ 77
Name Your Workflow ............................................................................ 77
Create a Workflow................................................................................ 78
Custom Workflows ............................................................................... 80
Phased Approach ................................................................................. 80
Custom Workflow Process..................................................................... 82
Workflow Templates ............................................................................ 84
Workflow Concepts .............................................................................. 93
Workflow Behaviors ............................................................................. 102
Workflow Schemes .............................................................................. 111
Workflow Schemes to Workflows Relationship ......................................... 111
Screens ................................................................................................ 113
Best Practices ..................................................................................... 113
Can't see a field? ................................................................................. 114
Screen Schemes ................................................................................. 115
Issue Type Screen Schemes ................................................................. 115
Best Practices ..................................................................................... 116
Standard Web Form Conventions .......................................................... 117
Custom Fields ...................................................................................... 118
Best Practices ..................................................................................... 118
Required Fields ................................................................................... 120
Field Configurations ............................................................................. 121
Standard and Important Fields .............................................................. 122
Field Configuration Schemes ................................................................. 123
Field Configurations to Field Configuration Schemes Relationship .............. 123
Proper Field Types ............................................................................... 125
Special Features .................................................................................. 126
Versions .............................................................................................. 129
Best Practices ..................................................................................... 130
Alternate Uses for Versions ................................................................... 130
Version Permissions ............................................................................. 131
Components ........................................................................................ 132
Examples ........................................................................................... 133
Best Practices ..................................................................................... 134
Permissions ......................................................................................... 135
Best Practices ..................................................................................... 135
Permission Scheme Worksheets ............................................................ 138
Issue Security ..................................................................................... 146
Best Practices ..................................................................................... 147
Issue Security Worksheets ................................................................... 147
Notifications ........................................................................................ 149
Best Practices ...................................................................................... 149
Standard and Custom Notifications ......................................................... 152
Bulk Change Notifications...................................................................... 156
Standard Capabilities ........................................................................... 156
Part 3: Fix and Clean JIRA Up ...................................................... 160

Audit .................................................................................................... 160
Areas to Tackle..................................................................................... 163
Unused Elements ................................................................................. 163
Duplicate Elements .............................................................................. 165
Practical Audit Example ........................................................................ 166
Inactive Projects .................................................................................. 168
Clean-Up Check-up .............................................................................. 172
Old Email Handlers ............................................................................... 172
Archive ................................................................................................. 173
Option 1: Prevent New Issues............................................................... 173
Option 2: Make the Project Read Only ................................................... 174
Option 3: Hide the Project .................................................................... 174
Option 4: "Archive" the Project .............................................................. 175
Option 5: Export the Project ................................................................. 176
Archive Clean-Up & Notification ............................................................. 177
Merge Applications or Start Over.......................................................... 178
Application Comparison ........................................................................ 178
Plugin Tracking .................................................................................... 182
Comparison Recommendations .............................................................. 182
Start Over ........................................................................................... 183
Expert Assistance ................................................................................. 184
Part 4: Maintenance..................................................................... 185

User Communication ............................................................................ 185
Announcement Banners ........................................................................ 185
Application Tracking and Statistics ...................................................... 187
Re-index .............................................................................................. 189
Re-index Triggers ................................................................................ 189
Types of Re-indexes ............................................................................ 190
Scheduled Maintenance ....................................................................... 191
Support and Emergency Escalation ........................................................ 192
Upgrade ............................................................................................... 194
High Level Upgrade Plan ...................................................................... 195
Detailed Upgrade Plan .......................................................................... 195
Standard Regression Testing................................................................. 196
Upgrade Wording ................................................................................ 198
Emergency Rollback ............................................................................ 205
REST API and Database Users ............................................................... 206
New Feature List ................................................................................. 206
Automated Testing .............................................................................. 208
Automation Set Up .............................................................................. 208
Monitoring ........................................................................................... 210
Incident Log ........................................................................................ 212
Year-End Clean-Up .............................................................................. 214
Year-End Analysis ................................................................................ 214
Part 5: Customization ................................................................. 218

Plugins and Add-ons ............................................................................ 218
Best Practices ..................................................................................... 218
Vet Plugins and Add-ons ...................................................................... 219
Plugin Installations .............................................................................. 220
Noteworthy Add-ons ............................................................................ 224
Extend JIRA ......................................................................................... 226
Get Data into JIRA ............................................................................... 226
Create Custom Displays ....................................................................... 232
Sync Data with JIRA ............................................................................ 233
Hacks................................................................................................... 235
Other Uses for JIRA ............................................................................. 240
JIRA as a CRM .................................................................................... 240
Asset Tracking .................................................................................... 245
Moving Labels ...................................................................................... 246
Bucket Lists......................................................................................... 247
Personal Goals ..................................................................................... 248
Other Ideas ......................................................................................... 248
Part 6: Bonuses ........................................................................... 250

Training Users ...................................................................................... 250
End User Training ................................................................................ 250
Admin Training Resources ..................................................................... 253
Get Certified ........................................................................................ 253
Bulk Import .......................................................................................... 255
Database Queries ................................................................................. 257
Configuration Elements ......................................................................... 257
Projects and Issues .............................................................................. 258
Users and Groups ................................................................................ 260
Filters and Dashboards ......................................................................... 263
Workflows ........................................................................................... 264
Add-ons .............................................................................................. 265
Database Specific................................................................................. 265
Query Resources .................................................................................. 266
Documentation ..................................................................................... 267
Support ................................................................................................ 267
Atlassian User Groups .......................................................................... 268
Summit Annual User Conference .......................................................... 268
Summit Justification ............................................................................. 269
Summit Tips ........................................................................................ 270
Other Books ......................................................................................... 273
Atlassian Experts ................................................................................. 273
Consulting ............................................................................................ 274
Conclusion .................................................................................... 274

Appendix...................................................................................... 275
Recommendations ............................................................................... 275
Index ................................................................................................... 275
Offer .................................................................................................... 279
How I Fell in Love with JIRA
My introduction to Atlassian products was by chance. The company I was working for was using an
ancient bug tracking application. By ancient, I mean software that would only load in a browser
version which was no longer available. In fact, the manufacturer had stopped supporting it many
years prior. The software was becoming increasingly unstable and a decision was made to switch to
JIRA. We were so excited to ditch the old software that we set up an official funeral for it at the
office. This was around the Halloween holiday, so we hung pictures of tombstones on the wall along
with screenshots of our most "ghastly" bugs. A team member wrote an obituary for the old
application. We covered the scene with spider webs and skeletons. It was a fun way to celebrate
that we were changing to JIRA and also say "good riddance" to our old system.
I was immediately amazed by what JIRA offered us. We were able to track all our work, not just our
bugs. The flexibility to work differently between projects and between issue types was something I
hadn't seen before. The ease of customization had me dreaming of all the ways we could improve
our processes. I found myself immersed in the user documentation, reviewing the internal materials
produced for the transition, and even helping others use this new application. I moved from being a
typical end user, to an application administrator, strategist, and trainer. JIRA administration became
an obsession and was easily the best part of my workday.
Today, I use JIRA and other Atlassian tools at my primary job, as a volunteer with the Atlassian User
Group program, to run my side business, and even at home. At home, JIRA tracks "bucket list"
items, personal goals, and my asset list, for insurance purposes. I use Confluence to collaborate
with family members, plan trips, track "to do" items, and capture research details for major
purchases. This book was written in Confluence and the book writing progress was tracked in JIRA.
These tools have become a vital part of my personal and professional life. It's safe to say I'm a huge
Atlassian fan.
Image: I'm currently in a relationship with JIRA.
jirastrategy.com | 1
Introduction: A Tale of Three Companies
There were once three companies. The first had a brand new JIRA instance that was smartly set up
and implemented. Everything was carefully planned and executed. The projects, issue types,
workflows, and other settings were standardized and built for needs of the users. All the
configurations and processes were documented and the users were well-trained. The transition from
an old issue tracking tool was simple and all the users were happy. The application was pruned and
maintained like a beautiful garden. Its administrators were carefully selected process leaders
who routinely cared for and meticulously shaped the garden's growth.
The second company had the complete opposite set up. Their JIRA instance was old and it had not
matured or changed in tandem with the organization. There were no standards, no recognizable
patterns, and no documentation. There was a free-for-all mentality that resulted in an
overgrown swamp of data. Anyone that desired a project customization was instantly made an
application administrator and had to make their own changes. Those changes were made without a
strategy and without regard for their impact on other projects or the application as a whole. The
swamp became more and more unmanageable each day.
The third company wanted JIRA to look and act like all their other internal applications. They spent
many months making visual and functional customizations. Eventually, so much had changed that
they couldn't upgrade without wiping out all the custom elements. Their users weren't able to take
advantage of all the new features and functions available in newer versions. One by one their add-
ons became unsupported and their application reached the dreaded "end-of-life" support status.
The recommendations in this book are a result of working in these environments and digging them
out of the swamp. Included are best practices, dos and don’ts, and recommendations you can adapt
to fit your company. Would you rather have an organized, tidy, and trimmed garden or a
foggy, contaminated, overgrown swamp?
Who This Book Is For

If you're a new Administrator, or your company is just getting started with JIRA, this book will show
you what actions to take up front, so you can have a well-planned and easy to maintain tool. If your
company has been using JIRA for a while, this book will show you simple ways to streamline your
instance and make daily work more manageable.
This book is written for the:
• part-time Application Administrator who helps out with JIRA in addition to your "official"
role;
• full-time Application Administrator for JIRA or the Atlassian product suite;
• Project Manager, Business Analyst, or other team member, who needs JIRA to fit the
needs of your teams; or the
• Systems Administrator or Database Administrator who supports many different internal

company tools.
2 | JIRA Strategy Admin Workbook

This book does not intend to teach end users how to use the software. The "how to" functional
information, both for end users and also for Administrators, is already documented. See the
"Resources" section for links to existing documentation, books, and other materials. This book will
not address the technical details of how to install the software, how to configure your server, or how
to sign up for an Atlassian customer account. And most of all, this book will not repeat information
already available!
This book also will not address JIRA Agile or JIRA Service Desk-specific strategies. Those topics
deserve dedicated books.
This book does not address JIRA Agile or JIRA Service Desk-specific strategies. However, this book
will help you establish and streamline vital processes. We'll do this using applicable examples and
easy to understand worksheets. As a result, your maintenance tasks will become easier to complete.
Customization requests from end users will be easier to respond to and accommodate. You may
even experience improved application stability and quicker user adoption.
Information in this book applies to both the JIRA Server "Download" version as well as the JIRA
Cloud "On Demand" version. Its language is tailored to JIRA 7 but the concepts apply to most
released versions.
What You'll Need

Not much! You will get the most out of this book if you:
1. are familiar with the purpose and use of an issue or project tracking tool;
2. have an end user's understanding of JIRA functions; and
3. have a willingness to think before you click in the JIRA Administration area!
While not all examples and recommendations may apply to your situation, you are encouraged to
consider the information and adapt it to your needs.
Any of the following additional skills will enhance your success: familiarity with process management
(software or otherwise), project management expertise, database management experience, inter-
department communication and liaison skills, the ability to train others, and a focus on long term
thinking and overall strategy.
Book Structure
The book is organized into six main chapters. "Part 1: Setting the Foundation" and "Part 2: Project
Configuration" address set up for a new application and concepts to enhance an existing application.
"Part 3: Fix and Clean JIRA Up" is for auditing and improving an existing application. "Part 4:
Maintenance" is about upgrading and maintaining the application once it's set up well. "Part 5:
Customization" tackles add-ons, plugins, and ways to extend the application. Finally, "Part 6:
Bonuses" contains additional content that didn't fit anywhere else.
The chapters in the Table of Contents are listed in the suggested order of action. Some
recommendations are dependent on previous chapters, while others can be implemented
independently. Chapters frequently reference each other when more or related information exists in
a different area. This is noted by the paperclip ( ) icon.
URLs
Where possible, URLs have been shortened so they are easier for print version readers to type into a
browser. For example, to read more about global permissions, you can type
jirastrategy.com/link/global-permissions instead of
https://confluence.atlassian.com/adminjiraserver071/managing-global-permissions-802592439.html.
The short version will redirect you to the correct place.
NOTE
Please be sure to check the version for any documentation page and change it to your application’s
version if necessary.
Terminology
The JIRA Server version was previously known as "JIRA Download" and the JIRA Cloud version as
"JIRA OnDemand." Throughout this book, the products will be referred to as JIRA Server and JIRA
Cloud.
An "asset" is used to describe the collection of configurations, schemes, and other items like custom
fields, components, settings, etc. "Asset" is also used to describe an item you own. Example: Asset
management.
"JQL" means "JIRA Query Language" which is a flexible way to search in JIRA. Read more about JQL
at: jirastrategy.com/link/advanced-searching.
An index is available at the end of the book. For digital versions, use any available "search" or "find"
features.

Conventions
The following icons represent special content:
Icon Use Notes
Chapter or Section Reference A reference to another section or chapter in the book
Recommendation or Tip Advice or something good to know
Do Something to do
Don't Something to avoid
Mistake A mistake I made; something to avoid
Example from the Swamp A real world example to avoid
Warning or Note Something important to know
Server Version Only Only applies to JIRA Server (not JIRA Cloud)
Brackets
Areas where you need to fill in your own value are noted in brackets. Example: In the sentence
"Today is [date]." replace the string "[date]" with the actual date. (Don't forget to remove the
brackets, especially in code snippet examples.)
Worksheets, Templates & Companion Materials

Download the worksheets, templates, and companion materials for this book from the JIRA Strategy
Store at: jirastrategy.com/store.
Use the coupon code for free digital downloads of the materials in the book.
Code: jsK1
Use the notification service to hear about book updates and new materials. Subscribe at:
jirastrategy.com/link/notify.
Errata
Have you found an error, a mistake, or a broken link? Please report it at jirastrategy.com/link/errata
so we can address it in the next edition. Please include a short description of the issue and the page
where you found it. Thanks in advance!
Have a different opinion or additional strategies to share? I'd love to hear them! Start the
conversation at: jirastrategy.com/link/conversation.
Comments, Feedback, and Questions

Reader feedback is always welcomed and encouraged. You can contact the author via:
jirastrategy.com/contact.

Part 1: Setting the Foundation
Whether you're setting up a fresh install or have inherited an existing application, now is the time to
get organized and set your application up for success. Use the tips in this chapter to:
• Create a support system of users who want the application to succeed
• Establish basic standards and determine how you'll enforce them
• Set up a request collection and management strategy
Even if your application is already a bit of a mess, you can stop the pollution, and make good "from
now on" decisions with the tips in part 1.
Establish an Advisory Board

Whether you've just started with JIRA or you've been using it for years, such a powerful and useful
application should not be directed by a single person. The people who set the strategy for JIRA use
may be different from those who actually perform maintenance and administrative functions. You'll
want a governance or steering committee, who can establish standards and support both the
application and the users.
NOTE
Not every member of the Advisory Board needs to have application administrative access!
Administrative access should be carefully limited. See the "Define Admin Users" section for
details.
Pick your board members carefully. You should seek out people who genuinely care about the
application and the processes it supports. You'll want members who are invested in the long-term
success of the software and of its users. It’s also important to have a diverse membership. For
example, if you have all engineers on the board, you'll only get engineering-focused opinions. Keep
the membership size to the smallest count needed to accomplish the mission of the board.
DON’T
Delegate only one person with management decisions and administrative actions.
Ideal Board Makeup
1. An End User who understands how other users work with the software every day (a technical
user or a non-technical user).
2. An Application Administrator who understands the software structure, database schema,

and overall capabilities.
3. A Project Manager, Business Analyst, or Strategist who understands effective processes

and project or resource management.
4. A VP who's responsible for the work tracked in JIRA.
5. A wildcard member who can keep the group focused, communicate with other groups, and
provide additional skills or expertise as needed.
The worst type of person to have on your board is someone with too narrow of a focus. Someone
only interested in their current, specific problem or use case will not make decisions that benefit the
software and user base as a whole. Be prepared to replace any board member who doesn't bring
value to the team or negatively impacts its mission.
Role of the Board

The board sets the standards for how the application will be used, how it should be structured, and
which custom elements to use. The board decides which kinds of requests are automatically
approved and implemented and which should be presented for consideration. Should new project
creation requests be immediately accommodated? What about new custom fields, add-on
installations, and scheme changes?
RECOMMENDATION
Any change that would impact multiple projects (or user groups), apply to a very narrow use
case, alter the way the application functions, or trigger the need for a re-index of the data,
should be carefully considered by the board.
Establish Standards
JIRA comes loaded with default schemes to get you started. For example, a default workflow,
permissions scheme, notification scheme, etc. Before you start building new custom schemes, the
board should decide how many of each you will be offered and for what purpose. Setting standards
will help keep your application uncluttered and easy to maintain.
Make all configurations as simple and as generic as you can, so they can be easily shared between
multiple projects and multiple teams. Then Project Leads can choose from the available standard
schemes.

But what if you need more options? If an additional workflow or customization is needed, the board
should decide whether that extra asset is worth maintaining. One additional scheme is not a
problem to maintain. But don't let your scheme count grow out of hand or you will quickly join other
companies in the swamp.
EXAMPLE FROM THE SWAMP
Think your application won't grow out of control? Here's a real example of exactly what
happened to one company without an advisory board to monitor requests.
JIRA
Scheme
Default Count Problem
Type
Count
Issue ~7 189 This company thought Issue Types were needed to
Types name each possible request type. (You and I know
their purpose is to allow for different workflows and
screens.)
Workflows ~4 150 This company let every software team have their own
differing workflows, complete with cutesy status
names and custom fields.
Custom ~ 30 330 This company had many similarly named, duplicate,
Fields and unused fields.
Scheme counts grew and grew to the point where it took a long time for the admin pages to
load! The same is true for all the other types of schemes not listed.
Handle Sensitive Information

Now that you know how and why to establish an effective board let's give this group a simple task.
Here's a good first task for your new Advisory Board: determine what kinds of sensitive information
is permitted in JIRA. It should be pretty easy to arrive at this decision. Your policy will depend on
whether your application is subject to compliance standards, how access to sensitive data is
controlled, other internal company information security policies, your industry, the laws in your
country, whether you accept credit card payments, and other related factors.
Worksheet: Security Policy Considerations
Answer the following questions to help you draft your information security policy.
1. How do you define sensitive information?
▪ Examples:
o Passwords, special codes, or secret keys
o Personally identifiable data (like social security numbers, date or place of

birth, etc.)
o Protected health information (like the health insurance plan an employee

has, disability claims they have filed, etc.)
o Employment information (like an employee identification number, citizen

status, salary, etc.)
o Credit card or payment data
o Proprietary company information
2. What scenarios involve sensitive information?
▪ Examples:
o When a candidate is interviewed or on-boarded, what personal information

is stored in JIRA?
o When new user access is granted, what is the procedure for providing
credential information?
o If a user needs their password reset, is it permissible to paste their new

password into their JIRA help issue?
o If a customer creates a help request, is payment information is involved?
3. Are users permitted to enter and store sensitive information?
4. Is there any company-specific or proprietary information that should not be stored in

JIRA?
▪ What information may harm the company if employees or the general public was
able to access it?
5. Where is sensitive information stored?
▪ Which JIRA projects are permitted to store sensitive information?
▪ Under what conditions?
▪ How is access to the project protected?
6. Who has access to sensitive information?
▪ Your application, system, and database administrators are likely to be able to

access all JIRA information. Is this acceptable?

▪ Are regular users able to access sensitive information?
▪ What security measures are in place to prevent access?
7. In what additional ways can sensitive JIRA information be accessed?
▪ Where is JIRA data backed up? Who can access the backup?
▪ How long is sensitive data retained?
▪ Is email sent from JIRA encrypted?
▪ Who is able to access sensitive information sent via email?
8. Is any user or use case exempt from this policy?
9. How are policy violations reported?
10. How are policy violations remedied?
Download this worksheet at: jirastrategy.com/link/security-policy. Use the code in the “Worksheets,
Templates & Companion Materials” section to download it for free.
Be sure to share your policy with your Legal, Compliance, Security and Audit teams, to make sure it
meets the needs of the company and supports other policies in place. Also, consider how to publicize
your policy. Will it become part of the standard employee procedures manual, will users agree to it
at the time they receive JIRA access, will users agree to it annually, or is another method
appropriate?
Enforcement
User education is the best preventative measure. Additionally, you'll want to proactively look for
violations of the policy. One way to do this is through simple JQL (JIRA Query Language) queries.
Set up filters or filter subscriptions to look for common words that may indicate a policy violation.
For example, to detect a password entered into an issue, use a query like:
text ~ "password" or text ~ "pass" or text ~ "passwd"
Obviously this method isn't fool proof, and false positives will be detected. If a false positive is
identified, remove it from your query. Example:
(text ~ "password" or text ~ "pass" or text ~ "passwd")

and issue not in (ISSUE-1, ISSUE-100)
In this case, the results will need to be manually reviewed.
Reporting Violations
A clear set of instructions for reporting problems needs to be defined. Once an issue is reported and
verified, a clear set of actions is needed for containing the problem.
When one company found a password in an issue comment, their procedure was to delete
the comment. This solution alone was highly ineffective. The password was exposed to
other users in the issue, made vulnerable via email notification when the comment was first
added, and exposed again via email when the comment was deleted. Even after the
comment was deleted, the original information remained as part of the issue's activity
history.
Instead, the exposed password needs to be changed immediately.
Manage Administrative Requests

By now, you should have a sound information security policy in place for JIRA. Congratulations - the
board has completed its first group assignment! Next, let's set up a smart way to manage JIRA
administrative requests.
The easiest way to manage user requests and support the software is from within JIRA itself!
1. Create a project to collect and track all requests and actions performed by JIRA
administrators.
Recommendation: Choose a JIRA support project name that will be easy for your users to
understand. (There's no time for clever names when users need support.)
2. Establish this project as the official method for all new project creation, application change, or
user support requests.
Recommendation: Use this same project to track other JIRA-specific tasks like user
assistance (new account creation, password resets, etc.) and to record routine maintenance
activities (like upgrades, re-indexing, etc.) This keeps all your application information in one
place.
3. Have the board establish what information is needed for each type of common request.
While JIRA logs administrative actions, the logs alone won’t explain why the change was
made, who requested it, or why it was implemented in a specific way. All this information
should be stored in the request record. Further, the administrator should record any notes
about their actions or implementation details so they can be understood by others or
referenced later.
Recommendation: For each new element created (project, scheme, etc.), use the
"description" field to reference the issue ID it was created for.
4. Create a list of request-specific questions to immediately present to the user. This helps get
the information you need up front to complete the request. The questions also establish the
choices available to the user.
A sample project configuration is available in the "Sample JIRA Support Project Set Up" section.

Support Metrics
How you set up your JIRA support project depends on what data points you will measure. Defining
these metrics will illuminate how you should leverage project assets like: Components, Custom
Fields, Versions, Labels, and Issue Types.
DON’T
If you're not planning to query for or report on a piece of information, don't devote a custom
field to it.
Worksheet: Top JIRA Support Measurements
What should you measure and why? Use the ideas below to create your own list of important
data points. Determining how you'll measure success may help the support team improve as
well.
1. How much support does JIRA require, compared to other internal applications?
▪ Reason: So you can calculate true maintenance costs and understand where to
spend time training staff and educating users
▪ Implementation: Use Components or a Custom Field to specify the relevant

application. (Example selections: JIRA, Confluence, Microsoft Office, Email, etc.)
2. What type of support or changes are most frequently needed?
▪ Reason: To track patterns and identify opportunities for automation, team

training, and end user training.
▪ Implementation: Issue Types (Example selections: Add Project, Modify Project,

etc.)
3. What is the relative priority of most requests? (Example: How many requests are
urgent?)
▪ Reason: So you can manage resource allocation and end user expectations
▪ Implementation: Use the standard Priority field.
4. How quick is the initial response to requests?
▪ Reason: To measure effectiveness of triage, response speed, resource allocation,

and customer satisfaction
▪ Implementation: Use dashboard gadgets like "Time to First Response." (Also

consider adding JIRA Service Desk. Product Info: jirastrategy.com/link/jsd)
5. How quickly are requests completed? (Example: Is the communicated Service Level
Agreement (SLA) being met?)
▪ Reason: To measure effectiveness, response speed, and customer satisfaction
▪ Implementation: The "Resolution Time Report" or dashboard gadgets like

"Resolution Time." (Also consider adding JIRA Service Desk. Product Info:
jirastrategy.com/link/jsd)
6. How much time is spent on requests? (Example: What is the cost per support request?)
▪ Reason: So work can be planned, true maintenance costs calculated, and to

justify future spending or system improvements
▪ Implementation: Use the Log Work function and Time Tracking standard fields.
7. What is the frequency of requests where no work is needed, invalid requests, or issues
caused by external forces? (Example: Problems that can't be reproduced, issues that
"work as designed", questions or research requests, improperly routed issues, network
outages, user error, etc.)
▪ Reason: So you can see where you're spending (or wasting) time and can better
educate end users
▪ Implementation: Use the standard Resolution field.
8. What patterns exist? (Example: What incidents occur frequently?)
▪ Reason: So you can recognize opportunities for automation, education, or

improvement in any category
▪ Implementation: Use Labels or a Custom Field.
9. How satisfied are requestors with the support they received? (Example: Are you
proactively educating users or just fixing issues?)
▪ Reason: So you can improve the level of support and educate users
▪ Implementation: Use a custom Workflow transition screen and Custom Fields.

See this in action in the "Customer Satisfaction Survey" section.
10. How well are support actions documented? (Example: Are support team members
educating each other?)
▪ Reason: So you can cross train, share knowledge, and save time
▪ Implementation: A periodic, manual review of resolution comments
11. How satisfied is support staff with tools, procedures, access to assistance, etc?
▪ Reasons: So you can identify and act on areas to improve, work better together,
and achieve a high level of morale
▪ Implementation: A periodic support team survey, inside or outside of JIRA
12. Which environment are changes made in? (Example: Production or the testing
environment.)
▪ Reason: So you can document differences between environments and see which
changes were tested
▪ Implementation: Use Labels or a Custom Field.
Download this worksheet at: jirastrategy.com/link/support-measurements. Use the code in the

“Worksheets, Templates & Companion Materials” section to download it for free.

All this data should help your support team discover where you are today, where you want to be in
the future, and help to set team strategy.
Sample JIRA Support Project Set Up

Now that you know what you your support metrics are, let's set up a JIRA Support project. Here's
an example project configuration.
Project Name JIRA Support
Project Key ATLAS
Project Type Software (or Support if you have JIRA Service Desk)
Issue Types
This project uses issue types based on the type of work.
RECOMMENDATION
Always include a "general" issue type, like "Task", to collect "other" types of work. If a user
selects "Task" when another type is more appropriate, the issue can easily be moved to the
correct type.
Issue Type Description

Add Project For requests for new JIRA projects
Modify Project For requests to change, customize, or archive existing JIRA projects
User For any user related request (Example: add access, add permissions, add to
groups)
Task A general type for "anything else"
Sub-task A general child type, to break up work for Tasks or large requests
Fields
Use standard and custom fields to collect the information needed from requestors and the support
metrics defined in the previous section.
All issue types share the following common fields:
Issue
Field Name Field Type Description Notes
Type
All Summary Standard n/a Required
Description Standard n/a Required
Priority Standard n/a Required
Requested Date Custom When would you like this Different from the "Due
completed by? Date"
Linked Issues Standard n/a n/a
Attachment Standard n/a n/a
Labels Standard n/a n/a
Standard n/a n/a
Assignee
Component/s Standard What type of request is this? Example selections:

Help Desk,
Customization, Training,
etc. Use this value to
route the request to the
proper team member.
Area Custom - Which application or area is Example selections:
Select List impacted? JIRA, Confluence,
(single NOTE: Only needed if Crowd, etc.
choice) multiple Atlassian applications
are supported by the same
JIRA project
Due Date Standard n/a The date the request is
expected to be
completed by the
support team
Time Tracking Standard n/a Includes Original
Estimate and Remaining
Estimate fields
Resolution Standard n/a n/a
User Instruction: Message Quick Survey For use on the
Survey Custom How did we do? Customer Satisfactions
Field (for Help us understand what went Survey transition
edit) well and what could be screen. See the
improved for future support Customer Satisfaction
requests. This optional survey Survey section. Also,
will take you approx. 1 minute create a "Survey" tab
to complete. Results and on the Edit and or View
feedback will be shared with screens.
the support team and
leadership. Requires the JIRA
Toolkit Plugin. Read
more about it in the
"Noteworthy Add-ons"
section.
Select List How was our speed in Example selections:
Speed
(single addressing your issue? Awesome, Good, Fair,
choice) Poor, Unknown

Communication Select List How was our communication Example selections:
(single about your issue? Awesome, Good, Fair,
Overall Select List How did we do overall in Example selections:
(single addressing your issue? Awesome, Good, Fair,
In addition to the common fields above, the following issue types use additional fields.
Issue
Field Name Field Type Description Notes
Type
Add User Message Please see the "Request a For use on the "New
Project Instruction: Custom New JIRA Project" Project" create screen
New JIRA Field (for documentation at: [URL]
Project edit)
Text Field n/a Required
Project Name
(single line)
Lead User Picker Who is the responsible lead of Required
(single this new project? See
user) "Responsibilities" at: [URL]
Modify Project Project Which project needs Required
Project Picker modification?
(single
project)
User Employee Text Field n/a Required
Name (single line)
Username Text Field n/a Required. NOTE: Don't
(single line) make this field of type
"User Picker" as this
may be a request to
add a user not already
in JIRA.
Email Address Text Field n/a Required
(single line)
Add to Group(s) Group Tip: Use the "Select n/a
Picker groups" icon on the right to
(multiple choose one or more groups.
groups) Every JIRA user needs to be in
the "jira-users" group.
Screens
This project uses the following screens. Included are the standard issue action screens (Create, Edit,
and View) and additional transition screens.
RECOMMENDATION
Organize any internal use type fields (Example: Time Tracking) on a separate tab. Create a
separate tab to hold the survey fields too.
Image: Three Tab Display
Screen Details
Screen Type
Screen Name Notes
(Action)
Create • Add Project: Create Build one "Create" screen for each issue main
type. (The Sub-task issue type can share the
• Modify Project: Create Task's create screen.)
• User: Create Collects the initial request information from

the requestor
• Task & Sub-task: Create
Edit, View • Add Project: Edit/View Build one shared "Edit" and "View" screen for
each issue type. (The Sub-task issue type
• Modify Project: Edit/View can use the Task's create screen.)
• User: Edit/View Provides access to all available fields for each

issue type
• Task & Sub-task: Edit/View
Transition • Request Info Build a transition screen with the Assignee
and Comments field, so any user can easily
ask questions without impacting the workflow
status.
This screen is triggered by a "Request Info"
triage button available in any status.
Transition • Triage This screen is triggered by the "Triage"
transition button in the initial status.
The team triage resource selects (or updates)
the proper Component/s, Area, Priority, and
Due Date.
Required fields: Priority, Component/s, Area

Transition • Estimate Work This screen is triggered by the "Start
Progress" transition button in the "To Do"
status.
On this screen, the support team member

enters (or updates) the Due Date and Time
Tracking ("Original Estimate") fields.
Transition • Implementation Details This screen is triggered by the "Ready for
Verification" transition button in the "In
Progress" status.
The support team member enters a

Resolution, Logs Work, and enters a required
Comment answering the question "What
actions were taken to resolve this issue?"
Required fields: Resolution, Comment

Transition • Customer Survey This screen is triggered by the "Pass"
transition button in the "Ready for
Verification" status.
The reporter is presented with an optional

customer satisfaction survey.
Customer Satisfaction Survey

One of the easiest ways to get and track user feedback is to collect it in the issue containing the
request. Set up a short, optional survey as part of the final step of the workflow. See “Sample
Customer Satisfaction Survey.”
RECOMMENDATION
Ask each user to verify the work done for their request. When they click the "Pass" transition
button in the workflow's "Ready for Verification" status, show a transition screen containing
optional survey questions.
NOTE
As responses aren't anonymous or private, it's possible that users will skip completion or may be
worried about responding honestly.
Sample Customer Satisfaction Survey
Image: Customer Satisfaction Survey
Sample Questions:
1. How was our speed in addressing your issue?
2. How was our communication about your issue?
3. How did we do overall in addressing your issue?
How To:
1. Create one new field, of type "Select list (single choice)”, for each question to ask.
▪ Add simple response values like: Awesome, Good, Fair, Poor, and Unknown
2. Create one new screen and add the fields created in the previous step.
▪ NOTE: The "Comments" field will be present on the screen by default. There is no
need to create another field to gather feedback in text format.
3. In the final workflow transition, show the screen created in the previous step.
4. Create a dashboard to count and show the results.

Code: Customer Satisfaction Survey Instructions
<div style="border: 1px solid #000; background-color: #f0f0f0; padding: 10px; margin: 10px;">
<b>How did we do?<b><br />Help us understand what went well and what could be improved for fu
ture support requests. This optional survey will take you approx 1 minute to complete. Result
s and feedback will be shared with the support team and leadership.</div>
Sample Workflow: JIRA Support

Now that we have defined Issue Types, Fields, and Screens, let's build the Workflow.
Use Case: The JIRA Support team uses a JIRA project to track user requests and collect feedback.
In this example, a request is entered, triaged by a senior team member, worked by a support team
member, and verified by the requestor.
Workflow Details
Workflow Name: JIRA Support
Short Description: JIRA user requests and

feedback.
Fields Required by Workflow: Resolution,

Comment
Narrative: There are five statuses. The requester creates an issue. The issue is in “Open” status
and a senior team member reviews the issue. They assign the issue, provide an initial time estimate
(goal) then set a target due date. When work begins, the assignee updates the time and date
estimates then moves the issue to “In Progress” status. After the work is complete, the assignee
moves the issue to "Ready for Verification" status and is automatically assigned back to the
requester. If they pass the issue, a customer satisfaction survey, with optional fields is displayed
and the issue is marked “Closed.” If the reporter fails the issue, it goes back to "To Do" status.
Alternatively, the issue can skip the verification step if it is not applicable. An issue can also be
"Reopened" after it is closed.
NOTE
This workflow requires the following add-ons: "Suite Utilities for JIRA", "JIRA Toolkit Plugin", and
"JIRA Misc Workflow Extensions." Read more about it in the "Noteworthy Add-ons" section.
Transition
Linked Button >> Behaviors (Triggers, Conditions,
Transition Screen
Status Destination Validators & Post Functions)
Status
Open Triage >> To Do Triage (Includes fields: • Fire an Issue Assigned event
Area, Components, that can be processed by the
Assignee, Time Tracking, listeners.
Due Date)
Close >> Closed Implementation Details • Fire an Issue Closed event that
(Includes Fields: Log can be processed by the
Work, Comment. listeners.
Required: Resolution,
Comment)
To Do Start Start Progress (Includes • Assign the issue to the current
Progress >> In Fields: Original user. (Please note that the issue
Progress Estimate, Due Date) will only be assigned to the
current user if the current user
has the 'Assignable User'
permission.)
Close >> Closed Implementation Details • Fire an Issue Closed event that
(Includes Fields: Log can be processed by the
Comment)
In Ready for Implementation Details • Assign the issue to the reporter.
Progress Verification >> (Includes Fields: Log
Ready for Work, Comment.
Verification Required: Resolution,
Comment)
No Verification Implementation Details • Fire an Issue Closed event that
Needed >> Closed (Includes Fields: Log can be processed by the
Comment)
Stop n/a • n/a
Progress >> To
Do
Ready for Pass >> Closed Survey (Includes Fields: • Fire an Issue Closed event that
Verification Speed, Communication, can be processed by the
Overall) listeners.
• Assign the issue to the last user
from the Developers role who
had this issue assigned before.
Fail >> To Do Comment (Required: • Assign the issue to the last user

Comment) from the Developers role who
had this issue assigned before.
• The Resolution of the issue will
be cleared.
Closed Reopen >> Open Comment (Required:

• The Resolution of the issue will
Comment)
be cleared.
• Assign the issue to the Lead
Developer.
• Fire an Issue Reopened event
that can be processed by the
listeners.
Appoint Ambassadors
Now that your board is set up, you've established success metrics to measure, and you've set up a
JIRA project to collect support requests and track application changes, there's one more group to
establish.
In addition to your board, you'll want to enlist the help of other users to disseminate information,
answer common questions, and serve as a liaison to your users. A small team of JIRA Ambassadors
is a vital asset when you need to execute changes to your current application or communicate the
change request process.
As with the Advisory Board, keep the team small but representative of your user base. The Project
Lead of each JIRA project makes an excellent ambassador candidate list. Project Leads are likely
already engaged in some level of project-level administration and may also be a team manager or
leader. If there are too many JIRA projects for the lead of each to be an Ambassador, instead
appoint one per project type. For example, one person can represent all the software-type projects,
another can represent all the business--type projects, and another for the support-type projects.
RECOMMENDATION
Use JIRA's project Categories feature to segment projects and group potential Ambassadors.
User Access Strategies

There are many different types of users, memberships, and use cases for maintaining them. In this
section, we'll explore different user types, permission levels, responsibilities, roles, and groups. We'll
also tackle how to manage new and departing users, set expectations, and create a user access
management strategy.
User Types
Users generally fall into one of the following types.
• Internal Users - Full time and part time employees who will remain with the company for
the foreseeable future
• External Users - Contractors, consultants, and temporary employees who will cease work
after a period of time
• Active Users - Users who regularly login and interact with issue data
• Inactive Users - Users who haven't logged in in X days and/or have left the company
• JIRA Core Users - Users of "Business" type projects with simplified views. This user has a
simplified project view without software development-specific features.
• JIRA Software Users - Users of "Software" type projects with views containing software
development concepts. This user will see development-specific features. (Example: Releases
tab, versions, development tools integration panel, etc.)
• JIRA Service Desk Users - Users of "Support" type projects with views containing support
concepts, like service level agreements (SLAs), portals, etc.
• Project Level Administrators - Users with permissions to manage settings for individual
JIRA projects. (Example: Components, project users, etc.)
• System Level Administrators - Users with the ability to perform absolutely every JIRA
administration function
• Application Level Administrators - Users with permissions to perform most JIRA

administration functions
NOTE
Some companies separate or give their administrative users both system and application levels of
permissions. For the differences between the two groups, see the "Managing Global Permissions"
documentation here: jirastrategy.com/link/global-permissions.
Test Users
RECOMMENDATION
Create one test user account to support each type of user scenario. Example: If you are an
Internal user with Application Admin access, create a generic account to test the effect of your
change as an Internal user with Regular access.

Make sure all of the user types noted above are accounted for in and mapped to your JIRA Roles and
Roles. See the "Roles and Groups" section for additional details.
DON’T
Create test administrative users, as that may introduce a security concern or violate your
company security policy.
Define Admin Users

The Advisory Board should determine the number of administrators needed (minimum and
maximum) to properly support the application. This range should be determined by user count,
project count, frequency of user requests, and aggressiveness of the routine maintenance schedule.
Having too few administrators leaves your application unsupported especially during holiday breaks,
emergency events, or when other company priorities arise. Having too many administrators results
in conflicting changes or modifications inconsistent with the overall application strategy.
At one company, there were no procedures to determine who was eligible for application-
level admin access. It didn't matter if you were a technical development team manager or a
non-technical project manager. It didn't matter if you had years of experience supporting
an application or had no experience at all. Anyone who asked for admin privileges got
them. At a company of approximately 1,000 users with roughly 50 admins, there were 45
too many! The users made any changes they wanted. Changes weren't planned, logged, or
communicated. Changes often had negative impacts on other projects or the application as
a whole. Schemes were duplicated multiple times. Custom fields were misspelled. Add-ons
were installed and never used or uninstalled. The stability and usability of the application
degraded every day. A complex query or a re-index would bring the entire application
down!
DON’T
Haphazardly grant administrative access.
Just like with the members of the Advisory Board, your JIRA Administrators need to be chosen
carefully, audited regularly, and approved by the application owner. An admin needs to consider the
health of the application, impact to the application, and maintenance implication for each decision
and change they make.
The worst type of person to have on your admin team is someone who doesn't understand the
structure of the application, doesn't communicate with stakeholders, or is too busy with other
application to devote the time needed to properly support JIRA.
Whether you hire a dedicated administrator or use existing employees as part of an administration
team, the roles, responsibilities, and expectations should be clearly defined.
Worksheet: Application Administrator Responsibilities
Use this worksheet to define the functions a JIRA Administrator should perform. Once finalized,
these items should become part of a job description.
1. Assist the JIRA Advisory board in maintaining established standards
2. Communicate standards, procedures, changes, and maintenance outages to JIRA

Ambassador team
3. Assist end users with user-specific settings
4. Assist Project Level Administrators with managing settings and maintaining their
projects
5. Complete approved customization requests (or suggesting alternative solutions within

established standards)
6. Manage users, groups, and access
7. Create and configure new projects, schemes, and assets
8. Remove projects, schemes, and assets when they are no longer needed
9. Perform application upgrades
10. Vet, install, and upgrade add-ons
11. Check logs for and address errors
12. Develop and maintain documentation and end user training materials
13. Monitor and ensure the overall health of the application
Download this worksheet at: jirastrategy.com/link/admin-responsibilities. Use the code in the

DO
Administrators should always document their changes. JIRA records who made what change
when, but not why the change was made or implemented in a specific way. Ideally this
information is stored in the JIRA Support project as recommended in a previous section. The
administrator should record any notes about their actions or implementation details so others
can reference them as needed. These records are especially important for multi-person
admin teams to handle complex user requests or when transitioning admin duties to new
users.

RECOMMENDATION
While it may be useful to break up admin duties by request type (example: user related request
vs project customization request), make sure to cross train your team so everyone is able to
support all functions if needed.
MISTAKE
My first admin experience was on the day I was made an application administrator! I had a
very good user-level knowledge of JIRA, but understanding how to use it verses how to
configure and manage it are very different things! Without proper training, I started building
a new project and brand new schemes to fit my use case. I followed the model from an
existing project and was on my way. Months later, I realized the model I followed was all
wrong. I had copied the mistakes of others. I had added to the overall mess. I should have
understood more about the application before I started making additions to it.
MISTAKE
The JIRA software management and learning environment was all wrong. There was no
company sandbox or test environment to learn in or try out changes. I should have set up a
local Server instance or a Cloud free trial for my pre-production experimentation. I should
have imported sample production data and configurations to my test area so I could see how
changes worked with real scenarios. I should have requested read-only database access,
rather than guessing at how the data was stored and structured. NOTE: Granting read only
database access gives users access to protected data and may violate your company security
policy.
RECOMMENDATION
Give your application admin team read-only access to the JIRA database. Understanding how
the data is structured will solve a lot of mysteries and make them better admins. They'll have
the ability to access additional data that's not available in the admin UI.
Project Leads
Each JIRA project has a listed "Project "Lead" (who is sometimes also the default issue assignee). As
such, there's an opportunity to involve additional users in project-level maintenance and
management.
DO
Identify a project lead for any new project creation request. (See the "New Project Request"
worksheet to create your own questionnaire.)
The lead can be selected on a case by case basis, or you could structure leads by project type
or category. For example, Paul will be the project lead for any software-type projects.
Project Leads also make great candidates for your JIRA Ambassadors group mentioned in
the "Appoint Ambassadors" section.
DON’T
Utilize application-level administrators also as project-level administrators. These are two
separately focused roles.
Responsibilities
Project Leads typically have the following responsibilities:
1. Set and maintain Components, Versions, and other project-specific settings in accordance
with established standards
2. Manage users and groups in the "Users and roles" area
3. Routinely triage (or appoint a triage person) to assign and review issues as they are created
4. Maintain the data and accuracy of data in the project space
5. Report any project issues or customization needs to the JIRA Support team
6. Respond to questions or approvals requested by the JIRA Support team
DO
Create a job aid or help document with best practices for your project leads. See “Sample
Guide to Guide to Configuring Your New Project”
Wording: Sample Guide to Configuring Your New Project
Welcome to your new JIRA project! As the listed lead of a project, you have certain project
maintenance responsibilities. You have access to the project's admin area, where you can
manage Users, Components, Versions and other project-specific settings. Access the project
admin area from the "Project administration" (in JIRA Server) or "Project settings" (in JIRA
Cloud) link in the left sidebar menu.
Here's what you need to know about your project settings:
Components
Components represent a grouping of issues in a project. This feature allows you to query
(search for) all items in your project associated with that component. Here are some
examples:
• Example 1: Your project is to build a car. You might want to group issues in your "car

project" by parts of the car that need work.
o Sample Components: Tires, Engine, Windows, Headlights, etc.
• Example 2: You have a cross-functional team where many different types of jobs are
performed. You might want to group issues by type of job or department.
o Sample Components: Marketing, Design, Support, Legal, etc.
• Example 3: Your project is for writing copy for the entire company. You might want to
group issues by where the copy will be posted.
o Sample Components: Website, Social Media, Employee Handbook, Product

Manual, etc.
With "Components," you can specify how all new issues of a certain type automatically get
assigned. Using the "cross-functional team" example above, you can assign any "Marketing"
request issues straight to Bob, and any "Design" related issues to Sue, etc. To set this up,
enter a username in the "Component Lead" field and set the "Default Assignee" field to the
"Component Lead." Alternatively, you can have all issues go to one specific person for triage or
even to no one (using the "Unassigned" option).
Component Set Up
Here's a sample component configuration, using the "cross-functional team" example above.
Component Default
Name Description Notes
Lead Assignee
Marketing For copy, ads, and username Component Auto assigns to the
social media tasks Lead username specified in
the "Component Lead"
column
Design For graphic design, username Project Auto assigns to the
UI, mockups, etc. Default lead for the entire
(Project Lead) project
Support For the Tier 1, 2, and n/a Unassigned Auto assigns to the
3 support teams "Unassigned" user
value
Legal For agreements, username Component Auto assigns to the
terms and conditions, Lead username specified in
disclaimers, etc. the "Component Lead"
column
DO
Make your component names descriptive but short. Really long and multiple word values
make issues harder to search for.
DON’T
Do not use Components to duplicate an existing JIRA field or function. For example,
don’t group issues by a person's name. JIRA uses the "Assignee" field to specify who
needs to act on an issue.
If you're not sure how you might want to use the Components feature, skip it and come back to
it later, after you've used the project for a while.
Read more: jirastrategy.com/link/managing-components
Versions
Versions are points-in-time for a project. They help you schedule and organize your releases.
RECOMMENDATION
Skip creating Versions if your team has no work to release! (Or, use it as another
distinguisher for something you want to track.)
If you are part of a development team, use the "Releases" page to add your "Versions" (unique
software version numbers). The "Name" column is what will be queried against, so make the
naming format short and easy. (Example: A simple name like "1.0" is easier to query than
"Version 1.0 Special Release").
NOTE
Only projects of the type "Software" and users in the "jira-software-users" group will see the
Versions feature.
Read more: jirastrategy.com/link/managing-versions
Project Maintenance
As a Project Lead or Administrator, it is your responsibility to:
1. Triage (review, prioritize, and assign) issues as they are created.
2. Add and update individual users or groups in your "Users and roles" area. (Don't forget
to remove any users who have left the team.)
3. Maintain your Components and Version list.

4. Report any project issues or customization requests to the JIRA Support Team.
5. Respond to any questions or approvals needed by the JIRA Support Team.
Need Help?
Contact the JIRA Support team at [contact info].
RECOMMENDATION
Involve your project-level admins in changes that impact their project(s). Example: A user
requests access to a project. That's a change that can be made by the Project Lead. Either
refer the action to them for completion or make the change and notify the lead, so they are
aware. For bigger changes, you may opt to obtain "approval" from the lead before making the
change. You can manage this entire process (and create a record of it) from the issue request in
the JIRA Support project.
RECOMMENDATION
Use the project's "Description" field to list the name of a single point of contact. This way, the
application admin team will always know who to contact if a change needs to be announced or a
project-level decision needs to be made. Using the “Description” field is also helpful if the lead
happens to be listed as a generic user or distribution list.
NOTE
The lead for each JIRA project can be seen on the project's "Summary" page and also in JIRA's "All
Projects" list.
Image: Project Description and Alternate Contact Info
Project Distribution Lists
RECOMMENDATION
Make sure any distribution list on your mail server has an identified owner. Not only will it allow
the owner to manage group membership, but it will help create a single point of contact for all
generic email addresses.
RECOMMENDATION
It may be useful to your admin team and/or your end users to publish a static list of "distribution
list" project leads.
Here's a template for the leads list.
Worksheet: Project Leads
JIRA's "All Projects" page lists the owner for each project. Some projects show a distribution
list or generic user instead. Here's a (manually maintained) list of leads for those specific
projects.
Project Key Listed Project Lead Single Point of Contact
Project Name PROJECT "Dev Team" Paul
... ... ... ...
RECOMMENDATION
In your project leads list, link the "Project" column entry to the project's Summary page. Link
the "Single Point of Contact" column entry to the user's JIRA profile page.

WARNING
It is possible create a generic "distribution list" user with a generic email address that forwards mail
notifications to multiple users. This is often used to notify a whole team, in support situations, for
example. Further, you can make that generic user the listed "Project Lead", default assignee, or
Component Lead. I recommend avoiding this however because:
1. The generic user becomes part of your licensed user count. Your licensed user count could
quickly expand if all teams were to use this setup.
2. This generic user is unlikely to login. These become extra accounts for the application admin
team to manage and periodically determine if they are still in use.
3. There's the potential for less accountability when a project is owned by many. If the lead or
default assignee is a distribution list, which team member is supposed to act? How will
reporters know who to contact about an issue? A single point of contact or single assignee is
always easier.
4. Individual users will receive an email notification in their personal account, and another exact
copy for each distribution list they are also a member of. This message duplication is
annoying to users and also creates additional log entries and mail server traffic.
External Users
Now or in the future you will need to let an external user access your application. Maybe it's a
temporary contractor you've hired to help on a project, an Atlassian technician troubleshooting a
JIRA issue, or a consultant for an audit or compliance activity. Regardless of the scenario, you
should prepare for it before you have the actual need.
DON’T
Neglect to consider external users. Their access should be treated specially.
Consider the following use cases:
• 2 external users from one company need access to the X JIRA project
• 3 external users from another company need access to the X and Y JIRA projects
• 4 temporary contractors need access to the Z JIRA project
The above use cases are real examples from a company unprepared for the possibility of
external users. As such, a user with access to one JIRA project, had access to all the
others. Even worse, any new JIRA user was also made a Confluence user! This meant that
any temporary employee had access to all internal company information, proprietary
documentation, and plans for the future in both applications!
DON’T
Don’t use external email addresses when setting up external users. Valuable company data
should never be sent through external mail servers.
All external users should be set up with a company provided email address. (This does not have to
be the same domain internal employees use but it should be a domain managed by the company.)
External email addresses allow sensitive and proprietary information to leave your company and be
retrieved insecurely from external servers. Remember that email notification is widely used in JIRA.
An email is triggered for any @mention or share action. Notifications are sent at any given point and
display change records. Filter results are sent out as email subscriptions. Do you really want
company JIRA data sent to @gmail.com email addresses? Of course not!
A former employee contacted the company to complain about JIRA data being sent to his
personal gmail.com email address. Upon further research, it was also discovered that data
was being sent to hundreds of other past or present users with external addresses in the
JIRA database.
See the "Former Employee Clean Up Procedure" section for ways to proactively avoid this scenario.
RECOMMENDATION
Create a group, for all external users, separate from the general "jira-users" group. This allows
you to give permissions sparingly and also quickly remove access for the whole group.
RECOMMENDATION
Make sure external users have a clear end date when their access should be removed. Create a
new issue, at the time they are hired, to remind the team to perform the removal at a future
date. See the "New User Request" worksheet to set this up.

Character Users
One way to make sure users read messages and notifications from the JIRA administrative team, is
to send them as a specially created fictional character. Messages from an individual user are boring
and get lost in the sea of emails. Humorous messages however, sent by a made up character, get
read and shared!
I've created the following characters to help share information. Use mine or create your own!
The JIRA Genie
This character represents all the behind the scenes magic and customization that goes on within
JIRA. When workflow problems are magically solved, it's because the Genie did it! When new
projects get configured just the way users want, they can thank the Genie.
Worksheet: JIRA Genie Persona
[insert Name Genie

persona Role JIRA administrator with magical customization powers
image]
Location Lives in a bottle, but can be summoned via
jiragenie@company.com
Characteristics Helpful and knowledgeable but a bit of a trickster when
users misbehave
Common Tasks New Project set up, Workflow Customization, End User
Training
The Genie is not all-powerful however. The Genie will
not update or transition your issues for you.
RECOMMENDATION
Use the JIRA Genie (or a similar persona) to remind users of their responsibilities and when they
need to take action.
Wording: Sample Reminder Notification from the JIRA Genie
Dear User,
I've been temporarily released from my lamp to remind you to [insert request details]. I have
many amazing magical powers, but I'm not all-powerful! I need your help to keep JIRA issue
data accurate and up to date. If you have any questions, I'll be in the Cave of Wonders
collecting today's wishes.
Sincerely,
The JIRA Genie
Download this wording at: jirastrategy.com/link/users-wording. Use the code in the “Worksheets,
Wording: New Project Message from the JIRA Genie
Dear User,
Your wish for a new JIRA project has been granted! I know your team of Forty Thieves is
anxious to get started, but first, please use your new administrative powers to create your
Components and Versions. It's quick; you'll finish it faster than Christina Aguilera can cut a
new single. If you have any questions, the JIRA Support team is only a short magic carpet ride
away.
Sincerely,
The JIRA Genie
Gerry the JIRA Gerbil
This character represents all the admin and application-level work required to maintain a happy JIRA
application. Gerry can be called upon for data issues, upgrades, clean up procedures, and archival
actions.
Worksheet: Gerry the JIRA Gerbil Persona
[insert persona Name Gerry

image] Role JIRA application and database administrator
Location Lives in the database, but can be queried via
gerrygerbil@company.com
Characteristics Generally very tame, until his database home gets
cluttered and hard to navigate
Common Tasks Application Clean Up, Upgrades, Data Archival
RECOMMENDATION
Use Gerry the JIRA Gerbil (or a similar persona) to alert users of system issues or administrative
tasks.

Wording: Sample Maintenance Notification from Gerry the JIRA Gerbil
You've heard of the JIRA Genie, but have you heard of the JIRA Gerbil? Meet Gerry, our
resident rodent! Gerry has been busy burrowing through our data, scurrying around all the
issues created, and getting JIRA cleaned up for us. Gerry has detected a problem however:
[insert problem details]. Rather than make everyone go fix the problem, Gerry lobbied to grant
you a one-time, non-trans-"fur"-able, "get off the hamster wheel" gift. We'll fix this problem
for you, with the understanding that you'll be more diligent with [task details] from now on.
Gerry is normally very tame - but don't test him! He's liable to chew your computer wires if
this problem occurs again. (Rodent high five to the folks who routinely address this problem.
Thanks!) It looks like Gerry has also detected a number of JIRA application inefficiencies.
There are remnants of "a veritable smorgasbord orgasbord orgasbord" cluttering up the tunnels
of his home. We'll be helping him address them by [solution details].
Good day Technoc-rat-s!
Wording: Sample Maintenance Reminder Notification from Gerry
Greetings,
Gerry the JIRA Gerbil has asked me to remind you of his New Year’s resolution: to let no JIRA
issue go unverified!
Please look for your issues in the following list: [filter URL]
Once you’ve made sure there’s no outstanding issues with the completion of your project,
please signify that by clicking the white “Reviewed” transition button. Then, we can officially
close the issue.
Gerbil high five!
RECOMMENDATION
Create your own JIRA characters to improve email open rates and info share. Consider making
these characters actual application users, with custom email addresses. (Example:
jiragenie@company.com) It will make important messages more likely to be read and less likely
to be filtered.
Download these personas and wording samples worksheet at: jirastrategy.com/link/character-users.

Use the code in the “Worksheets, Templates & Companion Materials” section to download it for free.
Roles and Groups
Permissions for roles, groups, and individuals are often confusing. Think of a role as a common
function on a team and a group as a list of individual users who perform that function. For example,
a soccer team has the following roles: a coach, a team captain, players, and fans.
NOTE
Default JIRA roles and groups such as Administrators, Developers, and Users may already exist
based on are specific to your version and license type.
RECOMMENDATION
Unless you're only using JIRA for software development, change the very specific and sometimes
confusing "Developers" role to a generic role name.
Using our soccer example, here's how the team could be reflected as four JIRA roles.
Soccer
JIRA Project
Team Notes
Role
Role
Coach Administrators The role name is purposely plural, meaning one or more individuals
who manage the project. See the "Responsibilities" section. This
is a default project role.
Team Leads The role name is purposely plural, meaning one or more individuals
Captain who assist the project administrators. This role can be used to grant
abilities that fall between those of an administrator and a regular
user. (This is a custom role manually added.)
Players Developers The role name is purposely plural, meaning one or more individuals
Members who do work within the project. The default role name is
"Developers" however, this is frequently a point of confusion for
non-software projects. Change this role to a more generic name that
indicates these users are "members of the team."
Fans Users The role name is purposely plural, meaning one or more individuals
who have a stake in a project. This is a default project role.

After your roles are established, it's time to populate them with groups and individuals. Groups are
containers for multiple individual users. You can add single users, groups, or a combination of both
for each role. The members of a role can also be left blank.
Soccer
Team JIRA Project Role Users Groups Notes
Role
Coach Administrators Coach none There is only one user, so use of a
David group is not warranted.
Team Leads Captain none There are only users, so use of a
Captain Mark, group is not warranted.
Captain
Joe
Players Developers None soccer-players There are 10 players, so use of a
Members group allows for easy user
management.
Fans Users None soccer-fans There are 15 fans, so use of a
group allows for easy user
management.
Best Practices
Application-level administrators should consider the following best practices so project-level

administrators can effectively manage their users.
DO
• Add the project lead to the "Administrators" role, so they can manage the project settings.
• Add the application-level administrators group to the "Administrators" role, so they can assist
the lead if needed.
o Alternatively (and even better) add the application-level administrators group to the
permission scheme. See additional details in the "Permissions" chapter.
• Add the "internal" users group to the "Users" role.
o Don't add the entire users group or you won't be able to restrict the project from
"external" users. See the "External Users" section for the recommended set up.
• Remind the project lead of their responsibilities. See the list and documentation wording in
the "Abilities and Responsibilities" section.
DON’T
• Create ultra-specific roles or name them in ways that won't apply to the entire company.
• Abuse the application-level "role default user" feature. If default users are added to a role,
they will apply to that role in EVERY project.
• Embed individual users and groups in Permission schemes where project-level won't be able
to manage them.
At one company, roles were utilized incorrectly. Instead of leveraging the default "Users"
role (which is part of every project), additional (duplicate) user roles were created and
named for specific projects. In addition to "Users," there were also "Project 1 Users",
"Project 2 Users", "Project 3 Users", etc. Since roles are used across all projects, all the
other projects had these line items in their roles list too. Further, default users were added
to all these custom, duplicate roles, meaning they were automatically added to other
projects. When new projects were created, administrators would have to manually remove
all those bogus users where they didn't apply. Instead of a tidy list of approximately 5 role
types, each project had 20. Project-level admins were routinely confused by what these line
items were for. The answer always was "Sorry, please ignore them. They don't apply to
your project."
User Management
User management is more than just "adding new users" as they join the company. Think of your
user list as a flower garden that needs regular attention to remain accurate. You have to establish
procedures on how to support new users as well as departing users.
New Users
New user creation requests should be logged just like any other JIRA related request. Use the
worksheets to establish your new user procedures.
Worksheet: New User Request
1. What is the user's full name?
2. What is the network username and email address?
3. What does the user need access to?
▪ Is this access warranted/approved?
▪ Is this request for a new or existing user?
▪ Is this a name change for an existing user?
4. How long should this user retain access? (For cases of role, test, or external user
accounts, there should be an access end date. Create a separate issue now to remind
the admin team to remove this user at a future date.)
Download this worksheet at: jirastrategy.com/link/new-user-request. Use the code in the


TIP
Turn this worksheet into a “Create” screen in your JIRA Support project!
Worksheet: New User Communication and Checklist
When a new user is added, give them access instructions, usage information, and instruction
for obtaining assistance. Download the "New User Communication and Checklist" template at:
jirastrategy.com/link/new-user. Use the code in the “Worksheets, Templates & Companion
Materials” section to download it for free.
Wording: Sample New Account Message
Hi @username, you have been added to the "jira-users" group, which gives you access to JIRA,
our project management and issue tracking app.
You can access it at [URL], using your [username and password details] credentials. JIRA
training materials are available at: [URL]
Please test your access and if all is well, click the "Pass" transition button, to close this request.
New User FAQs
Place answers to frequently asked questions next to the JIRA login form.
Example Questions:
• What credentials are used for login?
• How do new users receive accounts?
• How are passwords reset?
• Who can provide login assistance?
RECOMMENDATION
Use the "Introduction" feature to display login instructions to users.
To display login instructions, go to the "Introduction" field on the Admin > System > General
configuration page.
Next, add wiki markup (JIRA Cloud) or HTML (JIRA Server) formatted instructions to assist your
users.
NOTE
• The "Introduction" gadget must be present on your System Dashboard for the instructions to
show on your login screen. As such, the instructions will show on your default dashboard too.
o Tip: Consider moving the gadget to the bottom of the dashboard, as logged in
users probably don't need access information.
• Third party single sign-on apps may prevent the gadget from showing. (Example: The
gadget will display when JIRA is integrated with Crowd, but not with Google Apps.)
• The gadget will only display on the main login page, not for all login scenarios.
Image: Introduction
De-Activate User Accounts
The easiest way to manage a departing JIRA user's account is to have them assist with “clean up”
activities BEFORE they leave. Establish a procedure that notifies the JIRA Support team when an
employee is leaving the company including their termination date. Also collect their supervisor's
name, which is helpful for the “clean up” activities listed below.
DON’T
Wait for a user to leave the company before cleaning up their account.
User Checklist
Ask the user to do the following:
1. Reassign any incomplete issues to their supervisor
2. Change the reporter for any incomplete issues to their supervisor
3. Reassign project leads or component leads
4. Reassign any assets provided by add-ons
5. Delete any personal filters, dashboards, boards, or filter subscriptions
6. Remove any "favorite" designations

Of course, it's not always possible to have the user perform these actions. Their supervisor may be
able to help. Otherwise, consider changing the user's password and logging in as the user.
Admin Checklist
1. Reassign any shared filters
2. Reassign any shared dashboards
3. Remove any username references embedded in roles, workflows, permission schemes, or

issue security schemes
Recommendation: An easy way to find user assets is to search the JIRA database. Don't
attempt to remove records straight from the database; use the Admin area instead.
4. Remove any draft workflows
5. Remove user from any groups
6. Make the account inactive.
DON’T
Do not delete the user account! Instead, make them inactive to maintain a record of their
actions and issues.
Other Users
Any test, role, or distribution list user accounts should be created and removed in the same manner
as normal user accounts.
RECOMMENDATION
Make sure to collect the name of a single owner for each test, role, or distribution list account,
as this info is often difficult to obtain in the future.
Single Sign-On
RECOMMENDATION
When the application grows to over 50 users, it's time to consider a central user directory.
Single sign-on services are very useful mechanisms for access control. JIRA integrates with another
Atlassian application, called Crowd, as well as Google Apps, Active Directory, and other services.
Wherever you choose to manage application accounts, make sure you have a maintenance plan in
place. Be prepared for a little user confusion regarding how to set up an account, where to login,
and how to reset passwords. For example, what they see in the application, such as a password
reset function, might not work, if their password is stored in a different application. The screenshot
below shows two login forms when using Google Apps for authentication.
Image: Multiple Login Options
JIRA SERVER ONLY
In JIRA Server, when external user management is enabled, the "Can't access your account?" link
will be hidden. Users won't see any "forgot password" or "password reset" utilities.
Shared Access
Do you use more than one Atlassian application? While it's tempting to give all users access to all
applications, consider how applications may be used in the future and the impact of that decision on
user counts and licensing.
At one company, JIRA and Confluence both started out as IT-only tools. To save a step in
account creation, any user that attempted a JIRA login was automatically given an account
and placed in the "jira-users" general permission group. Confluence was setup with a global
permission which allowed anyone in the "jira-users" group to login. Subsequently, members
of the jira-users group were haphazardly added to some global Confluence spaces. This
worked for a while, but then non-IT teams started to use Confluence as well. There was
now no way to separate JIRA users from Confluence users. Since all JIRA users
automatically became Confluence users (whether they ever actually logged in to Confluence
or not) license usage appeared equal for both applications. The effort to decouple access
was a tedious and manual job. First, the "jira-users" group was removed from the global
Confluence permissions. Next, the "jira-users" group was removed from individual
Confluence spaces. Finally, any users who actually needed Confluence access were added
to the "confluence-users" general permission group. As a result, the Confluence user count
was only a quarter of the size of the JIRA user count.

Part 2: Project Configuration
Let’s explore the major project configuration concepts. Use this section for:
• A brief explanation of each configuration area with links to documentation
• Do's, don'ts, and best practices so you can avoid common mistakes
• Worksheets you can customize for your own needs
Name Your Schemes

The naming of schemes and assets in JIRA is so important that it deserves its own section. Smart
naming will ensure things are easy to find for administrators. These principles apply to every
scheme and chapter to follow. However, individual sections may contain additional naming
suggestions.
RECOMMENDATION
For each new element you create (project, scheme, etc), use the "description" field to reference
the issue ID it was created for. This way, you'll be able to quickly find all the supporting
documentation.
Image: Description Field Referencing an Issue ID
DO
1. Establish and use a standard naming convention. Assets in the administrative area are
generally listed alphabetically, so you should consider ordering in your naming structure.
2. Name assets for the function they support or the problem they are solving. Don't name
assets for the project that will use them!
▪ Example: A workflow name like "Development with Code Review" is more descriptive
and useful than "John's Team Workflow."
3. Names should be descriptive but generic enough so that they can be used for multiple cases
and by multiple products.
4. Make any scheme or asset name short and easy to understand. Long names will only lead
you into the swamp. Here’s why:
▪ Long and multiple word names make things harder to search and query for.
• Multi-word names require quotes in queries.
▪ Long names can take up too much room on a screen and will often be truncated
(making them harder to read and understand.)
▪ Long names take longer to type and increase the possibility of query or spelling
errors.
▪ Long names create longer URLs. (Example: When sharing filter results)
▪ Long names also take up more room in the database.
DON’T
Don't name schemes with the word "new" (e.g. "New Workflow") because it won't be new for
long! Unless you are diligent about updating names and descriptions, once something is no
longer "new", this naming convention quickly becomes useless.
JIRA Terminology
It is important to adopt a consistent terminology for JIRA and its features.
Example: A collection of issues is called a "project" not a "queue." JIRA’s documentation shows
"queue" only for email or JIRA Service Desk, not projects.
Referring to assets by their real names avoids confusion between users and also when you
communicate with Atlassian Support.
At one company, users had multiple names for the term “issues.” They called them tickets,
tasks, task requests, and even "a JIRA" as in "Go create "a JIRA" for that!" Use of the term
"JIRA" within issues made it hard for the admin team to separate actual application issues
from other issues. A simple query to find application problems would return issues that
included copy like: "here's the JIRA for the bug" or "execution doesn't match the
requirement in the JIRA." At a training event, users were speaking about "creating a JIRA”
which confused the audience who interpreted this to mean we were creating multiple JIRA
application instances, not just individual issues.
DON’T
Don’t invent custom names for standard JIRA elements.

Projects
Quick Explanation
Project – A collection of issues.
Initial Attributes:
• Name
• Key
• Project Lead
Additional Attributes:
• URL
• Project Type
• Project Category
• Avatar
• Description
Benefits:
• Projects can be set up per department, per team, or to track large initiatives.
When to Use:
• Create a new project when you need different Components, Versions, Permissions or
Notification strategies.
Documentation link: jirastrategy.com/link/jira-project
Strategy for Creating New Projects

Creating a repeatable and standard procedure will save you time when collecting and fulfilling project
creation requests.
Does this scenario seem familiar to you?
Mary: "Hi John, I need a new JIRA project created for the ecological initiative we'll start
working on soon."
John: "Sure Mary, what would you like this new project to be called? Who will be the project
lead? Will you need a task-based workflow or a support-based workflow? Also, when do you
need this created by?"
Mary: "John, let's call it "Wetlands Reconstruction. I need it by next week."
John: "Thanks Mary. I still need to know who the project lead will be and what type of
workflow you desire."
The conversation continues back and forth, likely over a few hours or even days until John finally has
the basic information he needs to create a new project. This is a waste of time. Instead, create a
standard template for each new project request.
Wording: Sample New Project Request Procedure
JIRA is a fantastic way to track your team's work or individual assignments. And it's not just
for developers! Project Managers, individual teams, and really anyone can benefit from JIRA's
project and task management features.
If your team doesn't already have a JIRA project, it's easy to get one created. To request a
new JIRA project, create an issue in the JIRA Support project. (Select the "Add Project" issue
type.)
TIP
Consider reusing existing workflows, statuses, fields, etc. for your new project.
Once the administration team has received your request, you may receive questions or
recommendations based on your request. Please note that it may take up to a week to
complete your project setup, depending on its complexity.
Your project will be in "test mode" until the configuration is complete. Therefore, your team
members may not be able to access the project during this period.
Only create test issues until you receive notice that the project is ready to process real issues.
Download this wording at: jirastrategy.com/link/project-wording. Use the code in the “Worksheets,
Worksheet: New Project Request
Ask questions that will help determine if and how to complete a request or propose an alternate
solution.
RECOMMENDATION
Ask what type of project is needed and assign the default or standard schemes built to fit
those needs. Don't ask questions that lead to customizations that you aren't willing to
accommodate. For example, asking the project lead to choose specific workflow steps
could lead to setup that is difficult to maintain and has too many custom elements. If
any customizations are needed, they should be handled separately.
Questions
Ask your users to answer the following questions as part of their new project request.
1. How many issues do you expect will be created per month?
2. What is the desired project name?

▪ This is the official name of the new JIRA project. It will be seen everywhere in
JIRA like the “All Projects” listing, issue breadcrumb links, and the header for
project summary and admin pages. Choose something that’s descriptive, unique,
short, and works for the long term. The maximum character limit is 80.
3. What is the desired project key?
▪ The key is a few letters used as a project's "short" name and to identify issue
IDs. For example, the issue ID "PROJ-1234", the key is "PROJ." The maximum
character limit is 10. The key can’t be changed once the project is created.
▪ Recommendation: Encourage users to choose their project key wisely or help

them choose. While you can technically change a project's unique key, it's not
recommended.
4. Who is the desired project lead?
▪ The name of the person in charge of the project from a JIRA perspective. This
person is listed as the project lead on the “All Projects” page and often the
default issue assignee. This person will be responsible for certain project
settings, like managing the list of users who can perform certain tasks within the
project. For more information, see the "Responsibilities" documentation.
5. What is the purpose of this project?
▪ For example, do you need a setup for task management, software development,
support, etc.?
6. Is there an existing project whose setup that you would like to use?
▪ If yes, provide an instruction like: "Set up this project like the existing
"PROJECTKEY" project."
7. How long will the project be used?
▪ Does the project have a known end date or archive date?
8. Are there any access restrictions?
▪ Specify who should have restricted view access. List any individual issue
restrictions. Provide restrictions for any actions like edit, set fix version, etc. that
need to be restricted.
9. Is there any other information you would like to provide?
10. Do you have any questions?
Download this worksheet at: jirastrategy.com/link/new-project-request. Use the code in the

TIP
Turn this worksheet into a “Create” screen in your JIRA Support project!
Considerations
When you are processing new project requests, there are a few other things to consider:
• Is this new project necessary to support the use case? Or should an existing project be used
to accommodate it?
• Should an existing similar project be archived?
• Does the requested project lead understand their responsibilities? See the
"Responsibilities" section.
• Are any requested customizations or new schemes warranted? If so, what impacts would
they have on other projects, user groups, of the application as a whole?
• Is a future archive action needed? If yes, create an issue now to remind the team to perform
it at a future date.
RECOMMENDATION
You should spend less than 10 minutes on each new project set up. Andre Lehmann,
JIRA/Confluence Administrator and Leader of the Saxony, Germany Atlassian User Group,
recommends using the JIRA Command Line Interface (CLI) add-on to set up new projects in
under a minute.
Name Your Project

Your project name and project key are critical attributes to help you identify your project. A best
practice is to make the project's title similar to the project key. Users should be able to
communicate using either project name.
Your project name should be descriptive yet generic. Example: A project with the key "ACME"
doesn't tell the user what kind of issues should be reported in that location.
The project key should be short in length.
One project had a 13 character key! While a long key is allowed in JIRA, it makes little
sense to make end users type something long.

DON’T
• Use keys containing "reserved" words.
o Example: A project with the key "JIRA" will result in strangely formatted queries.
▪ Atlassian uses "JRA", "CONF", and CWD" for their JIRA, Confluence, and
Crowd public bug reporting JIRA projects.
• Avoid keys containing numbers. The combination of a key with a number and sequential
issue IDs are likely to be confusing.
o Example: In the "YEAR2017" project, the first issue would be YEAR2017-1.
Project Categories
Project categories are simple groupings of similar projects. A project can only belong to one
category and there’s no way to create a project hierarchy. Categories are different than and in
addition to a project’s type.
Image: Example Categories
RECOMMENDATION
Always assign projects to a category. This will allow users to filter large groups of projects with
JQL. JQL example: category = "IT Support"
Share Project Schemes and Assets
One of the goals of the Advisory Board and the Application Administrative team is to share schemes
and assets between projects. All projects should be set up in the same way until there is a clear and
justifiable need to differ from the standard. A small list of shared schemes:
• makes new project creation faster,
• makes project maintenance easier,
• makes admin page load faster,
• allows user page loads and queries to return faster, and
• requires less records in the database.
The following assets were meant to be shared by many projects:
• Issue Types and Issue Type Schemes
• Workflows and Workflow Schemes
• Screens, Screen Schemes, and Issue Type Screen Schemes
• Fields, Field Configurations, and Field Configuration Schemes
• Notification Schemes
• Permission Schemes
• Issue Security Schemes
• Roles
The following assets are project-specific:
• Users
• Components
• Versions
RECOMMENDATION
If you must create a set of schemes that are specific to a certain project (and not likely to be
shared), it's helpful to use the project's unique key in the scheme's name. Example:
PROJECTKEY: Scheme Name.
DON’T
Don’t create brand new schemes for every new project.

Establish Scheme Defaults
JIRA comes with pre-loaded schemes named with the keyword "default." If those schemes lose their
integrity, they no longer represent good default settings, and new projects become harder to create.
RECOMMENDATION
See how far your application has strayed from the default by comparing it to the default set up
reference at: jirastrategy.com/link/clean-instance . Use the code in the “Worksheets,
With hundreds of schemes in every scheme category, one company had trouble selecting
the correct ones for a simple new project set up. The customized defaults no longer
represented what the ideal default settings should be.
RECOMMENDATION
There are a number of add-ons that can help you create a "project template." All you really
need to do, however, is keep your list of scheme options to a minimum. If there are only a few
choices, it won't be hard to pick the correct one for the project being built.
DON’T
Don’t let the "default" schemes become no longer the ideal default.
Project Configuration Strategy

It's important to set expectations before the project is configured. You'll want to avoid users
creating issues and trying to work in a project you are still configuring.
The second a new project appeared in the "All Project's" list, users began creating and
working new issues. Since the project was still being configured and customized, the
project likely didn't have the correct issue types, the desired workflow, and the requested
custom fields yet. This lead to premature trouble reports and questions about the project's
configuration.
RECOMMENDATION
To combat users interacting with a partly configured project, hide the project until all set up
items (including testing) are complete. Only let users testing the project have the "Browse"
permission.
Here's a helpful checklist when creating a new JIRA project. Completing items in a specific order can
make set up easier to complete. See “Project Configuration Recommendations” for additional
details.
RECOMMENDATION
For large, custom projects, paste the checklist into the request ticket and "check off" items as
you complete them. This will help requestors know how close they are to being able to test their
new project.
Worksheet: New Project Configuration Checklist
The checklist below is designed to guide you through the project configuration process. Please
do not start using your project (adding real issues) until all line items are completed. Look for
a green check mark next to each line item. Also, please look for any notes or action items for
you to complete. We look forward to completing the setup of your project.
Configuration Process
1. Create Project
▪ Display Name: [long name]
▪ Project Key: [key]
▪ Project URL: [URL]
2. Set Users and roles
▪ Set/Verify Project Lead
▪ Set Default Assignee
3. Set Project Details
▪ Link
▪ Project Type
▪ Project Category
▪ Icon
▪ Description

4. Create/Set/Verify Issue Types
5. Create/Set/Verify Permission Scheme
6. Create/Set/Verify Notification Scheme
7. Create/Set/Verify Workflow
8. Create Components
▪ A temporary "Test" value is available. Project Lead: please set up your

Components here: [insert link]
9. Create Versions
▪ A temporary "Test" value is available. Project Lead: please set up your Versions
here: [insert link]
10. Add Custom Fields
11. Verify Standard Capabilities
12. Create/Set/Verify Field Configuration
13. Create/Set/Verify Screens
14. Create Test Issues
15. Requestor Testing
16. Address Change Requests
17. Delete Test Issues
18. Unhide Project
19. Attach Configuration Screenshot
20. Remove Unused Schemes
Download this worksheet at: jirastrategy.com/link/project-checklist. Use the code in the

Project Configuration Recommendations
Consider the following recommendations as you complete each configuration step.
1. Create Project
▪ Display Name
o Recommendation: Echo the project's name back to the user. Note any
modifications needed. (Example: removal of special characters, shortening the
length, spelling or capitalization correction, etc.)
▪ Project Key
o Recommendation: Echo the project's unique key back to the user. Note any
modifications from the original request.
▪ Project URL
o Recommendation: Paste the project's URL so the user can easily access and
favorite or bookmark the new location.
2. Set Users and roles
▪ Recommendation: Remove general users from the "Users" role during project build
out. This will prevent users from creating issues before the project is ready to accept
them. Add just a few tester names to the "Users" role so others will be able to test
the project in the steps to follow. Add the “jira-administrators group” to the
"Administrators" role (unless already given access through the Permission Scheme) so
they can support project management efforts in the future.
▪ Set/Verify Project Lead
o Recommendation: Communicate the responsibilities of project ownership

with this user. See the "Responsibilities" section for tips.
o Recommendation: Resist the urge to list a distribution list or generic user as

the lead. See the "distribution list warning" in the "Project Leads" section for
more information.
▪ Set Default Assignee
3. Set Project Details
▪ Link
o Recommendation: Link to a location where a user can obtain more

information about the initiative or the team.
o Recommendation: If you use Confluence, make the unique JIRA key and the
Confluence key match, so both locations are easy to users to find.
▪ Project Type
▪ Project Category
▪ Icon
▪ Description
o Recommendation: Provide a single point of contact for the project for
application administrators and end users. If you decide to set a distribution
list or generic user as the Project Lead, add the name of the distribution list
owner here.
o Recommendation: Include the ID of the issue used to create the project, so

any set up or customization notes are easy to access.
Image: Project Description with Request ID
4. Create/Set/Verify Issue Types
5. Create/Set/Verify Permission Scheme
6. Create/Set/Verify Notification Scheme
7. Create/Set/Verify Workflow
8. Create Components
▪ Recommendation: If component values are not provided as part of new project

creation requirements, add a temporary value of "Test" and ask the project lead to set
them. This will avoid a UI error if components are required by the field configuration
and visually show that components still need to be set.
9. Create Versions
▪ Recommendation: If version values are not provided as part of new project

creation requirements, add a temporary value of "Test" and ask the project lead to set
them. This will avoid a UI error if components are required by the field
configuration and visually show that versions still need to be set.
10. Add Custom Fields
11. Verify Standard Capabilities (See the "Standard Capabilities" worksheet.)
12. Create/Set/Verify Field Configuration
13. Create/Set/Verify Screens
14. Create Test Issues
▪ Recommendation: Build administrative testing into your new project creation

workflow before requestor testing begins. Create one test issue for each available
workflow and/or screen/field configuration. Test both the expected workflow path and
any alternate paths. Completely populate every field to show the next set of testers
what data is expected and what it should look like.
▪ Recommendation: Don't be afraid to have fun with your new project test issues!
This is a good way to get your requestor interested in the project configuration
process. Create very silly sample issues, which are more likely to elicit response over
the bland summary title "Test Issue #1." See the “Character Users” section for
ideas.
15. Requestor Testing
▪ Recommendation: Build user acceptance testing into your new project creation
workflow. This testing is done by the requestor and any project or team leads before
the project becomes available to all end users. You may need to provide instructions
to help the testers understand what to test and what to look for. Have them create,
edit, and transition test issues.
16. Address Change Requests
17. Delete Test Issues
▪ Recommendation: Delete test issues in bulk and suppress email notifications

during the deletion process. Alternately, close issues and make it clear they were
created for test purposes.
18. Unhide Project
▪ Recommendation: Make the project visible by adding general users to the Users
role. (NOTE: This may only include the "internal" user's group. See the "External
Users" section for details.)
19. Attach Configuration Screenshot
▪ Recommendation: Take a screenshot of the project's administrative "Summary"

page so you'll have a record of the initial set up. Attach the screenshot to the new
project request issue.
20. Remove Unused Schemes
▪ Recommendation: JIRA may have auto created new schemes as part of new
project creation. Remove them if the project will use shared schemes instead.
Wording: Sample New Project is Ready Message
@username - your new JIRA project has been configured, tested, and is ready for use! Please
add the names of any users not already listed on your "Users and roles" page here: [URL].
For more information about your project's settings and the role of the project-level
administrator, please see: [URL]. See the "Responsibilities" section.
Finally, if all is well, please click the "Pass" transition button, to close this request.

Test New Project Configuration
RECOMMENDATION
Make sure the requestor has tested the project before making it available for general use. Have
them create a new issue (or one issue per Issue Type) and transition it fully through the
workflow. This may help uncover missed needs or requirements. It's much easier to make
configuration changes before the project is filled with real issue records. You'll also avoid
needing to retrain users or migrate entered data.
A new project to hold sensitive company data was requested. Everything was configured
except for the permissions. The requested restriction requirements were never provided
however. Regardless, people started using the project. The sensitive information was
available for any JIRA user to view.
DO
As noted in the previous recommendation, hiding a project from JIRA users until all
requirements are received and implemented is useful.
Configure Your Project

Periodically check in with your project leads to make sure the current configuration is meeting their
needs. Also provide documentation and resources to support additional requests and customization
needs.
DON’T
Don't set up a project and assume the lead knows how to properly maintain it.
RECOMMENDATION
Give the project lead simple instructions for configuring, maintaining, and requesting further
customizations. (See the documentation templates below.)
Wording: Configure Your New Project
Your new project is ready! Now what? As the project lead you can add or modify the project to
best suit your team’s needs. This document covers how to configure and maintain your project
in JIRA.
Administration Area
Each project has its own administrative area. A project-level administrator can manage all
settings for your project. They cannot however manage settings for other projects or make
application or system-level changes. As a project-level admin, you can't break anything, so feel
free to experiment with the project settings so they fit your needs. The only thing we can't
"undo" in JIRA is deletion of issues.
[Insert instructions for accessing the admin area in your version of JIRA.]
NOTE
If you do not see this link, it's possible that you were not added to the to the "Administrator"
line in the "Users and roles area" for this project. Please contact the JIRA Support team for
assistance.
Your first priority is setting up your Versions, Components, and Users and roles.
Versions
Versions are points-in-time for a project. They help you schedule and organize your releases.
You can also use Versions as another distinguisher for something you want to track. Skip this if
your team has no work to release.
If you are part of a development team, use the "Releases" page to add your "Versions" using
unique software version numbers. The "Version" column is what will be queried against, so
make the naming format short and easy. (Example: A simple name like "1.0" is easier to
query than "Version 1.0 Special Release").
Image: Sample Versions
NOTE
Only projects of the type "Software" and users in the "jira-software-users" group will see the
Versions feature.
Read more: jirastrategy.com/link/managing-versions

Components
Components represent a grouping of issues in a project. This feature allows you to query all
items in your project associated with that component. You can use this in a number of
ways. Here are some examples:
• Example 1: Your project is to build a car. You might want to group issues in your "car
project" by parts of the car that need work.
o Sample Components: Tires, Engine, Windows, Headlights, etc.
• Example 2: You have a cross-functional team where many different types of jobs are
performed. You might want to group issues by type of job or department.
o Sample Components: Marketing, Design, Support, Legal, etc.
• Example 3: Your project is for writing copy for the entire company. You might want to
group issues by where the copy will be posted.
o Sample Components: Website, Social Media, Employee Handbook, Product

Manual, etc.
The Component is the most powerful feature in a project. Not only can the project-level
administrator maintain the selection list, but this field has auto-assignment capabilities.
Example: If Component “X” is selected, assign Issue to user “Y.” Using the "build a car"
example above, you could use this to automatically assign any "Tires" request issues straight to
Mary, and any "Engine" related issues to John, etc.
Set up auto-assignment by entering a username in the "Component Lead" field. Then, set the
"Default Assignee" field to the value "Component Lead." Alternatively, you can assign all issues
to one specific person for triage or assign all issues no one (using the "Unassigned" option) for
later assignment.
NOTE
The auto-assignment ability only happens when a Component is selected as part of an issue
"create" action. Later, if a component is selected or changed, as part of an "edit" action, no
auto-assignment change will occur.
DO
Make the component names short. Really long and multiple word values make issues
harder to search for.
DON’T
The only thing you should NOT use Components for is to duplicate an existing JIRA field
or function. (Example: Don't use this to group issues by a person's name. JIRA uses
the "Assignee" field to specify who needs to complete an issue.)
If you're not sure how you might want to use the Components feature, skip it and come back to
it later. After you've used the project for a while, issue patterns should become clear.
Read more: jirastrategy.com/link/managing-components
Users and Roles
The "Users and roles" area gives specific users, or established groups of users, access to
perform certain actions within the project. The options to update the Project Lead and the
Default Assignee for all (not otherwise assigned) issues are at the top of the page.
There are a number of pre-established roles. For now, let's focus on the "Administrators" and
"Users."
Administrator
Any listed user or group with project-level admin rights can modify all settings for the project.
They will see what you are seeing right now. In general, this list should have as few names in
it as possible.
User
A user is someone involved with any aspect of a project. This is someone who creates issues,
requests work, completes work, reviews work, etc. Add the names of your individual team
members here.
Read more: jirastrategy.com/link/role-memberships
Conclusion
If you haven't already, create some sample issues so you can see how the project works. Also,
try transitioning an issue all the way from creation to completion to see how it behaves in its
life cycle. If the issue screens have the fields you need and the workflow functions as you need
it to, then you are done with your configuration! If not, you'll need to request further
customizations from the JIRA Support team.

Wording: Request Customization for Your New Project
Your JIRA project has been created and configured, but what if you need additional
customization? The following areas of your project can be further modified:
Fields
Are there fields on your create, edit, or view screens that will never be used? If so, ask for
these to be removed for your project.
Example: "Please remove the [fieldname] field from [projectname]'s" create, edit, and
view screens."
Is an expected field missing? Does a new custom field need to be created?
For any new field requests, provide the following information:
1. What is the desired field's name? (label)
2. What will the field be used for?
3. What field description should be shown to the user?
4. What is the field's type?
▪ What kind of field is needed? (What type of data will be collected?) Example
field types: text, number, date, checkbox, select list, URL, etc.
5. What field properties are needed?
▪ For a text field, will a single line or multiple lines of text be collected? For a
checkbox or select list, what are the individual selection values? (Example:
choice 1, choice 2, etc.)
6. What screens should the field be shown on? (Create, edit, view, or all?)
7. What are the validation rules? (if any)
Screens
Each issue type has three standard screens: create, edit, and view. In addition, you may have
transition screens that display as part of the workflow.
On these screens, you can customize the following:
• The fields displayed.
• The order of the fields.
• The presence of tabs. (If you have many fields, use tabs to break them up into logical
groups.)
Image: "Internal Details" Tab Example
NOTE
It is possible to hide a field on your "create" screen, but show it on your "edit" and "view"
screens. This is helpful for projects with complex data needs. It's best for your end users to
only ask for the information you absolutely need up front and collect additional details later.
This certainly means more screens to maintain, so only use this technique only when truly
warranted.
Workflows
There are two parts of a workflow to know about: statuses and transitions. A status is
a descriptor of an issue's current state. (Example: "In Progress" or "Closed.") A transition
is forward or backward movement between statuses. Between each status are a number of
transition buttons to facilitate movement. A transition button can also trigger a screen to
collect additional information, update existing information, or provide user instructions.

Use the provided "Custom JIRA Workflow Template" to craft your custom workflow. Draw a
workflow on paper first to ensure it makes logical sense and all forward and back transitions are
accounted for. After drawing the workflow, write the workflow out in words. This can uncover
additional needs you may have neglected to draw or consider. Note any steps that require
restrictions or special conditions.
Download this worksheet at: jirastrategy.com/link/workflow-documentation. Use the code in

the “Worksheets, Templates & Companion Materials” section to download it for free.
See also: "Responsibilities" in the "Project Leads" section.
Notifications
Your project can send email notifications for various standard and custom events. Notifications
can be sent to individuals, project roles, or (externally managed) corporate distribution lists.
Example notification rules:
• When an issue is updated, email the Reporter and Assignee.
• When an issue is reassigned, email the original Assignee and the new Assignee.
• If transition button X is clicked, email group/user Y.
• If action X occurs, email all the 'Watchers'.
This feature should be used sparingly, and only for most important events. If you send the
entire team an email for each and every content and status update, they are likely to filter their
JIRA email and miss the important messages. Email notifications should be considered a
passive and secondary monitoring method. (The primary method is for users to proactively
monitor issues by regularly logging into JIRA and utilizing filters and dashboards.)
Permissions
Your project has its own set of permissions that can be further customized. This includes
abilities to perform certain standard actions like: "Create Issue", "Assign Issue", "Manage
Watchers", etc. Standard actions can be restricted to project roles, groups, and individuals.
Restrictions can quickly become a maintenance nightmare however. It's best to only add
restrictions when absolutely necessary.
Questions? Please contact the JIRA Support team.
Issue Types
Quick Explanation
Issue Types serve as a simple distinguisher between requests.
Example: Bug, Task, Feature, etc.
Attributes:
• Name
• Description
• Type (Standard (Parent) or Sub (Child))
• Icon
Benefits:
• An icon provides a visual distinguisher in a filter, dashboard, board, or email notification.
• You can set a standard behavior (Example: screen) per type.
Documentation: jirastrategy.com/link/issue-types
Best Practices
DON’T
Create super specific or duplicate issue types
Before you create new issue types, consider what kinds of issues your users will report, and then
group them into one generically named item. Here's an example:
Issue Type
Kinds of Issues Notes
Name
I've found a: Bug Instead of multiple issue types, use a custom field to
Development Bug, collect the environment (location) of the bug.
Staging Bug,
Production Bug
I need a: Password, Access, or even The type of access needed by the user will be specified
Building Key, Server more generic in their request copy. If that's not enough and you'll
Account (Example: need to query on the type of access, use a label,
Support) component, or custom field to collect that level detail.

Ideally you would have one Issue Type to indicate a software error. Instead, one company
had 9! For example: Bug, Defect, Beta Defect, Bug Report, Development Defect,
Production Defect, etc. Additionally, there were 22 issue types with the word “Task” in
them! All these items were mere duplicates, not useful distinguishers.
The more issue types you have, the harder your application becomes to manage. A long
issue type list means a longer process to move issues or associate them with a different
workflow.
Issue Type Schemes

Quick Explanation
Issue Type Schemes – A group of Issue Types
Attributes:
• Name
• Description
• Default Issue Type (Example: Task)
• Issue Types (including Sub-tasks)

Benefits:
• Restrict a Project to a specific set of available Issue Types
o Example: A Project for a development team may utilize: Feature, Bug, and Task
o Example: A Project for a business team may utilize: Request and Task
Documentation: jirastrategy.com/link/issue-types
When it comes to creating issue types, it’s important to keep things organized.
At one company, there were a few projects that used the default Issue Type Scheme, which
contains every available issue type. Reporters in that project were overwhelmed when
creating a new issue. Why? Because they had to wade through over 100 available
selections! The choices weren't even listed alphabetically! Project leads couldn't easily
report on or segment the issues their teams were addressing. Don't assign the default
scheme.
DO
• Use sub tasks, which help users break up issues into manageable pieces.
• Order the Issue Types alphabetically, or by frequency of use, so users can quickly locate the
correct one.
DON’T
• Add Issue Types that are too specifically worded, or won't be shared by a large number of
projects.
• Add similar Issue Types. (Example: Don't use both "Bug" and Defect.")
• Set a default unless you are sure that type will be used most often by all projects.
How many different combinations of issue types could a company possibly need? One
company had 134! This was not because they were actually needed, but because new types
and schemes were created for every new project.
Sample Issue Type Groupings
Here are some sample issue types you might find in different types of projects.
Project Type Software Business JIRA Support
Issue Types
• Bug • Idea • New Project
• Code Review • Task • Modify Project
• Epic • Sub-task • User
• Improvement • Task
• New Feature • Sub-task
• Story
• Task
• Sub-task
Using the example in the table above, create one Issue Type Scheme for each of the three types of
projects. For each scheme, associate the appropriate Issue Types. Then, each project can use the
scheme that most applies to them. Example: All projects where software development occurs can
use the scheme called "Software." No need to create one separate scheme per project.

Image: Issue Type Schemes to Issue Types Relationship
Name Your Issue Types and Schemes
DO
• Issue Type Scheme names should describe the group of Issue Types, not the Project that
plans to use the grouping. Example: “Development Suite”
• Issue Type names should be generic. Example: “Task” is sufficient. Don’t make a new type
for every sort of task a user could request.
MISTAKE
When I made my first JIRA project, I created 4 new, duplicate, issue types. For example: I
created "Project Name Task" when the generic "Task" type already existed.
RECOMMENDATION
Publish to a list of available Issue Types. It may encourage end users to request existing values,
rather than proposing new or similar ones. Send users to the "Show Constants Help" page (at:
yourjiraurl.com/secure/ShowConstantsHelp.jspa), copy and paste a static list from JIRA, query
the database, or use the REST API to generate a quick list of available selections.
See the "Database Queries" section for more info.
Statuses
Quick Explanation
Statuses – descriptors for an issue's current state.
Example: Open, In Progress, Closed
Attributes:
• Name
• Description
• Category
Documentation: jirastrategy.com/link/jira-status
Status names must be unique; JIRA will not allow you to create duplicates.
Best Practices
DO
• Name statuses so they reflect a current state. Good status names immediately tell a user
what is occurring and what state an issue is in the workflow process. (Example: "Pending
Review", "In Review", "Being Reviewed", "Awaiting Review", etc.)
• Teach your users the difference between the "Resolved" and "Closed" statuses.
DON’T
• Create ultra-specific status names.
o Example: "Pending Review by Marketing" or "Pending Review by John." These are too
specific and make workflows hard to maintain and share between projects.
• Use the wrong word tense.
o Example: "Reviewed." A word in this tense is a "dead end" and doesn't tell the user
what needs to happen next. A word in the past tense is more suited as an action word
for a transition, rather than a current state.
• Create multiple variations that mean "Closed."
• Confuse the "Resolution" field with the final "Closed" status.
o Example: Rather than create statuses like "Abandoned" or "Rejected", use the
"Resolution" field to indicate the "how" or "why" an issue is in the "Closed" status.
• Create "temporary" or "dead" statuses where issues are likely to sit for an indefinite amount
of time.

o Example: "On Hold" (A status like this can be useful if a responsible party proactively
and regularly reviews issues in this state.)
RECOMMENDATION
It may be useful to publish a list of available statuses. It may encourage end users to request
existing values, rather than proposing new or similar ones. You can: send users to the "Show
Constants Help" page (at: yourjiraurl.com/secure/ShowConstantsHelp.jspa), copy and paste a
static list from JIRA, query the database, or use the REST API to generate a quick list of
available selections.
Status Categories
A status category helps a user visually identify where an issue is in its lifecycle. It's important to
assign a status to the most logical category selection. For example, early workflow statuses like
"Open" or "New" belong in the "To Do" category. Statuses in the middle of a workflow, like
"Awaiting Approval", "In Development", or "Being Verified" belong in the "In Progress" category. A
status at the end of a workflow, like "Closed" or "Done," belong in the "Done" category. Each
category has a unique color and is seen by end users on an issue's "view" screen or in a workflow
diagram.
Image: Status Categories
Resolutions
Quick Explanation
Resolutions – ways issues can be closed
Example: Fixed, Duplicate, Cannot Reproduce
Attributes:
• Name
• Description
Benefits:
• One selection value can be set as the default.

Documentation: jirastrategy.com/link/jira-resolution
What is a Resolution?
A Resolution answers the question: "Why is this issue closed?" If work was completed, the issue
may be marked as "Done" or "Fixed." If the issue is a duplicate of another issue, the reason for
closing is "Duplicate." If the issue works as intended or can’t be replicated, the resolution may be
"Won't Do" or "Won't Fix."
Resolutions prevent the need for long status names, like "Closed as Complete" or "Closed as a
duplicate.”
A Resolution is generally set at the time an issue reaches the "Resolved" status. An issue is shown
as "Unresolved" until a value is set for this field.
Image: An Unresolved Issue
RECOMMENDATION
Once an issue is marked “Resolved,” take your users to a transition screen as part of the
workflow. Alternatively, you can auto set a resolution using a workflow post function. It's
always better to allow the user to set the appropriate value, but even a generic value of "Fixed"
is better than allowing a closed issue to show the default value of "Unresolved."

One company had so many resolutions that they created a custom field to show a sub-set of
selections for specific projects. A workflow post function was then used to copy the custom
field value to the resolution field. Discrepancies between the selections in the custom field
and the Resolutions created application errors in the front end and back end. Instead of
creating a workaround, the company should have limited their Resolutions list to selections
that would work for all projects.
RECOMMENDATION
When an issue is reopened, use a workflow transition to clear the value of the "Resolution" field.
Bulk Update Resolutions

When it comes to cleaning up messes like the one mentioned in the swampy example, it would be
nice to use “Bulk Change” feature, but you can’t update issue resolution values that way. This
means, you have to get a little grimy and use a few workaround strategies to help you clean up a
Resolutions list. The pros and cons are provided for each strategy so proceed with caution.
1. Workflow Transition
Create a temporary workflow transition to update resolutions with a background post
function.
▪ PROS: This action will leave an audit trail as the changes will be logged as part of the
issue history.
▪ CONS: You need to create one transition and post function per status, per workflow.
This potentially means a lot of manual work. Additionally, your change may generate
a large amount of email notifications.
2. Third Party Add-on

You can implement a third party add-on like “ScriptRunner for JIRA” for example, which has a
"Bulk Fix Resolutions" feature. Read more about it in the "Noteworthy Add-ons" section.
▪ PROS: The change completes very quickly, you don't need to create new workflow
transition behaviors, and no email notifications are sent.
▪ CONS: This change leaves no audit trail. The issue update date is unchanged and
audit log records no activity.
3. Other
While these other options exist, none are recommended. Depending on the scope of the
problem, it may be best or easiest to fix a "missing Resolution" problem for all net new
issues, and leave existing issues as they are.
▪ Fix in another Application (Excel, for example)
o Export the problem issues, add Resolution values, and then re-import the
issues. The "External Issue Import" function can handle issue updates, as long
as the unique issue keys are provided for mapping. Alternatively, you could
import the issues into a new project.
▪ Backwards Transition
o Transition issues back to a pre-resolved state, set a Resolution as part of the

workflow, and bulk close the issues or continue to transition them to their
appropriate status.
▪ Direct Database Update
o Changing anything directly in the database is never recommended. If you

decide to take on this risk, at a minimum:
1. backup your data,
2. verify the backup,
3. thoroughly test your changes in a non-production environment,
4. have a database administrator standing by, and
5. have a robust rollback plan in case of unintended consequences.
RECOMMENDATION
To prioritize which issues to fix first, search for any issues beyond the "Resolved" status where a
resolution value is missing. JQL example: resolution = empty and status not in (open, "in
progress")
Unresolved Resolutions
In his book, Practical JIRA Administration, Matt Doar explains that "adding a Resolution named
"Unresolved" is a bad idea. Since the resolution field has a value, the issue will still be treated as
resolved by the standard JIRA gadgets." Here are some recommendations to avoid confusion and
clutter:
RECOMMENDATION
Treat "unresolved" as a reserved word. Never add it to your list of Resolution selections.
RECOMMENDATION
Alphabetize the Resolution selection list (and all others) so users can easily find familiar terms.

RECOMMENDATION
Don't create Resolution values like "On Hold" or "None" or any wording that sounds like an issue
isn't actually resolved. These selection types are invalid and confusing.
RECOMMENDATION
Don't create a Resolution value that means "Wrong Project" or "Wrong Type." If an issue is
created in the wrong project, then the problem shouldn't be marked "resolved" where it is.
Instead, use the "Move" command to move it to the correct place.
At one company, there were 34 resolution choices which included specific selections like
"Rejected by Security Team" and "Rejected by Finance Team." Additionally, there were no
selections for other departments that could reject a request. Many selections were
duplicates of each other. Some selections were invalid. For example, how can an issue that
is resolved also be "In Progress"?
RECOMMENDATION
Don't create overly specific Resolution values. For example, you probably don't need values like
"Rejected by Finance", "Rejected by Legal", and "Rejected by CEO" when a simple, more generic
"Rejected" value is sufficient. Only use non-generic values when there's a specific need or when
the data will be often queried.
At one company, resolutions weren't set by workflows. As a result, users would see all
issues, regardless of status, when viewing the "Assigned to Me" dashboard gadget. This is
because the gadget query rightly assumes unresolved issues are not completed.
Prevent the problem for new issues by addressing the workflow. Fix existing issues using one of the
"Bulk Update Resolutions" methods.
Priorities
Quick Explanation
Priorities – a relative ranking of severity or importance
Example: Low, Medium, High
Attributes:
• Name
• Description
• Icon URL
• Priority Color
Benefits:
• The display of priority levels can be ordered from highest to lowest.
• One selection value can be set as the default.

Documentation: jirastrategy.com/link/jira-priority
Best Practices
DO
• Set an appropriate color to represent the priority. Example: In web design, the color red
immediately conveys attention is needed. It's often used to display a warning, an error, or to
mark something urgent or important.
• Make sure the icon correctly represents the priority’s severity. The icon is only what is shown
on many screens.
RECOMMENDATION
Always place the "Priority" field before a requested date field on a screen. It may help set
realistic expectations to collect the importance before a date is entered.

Workflows
Quick Explanation
Workflows – the set of statuses and transitions that an issue goes through during its lifecycle
Example: Development Workflow, Task Workflow, Support Workflow, etc.
Attributes:
• Name
• Description
Parts:
• Statuses – descriptors for an issue’s current state
• Transitions – forward or backward movements between statuses
Documentation: jirastrategy.com/link/jira-workflow
A workflow is a standard set of statuses (steps) and transitions (movement between steps) that each
issue follows through in its lifecycle. Statuses take an idea from "conception" to "completion" or a
bug from "reported" to "fixed in production." Each project can have its own workflow and each issue
type within a project can have its own workflow as well. For example:
• A Task issue type might require a very simple workflow, with simple statues like "Open", "In
Progress" and "Closed."
• A Feature issue type might require additional statuses for steps that occur in the software
development process.
• Statuses for testing, code review, and deployment, for example, may make the workflow
more complex.
Name Your Workflow

• A Workflow name should describe the type of life cycle process, not the project that uses it.
Example: “Task Lifecycle”
• A Workflow Scheme name should describe the type of life cycle process group. Example:
“Development Lifecycle”
• A Status name should be short and reflect a current state in time.
Create a Workflow
RECOMMENDATION
In the beginning, keep workflows as simple as possible, until you've uncovered a deficiency or
process step that needs special attention.
The steps below outline the best practices for creating a workflow:
1. Before creating a new custom workflow, have the user explain their real life process to you.
The workflow should be as simple as possible.
2. First, draw (preferably on paper) a workflow to ensure it makes logical sense and all forward
and back transitions are accounted for. You can use the "Custom Workflow Documentation"
template as a way to communicate and document workflows.
3. After drawing the workflow, write the workflow out in words. This can uncover additional
needs you may have neglected to draw or consider.
4. Include logical backwards transitions so users can self-manage issues.
5. Give users options to abandon or stop progress on issues at appropriate times.
6. Give project-level administrators appropriate options to fix improperly transitioned issues.
▪ Example: Include a "reopen" transition button in the final status to deal with issues
that were improperly closed. (As this is a maintenance action, restrict this action to
project administrators.)
7. Use transition conditions sparingly. If a condition is needed, set the restriction to a project
role, rather than to individual, for easy maintenance.
8. Use transition validators and post functions to minimize the amount of manual work a user
has to do.
▪ Automatically assign an issue to the reporter when moving to an "information needed"

or "verification needed" type of status.
▪ Automatically assign an issue to the Project Lead in a "triage" type of status.
▪ Automatically move a parent issue to "In Progress" when a child issue starts progress.
Read more in the "Example Workflow Behaviors" section.
9. Name your statuses:
▪ Name statuses so they reflect the current state. Good status names immediately tell a
user what is occurring and what state an issue is in the workflow process. For
example, "Pending Review", "In Review", "Being Reviewed", "Awaiting Review", etc.
▪ Make any status names short and easy to understand what is happening with an issue.
Long, multi-word names are harder to query and may be truncated on certain
screens.

▪ Clearly define the difference between the "Resolved" and "Closed" statuses for your
users. See the "Resolutions" chapter for more information.
10. Name your transitions:
▪ A Transition name should be short and reflect an action taken.
▪ Good transition names immediately tell a user what action to perform to progress an
issue.
o Example: For an issue in "Pending Review" status, a good transition name

would be: "Review Complete." If you need a "pass/fail" situation, where an
action must pass a test before a transition can occur, good transition names
would be: simply "Pass" and "Fail."
▪ Bad transition names confuse the user about how to move forward.
o Example: "Review." A transition button should signify the start or end of an

action. The word "Review" is ambiguous. If a user clicks "Review," does that
mean they should start a review or that the review has already occurred?
Here’s a list of what not to do so you can avoid creating polluted workflows:
DON’T
• Use more statuses or transitions than are actually needed.
• Use statuses that you'll never query or report on.
• Use a "Closed" status before an issue is actually in its final state. ("Closed" should indicate no
remaining work of any type is needed.)
• Create ultra-specific status names or use the wrong word tense.
o Example: "Pending Review by Marketing" or "Pending Review by John." These are too
specific and make workflows hard to maintain and share between projects.
o Example: "Reviewed." A word in this tense is a "dead end" and doesn't tell the user
what needs to happen next. A word in the past tense is more suited as an action word
for a transition, rather than a current state.
o Create multiple variations that mean "Closed."
o Confuse the "Resolution" field with the final "Closed" status.
▪ Example: Rather than create statuses like "Abandoned" or "Rejected", use the
"Resolution" field to indicate the "how" or "why" an issue is in the "Closed"
status.
o Create "temporary" or "dead" statuses where issues are likely to sit for an indefinite
amount of time.
▪ Example: "On Hold” (A status like this can be useful if a responsible party
proactively and regularly reviews issues in this state.)
RECOMMENDATION
Build your workflow in a test environment first. Then, after you've verified all your changes,
export the workflow and import it into your production environment. This prevents users getting
spammed with test issue and transition notifications.
TIP
To modify the last status of a workflow that's in use, you must first make it inactive (disassociate it
with its current project or issue type.) An easier way is to make a copy of the active workflow, make
your changes to the copy, assign the copy to your project, and then delete the original.
TIP
Any inactive (unassigned) workflows will be listed under the "Inactive" header at the bottom of the
Workflow admin page.
Custom Workflows
It's easy to customize workflows and therefore easy to go overboard, creating more structure than
you really need. A Task issue type might require a very simple workflow, with simple statues like
"Open", "In Progress" and "Closed." A Feature issue type however might require additional statuses
for steps that occur in the real software development process. Statuses for testing, code review, and
deployment, for example, may make the workflow more complex.
Phased Approach
It's certainly possible to capture every little step in your work process and build that into a complex
and long JIRA workflow. An alternative however, is a phased approach. Simply break your process
into phases that represent a collection of smaller steps. The phases represent key decision points.
An issue can’t be moved to another phase until the requirements of that phase have been satisfied.
Each phase represents a status in JIRA, not a small step in the phase.

Example: Your company is hiring a new JIRA Administrator.
The hiring process requires a candidate to apply and interview before they are either hired or
excused. It's a simple process requiring a short workflow like:
Open > Review Application > Interview > Closed.
In the background however, during the main phases, many additional things are happening. For
example:
In the "Review Application" phase:
• The Human Resources department is checking the applicant’s documentation. (Example:

Was all needed paperwork submitted? Does the applicant have the necessary credentials,
certifications, or security clearances? Do their salary requirements fall within the position's
range?)
• Hiring managers are checking applications for experience and desired skill combinations, etc.
In the "Interview" phase:
• HR is setting up appointments with the applicants and sending them directions to the hiring
office.
• A conference room is reserved for interview meetings.
• Hiring managers are prepping their list of interview questions.
• Hiring managers are meeting with applicants and giving facility tours, etc.
In the above example, is it useful to create a status for every step that occurs in the interview
process? Do you need to track whether or not a conference room is booked for the interview? If the
answer to either question is "no" a phased approach may be more useful. If you do need to track
conference room bookings, you may need to add a status or require some field-level indication as
part of the workflow.
TIP
If you're not going to query for "all issues in a certain status", that status may not be necessary or
useful.
RECOMMENDATION
Building a custom workflow should always start on paper. The very last step in the workflow
customization process should be creating and testing it in JIRA.
Custom Workflow Process
Step 1: Write down (in words) the real-world process to complete a request.
RECOMMENDATION
Verify this process description with other end users. It's possible that a little known step was
mistakenly omitted or that it represents an ideal or changed process (which may differ from the
current process.)
Step 2: Using the written narrative, determine the Statuses. Identify the steps or high-level phases
an issue must go through in its lifecycle.
RECOMMENDATION
Help the requestor select existing status names. Only create new statuses if a feasible
alternative doesn't already exist. See the "Naming" section in the "Project Configuration"
chapter.
Step 3: Determine the Transitions. These are the buttons to allow forward movement, backward
movement, or other actions between statuses.
Step 4: Determine the Conditions (restrictions), Validators (rules), and Post Functions needed for
each transition.
Step 5: Determine any special needs. For example, allowing the project administrator to perform a
certain maintenance action.
Worksheet: Custom Workflow Documentation
Use this template to document workflows or collect workflow customization information. This
template may be most useful for the end user audience.
RECOMMENDATION
When building and documenting workflows, use a standard format, so the intricacies are
easier for users to predict and understand.
RECOMMENDATION
A graphical screenshot of a workflow doesn't tell the entire story. Always include a
narrative, explaining the workflow in words. Also include a table showing the transitions
and their embedded rules.

A workflow can be explained in these four ways: (1) the statuses, (2) the forward ("happy")
transition path, (3) the alternate and backward ("alternate") transition path(s), (4) and the
background rules visible to the application administrator. Each of the four areas should also
contain brief descriptions to explain flow diagrams.
View: Statuses
In Words: [insert]
Example: There are three statuses. On creation an issue is in “Open” status. When work
begins, an issue moves forward to “In Progress” status. Work is finally finished in the “Closed”
status.
[insert image]
View: Statuses + Forward Transitions
In Words: [insert]
Example: On creation an issue is in “Open” status. A user clicks the “Start Progress” transition
button to move forward to the “In Progress” status. A user clicks the “Close” transition button
to move to the final “Closed” status.
[insert image]
View: Statuses + Forward & Alternate Transitions
In Words: [insert]
Example: On creation, an issue is in “Open” status. A user clicks the “Start Progress”
transition button, to move to the “In Progress” status, or the “Close” transition button to move
to the “Closed” status. Once in the “In Progress” status, a user clicks the “Close” transition
button to move to the final “Closed” status, the “Stop Progress” transition button to move back
to the “Open” status, or the “Close” transition button to move to the final “Closed” status. In
the “Closed” status, a user clicks the “Reopen” transition button to move back to the “Open”
status.
[insert image]
View: Transition Behaviors

Transition Button
Linked Transition Behaviors (Triggers, Conditions,
>> Destination
Status Screen Validators & Post Functions)◊
Status
Example: Example: Start Example: Example: Fire a Work
Open Progress >> In Assign Started event that can be
Progress processed by the listeners.
...
◊ Workflows automatically have a number of standard transition behaviors. Example: Add a
comment to an issue if one is entered during a transition. Only document workflow rules
you've added or modified.
Download this worksheet at: jirastrategy.com/link/workflow-documentation. Use the code in the
Workflow Templates
Here are some standard and custom workflow templates to use as examples. All the examples are
explained using a standard template. This is an abbreviated version of the "Custom Workflow
Documentation" template above.
Worksheet: Custom Workflow Documentation (Abbreviated)
Use this worksheet as another way to build and document workflows. This template may be
most useful for the application administrator audience. See populated examples of this template
below.
Screenshot Details
[image] Workflow Name: [name]
Short Description: [description]
Fields Required by Workflow: [field list, if applicable]

Narrative: [workflow in words]
View: Transition Behaviors

Linked Transition Button >> Transition Behaviors (Triggers, Conditions,
Status Destination Status Screen Validators & Post Functions)◊
Example: Example: Start Example: Example: Fire a Work Started event
Open Progress >> In Assign that can be processed by the listeners.
Progress
...
◊ Workflows automatically have a number of standard transition behaviors. Example: Add a
comment to an issue if one is entered during a transition. Only document workflow behaviors
you've added or modified.
Sample Workflow: Atlassian's Task Management (Built-in)
This is the simplest workflow possible and it's Atlassian's default when you create a task
management type of project. It's helpful to understand default elements before creating custom
ones.
Use Case: Users have their own personal tasks to complete that are not associated to a large
project or even a team. Why not create a simple, company-wide, "to do" project?

RECOMMENDATION
Create a personal, "to do" list project by modifying the permissions scheme so users only view
and work on issues assigned to them. On the create screen, allow a user to set the assignee to
themselves, bypassing the project's default assignee.
Screenshot Details
Workflow Name: Simple "To Do" List
Short Description: A personal "to do" list for

anyone in the company.
Fields Required by Workflow: None
Narrative: There are two statuses. On create, an issue is in the initial "To Do" status. When work
is complete, the user clicks the "Done" transition button to move to the final "Done" status. If
additional work is needed, the user clicks the "Reopen" transition button to move back to the "To Do"
status.
Transition Button
Linked Transition Behaviors (Triggers, Conditions, Validators
>> Destination
Status Screen & Post Functions)
Status
To Do Done >> Done None
• Only users with Resolve Issues permission
can execute this transition.
• The Resolution of the issue will be set
to Done.
Done Reopen >> To Do None
• Only users with Resolve Issues permission
can execute this transition.
• The Resolution of the issue will be cleared.
NOTE
This default workflow uses a "Resolve Issues" condition. Give all users the ability to resolve issues in
the project's permission scheme or remove this rule from the two workflow transitions.
See this built-in workflow live in JIRA version 6.4 and higher.
Sample Workflow: Approval
While you can create multiple statuses to collect multiple approvals, you don't have to do it that way.
A status per approval creates an unnecessary bottleneck. Instead, use a transition button to collect
each approval. Once all approvals are granted, the issue can transition to the next status.
RECOMMENDATION
Katherine Burstein, Sr. Manager of Compliance and Dallas Texas AUG Leader, has a workflow
approval implementation that your auditors will love. "For our release process, I built a way to
capture various levels of approvals. There is an approval that must be given before the next five
sign-offs occur. The five sign-offs can occur in any order. Once they are completed there's a
final sign-off."
I love Katherine's suggestion so much, I built something similar. Here's a simple example.
NOTE
This workflow requires the "Suite Utilities for JIRA" add-on. Read more about it in the
"Noteworthy Add-ons" section.
Use Case: The Marketing and Legal departments need to approve issues before Development work
starts.
Screenshot Details
Workflow Name: Approval
Short Description: Two approvals must occur, in any order, before

work can begin.
Fields Required by Workflow: Marketing Approver, Legal Approver
Narrative: On create, an issue is in the initial "Open" status. Two approval transition buttons are
visible. When a Marketing Executive clicks the "Marketing Approved" button, their name is recorded,
displayed in the "Marketing Approver" custom field, and that transition button is hidden. When a
Legal Executive clicks the "Legal Approved" button, their name is recorded, displayed in the "Legal
Approver" custom field, and that transition button is hidden. When both approvals have been
recorded, the "Start Progress" transition button is visible and the workflow continues as normal.
(The remainder of the workflow is not documented.)

Implementation Details
1. Create two "User Picker (single user)" custom fields. Name them "Marketing Approver" and
"Legal Approver." These fields store the usernames of the approvers.
2. Create two transition buttons in the same status. Name them "Marketing Approved" and
"Legal Approved." These are the buttons the approvers click to indicate their approval.
▪ Image: Two Approval Transition Buttons
3. For each approval transition, use a "Permission" or user membership-type condition to hide
each transition from non-approvers. (Optional)
▪ Example: Only users in a group called Marketing Execs can execute this transition.
▪ NOTE: Never limit a transition ability to a single user. Always have a small list of
users for cases where the primary user is unavailable.
4. For each approval transition, use an "Update Issue Custom Field" post function to dynamically
set the approver value. The value is the name of the person who clicked the button. (This
function is provided by an add-on.)
▪ Example: The Marketing Approver of the issue will be set to %%CURRENT_USER%%.
5. For each approval transition, use a "Value Field" Condition to hide the transition once the
related field has a value.
▪ Example: The field Marketing Approver will have to be equal to value 'NULL'.
Compared as String.
▪ NOTE: Do not type the value "NULL." Simply leave the value field blank.
6. Create a "Start Progress" transition to move the workflow forward once all approvals are
recorded.
7. For the "Start Progress" transition, add a "Field Required Validator" to hide this transition until
all approvals are recorded.
▪ Example: The field Marketing Approver will have to be equal to value 'NULL'.
Compared as String.
▪ NOTE: Do not type the value "NULL." Simply leave the value field blank.
8. Add the "Marketing Approver" and "Legal Approver" fields to the issues "View" screen.
▪ NOTE: Don't add the fields to the "Create" or "Edit" screen. The values should be
auto-set by transitions and not manually manipulated by users.
▪ Image: Marketing has approved. Legal still needs to approve.
Linked Transition Button >> Behaviors (Triggers, Conditions, Validators & Post
Status Destination Status Functions)
Open Marketing Approved >> • Only users in group Marketing Execs can execute
Open this transition.
• The Marketing Approver of the issue will be set

to %%CURRENT_USER%%.
• The field Marketing Approver will have to be equal

to value 'NULL'. Compared as String.
Legal Approved >> Open • The Legal Approver of the issue will be set
to %%CURRENT_USER%%.
• The field Legal Approver will have to be equal

• Only users in group Legal Execs can execute this

transition.
Start Progress >> In • The field Marketing Approver will have to be equal
Progress to value 'NULL'. Compared as String.
• The field Legal Approver will have to be equal

In (The remainder of the ...
Progress workflow is not
documented.)
Closed ... ...
If an issue moves backward in the workflow or is reopened, you may want to clear the approval field
values and resubmit for approval.
You can use "Date Time Picker" custom fields to display the timestamp of the approval. You can use
a similar "Update Issue Custom Field" post function and the %%CURRENT_DATETIME%%
notation to set the field value. Don’t forget to record the approver's comments during the transition.
This is useful for conditional approvals. Example: "Marketing approves provided the total
Development effort is less than 1,000 hours."

Sample Workflow: Asset Management
This workflow shows a sample process for managing a tangible asset (like a computer), acquired
from a third party.
Use Case: A user requests a new computer, which creates new issue. Once the request is
approved, the machine is ordered. The order goes through the purchase, receipt, and configuration
processes. When the user receives the new computer, the record for the old computer is manually
updated to indicate it is retired.
Screenshot Details
Workflow Name: Asset Management
Short Description: Tracking of company assets from

request through disposal.
Fields Required by Workflow: Order Number, Received

Date, Comment, Deployment Date, Recipient,
Resolution
Narrative: There are seven statuses in this workflow. On creation, an issue is in “Pending
Approval” status. The approver clicks the "Approve" transition button to move to the "Pending
Purchase" status. Once the purchase has been made, the "Purchased" transition button is clicked
and the issue moves to the "Pending Delivery" status. The "Received" button is clicked if all is well
with the shipment. If the package needs to be returned, the "Return" button is clicked. Once the
package has been unwrapped, configured, and delivered to the user, the "Deployed" transition
button is clicked and the issue moves to "In Use" status. When an item has reached its end of life,
the "Retire" button moves the issue to the "Closed" status. If the item ever needs service while in
use, the "Repair" button is clicked. An item in "Closed" status can be brought back to use with the
"In Use" transition button.
NOTE
This workflow requires the following add-ons: "Suite Utilities for JIRA" and "JIRA Misc Workflow
Extensions." Read more about it in the "Noteworthy Add-ons" section.
Behaviors (Triggers,
Linked Transition Button >>
Transition Screen Conditions, Validators &
Status Destination Status
Post Functions)
Pending Approved >> Pending None • Assign the issue to the
Approval◊ Purchase Lead Developer.
Denied >> Closed None • Assign the issue to the
reporter.
Pending Purchased >> Pending Purchase (Includes • n/a
Purchase◊ Delivery fields: Order Number,
Vendor Name,
Purchase Date.
Required: Order
Number)
Pending Received >> Pending Received (Includes • n/a
Delivery Deployment fields: Received Date.
Required: Received
Date)
Return >> In Repair Comment • n/a
Pending Deployed >> In Use Deployed (Includes • n/a
Deployment fields: Deployment
Date, Recipient.
Required: Deployment
Date, Recipient)
Return >> In Repair Comment • n/a
In Use◊ Retire >> Closed Resolution (Includes • Fire an Issue
fields: Resolution, Closed event that can be
Comment. Required: processed by the listeners.
Resolution)
Repair >> In Repair Comment • n/a
In Repair Pending Delivery >> Comment • n/a
Pending Delivery
Pending Deployment >> n/a • n/a
Pending Deployment
In Use >> In Use Comment • n/a
Closed In Use >> In Use Deployed (Includes
• The Resolution of the
fields: Deployment
issue will be cleared.
Date, Recipient.
Required: Deployment • Assign the issue to the
Date, Recipient) Lead Developer.
• Fire a Issue
Reopened event that can
be processed by the
listeners.

◊ Tips:
• In the "Pending Approval" status: See the "Approval" workflow example to collect more than
one approval in the same status.
• In the "Pending Purchase" status: Collect just a few purchase details used to lookup the
purchase record stored in a separate system. Alternatively, use a JIRA project or issue type
for storing all purchase details!
• In the "In Use" status: The record for the old computer should be manually updated to
indicate it was retired.
Atlassian's Sr. Agile Coach, Dan Radigan, put together a comprehensive guide to asset management.
Download the ebook from: jirastrategy.com/link/asset-management
RECOMMENDATION
What do you do if you already have an inventory system with dedicated asset IDs? Line up
existing IDs with new JIRA IDs. Here's how: Export your existing asset data to a spreadsheet
like Excel. For each line item, add a column to represent the issue ID, in the JIRA key format.
Ex: Spreadsheet line item #15 will become ASSET-15 in JIRA. Use the CSV importer to get the
data into JIRA. Import all your existing IDs before manually creating any new records. I don't
usually recommend specifying the key in an import, but this is a special case. For more
information, see the "Bulk Import" chapter.
Sample Workflow: JIRA Support
This workflow is for supporting the JIRA application. See it in the "Sample JIRA Support Project
Set Up" section.
Sample Workflow: Choose Your Own Adventure
"Choose Your Own Adventure" is a series of children's books where the reader is given periodic
options. Their choice directs them to a specific page, where the story continues. The chosen options
along the way dictate which ending you receive.
RECOMMENDATION
Daniel Eads, Support Engineer and Ann Arbor, Michigan AUG Leader shows you can be
amazingly creative with workflows. "I built a short "Choose your own Adventure" game in JIRA.
The workflow allows different paths you can choose. Most steps have a 50/50 chance of failing
or winning. There is a post-function on each transition, which tells you the result of your choice
in a comment. Some statuses have a riddle for you to solve. I use a custom field for text input
and a validator in the transition to prevent advancement until the answer is correct."
Image: "Choose your own Adventure" Example
Also see Atlassian's Workflows Guidebook for more sample custom workflows:
jirastrategy.com/link/workflows-guidebook
Have a great workflow? Share it with the community at: jirastrategy.com/link/conversation.

Workflow Concepts
Now that you've seen a few sample workflows, it's time to talk about items that deserve special
attention.
Standard Issue Buttons vs. Workflow Transition Buttons
The menu buttons are often a source of user confusion. I've experienced the following:
• Because workflow transition buttons differ among projects and issue types, users aren't sure
which one to click.
• Users think the first workflow transition button is the issue's current status.
• The close visual proximity of the standard issues buttons to the workflow transition buttons
can also be confusing.
Here's a graphic you can use to show the two button types.
Image: Standard vs Workflow Issue Transition Buttons
Download this graphic at: jirastrategy.com/link/button-graphic. Use the code in the “Worksheets,
RECOMMENDATION
Don't name a workflow transition button with the same name as a standard issue button.
Otherwise, you'll have two "Assign" buttons or two "Comment" buttons, which will really confuse
your users.
Resolved vs Closed
"Resolved" and "Closed" are confusingly similar statuses, especially for non-development teams.
The JIRA documentation describes them as:
"Resolving an issue indicates that the developers are satisfied the issue is finished."
"Closing an issue indicates that there is no more work to be done on it, and that it has been
verified as complete."
MISTAKE
For quite some time, I didn't understand how "Resolved" and "Closed" were used to build
workflows. When presented with both transition options, users didn't understand which to
select either. This led to issues considered as "done" in either status! There was no way to
report the total work "done" without manually adding counts from the two statuses together.
Issues languished in "Resolved" status until I figured this out and globally fixed it.
RECOMMENDATION
There should only be one status where it's clear that no additional effort is required. The
standard "Closed" status or the business project-friendly "Done" status is sufficient.
Alternate Transitions
The "happy path" (forward) transitions are often self-explanatory. But what if you need to offer
back steps or alternate paths?
RECOMMENDATION
Pick a naming convention that clearly indicates a transition is a backward step or a shortcut.
Example: "Back to Open" or "Skip to Closed"
Image: Sample Backwards Transition
RECOMMENDATION
When creating a temporary transition, name it "temp" so it's easy to spot (or search the
database for) if you forget to remove it.
Illogical Statuses & Transitions

Consider the workflow pictured. The first status is "In Progress." This communicates to the reporter
that the minute their issue is created, someone is working on it. This is often not the case however.
Normally, issues need to be triaged, prioritized, approved, or even reviewed for understanding first.
Instead, the first status in this workflow should be "Open,” "To Do," or something similar. ("Open"
and "To Do" are standard JIRA status names.) The first status should signify to the end user that
the issue has been received, but no action has been taken yet.
Image: Incorrect Expectation Example
"Issue Closed" Post Transitions
MISTAKE
When I created my first custom workflow, I made two incorrect assumptions:
(1) That JIRA treated transitions to the "Closed" status specially. I thought there was logic in
the background making “Closed” the final step in a workflow.
(2) A status change would trigger an "Issue Updated" line item.
This all made perfectly logical sense to me, except both assumptions are totally wrong!
JIRA has no special regard for the status named "Closed"; it is a status just like any other.
When you create a new workflow transition, a default post function is automatically added. It
reads "Fire a Generic Event event that can be processed by the listeners." Instead, update it
to read "Fire an Issue Closed event that can be processed by the listeners." See the
screenshot example in the “Standard and Custom Notifications” section.
Broken Workflows
Sometimes workflows break or develop conflicts due to administrative actions in other areas of JIRA.
The built-in Integrity Checker function can sometimes detect and resolve these issues, but other
times, your users will report a missing transition button, a visual error after clicking a transition
button, or other unintended behavior.
Read more about the Integrity Checker here: jirastrategy.com/link/integrity-checker.
MISTAKE
I had just finished a project which involved custom date fields with workflow validation rules. We
later decided to use custom time stamp fields instead of custom date fields. Since JIRA doesn't
easily let you change types of custom fields, I would need to delete the new fields, re-create them in
the new "Date and Time" format, and update all the workflow behaviors. When I deleted the original
fields, I assumed JIRA deleted the related workflow behaviors, like it removed fields from any
screens using them. I was wrong! I immediately caused conflicts in my active workflows and
received numerous error reports from end users. The only solution was to restore the workflow to
its previous state or quickly delete and replace any of the problem rules. (I did the latter.)
RECOMMENDATION
Before deleting a custom field, search for it in the "descriptor" column in the "workflows"
database table. Remove any workflow behaviors associated with the custom field first.
Workflow XML
Extensible Markup Language (XML) is a way to encode information in a format that is readable by
both humans and machines. All workflow behaviors are stored as XML in the “descriptor” column of
the "jiraworkflows" database table. Knowing just a little bit about the XML creates the ability to find
common behaviors between multiple workflows. See the "Dead Steps" and "Finding Embedded
Workflow Behaviors" examples below.
Here's the XML for Atlassian's built-in, simple, 2 status, "Task Management" workflow.
Image: Task Management Diagram View
Image: Task Management Text View

Sample Workflow XML
1. <?xml version="1.0" encoding="UTF-8"?>

2. <!DOCTYPE workflow PUBLIC "-
//OpenSymphony Group//DTD OSWorkflow 2.8//EN" "http://www.opensymphony.com/osworkflow/workflow_2
_8.dtd">
3. <workflow>
4. <meta name="jira.description">Task Management workflow</meta>
5. <meta name="jira.update.author.key">[author username]</meta>
6. <meta name="jira.updated.date">1474575985218</meta>
7. <initial-actions>
8. <action id="1" name="Create">
9. <meta name="jira.i18n.submit">common.forms.create</meta>
10. <meta name="jira.i18n.title">common.forms.create</meta>
11. <validators>
12. <validator name="" type="class">
13. <arg name="permission">Create Issue</arg>
14. <arg name="class.name">com.atlassian.jira.workflow.validator.PermissionValidator</arg>
15. </validator>
16. </validators>
17. <results>
18. <unconditional-result old-status="null" status="open" step="1">
19. <post-functions>
20. <function type="class">
21. <arg name="class.name">com.atlassian.jira.workflow.function.issue.IssueCreateFunct
ion</arg>
22. </function>
24. <arg name="class.name">com.atlassian.jira.workflow.function.issue.IssueReindexFunc
tion</arg>
25. </function>
27. <arg name="eventTypeId">1</arg>
28. <arg name="class.name">com.atlassian.jira.workflow.function.event.FireIssueEventFu
nction</arg>
29. </function>
30. </post-functions>
31. </unconditional-result>
32. </results>
33. </action>
34. </initial-actions>
35. <steps>
36. <step id="1" name="To Do">
37. <meta name="jira.status.id">10000</meta>
38. <actions>
39. <action id="21" name="Done">
40. <meta name="jira.i18n.submit">jira.issuetracking.simple.workflow.action.done.name</met
a>
41. <meta name="jira.description"></meta>
42. <meta name="jira.i18n.title">jira.issuetracking.simple.workflow.action.done.name</meta
>
43. <meta name="jira.fieldscreen.id"></meta>
44. <restrict-to>
45. <conditions type="AND">
46. <condition type="class">
47. <arg name="permission">RESOLVE_ISSUES</arg>
48. <arg name="class.name">com.atlassian.jira.workflow.condition.PermissionCondition
</arg>
49. </condition>
52. <arg name="class.name">com.atlassian.jira.workflow.condition.PermissionCondition
</arg>
53. </condition>
54. </conditions>
55. </restrict-to>
56. <results>
57. <unconditional-result old-status="Not Done" status="Done" step="3">
60. <arg name="field.name">resolution</arg>
61. <arg name="field.value">10000</arg>
62. <arg name="class.name">com.atlassian.jira.workflow.function.issue.UpdateIssueF
ieldFunction</arg>
63. </function>
65. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowupdateiss
uestatus-function</arg>
66. <arg name="class.name">com.atlassian.jira.workflow.function.issue.UpdateIssueS
tatusFunction</arg>
67. </function>
69. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowcreatecom
ment-function</arg>
70. <arg name="class.name">com.atlassian.jira.workflow.function.misc.CreateComment
Function</arg>
71. </function>
73. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowgeneratec
hangehistory-function</arg>
74. <arg name="class.name">com.atlassian.jira.workflow.function.issue.GenerateChan
geHistoryFunction</arg>
75. </function>
77. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowreindexis
sue-function</arg>
78. <arg name="class.name">com.atlassian.jira.workflow.function.issue.IssueReindex
Function</arg>
79. </function>
82. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowfireevent
-function</arg>
83. <arg name="class.name">com.atlassian.jira.workflow.function.event.FireIssueEve
ntFunction</arg>
84. </function>
87. </results>
88. </action>
89. </actions>
90. </step>
91. <step id="3" name="Done">
93. <actions>
94. <action id="51" name="Reopen">
95. <meta name="jira.i18n.submit">jira.issuetracking.simple.workflow.action.reopen.name</m
eta>
96. <meta name="jira.description"></meta>
97. <meta name="jira.i18n.title">jira.issuetracking.simple.workflow.action.reopen.name</me
ta>
98. <restrict-to>
99. <conditions type="AND">
102. <arg name="class.name">com.atlassian.jira.workflow.condition.PermissionCo
ndition</arg>
103. </condition>

106. <arg name="class.name">com.atlassian.jira.workflow.condition.PermissionCo
ndition</arg>
107. </condition>
108. </conditions>
109. </restrict-to>
110. <results>
111. <unconditional-result old-status="Not Done" status="Done" step="1">
114. <arg name="field.name">resolution</arg>
115. <arg name="field.value"></arg>
116. <arg name="class.name">com.atlassian.jira.workflow.function.issue.Updat
eIssueFieldFunction</arg>
117. </function>
119. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowup
dateissuestatus-function</arg>
120. <arg name="class.name">com.atlassian.jira.workflow.function.issue.Updat
eIssueStatusFunction</arg>
121. </function>
123. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowcr
eatecomment-function</arg>
124. <arg name="class.name">com.atlassian.jira.workflow.function.misc.Create
CommentFunction</arg>
125. </function>
127. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowge
neratechangehistory-function</arg>
128. <arg name="class.name">com.atlassian.jira.workflow.function.issue.Gener
ateChangeHistoryFunction</arg>
129. </function>
131. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowre
indexissue-function</arg>
132. <arg name="class.name">com.atlassian.jira.workflow.function.issue.Issue
ReindexFunction</arg>
133. </function>
136. <arg name="full.module.key">com.atlassian.jira.plugin.system.workflowfi
reevent-function</arg>
137. <arg name="class.name">com.atlassian.jira.workflow.function.event.FireI
ssueEventFunction</arg>
138. </function>
141. </results>
142. </action>
143. </actions>
144. </step>
145. </steps>
146. </workflow>
Sample Workflow XML Notes
• Within the <initial-actions></initial-actions> section are behaviors for everything that

happens before the first status, in the create step.
o The Create action has a permission validator as seen on lines 11-16.
• Within the <steps></steps> section are all the workflow statuses. Each step includes the step
ID, status name, and status ID.
o The <actions></actions> section contains all the transition buttons for the status.
▪ All conditions, validators, and post functions are defined here.
• This built-in workflow doesn't have a transition screen, but if it did, the XML would look like:
<meta name="jira.fieldscreen.id">10124</meta> where "10124" is the unique ID of the
screen.
Dead Steps
Workflow statuses that contain no incoming or outgoing transitions should be cleaned up. I call
these "dead steps" for lack of a better term. In JIRA 6.4 and later, there's a workflow validator
feature which highlights “dead steps” in the "diagram" mode. This method is helpful for a single
workflow.
RECOMMENDATION
For multiple workflows, search the XML to detect statuses with no incoming or outgoing
transitions.
You can export the rows in the “jiraworkflows” table to a text file. The XML powering the workflow is
stored in the "descriptor" column. Open the file in a text editor, like Notepad++. (notepad-plus-
plus.org)
Search for the string:

1. </meta>
2. </step>
If found, you'll have a list of workflows to further investigate.
A status with a transition has multiple "actions." In the XML example below, the "In Progress" status
has a transition button called "Done" with the description "Work has been completed."
1. <step id=""2"" name=""In Progress"">
2. <meta name=""jira.status.id"">10101</meta>
3. <actions>
4. <action id=""15"" name=""Done"" view=""fieldscreen"">
5. <meta name=""jira.description"">Work has been completed.</meta>
6. <meta name=""jira.fieldscreen.id"">12221</meta>
7. <results>...

A status without a transition has no defined "actions."
1. <step id="3" name="Reopened">
3. </step>
Notes:
• False positives are possible. For example, transitions in a "Closed" status may be omitted by
design.
• Don't edit the workflow XML. It is much easier to make workflow changes in JIRA instead.
Find Embedded Workflow Behaviors
JIRA SERVER ONLY
This information is for users of the Server application type only.
There are multiple ways you can grant permissions in JIRA. The most common ways are using
project-wide "Permission Schemes" (managed by the application-level administrators) and project-
wide "Roles" (managed by the project lead or project-level administrators.) Individuals can be given
permissions as well as groups.
But what happens when a user reports not having a workflow-related permission? Each workflow
transition button can have its own rules for who can see the button, when the button is clicked, and
what happens when the button is clicked. These rules are embedded in the workflow which can be
hard to find; workflows can have an unlimited amount of transition buttons.
When it's not feasible to manually check the rules for each individual transition, search the database
to find the conditions. All workflow behaviors are stored as XML, in the JIRA "jiraworkflows" table, in
a column called "descriptor." If you explore the XML, you'll notice a pattern.
For example:
1. When a transition is restricted to a group, the code <arg name="group">[group-name]</arg> or

<arg name="hidGroupsList">[group-name]</arg> is present.
2. When a transition is restricted to a role, the code <arg name=\"hidRolesList\">[role-

name]</arg> is present.
As such, you can use a query to get a list of workflows with transitions restricted to groups or roles.
NOTE
Since database types differ and database structures change between versions, it's not possible to
provide queries guaranteed to work in your environment. Instead, work with your database team to
craft the queries you need, for your specific database set up, and for your query efficiency needs.
Sample Query:
SELECT id, workflowname FROM jiraworkflows WHERE descriptor LIKE "%<arg name=\"group\">%" OR
descriptor LIKE "%<arg name=\"hidRolesList\">%" OR descriptor LIKE "%<arg name=\"hidGroupsLis
t\">%"
Further refine your query as needed, so you can manually explore within a small subset of workflows
until you find the info you need.
One company had over 100 workflows and thousands of workflow transitions. None of the
workflows were documented and many were created years ago. The only quick way to find
which workflows had transition restrictions was through a database query.
MISTAKE
I once used the workflow "diagram" (visual) mode to change a status. I thought the change
would only apply to that one workflow. Instead, I changed the name of the entire status in all
of JIRA! Users alerted me to the problem when their workflows stopped working properly and
their filters broke.
Workflow Behaviors
JIRA comes with a number of built-in workflow Conditions, Validators, and Post Functions. In this
section, we’ll cover the most useful for practical strategies.
Standard Conditions
A Condition checks whether a transition should be performed by a user. If a Condition is true, a user
sees the transition button. If a Condition is false, the transition button is hidden. As such, a user
may encounter an issue with no transition buttons available to them.
RECOMMENDATION
Include all conditions in your workflow documentation so users know why they don't see certain
transition buttons and who can see them.

The most useful are:
Name JIRA Description Use Case Examples
Hide Condition to hide a transition from • Auto transition a parent issue to "Closed"
transition the user. The transition can only status, when all child issues are in
from user be triggered from a workflow "Closed" status.
function.
o See this in use in the "Example
Workflow Behaviors" section.
• Allow a script or the REST API to perform

an action, while hiding the ability from a
user.
Only Condition to allow only the assignee • Simple check and balance, especially if
Assignee to execute a transition the Assignee cannot be modified or is
Condition restricted to a set of users.
Only Condition to allow only the reporter • Simple check and balance, especially if
Reporter to execute a transition the Reporter cannot be modified or the
Condition Create ability is restricted to a set of
users.
Permission Condition to allow only users with a • Restrict an administrative function (like
Condition certain permission to execute a closing an old issue regardless of status)
transition to the Administrators role.
• Restrict a transition to users who have
another specific permission (Example:
"Manage Sprints", "Schedule Issues",
etc.)
Previous Condition to check if the issue has • Useful for auditing. (Make sure an issue
Status transitioned through a specified went through an "Approval" status.)
Condition status or not
Separation Condition preventing a user to
• Make sure the user who did the work isn't
of Duties perform the transition, if the user
the same user verifying the work.
condition has already performed a transition
on the issue • Prevent the same user from providing
multiple levels of approval.
Sub-Task Condition to block parent issue • Prevent a parent issue from transitioning
Blocking transition depending on sub-task to "Closed" status until all child issues are
Condition status in "Closed" status.
User Is In Condition to allow only users in a • Only users in the "internal-users" group
Group given group to execute a transition can perform an action. Restrict external
users. (Example: contractors.)
User Is In Condition to allow only users in a • Only users in the "Developers" role can
Project Role given project role to execute a indicate development is complete.
transition
Additional Conditions
These Conditions are from the "Suite Utilities for JIRA" add-on. Read more about it in the
User Is In Condition to allow only users in a • Similar to the standard "User Is In Group"
Any Group given group to execute a above, except membership can include
transition multiple groups.
User Is In Condition to allow only users in a • Similar to the standard "User Is In Role"
Any given project role to execute a above, except permissions can include
Project transition multiple roles.
Role
User Is In Allows only users in a given • Only the user listed in the "Tester" custom
Custom custom field to execute the field can complete the verification step.
field transition
Value Field Allows to execute a transition if • Only show the "Approve" transition if the
the given value of a field is equal "Approval" field is null.
to a constant value, or simply
set.
• Restrict who can start work on issues where
the value in the "Risk" custom field is greater
than or equal to 3.
Standard Validators
A Validator checks whether certain data exists before the transition occurs. If a Validator is true, the
transition succeeds. If a Validator is false, the issue does not transition until the data updates or
returns true.

Permission Validates that the user has a • Restrict an administrative function (like
Validator permission closing an old issue regardless of status) to
the Administrators role.
• Restrict a transition to users who have
another specific permission (Example:
"Manage Sprints", "Schedule Issues", etc.)
Previous Validates that the issue has • Useful for auditing. (Make sure an issue went
State previously transitioned through a through an "Approval" status.)
Validator specific state o A similar function, called "Previous
Status Validator" is also provided by
the "JIRA Misc Workflow Extensions"
add-on.

Additional Validators
These Validators are from the "JIRA Misc Workflow Extensions" add-on. Read more about it in the
Field has single Multi-select Field has not • An issue can only be part of one fix version.
value Validator more than one value during
• Only one Component can be selected.
transition
Comment A validator that forces users
• A comment must be entered for transitions
Required to enter a comment during a
like: "Reopen", "Fail", etc.
Validator transition
o A similar function also provided by
the "Suite Utilities for JIRA" add-on.
Parent Status Validates that the parent • Prevent new Sub-task creation after a parent
Validator issue is in required state issue is resolved.
These Validators are from the "Suite Utilities for JIRA" add-on. Read more about it in the
Field Required Field must not be empty • An issue can't be resolved if the "Fix
Validator during the transition Version" field is empty.
• An issue can't be closed if no work has been
logged.
• A comment must be entered for transitions
like: "Reopen", "Fail", etc.
o A similar function specifically for

comments is also provided by the
"JIRA Misc Workflow Extensions" add-
on.
Date Compare Compare two dates during a • The resolution date must be less than or
Validator workflow transition equal to the due date.
Regular Validate field contents • Verify that the "Business Value" custom field
Expression against a regular expression has a value greater than $5,000 USD.
Check during a workflow transition
Conditions vs Validators
It’s important to note the different behaviors between conditions and validators. Transition buttons
will be hidden for failed Conditions. For failed Validators, the transition buttons show, however. This
is because the validity check happens just after the transition button is clicked.
Standard Post Functions
A Post Function is an additional rule or action that occurs after the transition. The functions only
execute if the transition is successful.

Assign to Assigns the issue to the • When transitioning to an "In Progress" type
Current User current user if the current status. (The user starting progress is likely
user has the 'Assignable the user doing or responsible for the work.)
User' permission
Assign to Lead Assigns the issue to the • When an issue is reopened or fails
Developer project/component lead validation. (This lets the team lead know to
developer investigate or re-assign.)
Assign to Assigns the issue to the • When an issue is closed, ready for
Reporter reporter validation, or more information is requested.
Update Issue Updates a simple issue field • Change the "Assignee" to a predefined
Field to a given value. username.
• Change the "Resolution" to a predefined
value.
Additional Post Functions
The following are provided by the "Suite Utilities for JIRA" add-on. Read more about it in the
Update Issue Updates an issue custom field • Similar to the default "Update Issue Field"
Custom Field to a given value but for custom fields.
Clear Field Clear value of a given field • When an issue is reopened, clear the value
Value of the "Resolution" field.
Default Post Functions
The following Post Functions are automatically added to each transition you create:
• Set issue status to the linked status of the destination workflow step.
• Add a comment to an issue if one is entered during a transition.
• Update change history for an issue and store the issue in the database.
• Re-index an issue to keep indexes in sync with the database.
• Fire a generic event that can be processed by the listeners.
In most cases you won't need to modify these default actions or their order. The order of post
functions is important. See this knowledgebase article, jirastrategy.com/link/post-function-create,
about the order on the "Create" step, for example.

For the last line item, you may want to change "Generic Event" to a value more appropriate for the
transition. For example, a "Work Started on Issue" event when progress begins, or an "Issue
Resolved" event when an issue transitions to the "Resolved" status. Use these events to send email
notifications.
TIP
Many add-ons provide additional workflow functions. As noted in the "Plugins and Add-ons" section,
some workflow functions come pre-installed in Cloud environments. You may need to enable
them from your "Manage add-ons" admin page.
Read more about Conditions, Validators, and Post Functions at: jirastrategy.com/link/advanced-
workflow-config.
Example Workflow Behaviors
Auto Transition Parent Issue
Use Case: When all child issues are closed, automatically transition the parent so users won't have
to do it manually.
NOTE
This requires the JIRA Misc Workflow Extensions add-on. (jirastrategy.com/link/jira-misc-workflow-

extensions) Read more about it in the "Noteworthy Add-ons" section.
Implementation:
1. In the parent issue's workflow, add a Post Function, which will only be used by this automatic
process.
▪ Add the "Hide Transition" Condition to hide the button from regular users.
o NOTE: This transition cannot have any Screens or required field Validators.
▪ Add a "Sub-Task Blocking Condition." This prevents the parent from transitioning until
all children are closed.
o Example: All sub-tasks must have one of the following statuses to allow parent
issue transitions: Closed
2. In the child issue's workflow, add a "Transition Parent Issue" post function to all "Close"
transitions.
o Example: Transition X will be triggered on the issue's parent issue. (X is the

ID of the transition in the parent workflow or the transition's name if it's
unique.)
o Move the post function to the last position in the list. (This rule must run last.)
Use Case: When a work starts on a child issue, automatically start work on the parent issue, so
users don't have to manually do it.
NOTE

Implementation:
1. In the child workflow, add a post function to the "Start Progress" transition.
▪ Example: Transition "Start Progress" will be triggered on the issue's parent issue.
Prevent Child Issues
Use Case: Once a parent issue is closed, new child issues shouldn't be created.
NOTE

Implementation:
1. In In the child issue's workflow, click on the first status (Example: "Open") and select the
"Create" action.
▪ Add the validator called "Parent Status Validator" to check the parent issue's status.
o Example: The parent issue of current issue must be in one of the following
statuses: Open, In Progress
o Include every possible parent status, except "Resolved" and/or "Closed."
If a user attempts to create a child issue after all work is complete or after the parent issue is closed,
they receive the following error: Error creating issue: Transition is not authorized because current
Issue's parent Issue should be in one of the following statuses: [Open, In Progress]

Image: Sub-task Creation Error
Prevent Child Issue Progress
Use Case: Progress can't begin on a child issue until the parent issue is in the "In Progress" status.
NOTE

Implementation:
1. In the child issue's workflow, add the validator called "Parent Status Validator" to the "Start
Progress" transition.
▪ Example: The parent issue of current issue must be in one of the following statuses:
In Progress
If a user attempts to start progress on a child issue before the parent issue, they receive the
following error: Transition is not authorized because current Issue's parent Issue should be in one of
the following statuses: [In Progress]
Prevent Parent Closure Until Child Issues are Closed
Use Case: If no child issues exist, allow a parent issue to be closed. This is useful to close
duplicates or when work can't be done. If one of more child issues exist, the child must be closed,
moved, or deleted before the parent can be closed.
Implementation:
• In the parent issue's workflow, for any "Close" transition, add a Sub-task blocking Condition.
o Example: All sub-tasks must have one of the following statuses to allow parent issue
transitions: Closed
The "Close" transition will be shown or hidden based on the above condition.
Transition Ordering
There are some additional properties that can enhance your workflows. An especially useful one
is "opsbar-sequence."
RECOMMENDATION
Use the "opsbar-sequence" property to order transition buttons.
• Always order the buttons in the order they’re most likely to be used. The most likely, "happy
path" transition button should be displayed first.
• Use ordering values like 10, 20, 30 (instead of 1, 2, 3). If a new transition is needed, you
can insert it without having to reorder the existing transitions.
Documentation: jirastrategy.com/link/workflow-properties

Workflow Schemes
Quick Explanation
Workflow Schemes – the mapping of workflows to Issue Types
Attributes:
• Name
• Description
• Associated Workflow(s)
Example:
• A project for a business team who utilizes Task and Sub-task Issue Types would have a
“Task" Workflow Scheme.
o Both Issue Types share the same life cycle steps. Multiple business projects share
this standard Workflow Scheme.
Documentation: jirastrategy.com/link/jira-workflow
Workflow Schemes to Workflows Relationship
Here are some sample workflows and issue types you might find for a software development project.
Workflow Issue Types Notes
Bug This workflow may include defect-specific
• Bug
steps. Example: Verification
Feature This workflow may include new feature-
• Improvement
specific steps. Example: Prioritization
• New Feature
• Story
Task This workflow is likely to be very simple

• Task
and include no special steps.
• Sub-task
• All Unassigned Issue Types

(representing "everything else")
Using the example in the table above, create one Workflow for each of the three types of work. For
each Workflow, associate the appropriate Issue Types. Then, each Issue Type will have
a consistent lifecycle across multiple similar projects.
Image: Sample Software Development Workflow Scheme
For additional workflow materials, visit the JIRA Strategy Store at: jirastrategy.com/store.

Screens
Quick Explanation
Screens – define which fields are present, and their display order
Example: Summary (Title), Description, Assignee, Reporter, etc.
Attributes:
• Name
• Description
• Associated Fields
• Tabs (optional)
Screen Types:
• Create
• Edit
• View
• Transition
NOTE
A field can be present on a screen, but can be invisible to the end user if hidden in a project's
Field Configuration scheme.
Documentation: jirastrategy.com/link/jira-screen
Best Practices
DO
• Use a single screen for all issue actions. If there are too many fields, or data has to be
entered in stages, then use multiple screens.
• On the Create screen, include only the fields the user must populate. Too many fields or
extra "optional" fields can overwhelm the user.
• On the Edit and View screens, include all fields, so issues are easy to update.
o Create tabs to better organize fields.
o Alternatively, you can update certain fields as part of a workflow transition.
• List fields in a logical order, preferably in the order a user would be likely to supply the
information.
• Have a consistent field order for screens and projects. Users expect and appreciate a
standard.
DON’T
• Collect data you won't query or use.
• Add multiple date format or component-type fields on one screen. This may impact
screen load time, as the UI for these types is more complex.
• Ignore standard UI web form practices. See the "Standard Web Form Conventions"
section.
• Have a custom Screen Scheme per project.
• Add fields to shared screens that don't apply to all projects.
At one company, the "Epic Link" field was added to the global Create screens. Since that
field didn't apply to the majority of projects, users who were not familiar with this field were
confused.
When a field has a narrow usage, create a custom screen and apply it to the appropriate project(s).
Can't see a field?
• Check that the field is on the screen.
• Check the field's settings for Issue Type and/or project scope restrictions.
• The field may be hidden in the project's Field Configuration scheme.
• Check the "Configure Fields" button on the top right of a Create or Edit screen. The field may
be hidden in your personal view.
• If you use the ScriptRunner for JIRA add-on, a field may be hidden by a "behavior."
• Use the “Where is my field?” admin helper function. Read more:

jirastrategy.com/link/admin-helper
NOTE
You cannot change the following View screen elements:
• The location of any lists of users (Example: assignee, reporter, and participants-type
fields) and date-type fields which display on the right of the issue page.
• The display order of fields like: "Summary," "Description," "Linked Issues," and
"Attachments."

These elements are part of a hard coded template that you can't change without modifying core
application files (not recommended).
Screen Schemes
Quick Explanation
Screen Schemes – an association of screens with different issue operations
For example, one screen for "Create", a second for "Edit", and a third for "View."
Documentation: jirastrategy.com/link/screen-scheme
Issue Type Screen Schemes

Quick Explanation
Issue Type Screen Schemes – an association of screens with different issue types
For example, you can use one screen scheme for handling "Bug" issue types and a different
screen scheme for handling "Task" issue types. Coupled with screen schemes, this creates highly
configurable screen possibilities.
Documentation: jirastrategy.com/link/issue-type-screen-scheme
Screens, Screen Schemes, and Issue Type Screen Schemes work together to create a functional
relationship. Issue Types and Workflows have a parent-child relationship which is easy to
understand. Screens have an additional "grandparent" level however - the Issue Type Screen
Scheme. Atlassian explains this relationship well with the diagram at:
jirastrategy.com/link/screens-schemes-fields.
Simple Example
In this example, there's one Issue Type Screen Scheme, Screen Scheme, and Screen for all issue
types and operations. All the screens in this project display the same fields regardless of issue type
or action.
Grandparent Parent Child
Issue Type Issue Type Issue Screen Fields Screens
Screen Operation Scheme
Scheme
• Epic Development • Create Development • Summary Development
Issue Type Screen Scheme Screen
• Task Screen Scheme • Edit • Assignee
• Bug • View • Description
• Story • Fix Version
• etc.
Complex Example
In this example, the Epic and Task issue types share the same list of fields for all issue operations.
The Bug and Story issues types, however behave differently. On create, a Bug or a Story shows the
"Development Screen - Create" screen which displays four fields. However, on edit or view, a Bug or
Story shows the "Development Screen - Edit/View" screen which contains an additional field called
"Fix Version."
Issue Type Issue Type Issue Screen Scheme Fields Screens
Screen Operation
Scheme
• Epic Task Issue • Create Task Screen • Summary Task Screen
Type Screen Scheme
• Task Scheme • Edit • Assignee
• View • Description
• Bug Development • Create Development • Summary Development
Issue Type Screen Scheme Screen -
• Story Screen • Assignee Create
Scheme
• Description
• Due Date
• Edit Development • Summary Development
Screen Scheme Screen -
• View • Assignee Edit/View
• Description
• Due Date
• Fix Version
Best Practices
DO
• Have one Issue Type Screen Scheme per Issue Type.
DON’T
• Don’t have one Issue Type Screen Scheme per project.

Standard Web Form Conventions
When creating screens, be aware of the web and application standard conventions your users expect.
Here are some tips for effective and useful web forms.
1. Don’t ask too many questions.

Only ask for information that you’ll use. For example, if you plan to respond to issues via
email, only ask for an email address (not an email address, a phone number, and a mailing
address.) If you already have the reporter's email address on file, don't ask them to type it.
Short web forms are more likely to be completed. Users dislike providing many ways for you
to contact (aka spam, annoy) them.
2. Ask specific questions.

Use field descriptions to ask the user for specific information or to provide formatting
instructions. Asking a specific question gives you better information to work with than a
blank or “Enter your message here” description. Examples: “What software do you need
installed?” or "What is the expected result of the defect you're reporting?”
3. If a field has a validation requirement, tell the user what the requirement is.
Give clear and easy to understand directions. Don't wait for a user to enter data incorrectly
before providing them with formatting instructions. For example, tell the user to enter their
phone number in the format: ###-###-#### rather than give them the error “Please enter
a valid phone number.”
4. Confirm successful submissions.

After a user clicks the submit button, there should be a confirmation that the message was
received (or an error message if there were any problems.) JIRA handles this functionality by
default.
5. Post and adhere to your privacy policy.

Any time you collect user information, you should have an easily accessible privacy
statement that addresses what you collect, how you use it, and under what circumstances, if
any, you disclose it. If completing a form means you’ll add their email address to your
newsletter system, for example, that needs to be clear. This is important for public instances
and when you use JIRA for customer support.
6. Consider your audience.

As with everything web related, create forms with the end user and their specific goals in
mind. You may need separate forms for existing customers, new prospects, or different
situations. Don’t try to serve all users and all conditions from the same form.
Finally, and most importantly, make it easy, intuitive, and painless to complete forms. The process
should be simple for end users.
Custom Fields
Quick Explanation
Custom Fields – additional fields, in addition to the standard, built-in fields
Attributes:
• Name
• Description
• Type (Example: Number, text, date, etc.)
• Settings/Options (Example: Selection values, validation rules)
Documentation: jirastrategy.com/link/custom-field
Best Practices
DO
• Limit the number of custom fields. Only create the necessary fields that will be queried and
used by multiple projects. Too many custom fields can affect performance.
• Use a Field Configuration or the Context feature if you need different field descriptions or
values. Don't duplicate custom fields.
DON’T
• Create more than one field with the same name. Even if the field is of a different type, the
names will be confusing for application administrators when creating screens and for end
users during queries.
Image: Query with Duplicate Fields

How does the end user know which to select?

• Create fields with different tenses or in singular and plural format.
Image: Similar Fields with Different Tenses
• Create similar fields.
One company had three custom fields that all meant the same thing which caused
confusion. (Example: “Business Owner,” “Previous Owner,” and “Project Contact.”) One
custom field, or the use of the standard "Reporter" field, should have been used to signify
who owns an issue.
• Use special characters.
Another company had a 25 character field labeled "Project Owners / Contacts." The slash
and space before and after the slash result in an ugly query.
Image: Query for Field with Special Characters
Important: A large number of Custom Fields creates a slow JIRA application. If the custom field
admin page is slow to load, that's one indication there too many! Read more about sizing
recommendations at: jirastrategy.com/link/sizing-guide and watch this enlightening video about
performance at scale at: jirastrategy.com/link/performance-scale.
Before You Create Custom Fields
RECOMMENDATION
Define what data points you need to report on before creating custom fields. What information
needs to be queried to return a list of issues vs. what information just needs to be visible in a
single issue? Example: You collect a serial number for a piece of equipment. What will you do
with that information? Will you produce a report of all serial numbers in all issues? If so, this is
easiest with a custom field. No report needed? That piece of information can be included in a
standard field instead. Read Atlassian's excellent article on "Field Greatness" here:
jirastrategy.com/link/field-greatness.
Required Fields
There are two ways to require field completion. (1) Make a field required in the project's "Field
Configuration" scheme. This method shows a red asterisk symbol on the Create and Edit screens,
visually showing the requirement. If a field is left blank, a red in-page error displays after form
submission. (2) Make a field required using a “Workflow transition” validation rule. This method
shows a red error on the transition overlay screen. No red asterisk displays next to the field.
The best method depends on the situation. To require a field on the Create screen, use the "Field
Configuration" method. To require a field three steps into your workflow, for example, use the
“Workflow transition” method.
If a required field is not available on a screen, your user sees an error and they can't proceed.
RECOMMENDATION
It may be useful to publish a list of available custom fields and their uses. It may encourage end
users to request existing values, rather than proposing new or similar ones. You can: send
users to the "Show Constants Help" page (at: yourjiraurl.com/secure/ShowConstantsHelp.jspa),
copy and paste a static list from JIRA, query the database, or use the REST API to generate a
quick list of available selections.

Field Configurations
Quick Explanation
Field Configurations – provide the ability to change field behavior
Attributes:
• Name
• Description
• All Available Field Settings

Documentation: jirastrategy.com/link/field-config
DO
Show standard fields the user expects to see in all projects. See the "Standard
Capabilities" section for examples.
DON’T
Don’t require fields not present on screens. The users will see errors and won’t be able to
create or transition issues.
At one company, fields were configured poorly with hidden attachments and description
fields. Without the proper fields to collect their information, the users had trouble entering
issues.
Standard and Important Fields
The following fields should always be available, even if not all users will enter data.
Field Notes
Reporter Show and make required. A reporter, or single point of contact, should always
be provided.
NOTE: In newer versions of JIRA, an issue's "Creator" will also be logged. (The
original "Creator" can differ from the current "Reporter." This is common when
reporters change teams, change focus, or leave the company.)
Description Show and make required. A detailed description of the issue should always be
provided at the time of creation.
Components Show. All projects should be able to use this helpful routing and classification
feature.
Priority Show. This helps set the expectation of issue severity, so teams can prioritize
their work (or reset expectations.)
Due Date Show. While projects may use this date differently, having a target date is useful
information. (Example uses: code complete date vs. requested date, etc.)
Attachment Show. All projects should be able to store supporting and additional
documentation.
Linked Issues Show. All projects should be able to link to other related issues.
Time Tracking Show. All projects should have the ability to estimate effort.
Log Work Show. All projects should have the ability to show progress and report actual
effort.

Field Configuration Schemes
Quick Explanation
Field Configuration Schemes – used to map Field Configurations to Issue Types
Attributes:
• Name
• Description
• Associated Field Configuration(s)
Documentation: jirastrategy.com/link/field-config-scheme
Field Configurations to Field Configuration Schemes Relationship

In this example, four fields have specific settings. The "Condition" field shows for the “Task” issue
type but is hidden for "Sub-task." The two field configurations allow you to have one screen that
behaves slightly differently between issue types.
Issue Type Field Field Custom Fields Field Settings
Configuration Configuration
Scheme
• Task Asset Field Task Field • Description Wiki Renderer
Configuration Configuration See the "Renderers"
Scheme section for more info on
this setting.
• Price Required
• Quantity Optional
• Condition Shown
• Sub-task Asset Field Sub-task Field • Condition Hidden
Configuration Configuration
Scheme
Alternately, you could utilize the opposite set up: two screens (one without the "Condition" field)
and one field configuration.
Another set up to consider is to put all fields on one screen and use a field configuration to hide any
that shouldn't display for a certain issue type.
Worksheet: New Custom Field Requests
Determine what field requirements to collect from end users based on their knowledge level. If
the questions below are too technical, collect basic information (field name and use, for
example) and the Advisory Board can determine the proper additional parameters.
Questions
1. What is the desired field name? (The text shown to the left of the field.)
2. What will the field be used for?
3. What field description should be shown to the user?
4. What is the field type? What type of data will be collected? Example field types: text,
number, date, checkbox, select list, URL, etc.
5. What field properties are needed?
▪ For a text field, do you need to collect a single or multiple lines of text? For a
checkbox or select list, what are the options? Example: choice 1, choice 2, etc.
6. What screens should the field be shown on? (Create, edit, view, or all?)
7. If applicable, what are the validation rules?
Download this worksheet at: jirastrategy.com/link/custom-field-requests. Use the code in the

TIP
Turn this worksheet into a “Create” screen in your JIRA Support project.
Considerations
• Is the field name (and selection values) generic enough for multiple projects?
• Is the field type logical for the data type? Example: Don't use a text field type to collect a
web address. Instead, use the URL field type.
• Is the field similar to or a duplicate of an existing field?
• Does the field duplicate standard JIRA functionality?

Proper Field Types
When creating a new field, be sure to select the best type for the use. Once a field type is chosen, it
cannot be changed. To "change" a field type, you'll need to create a new custom field, migrate any
stored data from the original field to the new field, remove the original field, then update screens to
show the new field.
Text Field (single line) vs Text Field (multi-line)
Choosing between the two is a matter of determining the desired character length. Is the text limit
255 characters or less? If so, the "Text Field (single line)" type is the best choice. For long,
paragraph-type responses, the "Text Field (multi-line)" type is the best choice.
Checkboxes vs Radio Buttons
These two field types are misused. The user-interface (UI) rules are the same in JIRA as they are for
any website or online application.
Checkboxes - If the user can choose multiple selections, the checkbox field type is appropriate.
The user can choose neither, one, or several options for one question.
Radio Buttons - If the user must choose only one of multiple, mutually exclusive options, the
radio buttons type is appropriate. The user can only choose one, so use distinct selection labels.
Image: Checkboxes and Radio Buttons
RECOMMENDATION
For all selection-type fields, offer an "other" selection, to cover all potential non-listed responses.
One company used text fields to collect date values. This meant dates were entered in
multiple formats. (Example: Jan 1, Jan 01, January 1st, 1/1, etc.) Without the standard
format built into the date field type, this information was impossible to query for or sort by,
making it less useful.
Special Features
Message Custom Field
There's an add-on (for both JIRA Cloud and JIRA Server) called the "JIRA Toolkit Plugin" that
provides two very helpful field types called "Message Custom Field (for view)" and "Message Custom
Field (for edit)." These fields allow you to display text or HTML on your issue or workflow transition
screens. They particularity help to provide additional instruction, display a warning, or link to
additional information.
To place a message on a view screen, use the "Message Custom Field (for view)" field type. To place
a message on a create, edit, or transition screen, use the "Message Custom Field (for edit)" field
type.
Image: Sample User Instruction Message (Transition Screen)

Image: "Message Custom Field" Types in the "Select a Field Type" Admin Overlay
Read more about it in the "Noteworthy Add-ons" section.
NOTE
This plugin may already be installed in your JIRA Cloud instance. You may need to enable it.
Custom Field Contexts
Use JIRA's "Contexts" feature to change how a custom field is used for projects and issue types.
Remember, no need to create duplicate fields!
For example, let’s say you create a custom single selection field with the following attributes:
Field Name: Swamp Animals

Field Description: Select your favorite of these animals commonly found in a swamp. (This
description is shown to the user.)
Field Options: Alligators, Crayfish, Shrimp, Snakes, Tadpoles
If a different project needs a similar field, create a new context for that field. Change the attributes
slightly to fit your needs. For example:
Context Name: Swamp Reptiles

Context Description: Limit selections to only reptiles commonly found in a swamp. (This
description is only visible in the Admin area.)
Context Options: Alligators, Snakes, Turtles
Project: Demonstration Project
When you use the "Swamp Animals" field in the "Demonstration Project," its field label reads
"Swamp Reptiles" and has its own description and selection values. When you use the "Swamp
Animals" field in any other project, it uses the attributes specified for the original custom field.
Image: One Custom Field with Two Contexts on the "Configure Custom Field" Admin Page
NOTES
• A custom field can only have one context per project. (You can't use multiple contexts in the
same project, even if there are multiple Issue Types.)
• Only want to change a field's description? Do that in the project's Field Configuration
Scheme.
Documentation: jirastrategy.com/link/context
Renderers
Use the "Renderers" feature to affect how text field content displays to the user. There are two
display options. The "Default Text Renderer" displays plain text and the "Wiki Style Renderer"
displays formatted text. Renderers are configured per field, allowing a flexible combination of plain
text and rich text fields.

RECOMMENDATION
For the "Description" and "Comment" fields, use the "Wiki Style Renderer." This allows users to
apply text formatting (colors, bold, italics, strike-through, etc.), add elements (bulleted and
numbered lists, images, tables, etc.), and "tag" a user (@username). The usefulness of text
formatting likely outweighs any application performance concerns.
Image: Sample Wiki Markup vs Text Markup

Which message is most likely to be noticed?
Documentation: jirastrategy.com/link/renderers
Versions
Quick Explanation
Version (also referred to as "Fix Version") – a grouping of issues by date or period of time
Versions are traditionally used to signify issues in a specific software release.
Attributes:
• Name
• Description
• Start Date
• Release Date
Example:
• 1.1.1
Notes:
• The ability to set a Version is coupled with the Resolve permission in a project's Permission
Scheme.
• A project administrator can create versions.
• An issue can be associated with multiple Versions.
Documentation: jirastrategy.com/link/managing-versions
Best Practices
DO
• Match version naming conventions already used in other systems.
o Example: If the release is named "1.1.0" in another system, don't name it "1.1" in
JIRA.
o These two values are fundamentally equal but their format differences make them
harder to remember and utilize.
• Ensure version format consistency within a project and across the organization.
o Example: Decide on one naming convention so users can easily predict the next value
• Create a version called "backlog" to group unscheduled work.
DON’T
• Have a complicated format. Users shouldn't need a reference manual to understand the
meaning of the version syntax.
o Example: "1.1" is easier to understand and reference in communication than

"1.1.x.y.release."
• Use the release date in the Version name.
o Example: "1/1/2015 Release." If a release date needs to shift, you should only have
to update the "Release Date" field, not the release "Name."
• Avoid using unnecessary words like "version", "iteration", or "sprint" in version names.
o Example: Use "1.1" instead of "Version 1.1." The word "Version" is redundant.
• Avoid specifying the release type in version names.
o Example: "1.1 Major Release”
o Instead, use the "Description" field to distinguish a major release from a minor, point,
or emergency release.
Read about the Semantic Versioning Specification at: semver.org
Alternate Uses for Versions

Teams without traditional "releases" can benefit from the Versions feature too!
You can use versions to group issues by week name, month name, quarter, or by any other
imaginable category. Use this functionality as a secondary distinguisher (similar to "Components"
but without the automatic assignment ability.)

Image: Versions Grouped by Quarter
This may be helpful for less technical users, who'd have trouble querying for issues within a date
range. In contrast, if a project already uses a "Due Date" type of field, that alone creates an
effective grouping. (There may be need for an issue with a "Due Date" to also have date-based
Version.) Consider whether users would benefit from this categorization or if it creates needless data
duplication.
Here's an easy way to further group project issues by category. Note that the Date fields are not
required.
Image: Versions Grouped by Category
Version Permissions
Only projects of the type "Software" and users in the "jira-software-users" group see the Versions
feature. The ability to set a fix version is coupled with the "Resolve" permission. Remember to
grant the "Resolve" permission for users who set this value.
Gregory Van Den Ham, IT Manager and Leader of the Chicago Atlassian User Group likes to use
versions to specify years. "They show up nicely on boards. Simple, clear, easy to gleam through for
knowledge. As a Manager, I need information quickly - especially when my teams' work is linked to
others and can cause blockers. With this versioning structure, I can quickly understand when work
needs to be scheduled if it’s in the backlog."
Image: Versions as Years (Board View)
Components
Quick Explanation
Components - a project specific distinguisher with auto-assignment capabilities
Example: If Component “X” is selected, assign Issue to user “Y.”
Attributes:
• Name
• Description
• Component Lead
• Default Assignee
Documentation: jirastrategy.com/link/managing-components
The Component is the most powerful feature in a project because:

• The selection list is maintainable by a project-level administrator
• It forms a natural Issue grouping that can be queried
• Automatic assignment removes the need for manual work
• An issue can be associated with multiple Components

Examples
Here are three examples of component strategies.
1. Assign Issues by Responsibility Area
Image: Components by Management Area
RECOMMENDATION
Worried about auto assignment when a user is out of the office? Set the expectation that a
supervisor needs to proactively attend to issues whenever a team member is out.
RECOMMENDATION
The Component assignment routing logic is complex. This article by Mikey Schott
at ServiceRocket helped me understand it and it may help you. Visit:
jirastrategy.com/link/auto-assign
2. Assign Issues by Request Type
Image: Components by Hardware Type
3. Assign Issues by Location
Image: Components by Country
Best Practices
• Component options should answer only 1 question.
o Example: Using the selection examples above, the options "Process," "Laptop," and
"United States" should never appear in the same Components list.
• When creating a new project, set one "test" Component in case the field is required in the
Field Configuration Scheme.

o Image: Potential Missing Component Error
• Ask the project lead to create the real Components and manage the list.
• Consider an “Other” selection to cover all potential non-listed responses. Automatically

assign "Other" issues to the default Project Lead.
• Component names should be short. One word values make for the easiest queries.
Permissions
Quick Explanation
Permission Schemes – a set of project permissions
Attributes:
• Name
• Description
• Settings for Users/Groups/Project Roles

Documentation: jirastrategy.com/link/permissions
Best Practices
DO
• Limit the number of project-level administrators.
• Let the project-level administrator manage as much as possible in the "Users and roles" area.
Use the Roles to power the Permission Scheme.
• Create groups and use them in roles or Permission Schemes.
• Add groups, distribution lists, or generic users to roles or Permissions Schemes before
individual users.
• If you create groups, you need a plan to keep them up to date. Unmaintained lists quickly
become useless.
• If you use nested groups (available through Crowd-Atlassian's authentication application), use
the highest group possible in roles of Permission Schemes. I recommend you add the parent
group instead of adding all sub-groups individually.
DON’T
• Add individual names to the permissions scheme.
o There are certainly exceptions but this quickly becomes hard to maintain.
Furthermore, the project-level administrator cannot manage individual names in the
permission scheme.
• Set unnecessary restrictions.
• Start with the most transparency possible and add on slowly as needed. Except for a very
small number of projects (e.g. your corporate security team), most projects should be open
to all JIRA users to see and interact with.
• Restrict a project so heavily that users have to contact application administrators to perform
simple operations.
• Duplicate permissions.
o Example: User Mary is part of the "jira-users" group. Specifying a permission for both
Mary and jira-users is redundant.
RECOMMENDATION
Create a group for your application-level administrators and add this group to the
"Administrators" line item in every Permission Scheme. This enables admins to assist with
project requests (settings changes, bulk updates, etc.) without having to first temporarily add
themselves to the Administrator Role for a project.
One application administrator "archived" projects by setting the "browse" permission only to
their username. When this user left the company, so did knowledge that other projects
even existed. These additional projects were coincidentally discovered during a database
examination.

Wording: Permission Schemes Overview
A Permission Scheme is used to control project-level access and abilities to perform certain
standard actions. This is different than controlling access to specific issues in a project.
Standard actions include abilities like "Create Issue," "Assign Issue," "Manage Watchers," etc.
While we try to share settings between projects, it is possible for each JIRA project to have its
own permission settings. A project-level administrator can view their project's "Permissions"
page, in the project's admin section, to see the current setup. However, any permission
changes are made by JIRA application administrators.
Download this wording at: jirastrategy.com/link/scheme-wording. Use the code in the “Worksheets,
Worksheet: Determine Permissions
Answer the following questions to create a permissions strategy that fits your needs.
Question Consideration
1. Is your JIRA application subject • You may need more stringent Permission Scheme
to compliance or industry-specific restrictions than recommended below.
standards?
2. Do you need to keep a legal • Most user actions are automatically logged.
record of actions in JIRA? • View an issue's activity history, the audit log, or the
database for details.
3. Do you need to keep a legal • Restrict the deletion of issues, comments, and
attachments in the Permission Scheme.
record of content in JIRA?
4. Do certain projects need to be • Restrict access of the "Browse" line item in the
Permission Scheme.
hidden from general users?
5. Do certain issues need to be • Consider using issue-level security. See the "Issue
hidden from general users? Security" section for details.
6. Does JIRA store sensitive or • Make sure you have a clear information security
proprietary information? policy. See the "Handle Sensitive Information"
section for details.
• Restrict access to data from external development
tools in the Permission Scheme.
7. Do external users have JIRA • Make sure you're able to segment external users and
access? quickly remove access. See the "External Users"
section.
8. Is JIRA the official time keeping • Restrict the deletion of worklogs.
application?
Download this worksheet at: jirastrategy.com/link/determine-permissions. Use the code in the

RECOMMENDATION
For each permission you restrict, consider what risk or problem you're trying to address. Does
JIRA already mitigate the risk (by logging user actions, for example?) Is there a specific
compliance requirement to satisfy? Can the issue be solved with user education instead?
Permission Scheme Worksheets

The worksheets below include recommendations for specific scenarios. Modify the worksheets to fit
your permissions needs. Since most end users won't be able to see Permission Scheme settings,
add this information to your user help files and documentation.
NOTE
This example references a custom role called "Leads." See the "Roles and Groups" section for
details.

Here's a recommended configuration for general use projects.
Worksheet: Normal Access
The table below shows the recommended permissions set up.
Project Permissions
RECOMMENDED Users /
Permission Notes
Groups / Project Roles
Administer Projects • Group (jira- • Add the group "jira-
Ability to administer a administrators) administrators" to every line to
project in JIRA allow the admin group to test
• Project Role
and make requested or needed
(Administrators)
changes.
Browse Projects • Group (jira- • Add your general user group.
Ability to browse projects administrators) (Example: jira-users)
and the issues within
• Role (Users) • Allow users to see that the
them
project and its issues exist. This
ensures the project appears in
the "all projects" list and returns
issues in queries.
View Development Tools • Group (jira- • Permission to view the
Allows users to view administrators) Development tab, which displays
development-related information from external tools
• Role (Users) OR Role
information on the view like Bitbucket, GitHub, Stash,
(Developers)
issue screen, like FishEye, Crucible, Bamboo, etc.
commits, reviews and
build information.
View Workflow • Group (jira- • Expose the diagram so users can
Users with this permission administrators) see where issues are in the
may view a read-only workflow.
• Role (Users)
version of a workflow
Issue Permissions
RECOMMENDED Users /
Permission Notes
Create Issues • Group (jira- • Allow any user to create an
Ability to create issues administrators) issue. Don't require a user to get
entry help from another user.
• Role (Users)
Edit Issues • Group (jira- • JIRA keeps a history of all
Ability to edit issues administrators) changed data, so there's little
risk in allowing users to make
• Role (Users)
updates.
• If this must be restricted,
consider allowing the reporter to
make updates to their own
issues.
Schedule Issues • Group (jira- • You may want to restrict this
Ability to view or edit an administrators) ability to project leads,
issue's due date developers, or administrators.
• Project Role
(Administrators)
• Project Role (Leads)
• Project Role
(Developers)
Move Issues • Group (jira- • Encourage users to move
Ability to move issues administrators) misfiled issues or change them to
between projects or a more appropriate issue type.
• Role (Users)
between workflows of the
• JIRA keeps a history of all initial
same project (if and moved issue keys. See
applicable). Note the
the "Database Queries" section
user can only move issues
for more info.
to a project he or she has
the create permission for.
Assign Issues • Group (jira- • If this must be restricted,
Ability to assign issues to administrators) consider allowing the current
other people user to reassign.
• Role (Users)
• If this must be restricted, be
prepared to regularly maintain
the access list.
Assignable User • Group (jira- • Allow issues to be assigned to
Users with this permission administrators) any JIRA user. This is useful if
may be assigned to issues action is needed from someone
• Role (Users)
outside the issue's current
project.
• If this must be restricted, be
prepared to regularly maintain
the access list.
Resolve Issues • Group (jira- • You may want to restrict this
Ability to resolve and administrators) ability to project leads,
reopen issues. This developers, or administrators.
• Project Role
includes the ability to set
(Administrators)
a fix version.
• Project Role
(Developers)
Close Issues • Group (jira- • n/a
Ability to close issues. administrators)
Often useful where your
• Role (Users)
developers resolve issues,
and a QA department
closes them.
Modify Reporter • Group (jira- • Allow all users to update the
Ability to modify the administrators) reporter. This is useful when
reporter when creating or reporters change teams, change
• Role (Users)
editing an issue focus, or leave the company.
• JIRA keeps a history of the

original reporter (stored as
"Creator.")
• If this must be restricted,

consider allowing the reporter to
be able to reassign to a
colleague.
Delete Issues • Group (jira- • Restrict this permission for legal,

Ability to delete issues administrators) compliance, and auditing
reasons.
• Project Role
(Administrators) or • Instead of deleting, encourage
Leave Blank users to re-purpose or close
unneeded issues with a
Resolution of "Won't Fix," "Won't
Do," etc.
• Train users to delete sparingly.
Link Issues • Group (jira- • n/a
Ability to link issues administrators)
together and create linked
• Role (Users)
issues. Only useful if issue
linking is turned on
Set Issue Security • Group (jira- • Only set this if an Issue Security
Ability to set the level of administrators) Scheme is used.
security on an issue so
• Leave Blank
that only people in that
security level can see the
issue
Transition Issues • Group (jira- • n/a
Ability to transition issues administrators)
• Role (Users)
Voters & Watchers Permissions
RECOMMENDED Users /
Permission Notes
View Voters and Watchers • Group (jira- • n/a
Ability to view the voters administrators)
and watchers of an issue
• Role (Users)
Manage Watchers • Group (jira- • Allow all users to add/remove
Ability to manage the administrators) anyone else as a watcher. This is
watchers of an issue a useful method of info sharing.
• Role (Users)
• Alternatively, train users to use
the "Share" function.
Comments Permissions
RECOMMENDED Users /
Permission Notes
Add Comments • Group (jira- • n/a
Ability to comment on administrators)
issues
• Role (Users)
Edit All Comments • Group (jira- • Users many not appreciate others
Ability to edit all administrators) editing their comments.
comments made on
• Project Role • JIRA will visually indicate when a
issues
(Administrators) comment has been edited.
• JIRA keeps a history of comment
changes. The original comment is
available in the issue history.
Edit Own Comments • Group (jira- • Let all users edit
Ability to edit own administrators) their own comments.
comments made on • JIRA will visually indicate when a
• Role (Users)
issues comment has been edited.
• JIRA keeps a history of comment

changes. The original comment is
available in the issue history.
Delete All Comments • Group (jira- • Restrict this permission for legal,
Ability to delete all administrators) compliance, and auditing
comments made on reasons.
• Project Role
issues
(Administrators) OR • Train users to delete sparingly.
Leave Blank
Delete Own Comments • Group (jira- • Let all users delete
Ability to delete own administrators) their own comments.
comments made on
• Role (Users) • The original comment is available
issues in the issue history.
Attachments Permissions
RECOMMENDED Users /
Permission Notes
Create Attachments • Group (jira- • n/a
Users with this permission administrators)
may create attachments
• Role (Users)
Delete All Attachments • Group (jira- • Restrict this permission for legal,
Users with this permission administrators) compliance and auditing
may delete all reasons.
• Project Role
attachments
(Administrators) OR • This ability is useful if the
Leave Blank attacher is unavailable, leaves
the company, etc.
• Train users to delete sparingly.

Delete Own Attachments • Group (jira- • Let all users delete their own
Users with this permission administrators) attachments.
may delete own
• Role (Users) • This ability is useful for removing
attachments old attachment versions or
unnecessary uploads.
Time Tracking Permissions
RECOMMENDED Users /
Permission Notes
Work On Issues • Group (jira- • Encourage users to track time,
Ability to log work done administrators) even if it's not required.
against an issue. Only
• Role (Users)
useful if Time Tracking is
turned on.
Edit Own Worklogs • Group (jira- • Allow all users to edit their own
Ability to edit own administrators) worklogs.
worklogs made on issues
• Role (Users)
Edit All Worklogs • Group (jira- • Allow supervisors to correct a
Ability to edit all administrators) work record, during a leave of
worklogs made on issues absence, for example.
• Project Role
(Administrators)
Delete Own Worklogs • Group (jira- • Allow all users to delete their own
Ability to delete own administrators) worklogs.
worklogs made on issues • Role (Users)
Delete All Worklogs • Group (jira- • Restrict this permission for
Ability to delete all administrators) finance or auditing reasons.
worklogs made on issues
• Project Role
(Administrators) OR
Leave Blank
Worksheet: Read Only Access
Here's a recommended configuration for a "read only" project. This is a project that's still visible
but you can’t create, edit, transition, or work on any issues.

RECOMMENDED Users /
Permission Notes
Administer Projects • Group (jira- • Needed so application-level
Ability to administer a administrators) administrators can perform
project in JIRA maintenance actions. (Example:
Reassign the project to a "Read
Only" category.)
Browse Projects • Group (jira- • Allow users see that the project
Ability to browse projects administrators) and its issues exist. This ensures
and the issues within the project appears in the "all
• Group (jira-users)
them projects" list and returns issues in
queries.
ALL OTHER PERMISSION • Leave Blank • All remaining line items
LINE ITEMS (especially "Edit Issues" and
"Transition Issues") must be left
blank to deny those permissions.
Worksheet: No New Issues
Here's a recommended configuration for a project about to be archived or where work is about to
conclude.

RECOMMENDED Users /
Permission Notes
Create Issues • Leave Blank • Prevent new issues creation or

Ability to create issues existing issues from being moved
into this project.
ALL OTHER PERMISSION • Same as defined in the • See the "Normal Access"
LINE ITEMS "Normal Access" worksheet above.
example

Worksheet: Fix Version Alternate Use
Here's a recommended configuration for a project using Fix Versions as a secondary grouping
mechanism. See the "Alternate Uses" section in the "Versions" chapter.

RECOMMENDED Users /
Permission Notes
Resolve Issues • Group (jira- • In this example, the "Fix Version"

Ability to resolve and administrators) functionality is used as a
reopen issues. This • Project Role (Users) secondary distinguisher (like
includes the ability to set "Components.") See the
a fix version. "Alternate Uses" section in the
"Versions" chapter for details.
• The ability to set Fix Versions is

coupled with the "Resolve"
permission.
ALL OTHER PERMISSION • Same as defined in the • See the "Normal Access"
LINE ITEMS "Normal Access" worksheet above.
example
Download this worksheet at: jirastrategy.com/link/permission-worksheets. Use the code in the

RECOMMENDATION
It may be useful to publish a static list of projects that are specially secured. Since end users
can't always see protected projects or review permission settings, documentation can cut down
on the "Why can't I?" questions.
Worksheet: Secured and Protected Projects
Use this worksheet to document any projects that have special restrictions or permissions. Link
the "Project" column value to the project's Summary page and any contact names to the user's
JIRA profile page.
The following projects are specially restricted.

Project Key Security Type Notes
Project PROJECT1 Restricted "Create" action Contact Paul to be granted
Name 1 Create permissions.
Project PROJECT2 Issues restricted to usernames Contact the Reporter to be
Name 2 listed in the "Special Access" added to an issue's access list.
custom field
Project PROJECT3 Issue Security Scheme n/a
Name 3
Project PROJECT4 Project restricted to members of n/a
Name 4 the Dev Team
... ... ... ...
Issue Security
Quick Explanation
Issue Security Schemes – settings to control access at the issue level
Attributes:
• Name
• Description
• Restriction (Users / Groups / Project Roles)

Documentation: jirastrategy.com/link/issue-security
To restrict access at the project-level, use a Permission Scheme. To restrict access to certain issues
within a project however, use an Issue Security Scheme.

Best Practices
• Add the Reporter to the access list. Generally the person who reported the issue should be
able to view and follow it.
• Set a default security level. Usually all issues viewable by default. To hide all issues, use
a Permission Scheme instead.
• Use Roles or Groups instead of individual user names, so schemes can be shared with other
similar projects.
DO
Don't forget to add users to the "Set Issue Security" line item in the project's permission
scheme. Only named users can apply a security level to an issue (even if they are members
of the specified security level.)
Wording: Issue Security Scheme Overview
An Issue Security scheme is used to control access to specific issues within a project. This is
different than controlling access to a project as a whole. While we try to share settings
between projects, it is possible for each JIRA project to have its own issue security settings. A
project level administrator can view their project's "Issue Security" page, in the project's admin
section, to see the current set up. However, any security changes are made by JIRA
application administrators.
Issue Security Worksheets

The worksheets below include recommendations for specific scenarios. Modify the worksheets to fit
your security needs. Since most end users won't be able to see Permission Scheme settings, add
this information to your user help files and documentation.
Worksheet: Simple Example
The table below shows a simple issue security set up.

RECOMMENDED Users /
Security Level Notes
Admin • Project Role • Once created, the Security Level name and
Project Admin, (Administrators) description are not edible. To change
Reporter labels, add a new level and delete the
• Reporter
existing one. (This also requires
reassigning issues in the original security
level.)
Lead • Project Role • n/a
Project Admin, (Administrators)
Reporter,
Additional Users
• Reporter
Worksheet: Soccer Team Hierarchy
Using our soccer example, here's how the team could be reflected in an issue security scheme.
Example: A soccer team has the following roles: a coach, a team captain, players, and fans.
RECOMMENDED
Security Level Users / Groups / Notes
Project Roles
Staff • Project Role • For issues that only team staff should
Coach, Team Doctor, (Administrators) see. Example: A request for an
Referee appointment with the team doctor
• Reporter
Players • Project Role • For issues that team staff and players
Team Captain, (Administrators) can see. Example: A request to move
Athletes Saturday's practice to Sunday
• Project Role
(Leads)
• Reporter
Fans • Project Role (Users) • For issues that any project user can see.
Parents, Community Example: A request to expand the
• Reporter
Members games per season next year
Download this worksheet at: jirastrategy.com/link/issue-security-worksheets. Use the code in the

NOTE
Too many Issue Security Levels can impact JIRA performance. Atlassian recommends no more than
10 levels in a scheme.

Notifications
Quick Explanation
Notification Schemes – settings for email messages sent at issue lifecycle events
Example: Issue Created, Issue Updated, Issue Assigned, etc.
Attributes:
• Name
• Description
• Notification Settings
Documentation: jirastrategy.com/link/notification-scheme
Best Practices
DO
• Create one scheme per notification strategy, not one per project.
o Example: A “Notify Project Users” scheme or a “Notify Project Users and C-Level
Execs Scheme”
• Control "issue spam" as much as possible.
o If you notify users at every possible step, too much email will be generated, users will
filter messages, and ultimately not see them.
• Be mindful of how JIRA email queue impacts the company email server.
• Reuse existing notification schemes.
o Except for a small subset of projects, most have the same notification needs.
DON’T
• Set unnecessary notifications. Only a small set of projects need custom notification points or
generic event handlers.
o Notifying users at every possible step generates too much email. Users will filter
messages and ultimately not see them.
• Add impossible or useless notifications.
o Example: Don't "notify watchers on issue create" if there is no watcher addition

capability on a create screen.
• Notify users of their own actions.
• Don't "notify reporter on issue create." It creates useless email traffic.
• Add the entire "jira-users" group to any line item.
Wording: Notification Scheme Overview
A Notification Scheme is used to control who receives system generated emails at standard
issue events. These events include: "Issue Created," "Issue Updated," "Work Logged," etc.
While we try to share settings between projects, it is possible for each JIRA project to have its
own notification settings. A project level administrator can view their project's "Notifications"
page, in the project's admin section, to see the current set up. However, any notification
changes are made by JIRA application administrators.
Worksheet: Notification Scheme
The worksheet below includes recommendations for a simple notification scenario. Modify the
worksheet to fit your needs. Since most end users won't be able to see Notification settings, add
this information to your user help files and documentation.
NOTE
This example references a custom role called "Observers." This role might represent your
compliance team, finance team, auditor, or other interested party who's not a regular project
member.
Standard Notification Points
The table below shows the recommended notification set up.

RECOMMENDED
Events Notes
Notifications
• Project Lead • Only include "Current Assignee" if a user
Issue Created
or an automatic action will set this value
• Current Assignee on ticket creation.
• Project Role (Observers)
Issue Updated • All Watchers • n/a
• Current Assignee
• Reporter
Issue Assigned • Current Assignee • When the assignee changes, a
notification will be sent to the previous
assignee and the current assignee.
Issue Resolved • All Watchers • n/a
• Reporter
Issue Closed • All Watchers • n/a
• Reporter

Issue • All Watchers • n/a
Commented
• Reporter

Issue Comment • All Watchers • n/a
Edited
• Reporter

Issue Comment • All Watchers • n/a
Deleted
• Reporter
Issue • All Watchers • n/a
Reopened
• Reporter
Issue Deleted • All Watchers • n/a
• Reporter

Issue Moved • All Watchers • n/a
• Reporter
• Project Lead
Work Logged • Project Lead OR Leave • Only useful for projects using time
On Issue Blank tracking functions
Work Started • Project Lead OR Leave
On Issue Blank
Work Stopped • Project Lead OR Leave
On Issue Blank
Issue Worklog • Project Lead OR Leave
Updated Blank
Issue Worklog • Project Lead OR Leave
Deleted Blank
Generic Event • Leave Blank • This is an extra event notification for
workflow transitions.
Download this worksheet at: jirastrategy.com/link/notification-worksheet. Use the code in the
Standard and Custom Notifications

Each issue-level activity is associated with an event. For example, an event called "Issue Created" is
triggered each time a new JIRA issue is created. JIRA automatically sends email notifications when
standard events are triggered. Standard examples: Issue creation, assignment, updated, resolved,
etc. Some events rules are stored internally in JIRA and others are stored as workflow transition
post functions.
Documentation: jirastrategy.com/link/custom-event
RECOMMENDATION
Don't forget to set an "Issue Closed" post transition in your workflows to send an "Issue Closed"
notification. Change the default function from "Generic Event" to "Issue Closed."
Image: Issue Closed Workflow Post Function
See also: "Set an "Issue Closed" Post Transition" in the Workflows chapter.
Additionally, you can alert recipients at your own custom notification points. A custom event trigger
alerts users when something specific occurs.
Simple examples:
• Alert the lead developer that an issue is ready for code review.
• Alert the testing team that an issue is ready for verification.
• Alert a senior exec that approval is needed.

Adding a custom notification is a three step process. First, create a new event, on the System >
Events admin page, and select the "Generic" template. The new event is now be available for use in
a Notification Scheme. Second, add users, roles, or groups to the new event in the associated
Notification Scheme. Third, add a post transition, in the associated Workflow, to trigger the event
notification.
In the example below, let’s add a custom notification called "Ready for Verification" in three steps.
Image: New Event
Image: Notification Scheme Assignment
Image: Workflow Post Function
RECOMMENDATION
Adding roles or groups to the Notification Scheme event is easier to maintain than adding
individual users. Alternatively, create a distribution email address on the mail server. This
allows the list's owner to make membership changes outside of JIRA.

Wording: Status Update Email Notification Instructions
An email address can be used to notify users of a state or event in JIRA. Here are some
questions to guide you through the setup.
Step 1: Set up a Distribution List Email Address on the Mail Server

Please coordinate with your Corporate Email team.
1. What is the desired email address?
▪ This address must be on an internal domain. For security purposes, no external

(gmail.com) addresses should be used!
2. Who is the owner of the distribution list?
▪ Please have an owner set, so we can identify who to contact with issues.
▪ As the owner, make sure you have permissions to add and remove users, so you
can keep your distribution list up to date.
3. Who are the distribution list members?
▪ You can ask email team to add members now, or add them yourself later.
4. Who should have access to this mailbox?
5. What type of access is needed (e.g. Read emails, full access, "send as," etc.)?
6. Does this address forward mail to any other addresses?
7. What type of retention policy should be used?
▪ Example: When can emails older than certain age can be deleted?
Step 2: Set up the Email Address in JIRA

Please coordinate with your JIRA Support team.
Create a JIRA Support issue that includes the following information:
• What is the email address?
• Which JIRA project will use this email address?
• Which issue type(s) in your JIRA project will use this address?
• At which status change or event should the notification take place?
Download this wording at: jirastrategy.com/link/email-notification. Use the code in the

Bulk Change Notifications
The "Bulk Change" feature provides the ability to modify multiple issues at once. For example,
resolve fifty issues in one step. A global permission defines who may use this feature.
RECOMMENDATION
When changing issues in bulk for administrative reasons, uncheck the "Send mail for this
update" option that appears at the very bottom of the "Step 3 of 4: Operation Details" page.
NOTE: This checkbox is only available to users with project-level administrative permissions.
This allows admins to make bulk changes "behind the scenes" without generating excess
notification emails. The change is logged in the database as expected and is visible in an issues
"Activity" area.
Image: Bulk Change Notification Option
Standard Capabilities
Users should have the benefit of all the features and automation JIRA has to offer. Have you ever
tried to work in a project where simple abilities, like adding attachments or labels, are hidden or
unavailable? Have you come across a situation where users have been given a permission they can't
actually use? Example: Users are able to "Assign" however, the assignee field isn't on the edit
screen.
One company had some strange settings. They didn't want abilities like versions,
components, priorities, labels, or attachments. They hide these useful elements in the field
configuration.

Worksheet: Standard Capabilities
Use this worksheet to create your list of "must have" abilities. When creating a new project, double
check that the following useful features are included.
Project Type: General Projects
Create Screen
• Summary (Standard, required field)
• Description
o Recommendation: Make this a required field in every project. Resist the temptation
to use a different field (like "Notes" or "Details") to collect basic issue creation
information.
o Recommendation: Use the "Wiki Style Renderer which allows users to input rich
text. The usefulness of text formatting likely outweighs any application performance
concerns.
• Component/s
• Priority
• Due Date
o Recommendation: Listing the "Due Date" field after the "Priority" field helps
requestors set realistic speed expectations.
• Linked Issues
• Attachment
• Labels
• Wiki Rendered Description Field (for rich text and @mention tagging)
• Wiki Rendered Comment Field
DON’T
Require a user to submit initial information in multiple steps. (i.e.: Create an issue then edit
it to provide more initial information.) Place all absolutely essential fields on the "Create"
screen. Example: For projects where a screenshot is helpful for troubleshooting, make sure
the "Attachment" field is on the "Create" (as well as the "Edit") screen. Otherwise, you may
never receive that important attachment.
Edit/View Screen
• Assignee
• Reporter
o Since JIRA version 6.2, both a "Creator" and a "Reporter" are logged in the database.
This allows users to create issues on behalf of others and modify the Reporter without
impacting auditing.
• Labels
• Time Tracking (includes Original Estimate and Remaining Estimate fields)
o Recommendation: Even if your organization doesn't (or is resistant to) estimating

work, still enable the ability as an optional feature.
• Log Work
o Recommendation: Even if your organization doesn't (or is resistant to) to logging

work, still enable the ability as an optional feature.
RECOMMENDATION
Is the field list getting long? Consider adding an "Internal Details" tab to group administrative-
type fields.
Image: Multiple Tabs
Project Type: Development Specific

All of the above plus:
• Fix Version
• Epic Link
• Other "Agile" fields helpful to Development teams (e.g. Sprint)
Download this worksheet at: jirastrategy.com/link/standard-capabilities. Use the code in the

RECOMMENDATION
Take screenshots of your standard Create and Edit screens. Provide them as choices for new
project requests. Encourage the use of existing screens where possible.
Part 3: Fix and Clean JIRA Up
Few of us are lucky enough to start out with a fresh and clean JIRA installation. Fewer of us will
make no configuration mistakes along the way. If your application is already a mess, there are steps
you can take to clean it up.
In part 3, we'll tackle auditing the configuration you have, removing old and unused elements, and
discuss alternate options.
Audit
Before you begin to make changes, you need to investigate your current configuration. What is your
set up today? Why is it the way it is? Does it support your current needs? After you learn more
about what you have, you can start to plan incremental improvements.
Step 1: Understand Your JIRA Set Up
Start by viewing the "System info" page in the JIRA admin area. The projects, issues, custom fields,
workflows, and other stats are tallied there. Also, visit the "Add-ons" admin page and review the
items in the "User-installed" category. Use the worksheet below to record the total counts, so you
can track changes and progress over time.

Worksheet: System Stats
Item Date 1 Date 2

Version
Issues
Attachments
Comments
Components
Custom Fields
Groups
Issue Security Levels
Issue Types
Issues
Priorities
Projects
Resolutions
Screen Schemes
Screens
Statuses
Users (and Admin
Users)
Versions
Workflows
Add-ons
Download this worksheet at: jirastrategy.com/link/system-stats. Use the code in the “Worksheets,
Next, visit the admin area for every scheme and project asset. Examine the admin pages under the
headings: Issue Types, Workflows, Screens, Fields, and Issue Attributes.
RECOMMENDATION
Copy all the info on the page into an Excel spreadsheet, or get the info from a database query.
This will help you to compare and make notations next to each item.
Specifically, look for items that are unused and items that are duplicated.
The admin pages show additional columns containing links to associated elements. If the columns
are blank, the item is not currently in use. In the example below, "Quantity" field is used on the
"Asset Screen," however, the "Total Quantity" field is unused.
Image: Two Similar Custom Fields
On the "Workflows" and "Workflow Schemes" page, also look for items listed in the "Inactive"
category at the bottom of the page.
Duplicated items might share the same name, a similar name, or simply serve the same purpose. In
the screenshot example above, the field named "Total Quantity" is likely a duplicate of "Quantity."
Even if the field isn't an exact duplicate, two similar fields are likely unnecessary.
For now, just note the unused and duplicate elements. Don't delete anything yet! If elements need
further investigation, do that work now and record the results for action later.
Step 2: Set Goals
After you complete the review, it's time to think about the future state to get to. What are your
goals? What will the clean-up actions accomplish? Here are some examples:
• Remove unused schemes so useless configuration elements aren't stored.
• Reduce the custom field count by 50% so application performance is fast.
• Support only a handful of workflows, to cut down on administrative overhead, and have a
consistent experience for end users.
Step 3: Test and Backup
• Before you make any changes, you must backup your data and verify the backup.
• For any large or complex changes, you may also want to test in a staging environment first.
• Always be aware of what issues your change may cause and how to un-do your change if
needed.
Step 4: Start the Clean Up
Now you're ready to start removing unused and duplicate assets. Work slowly, making only small
changes at a time. After major changes, do another backup. Use the sections below to help you
with your clean-up process.

Areas to Tackle
At one company, no clean-up efforts had ever taken place. The application grew organically
and muddier by the day. New customizations were added but none were ever removed.
This created a swampy mess of schemes and settings. To clean up this swamp, the first
step is to survey the schemes and settings and get rid of old and unused items. Delete any
inactive workflows, unused custom fields, or disassociated schemes. Next, examine all
projects to determine which are still active and which have no recent activity. Post
examination revealed 30% of projects could be "archived." Custom notification and
permission schemes for these projects were not needed. The last step was to remove the
defunct incoming mail server settings. Just by removing unused resources, there was a
20% reduction in scheme count and a 30% reduction in database record count.
Unused Elements
By now you have a list of all unused issue types, workflows, screens, fields, statuses, resolutions,
priority, and related schemes. These are the easiest to address, so delete them first. Here's how to
identify them using simple browser tools.
Visit the admin page for each item listed. Use the information in the "identification" column to detect
unused schemes.
Item Identification Deletion Notes
Issue types • Look for issue types only used by the • Before deletion, JIRA
default scheme, which may be labeled displays a usage count.
"Default Issue Type Scheme."
• You may need to migrate
• Query the issue type (Example: type = issues to a different type
bug) to determine its popularity. before deletion is allowed.
Issue type • Use the browser's find command (CTRL-F) • Before deletion, JIRA
schemes to search the page for the string "No advises you which projects
projects." are using the scheme and
that they will be changed to
the default global issue type
scheme.
Workflows • Expand the "Inactive" section at the bottom • Before deletion, JIRA
of the page. displays a generic "are you
sure you want to delete"
o Use the browser's find command confirmation screen
(CTRL-F) to search the page for the
string "Delete." (Only unassociated • Workflow deletions cannot
items can be deleted.) be undone. Consider
exporting the workflow first.
o Alternate: Look for line items with a
blank in the "Assigned Schemes"
column.
o The "Assigned Schemes" column
may point you to unused Workflow
Schemes as well.
Workflow • Expand the "Inactive" section at the bottom • Before deletion, JIRA
schemes of the page. displays a generic "are you
o Use the browser's find command confirmation screen.
(CTRL-F) to search the page for the
string "Delete." (Only unassociated
items can be deleted.)
o Alternate: Look for line items with a

blank in the "Projects" column.
Screens • Use the browser's find command (CTRL-F) • Before deletion, JIRA
to search the page for the string "Delete." displays a generic "are you
(Only unassociated items can be deleted.) sure you want to delete"
confirmation screen.
• Alternate: Look for line items with a blanks
in the "Screen schemes" or "Workflows"
column.
Screen • Use the browser's find command (CTRL-F) • Before deletion, JIRA
schemes to search the page for the string "Delete." displays a generic "are you
• Alternate: Look for line items with a blank
in the "Issue type screen schemes" column.
Issue type • Use the browser's find command (CTRL-F) • Before deletion, JIRA
screen to search the page for the string "Delete." displays a generic "are you
schemes (Only unassociated items can be deleted.) sure you want to delete"
in the "Projects" column.
Custom fields • Look for line items with a blank in the • Before deletion, JIRA
"Screens" column. displays a generic "are you
• Do a JQL query to see how the field may confirmation screen.
have been used in the past. Example:
cf[10601] is not empty • The following warning is
also displayed: "Note:
Deleting a custom field
removes all matching values
from all issues."
Field • Use the browser's find command (CTRL-F) • Before deletion, JIRA
configurations to search the page for the string "Delete." displays a generic "are you
in the "Field Configuration Schemes"
column.
Field • Use the browser's find command (CTRL-F) • Before deletion, JIRA
configuration to search the page for the string "Delete." displays a generic "are you
schemes (Only unassociated items can be deleted.) sure you want to delete"

Statuses • Use the browser's find command (CTRL-F) • Before deletion, JIRA
to search the page for the string "No displays a generic "are you
associated workflows" or "Delete." sure you want to delete"
Resolutions • See the "Practical Audit Example" below. • Before deletion, JIRA
displays a usage count and
also helps migrate any
issues to a different
resolution.
Priorities • Query the priority level (Example: priority • Before deletion, JIRA
= trivial) to determine its popularity. displays a usage count and
also helps migrate any
issues to a different priority.
Issue security • Use the browser's find command (CTRL-F) • Before deletion, JIRA
schemes to search the page for the string "Delete." displays a generic "are you
Notification • Look for line items with a blank in the • Before deletion, JIRA
schemes "Projects" column. advises you which projects
are using the scheme and
that you should manually
reassign them.
Permission • Look for line items with a blank in the • Before deletion, JIRA
schemes "Projects" column. advises you which projects
are using the scheme and
that they will be changed to
the default permission
scheme.
Duplicate Elements
Sometimes duplicate elements are easy to find; they have the same or similar names. Other times,
two elements have different names but serve the same purpose. If you understand how your
custom elements are used, it is easier to identify duplicates.
In the example below, there are similar fields of the same type.
Image: Two Similar Custom Fields
Now, you need to figure out which of the fields to retain. There are three things to consider:
1. Which field is more popular?
2. Which field has a better name?
3. Which field is easier to delete?
It's generally easier to retain the most popular field. To determine popularity, query each field (i.e.
quantity is not empty) and count the total results. In this case, let's say "Quantity" is more popular
and also has the better name. "Total Quantity" will be removed.
If there aren't many records using "Total Quantity," you may be able to just remove the field.
However, if you need to retain existing data, copy the values from the "Total Quantity" to the
"Quantity" field. There are a few ways to accomplish this:
• Use the "Copy value from other field" post function from the Suite Utilities for JIRA plugin.
Read more about these plugins in the "Noteworthy Add-ons" section.
• Use the "Copy custom field values" function from the ScriptRunner for JIRA plugin.
• Use the "Copy field value" command from the JIRA Command Line Interface (CLI) plugin.
• Export the issue data, manually change the data, and re-import.
Once you copy the data, update any screens using the "Total Quantity" field to use "Quantity"
instead. Then, delete the "Total Quantity" field.
Practical Audit Example
Let's audit the list of "Resolutions" as a practical example.
1. Examine all selections on the admin "Resolutions" page or in the database.
2. For each resolution, record the popularity (frequency of use) count, which helps you choose
between similar selections.
3. Look for poorly named selections or duplicates that are not widely used.
4. Look for descriptions that are unclear or left blank.
5. Remove undesired selections with the "Delete" link on the "Resolutions" page.
NOTE
After clicking the "Delete" link, JIRA displays a usage count and will help migrate any issues to a
different resolution. Not all assets have this pre-delete check or migration availability. See the
table in the "Unused Elements" section for more information.

Resolution Current Current
Popularity Proposal Notes
ID Name Description
1 Works as 1400 Improve New description copy:
Works as designed
Designed description "Not a defect. The
reported behavior is
expected."
2 Not a The issue will not 400 Remove Duplicate of "Works as
Defect be addressed; the Designed"
feature is working
as designed.
3 On Hold The issue has been 100 Remove Invalid selection. (An
deferred. issue that is "On Hold"
has NOT been
resolved.)
...
You can also use a filter and a dashboard to gauge resolution popularity. A simple query,
like resolution is not EMPTY and a pie chart shows usage count.
Image: Resolution Popularity Pie Chart
JIRA comes with five pre-loaded Resolution values, but one company had expanded that list
to over 30. Many were duplicates, invalid, unnecessary, or unused.
This same audit activity should be done with Statuses and Priority values as well.
Inactive Projects
Periodically, you should look for stagnant projects. Four common reasons projects sometimes see
little or no use are: the initiative is complete, the system has been decommissioned, company
priorities change, or teams reorganize.
At one company, each company initiative had a JIRA project. After an initiative was
complete, the team moved on to new initiatives, but their JIRA project remained open and
available. As such, users were reporting issues in inactive and unmonitored projects.
Unaddressed issues lingered in these old projects.
There are a few ways to manually detect inactive projects:
• The Project Lead has left the company or is listed as "inactive."
• A large percentage of reporters or assignees have left the company or are listed as "inactive."
• The project has a low total issue count.
• No new issues were created.
• No recent updates for existing issues.
• The initiative has ended or the related system has been decommissioned.
• The Project Lead reports it is no longer needed.
Use the following worksheet to list all your projects and their attributes, so you can determine which
are inactive.

Worksheet: Project Status
Project Project Inactive Issue Last Recomm

Key Notes
Name Lead1 Lead Count2 Update3 endation
Project PROJECT1 Mary No 1000 2016- n/a n/a
1 01-01
Project PROJECT2 John Yes 1 2000- Archive The Project
2 (Inactive) 01-01 Lead has left
the company,
only one issue
was ever
created, and
no issue
updates have
been made
since 2000.
This project is
no longer
needed.
...
Download this worksheet at: jirastrategy.com/link/project-status. Use the code in the “Worksheets,
There are multiple ways to detect potential archive candidates.
1. To find an inactive Project Lead, look at the lead assignment on a project's "Summary" page
or on any project admin page. Inactive users will show the copy "(Inactive)" after their
name. Additionally, view the "all projects" list and use the browser's find command (CTRL-F)
to search the page for the string "Inactive."
2. Use a JQL statement, like project = project-name, to get a project's total issue count.
3. To find the date of the last updated issue, use a JQL statement like project = project-
name order by updated DESC. The most recently updated issue will be displayed first. You
can also use the database to find this information. See the "Database Queries" section for
details.
Use any of the methods listed in the "Archive" chapter to hide, make read only, or remove access
to the "inactive" projects.
Once you've made projects inactive, you may be able to continue cleaning up by removing additional
schemes and assets.
Wording: Sample Inactive Projects Notification
Use the following sample messaging to communicate upcoming archive activities to your users.
As part of our regular JIRA maintenance activities, we archive projects that appear inactive.
The following projects haven’t been updated since the first half of this year. If you’d like to
keep your project(s) around, please respond to this message. Otherwise, the JIRA Support
team will archive them on [date].
Key Project Name Lead

...
Inactive Employees
Have all former employees been made "inactive"? If yes, great! But that's only one step for dealing
with user data left behind.
TIP
Do not delete a user, as you'll want to keep a history of their actions in the software.
Former Employee Clean-up Procedure
Here is a sample clean-up process to follow when a user leaves the company:
Perform the steps below before you make a user "inactive." You may need to log in as the user to
delete old assets.
The easiest way to uncover user asset is to search the database for their username.
The ScriptRunner plugin can be used to automate some of the steps below. Read more about it in
the "Noteworthy Add-ons" section.
1. Move any "not closed" assigned issues to the user's supervisor.
▪ JQL: assignee = username and status not in (closed)
▪ JQL: assignee = username and resolution is EMPTY
2. Move any "not closed" reported issues to a user's supervisor.
▪ JQL: reporter = username and status not in (closed)
▪ JQL: reporter = username and resolution is EMPTY
3. Remove unshared custom dashboards, gadgets, filters, filter subscriptions and boards.
▪ Login as the user and delete the assets.

TIP
Login as the user in a different browser than you are logged in as admin.
4. Remove favorite designations for dashboards.
5. Move shared (subscribed to, favorited by others) dashboards to the user's supervisor or to a
generic user account.
▪ It's only worthwhile to retain dashboards if they are used by other active users.
o The easiest way to change ownership of shared filters and dashboards is with
the "Change Owner" functions the Admin > System area.
o Alternately, use a copy of the query so a different user can recreate a filter or
dashboard in their own account.
o You could also move highly used filters or dashboards to a generic (persistent)
user account for easy updating in the future.
6. Remove favorite designation for filters.
7. Move shared (subscribed to, favorited by others) filters to the user's supervisor or to a
generic user account.
▪ It's only worthwhile to retain filters if subscribers are active users.
8. Reassign project leads to the user's supervisor.
9. Reassign component leads to the user's supervisor.
10. Remove filter subscriptions.
11. Remove draft workflows.
12. Reassign agile boards to the user's supervisor.
▪ Change board administrators on the "General" page in the board's "Configure" area.
13. Check workflows for auto assignment transition behaviors. See the detection method in
the "Finding Embedded Workflow Behaviors" section.
14. Make the user account inactive.
Clean-Up Check-up
When you’re wading through mucky JIRA projects during the clean-up phase, you never know what
is lurking underneath. It’s important to check how each clean-up activity impacts other areas of the
application.
MISTAKE
JIRA comes with five link types. (e.g. blocks, clones, duplicates, etc.) At one company the
list of link types grew to 20 different options! To remedy this, I removed unused, outdated,
and duplicate types. JIRA handled the migration, automatically updating any issues
associated with those old types. Subsequently, this changed the “Updated Date” to today's
date for a large amount of old issues. An internal app using the REST API was using the issue
"Updated Date" field to limit the number of issues in its own application. My change caused
an increase in the scope of their queries, the queries timed out, and their app stopped
functioning! In this case, it’s important to know exactly what any apps using the REST API
are doing. That way you can consider them when making global changes.
Quick Clean-up Check-up
• After a clean-up action, manually verify the results
• Run the Integrity Checker
• Run system health tools
• Review the application logs for errors
• Identify impacts on any apps or APIs
• Be ready to respond to any resulting user trouble reports
DO
Always test the impact of any clean-up activities in a test environment first.
Old Email Handlers

Part of your scheduled maintenance procedure is to check Incoming Mail Servers and Mail Handlers.
Remove configurations for servers that no longer exist. Clean-up connections to deleted email
addresses.
• For Mail Servers, use JIRA's "Incoming Mail" admin area to test the connection to any mail
server.
• For Mail Handlers, verify the listed email address is valid. (Send a test message to the
address from your email program.)
o Next, verify the Project and Issue Types for that address still exist.

o Finally, verify an issue is properly created, in JIRA, from the test message you
previously sent.
DO
Fix or remove any malfunctioning servers or handlers.
Archive
While JIRA doesn't have an official archive mechanism, there are a number of ways to "retire"
inactive projects.
Option 1: Prevent New Issues

With this option, you can work on existing issues, but you can’t create nor add new issues to the
project. This option (temporary) is good when a team is transitioning to a new project. Set a
transition end date for completion of another method listed below.
1. Add a notice to the project's "Summary" page.
▪ Sample notification: "Notice: This project is being decommissioned. New issues can
be reported in the [project name] project instead."
▪ Image: Summary Page Message
2. In the project's Permission Scheme, remove all users and groups from the "Create Issues"
line item.
See the "No New Issues" worksheet in the "Permissions" chapter for more information.
Option 2: Make the Project Read Only
With this option, you can’t work (update, resolve, etc.) on existing issues. Neither can you create,
add, or remove issues from the project. This option is for when a project needs to stay visible for
documentation or knowledge-share reasons.
1. Add a notice to the project's "Summary" page.
▪ Sample notification: "Notice: This project is in "Read Only" mode. Existing issues can
be viewed for historical purposes, but no issues can be created, updated, or worked."
2. In the project's Permission Scheme, change the "Administer Projects" line item to "Group
(jira-administrators)" so application-level admins can still perform actions. (Example:
Reassigning the project to the "Read Only" category.)
▪ Make sure the "Browse Projects" line item contains "Group (jira-users)" (or "jira-core-
users", "jira-software-users") so users can view the project and issue data.
▪ Remove all users and groups from any other line items (especially "Edit Issues" and
"Transition Issues").
3. Create a project category called "Read Only" and assign the project to that category.
▪ Recommendation: If you have a lot of categories, prefix categories for "inactive"

projects with an "x" (Example: "x Read Only") so it shows at the bottom of the
alphabetical list.
See the "Read Only Access" worksheet in the "Permissions" chapter for an example.
Option 3: Hide the Project

This option hides the project from all users. The project does not appear on the "All Projects" list
and issues don’t return in queries and search results. Also, any filters, dashboards, and other
reports referencing the project's "long name" no longer function.
▪ In the project's Permission Scheme, remove all groups, roles, and users from the "Browse"
line item.
RECOMMENDATION
For any archived or "hidden" project, add the jira-administrators group to the "Browse" line
item. This way, admins will still know the project exists.

Option 4: "Archive" the Project
This option makes the project "read only" (like option #2 above) and classifies the project as
"archived." This option is for when work on a project has concluded, but it needs to remain visible to
users for historical or reference purposes.
• Add a notice to the project's "Summary" page.
o Sample notification: "Notice: This project is in "Read Only" mode. Existing issues can
be viewed for historical purposes, but no issues can be created, updated, or worked."
• In the project's Permission Scheme, grant the "Administer Projects" permission to the "jira-
administrators" group, grant the "Browse Projects" permission to the "jira-users" group, and
leave all other permission line items blank.
• Change the project's long project name to "Archived: [project name]"
o Recommendation: Use a consistent naming format for ordering archived projects.

If you have a lot of projects, prefix the project name with an "x" (Example: "x
Archived: [project name]") so it shows at the bottom of any project list. (Example:
The "All Projects" page, configuration drop down menus, administrative settings pages,
etc.)
o NOTE: A project name change will break filters and dashboards using queries in the
format: project = project name. Queries referencing a project's key however
(Example: project = project key) will remain functional.
o Search the database to see how many filters will need updates. See the "Database
Queries" section for details.
• Create a project category called "Archived" and assign the project to that category.
o Recommendation: If you have a lot of categories, prefix categories for "archived"

projects with an "x" (Example: "x Archived") so it shows at the bottom of the
alphabetical list.
• Change the project's icon to a unique image used to signify projects in this state.
Image: Four Project Settings Indicate an Archived Project
RECOMMENDATION
Teach end users to exclude archived projects in their filters with JQL. Ex: assignee =
currentuser() and category != "x Archived"
Option 5: Export the Project

This option involves exporting and storing data in an external location. Make sure the external
location is backed up and retained in accordance with your company's standard corporate data
retention policy. After export, delete the project, configurations, and issues from the application.
This option is for when data needs to be retained for legal and compliance reasons, however, it
doesn't need to be accessed regularly, within JIRA.
NOTE
Filters, dashboards, and other reports referencing the project will no longer function. Also, the
export may reference attachments but does not contain the actual attachments. All JIRA
attachments are stored on the JIRA server itself.

WARNING
Re-importing data can be tricky, especially if you've upgraded since the export. You should do
extensive export and import testing to make sure this method fits your needs in the long term. If
you think you'll ever need to view this data again within JIRA, you may be better off with one of the
previous options. Alternatively, you can set up a second application instance for the sole purpose of
housing the archived data. Of course, you'll need to maintain this additional instance, upgrade it in
tandem with your primary instance, and consider any licensing impacts.
WARNING from Atlassian: "Restoring a project from a backup is not a trivial task. You may be
required to change the configuration of your target JIRA instance to accommodate the project
import. (A backup/export file contains only issue (field value) data - not JIRA or Project
configuration data. Example: Workflows, presence of custom fields, etc.) Additionally, the Project
Import data mapping can be resource intensive on your hardware and may take a long time to
complete. Note: The Project Import tool will lock your instance of JIRA during the actual data
import, so please ensure that your instance does not need to be accessible during this time. We
strongly recommend that you perform a full backup of your target JIRA instance before attempting to
restore a project into it." Read more: jirastrategy.com/link/restore-project
Archive Clean-Up & Notification

To perform clean-up for any form of "archive" action, consider the following:
1. Use the "Bulk change" feature to move all "not closed" issues to another project, if desired.
2. Bulk unassign (or reassign) all "not closed" issues.
3. Export some or all issues to .xls or .xml format. (For local or alternative backup purposes.)
4. Notify any recent users of the project.
▪ Recommendation: Use a JQL or database query to get a list of all recent reporters
and assignees in a project. See the "Database Queries" section for details.
5. Ask users to remove the project from their filters.
6. Change the Notification Scheme selection to "None."
7. Delete any unnecessary assets. Example: a previously used custom Notification or

Permission Scheme.
RECOMMENDATION
When making the same change to a large number of projects, get a list of project keys from the
database, copy the admin page base URL, and concatenate the two, using Excel, to make new
links. Then, launch all the links directly to the appropriate configuration pages. That avoids a
lot of time-consuming clicks when there are a lot of projects.
Merge Applications or Start Over
You may find yourself in a situation where multiple JIRA applications should merge into one, data
from an existing instance should move to a brand new one, or you need to start over from scratch.
Consider the example company from the introduction who spent many months making
visual and functional customizations. They changed so much that they couldn't upgrade
without wiping out all the custom elements. They concluded the only way to move forward
was to forgo their customizations, stand up a new instance, and migrate their historical
information.
At one company, the Finance department noticed they were paying for two separate JIRA
licenses. One team was using a Cloud instance and another team had a Server instance
running on an old machine under someone's desk. The teams had to decide which
application type would be retained and how to merge the data.
Application Comparison
To determine the best course of action you need to compare the strengths and weaknesses of each
set up. It's also helpful to gauge just how different your set up is to the JIRA default.
Download a version-specific default set up reference at: jirastrategy.com/link/clean-instance. Use

the code in the “Worksheets, Templates & Companion Materials” section to download it for free.
Top 5 Comparison Considerations
1. How do integrations, connections to other apps, and levels of customization differ?
2. What are the hardware, software, database, and network abilities of each application?
3. What are the differences between authentication methods and security strategies?
4. How often are upgrades able to be performed and how much downtime can be sustained?
5. Which set up has the most robust application maintenance and user support procedure?

Worksheet: Application Comparison
Use the worksheet below to compare the strengths and weaknesses of each set up.
This information is compiled for the purposes of comparing two implementations of the same
application. This data enables informed migration decisions.
Overall
What are the strengths and weaknesses?
Item Considerations App 1 App 2
Strengths What are the best aspects of the set up? What aspects
should be retained?
Weaknesses What are the worst aspects of the set up? What aspects
or data can be excluded?
Application
What are the general stats and overall size? How is the app used? How much of the data is
current vs historical?
Application, What are the application details? (Example: Software
Install and/or Core, Cloud or Server.)
Type, Version
Issues How many?
Attachments How many? Where are they stored?
Comments How many?
Projects How many? How many need to be retained?
Workflows How many? How many need to be retained?
Custom Fields How many? How many need to be retained?
Issue Types How many? How many need to be retained?
Statuses How many? How many need to be retained?
Users How many?
Admin Users How many? Is that number appropriate? (i.e. limited)
Groups How many? How many need to be retained?
Plugins How many? Which are vital?
Licensing & Which license tier? What is the annual cost?
Costs
Usage How is JIRA mainly used? (Example: For software
development, customer support, etc.)
Ownership Who owns, administers and maintains the application?
How are change requests and customizations managed?
Authentication
How is access managed? How and where are accounts created? What do general users have
access to?
Access How are new users requested? How are new accounts
Requests created?
Credentials Where are credentials stored? How do users receive
them? How are password resets handled?
Security Who receives access? What information to regular users
Strategy have access to? What types of actions?
Hardware & Server
What hardware is powering the app? Is it well maintained? Is it stable? Is it likely to remain in
inventory?
Hardware What hardware is powering the app? (Include specs.)
Is it likely to remain in inventory?
Server What server software is powering the app? (Include
Software specs.)
Bandwidth & What is the bandwidth and capacity? Can it adequately
Capacity handle current traffic? Future additional users and
traffic?
Backup How is data backed up? How often? Where is the
backup stored? Who has access to it?
Security How is it secured internally and externally?
Mail What mail server is connected? Can it adequately
manage current notifications? Future additional users
and traffic?
Support Is it well maintained and actively supported? Who's
supporting it? Are there any "behind the scenes"
concerns?
Additional What additional sandbox environments are available?
Environments
Database
What database is powering the app? Is it well maintained? Is it stable?
Database What database is powering the app?
Type, Version
Connections What is the bandwidth and capacity? Can it adequately
manage current traffic? Future additional users and
traffic?
Backup How is data backed up? How often? Who has access to
it?
Security How is it secured internally and externally?
Size How large is the data? How much more data can it
accommodate?
Support Is it well maintained and actively supported? Who's
supporting it? Are there any "behind the scenes"
concerns?

Integrations, Connections, REST API
What other apps does JIRA connect to? What other integration points exist? How is the
REST API used?
Integrations What internal or external applications use the REST API?
What do these apps do? What information do they
access?
Connections What applications are connected?
Data Insertion What Issue Collectors, Incoming Mail Handlers, bulk
action, or import methods are in use? (Also consider
insertion by plugins.)
Maintenance
What actions are taken to maintain the application?
Standard What is the standard maintenance procedure? How often
Maintenance is maintenance performed? Are activities proactive or
aggressive?
Upgrades What is the upgrade procedure? How often are upgrades
performed? When is the next scheduled upgrade?
Monitoring What manual or automatic application monitoring is in
place?
Analytics What additional analytics are available?
Downtime and Is the application stable? What was the cause of the last
downtime event? How frequently is the application
Stability
unavailable?
Archival How is historical data handled?
Automation What procedures are automated?
User Support
How are end users supported? What documentation or training avenues exist? How
knowledgeable is the support team?
Support Who supports users? What is the escalation path for
trouble reports?
Experience How high is the support team's knowledge level?
Training Have any training courses or certifications been
completed?
Other
What else is useful to know?
Special Policies What additional special policies or procedures exist to
and Procedures support the health of the application?
Hacks and Non- What hacks are in place? Why are they needed?
Standard Uses
Trials and Tests Are any companion applications or plugins being tested?
Download this worksheet at: jirastrategy.com/link/application-comparison. Use the code in the
Plugin Tracking
You should also compare installed add-ons. Use this template to record and compare those details.
Worksheet: Plugin Tracking
The easiest way to access your plugin data is through the database. See the "Database
Queries" section for an example. Additionally, your plugins are listed in the JIRA administration
area or in your Atlassian account profile. Use this worksheet to record additional information,
track changes over time, or compare plugins between two applications.
Market Last
Created
ID Type Name place Upgrade Cost Version Notes
Date
URL Date
10001 Application SUPPORT-
123
10002 User- SUPPORT-
installed 124
...
Download this worksheet at: jirastrategy.com/link/plugin-tracking. Use the code in the

Comparison Recommendations
You can make an informed decision once analysis of both applications (or one application vs the JIRA
default) is complete.
RECOMMENDATION
Decide which application is better on a line item basis. At first glance, you may be tempted to
retain the instance with the best hardware or the best database. It's only the "best" if it's
stable, well maintained, and likely to remain in inventory for the long term.
RECOMMENDATION
Carefully consider the big differences between installations. (Example: Cloud vs Server, local vs
delegated authentication, differing versions, etc.) Consider features and connections that must
be retained. Don't retain or migrate old data and configurations you don't need.

RECOMMENDATION
Consider who is best equipped to make and execute merge and migration decisions. Keep
emotion or loyalty to one system out of the decision process. The end goal should be to create
the best overall environment and experience for your users.
RECOMMENDATION
Consider how merging data from another system might clutter the cleaner system. Are there
clean up actions to perform on both applications before the merge? Are there changes to make
for an easier migration? (Example: Syncing application versions, or making the list of Statuses
match.)
Take the best aspects of each instance and incorporate them into the new, go forward, set up.
Start Over
You may need to convince your organization that starting over is smarter than fixing your current
application issues. What might you gain by starting over? Think about how much time or money
could be saved. How would administrators and end users benefit? Here are some talking points for
your proposal (pros) as well as challenges (cons) to consider.
Pros and Cons of Starting Fresh

PROS
Reduce the size of your • Leave old, unused projects behind
instance
• Leave closed issues or unlikely to be worked issues behind
• Regain attachment or database storage space

Revamp your usage or • Leave past configuration mistakes behind
configuration strategy
• Ditch needless customizations and use standard features instead
Refresh the technology • Escape old log errors or corruption
• Ditch database tables created by old or unused add-ons
• Update the database schema to the latest standard
• Upgrade the database version or change database types
• Upgrade the application version

Clean up user access • Leave inactive users and their assets (e.g. saved filters) behind
• Ditch un-maintained groups

Restart issue numbering • Example: The next ID starts at ISSUE-1, not ISSUE-1058741.
CONS
Resistance to change • Users are sometimes resistant to change, even when it's needed
• Users battle fear of the unknown, loss of access, or loss of access

to data
• Decision makers are apathetic or daunted by the scope of the task

Storing existing data • Access to existing data as a historical record
• Old data in one system, new data in a different system

Licensing and support • Multiple instances may temporarily (or permanently) increase
license costs
• Multiple instances will require additional storage, hardware,

resources, administrative support, etc.
User impact • Users may experience downtime
• Users may need to adapt to a different environment
• Users may require re-training
Expert Assistance
Starting over or merging applications is no small task. How you proceed with the data you've
collected and knowledge you've gained through the exercises above depends greatly on the specifics
of your setup and needs. The actual process is challenging and different for everyone. As such, I
can't provide a universal recommendation for how you should do yours. Instead, this is an excellent
opportunity to engage an Atlassian Expert partner. Read more about expert assistance in the
"Atlassian Experts" chapter.

Part 4: Maintenance
A maintenance strategy and proactive action is essential to a healthy application. In part 4, let’s set
up a maintenance plan, prepare for upgrades, and discuss ways to monitor and report on progress.
User Communication
Good and early communication is always best. Use the examples below to create a library of
maintenance messages for common scenarios. Afterward, you can quickly post alerts and send vital
information to your user base.
Announcement Banners
The easiest way to communicate with users is through the built-in "Announcement banner"
functionality. Set a banner from the "System" admin menu. Here are some banner examples for
common situations along with some code snippets (for use with the Server application type).
WARNING
Always test your code outside of JIRA and be sure to close all markup tags. If pages render
incorrectly due to code errors, remove the banner code from the database. See the instructions at:
jirastrategy.com/link/remove-banner.
MISTAKE
One day while I was editing an announcement banner, my cat jumped onto my keyboard and
submitted half written code! He’s submitted or edited JIRA issues in the past but his careless
paw placement this day really caused a problem. All the end user and admin pages failed to
render content! I had to stop the application, remove announcement banner records in the
database, and restart JIRA. Luckily, this happened in a development instance where I’m the
only user and the only human inconvenienced. The cat and I have since had a chat about his
work performance.
Planned Maintenance
<div style="border: 1px solid #b46800; background-color: #fff; padding: 10px;">

<b>Maintenance Outage</b><br />JIRA will be down on [day], [date], starting at [time]
[timezone], and lasting approx [number] hours. Thank you for your patience while we perform
standard maintenance.</div>
Emergency Maintenance
<div style="border: 1px solid #000; background-color: #f00; padding: 10px; color: #fff">
JIRA will be down for critical server patching today, [date]. The outage will start at approx
[time] [timezone] and last for approx [number] minutes. During this time, the application
will be unavailable. Thank you for your patience while this important security update is
applied.</div>
Image: Sample Urgent Banner Message
Procedure Change
<div style="border: 1px solid #27798d; background-color: #fff; padding: 10px;">

<b>Changes to Approval Procedure</b><br />The "Approval" transition buttons are now hidden
for most users. <a href="[link]" target="_blank">Read announcement</a></div>

<b>Status Clean Up</b><br />We're cleaning up our statuses! <a href="[link]">Read more</a>
about the impacted projects and personal or shared filters you may need to update after the
change.</div>
<div style="border: 1px solid #000; background-color: #C5E3BF; padding: 10px;">

<b>New JIRA Plugin Added:</b> Is there a procedure you repeat often? Speed it up with bulk
sub-task creation! <a href="[link]" target="_blank">Read more</a></div>
Image: Sample Plugin Addition Banner Message
Training

<b>JIRA Training</b><br />The next "Intro to JIRA" training session will be on [day], [date]
at [time] [timezone]. <a href="[link]">Read more</a></div>
Upgrade
<div style="border: 1px solid #9e1c1c; background-color: #fff; padding: 10px;">

<b>Upgrade Outage</b><br />The upgrade will start on [day], [date] at [time] [timezone] and
conclude before the start of business on [day], [date]. During the upgrade window: (1) you
<b>WILL NOT</b> be able to login to JIRA, (2) any changes attempted <b>WILL NOT</b> be
retained, (3) API calls will fail, and (4) issue creation via email will fail. For a list of
new features and fixes, see our <a href="[link]" target="_blank">JIRA Upgrade</a> notes.
</div>

Image: Sample Upgrade Outage Banner Message
Additional Examples
• See an additional upgrade notification template in the "Upgrade Wording" section.
• See a conditional (project-specific) notification code example in the "Hacks" chapter.
Application Tracking and Statistics

How many users, issues, and projects, do you plan to have next year? What is the expected percent
of annual growth? What hardware or human support will be required? Tracking and analyzing your
application statistics can help you predict and plan for growth. The number of users and the amount
of content, logs, add-ons, indices and caches influences the overall size of your application.
Additionally, each user has their own custom dashboards, filters and boards, which increases data
size.
RECOMMENDATION
Compare your numbers over time by periodically taking a snapshot of your application and
database statistics. You can take a screenshot of the "System Info" page in the admin area or
an export of the counts from your database. Alternatively, you can take a virtual snapshot,
backup a copy, or clone your entire system.
RECOMMENDATION
Install a local version of JIRA that you never modify so you always have a way to compare the
default setup to your own. Alternatively, a version-specific default setup reference is available
at: jirastrategy.com/link/clean-instance . Use the code in the “Worksheets, Templates &
Companion Materials” section to download it for free.
Worksheet: Use and Future Predictions
Use the admin area and database to obtain counts in each statistic area below. Pay particular
attention to your largest database tables. Make a prediction for what type of growth or decrease
to expect. Include any additional information or factors influencing the data. Include
instructions to easily get to the data again (a URL, sample query, etc.) Link any JIRA issues filed
in response to a prediction. Example: Increase limits on attachment storage space.
Repeat this effort quarterly or semi-annually, as needed by your growth rate.
Key: ↑ = increase, ↓ = decrease

% % Q4 Pre
Statistic Q1 Q2 Q3 Notes
Change Change diction
Issues 623, 660, ↑ 6.02 700, ↑ 6.06 6% As shown on the
165 679 716 increase "System Info" page
every 3 or with the query:
months. SELECT count(*)
42K new FROM jiraissues
issues
are
expected
each
quarter.
Projects
Custom
Fields
Workflows
Attachments
Comments
Users Consider users who
are reading data vs
users who are
adding and editing
data. Consider
"jira-core-users" vs
"jira-software-
users."
Groups
Database GB GB GB
Size
Table Count Table counts can
fluctuate based on
upgrade and plugin
install activity.
Table: Rows: Rows: Rows: The changeitem
changeitem MB: MB: MB: table stores change
history records for
each issue.
Table: Rows: Rows: Rows: The jiraaction table
jiraaction MB: MB: MB: logs user action,
types, and content.

Table: Rows: Rows: Rows: The jiraissue table
jiraissue MB: MB: MB: contains all issues
and basic data, like
status, reporter,
components,
watchers, etc.
Table: Rows: Rows: Rows: The
customfield MB: MB: MB: customfieldvalue
value table includes text
and date entries
associated with
custom fields.
Plugins Count: Count: Count: How many plugins
Rows: Rows: Rows: are installed and
MB: MB: MB: how much database
space does that
represent?
Log Size
Index Size
Cache Size
Download this worksheet at: jirastrategy.com/link/future-predictions. Use the code in the

Re-index
JIRA creates an index of field data to return search results faster. A re-index is recommended after
major data or configuration changes or if the index is corrupt. When you need to re-index, the
following message appears at the top of any JIRA Admin page:
"We recommend that you perform a re-index, as configuration changes were made to 'Custom Fields'
by [username] at [timestamp]. If you have other changes to make, complete them first so that you
don't perform multiple re-indexes."
Re-index Triggers
The following actions trigger the need for a re-index:
• New custom fields and field configuration changes
• Plugin installation
• Manual entry of issues or manual changes in the database
• Search queries returning incorrect results
• Index file corruption
A re-index can take seconds or hours to complete, depending on the amount of data, server
capabilities, and the method.
Types of Re-indexes
1. Lock JIRA and rebuild index
▪ With this method JIRA will be unavailable to users until the re-index completes. It is
the fastest to complete, however it cannot be canceled once started. This method is
initiated from the JIRA administrative area.
2. Background re-index
▪ With this method, the application remains usable however, the re-index takes longer,
and users are likely to experience a performance impact. This method is also initiated
from the JIRA administrative area.
3. Re-index individual projects (Available in JIRA 6.2 and higher.)
▪ With this method, only a single project is re-indexed, not the entire database. This
method can be initiated from a project's administrative area.
RECOMMENDATION
Perform any re-index activities during periods of low usage.
RECOMMENDATION
When a re-index is needed, consider using a script to trigger it during the middle of the night.
RECOMMENDATION
Make re-indexing a standard part of your maintenance activities and upgrade plan. See the
"Scheduled Maintenance" and "Upgrade" chapters for more information.

Scheduled Maintenance
Completing regular, scheduled maintenance is important for a healthy application. Start by making a
list of all the necessary actions and needed frequency. Use the worksheet below for ideas.
Worksheet: Scheduled Maintenance
Use this worksheet to identify and document recurring maintenance activities. Select frequencies
that fit your specific needs and availability.
Item Frequency Notes
Upgrade JIRA 2 times a Upgrade JIRA to the latest stable version. See
year the "Upgrade" chapter.
Environment Data 3 times a Copy production data to the testing environment. This
Sync year can be done independently or as part of an upgrade event.
Plugin Quarterly Review new plugin requests. Remove expired or unused
Installs/Removals plugins. See the "Plugin and Add-on Vetting Procedure"
section.
Archival 2 times a Archive projects where issues haven't been created or
year updated in X days. See the "Archive" chapter.
Re-index Monthly Perform a re-index, if needed, to cover all the
configuration changes made during the month. See
the "Re-index" chapter.
Address Log Errors Quarterly Review the application error log and select one issue to
address.
Restart As Needed Restart the application or server when needed.
Admin User Audit Quarterly Review the application admin access list. Compare it
against previous audit lists. Make needed access
changes.
Check Incoming Quarterly Verify mail server connections. Verify mail handlers are
Mail Settings still needed.
Clear Tokens Monthly Clear tokens stored by the "Remember My Login" feature.
Run System Monthly Run the Integrity Checker and Health Check functions.
Checks Address detected issues.
Inactive Users Quarterly Deactivate users who haven't logged into the application
in X months.
Database Admin Quarterly Review the database admin access list. Compare it
User Audit against previous audit lists. Make needed access
changes.
Server Admin User Quarterly Review the server admin access list. Compare it against
Audit previous audit lists. Make needed access changes.
Database Contents 2 times a Review database contents. Look for extraneous data.
Audit year (Example: A table for an uninstalled plugin.) Verify
unexpected tables haven't been added and no malicious
data is stored.
Server Contents 2 times a Review file system contents. Look for files to delete,
Audit year move elsewhere, or skip during backup. Verify
unexpected files haven't been added and no malicious
data is present.
Review Support 2 times a Review, prioritize, and purge backlog items.
Backlog year
Review/Update 2 times a Examine automated test criteria. Look for data or
Automated Tests year application changes to address.
Record Stats 2 times a Compile a new set of application usage data points.
year See the "Application Tracking and Statistics" section.
Compile Annual 1 time a Record team stats and accomplishments. Use the data to
Report year create goals for the coming year.
Create Annual 1 time a Create issues for completion of all maintenance activities
Issues year for the coming year.
Recommendation: Create one maintenance issue.

Create one Sub-task per maintenance item. At the start
of a new year, simply clone all the needed issues in one
step.
Review Plan 1 time a Review and update this maintenance plan.
year
Renew License 1 time a Renew license and update the application license key.
year
Download this worksheet at: jirastrategy.com/link/scheduled-maintenance. Use the code in the
Support and Emergency Escalation

For events and emergencies that happen outside of normal work hours, consider creating a support
plan. Does the emergency support team know what to do and who to contact?
RECOMMENDATION
Create an "emergency" JIRA cheat sheet for after-hours support teams. Make sure the
information is easily accessible and prints on a single page.
Use this template to create your own.

Worksheet: Support and Emergency Escalation
What is JIRA?
JIRA is commercial software, used for issue tracking and project management.
At [company name], we use JIRA to:
• Schedule new projects
• Manage our project pipeline
• Report and fix bugs
• Triage issues
• Report time and monitor progress
• Track changes and tasks
• Keep an authoritative, historical, and legal record of what we’ve done
JIRA also integrates with other critical applications like: [application list]
Who Uses JIRA
JIRA is used primarily by: [list of teams and business groups]. We have approximately [user
count] users.
JIRA [is or is not] a customer facing application. The access URL is [URL].
Escalation Paths & Emergency Contacts
What team should be contacted?

Issue Contact Contact Details
Application is Down Systems Team Name, Phone, Email, IM
Application is Slow Network Operations Center
Emergency Maintenance JIRA Support Team
...
Emergency Instructions
Restart the application by: [insert specific instructions]
Restart the server by: [insert specific instructions]
Scheduled Maintenance
[Link to maintenance and upgrade schedule]
Stability Background
[Link to any previous emergency or performance issues]
Important Dates
[Link to event schedule]
Example:
Date Event Contact
Jan 1 Atlassian License Renewals Name
Jun 1 SSL Expiration Systems Team
Sep 10 Upgrade JIRA Support Team
Jun 30 Atlassian Training Classes Expire (1 class, 2 seats) Name
Download this worksheet at: jirastrategy.com/link/emergency-escalation. Use the code in the

Upgrade
JIRA SERVER ONLY
For most JIRA Server users, an upgrade is a major activity that requires carefully planning. What is
your upgrade plan? How will you prepare? How will you ensure success? How often will you
upgrade?
Use this worksheet to establish a road map and document past upgrade events.
Worksheet: Upgrade Roadmap and History
Upgrade Date Version Tracking Issue Notes

1/1/16 6.4 ISSUE-1 30% faster than the previous version.
6/1/16 7 ISSUE-2 Includes a change to the user-account
model.
... ... ... ...
When you upgrade: conduct research, install in a test environment, and test against your real data
set. When all is well, repeat the install and test process in the production environment then
communicate the changes to your users. There are five high level steps:

High Level Upgrade Plan
There are 5 main phases of an upgrade plan.
Step 1 Research
Conduct pre-upgrade change and compatibility research
Step 2 Pre-Upgrade Tasks (Test Environment)
Copy all production data to lower test environments

Remove unneeded add-ons, expired plugin trials, or other unneeded elements
Upgrade and test in the pre-production environment
Step 3 Upgrade Preparation
Line up resources, schedule production upgrade activities, and announce plans
Step 4 Upgrade Tasks (Production Environment)
Backup production data

Remove unneeded add-ons, expired plugin trials, or other unneeded elements
Update and test in the production environment
Step 5 Communication
Announce upgrade and communicate changes and benefits to users
RECOMMENDATION
Document and publish a static list of upgrade plans and activities. This is useful to your admin
team and/or your end users.
Detailed Upgrade Plan

A well-crafted plan can help ensure upgrade success. Use the template below to create your plan.
Customize it to fit your needs and environment. This worksheet may contain more or fewer steps
than necessary for your situation, but it gives you a great starting point. Don’t forget to update the
plan after each upgrade.
Worksheet: Upgrade Plan
Download this worksheet at: jirastrategy.com/link/detailed-upgrade-plan. Use the code in the

WARNING
Do not store the upgrade plan in JIRA, as it will be unavailable for extended times during the
upgrade.
Standard Regression Testing

A standard set of tests help you verify application stability after any major change. What common
things do you expect to always work regardless of the type of change? Use the worksheet below to
create a regression test plan.
RECOMMENDATION
Create a regression testing issue. Create one Sub-task per test point. Use the "Notes" and
"Testing Hints" as the Sub-task description. Each time regression testing is needed, just clone
the issues.
Worksheet: Standard Regression Testing
Here are some high-level tests, covering a broad area, to verify standard functions. Shorten the
list or add your own tests as needed. Don't forget to consider add-on or customization-specific
tests!
Category Test Notes
General Is login authentication completed External user management may need

quickly? to be enabled.
General Does a single issue load quickly? Review [issue ID].
Standard Issue Can a new issue be created or Retain the new issue for use in the
Operations cloned? "delete" action.
Standard Issue Can an existing issue be edited? Make a change in a custom date field.
Operations (This tests a field update, input
validation, and the picker UI all at
once.)
Standard Issue Can an issue be moved? Move [issue ID] to the [project]
Operations project.
Standard Issue Can an issue be deleted? Delete the issue from the earlier
Operations "create" action.
Standard Issue Can an issue be linked to another Link [issue ID] to [issue ID].
Operations issue?
Query Does a simple query return results? Example: created > startOfWeek()
Query Does a complex query return Example: status changed to "In
results in a timely manner? Progress" and timespent > 30m
Filters Do results from existing personal n/a
filters load?

Filters Do results from existing shared Review [filter URL].
filters load?
Filters Can new filters be created and Retain the new filter created for use in
saved? the "Dashboards" section.
Dashboards Do results from existing personal n/a
dashboards load?
Dashboards Do results from existing shared Review [dashboard URL].
dashboards load?
Dashboards Do gadget or data-intensive Review [dashboard URL].
dashboards load?
Dashboards Does the "Default System" Review [dashboard URL].
dashboard display properly?
Workflows Does a single item transition Transition an issue in the from
property? creation to completion.
Workflows Does a bulk transition complete Transition [issue ID] and [issue ID] to
properly? [status] status.
Workflows Does the Integrity Checker indicate Review the results and let the Checker
any problems? attempt to fix errors.
Permissions Are the intentionally restricted Test access to the [project name]
projects still protected? project.
Permissions Are protected transitions Test a transition button only visible for
functioning properly? a subset of users.
Mail Are issue update email notifications Was a notification received for the
Notifications arriving as expected? previous "update issue" action?
Mail Is the mail queue backed up or Verify at [admin page URL].
Notifications show errors?
Mail Are email issue create requests Verify that a message to [email
Notifications correctly processed? address] creates an issue in the
[project name] project.
Plugins Test of: [plugin name] List any specific features to verify.
Plugins Are there any unexpected Verify at [admin page URL].
messages on the Manage Add-ons
page? (Example: "Update
Available")
Attachments Are attachments present? Review [issue ID]. Verify [attachment
count] or more attachments exist.
Attachments Can new files be attached? Add a new attachment to [issue ID].
Connections Are connections to other Example: Review a Confluence page
applications succeeding? using the "JIRA Issues" macro.
Connections Can JIRA connect to the Atlassian Verify at [admin page URL].
Marketplace?
Logs What errors or issues do the log Which of the noted issues are new
files reveal? since the upgrade?
New Features Are problems presented by any Verify new features as an application-
new features? level admin, a project-level admin, and
as a regular user.
Reset Reset any issues or settings n/a
modified to their default state.
Delete any issues created for
testing purposes.
Other How is the system performing Are users reporting performance
under load? issues?
Download this list as an Excel file, which can be imported into JIRA, at:
jirastrategy.com/link/regression-testing. Use the code in the “Worksheets, Templates & Companion
Materials” section to download it for free.
Upgrade Wording
Create standard messages to save time and energy during an upgrade event. This also ensures a
correct and consistent message.
These sample snippets are listed in order of their execution in the Detailed Upgrade Plan
worksheet.
Pre-Upgrade Tasks (Test Environment)
REST API and Database User Notification
You are receiving this message because of your JIRA REST API or database use. We're
upgrading JIRA and need you to confirm that your integration works in the new version.
Please test your apps against our newly upgraded test environment at: [location]. The login
credentials are: [credential information].
Please also review the API documentation for JIRA version [number].
• [Insert link(s) to documentation]
We need to know:
1. Are any changes required for your application?
2. Have and integrations been added or removed since our last upgrade?
Thank you for checking,

The JIRA Upgrade Team
Upgrade Preparation
Identifying Resources
We're planning the next JIRA upgrade. Would you please identify a resource to assist on the
Upgrade Team? Add your resource details to the table below:

Resource Resource Contact
Area Needs (Day)
Name Details
Release Manager: Upgrade Preparation (Pre-Upgrade) [name] [phone, email, IM]
Upgrade Tasks (Day of Upgrade) ...
Communication (Post Upgrade)
Upgrade Team: Upgrade Preparation (Pre-Upgrade)
Upgrade Tasks (Day of Upgrade)
Emergency - On Call (Post Upgrade)
Database Team: Emergency - On Call (Post Upgrade)
Systems Team: Emergency - On Call (Upgrade
Window)
NOC Team: Emergency - On Call (Upgrade
Window)
Upgrade plan details are available at: [location]
Thanks in advance,
Upgrade Plan Review Meeting
This is the final review of the plan for the [date] JIRA upgrade event. Please review prior to the
meeting and bring your questions, concerns, or plan updates.
Conference Instructions:
Please call: [conference line]
Lockdown Calendar Reminder
Dear JIRA Admins,

Please refrain from making unscheduled configuration or re-index causing changes in the JIRA
environments (production or test) during the lockdown window noted below. This is to ensure
application integrity for the [date] upgrade.
Lockdown Window:
From: [date]
To: [date]
Also, please communicate this message to users with existing customization requests.
Thanks for your cooperation,

Upgrade Day Calendar Reminder
The JIRA upgrade to [version] begins [date] at [time]. We expect to complete the upgrade by
[time] that same day.
Please call: [conference info]
Upgrade Contacts:
Resource Resource
Area Needs (Day)
Name Contact Details
Release Manager: Upgrade Preparation (Pre-Upgrade) [name] [phone, email, IM]
Upgrade Tasks (Day of Upgrade) ...
Communication (Post Upgrade)
Upgrade Team: Upgrade Preparation (Pre-Upgrade)
Upgrade Tasks (Day of Upgrade)
Emergency - On Call (Post Upgrade)
Database Team: Emergency - On Call (Post Upgrade)
Systems Team: Emergency - On Call (Upgrade
Window)
NOC Team: Emergency - On Call (Upgrade
Window)
Status Check Calendar Reminder
Please join the upgrade conference line for a brief status check.
Outage Page Code
<div style="border: 1px solid #9e1c1c; background-color: #fff; padding: 10px;">

<b>Upgrade Outage</b><br />The upgrade will start on [day], [date] at [time] [timezone] and
conclude before the start of business on [day], [date]. During the upgrade window: (1) you
<b>WILL NOT</b> be able to login to JIRA, (2) any changes attempted <b>WILL NOT</b> be
retained, (3) API calls will fail, and (4) issue creation via email will fail. For a list of
new features and fixes, see our <a href="[link]" target="_blank">JIRA Upgrade</a> notes.
</div>

Communication to End Users
Pre Upgrade End User Notice
Dear JIRA Users,
Exciting news: a JIRA upgrade is on the way! The upgrade begins [date] at [time] and
concludes before the start of business on [date].
During the upgrade window:
1. you WILL NOT be able to login to JIRA,
2. any changes attempted WILL NOT be retained,
3. REST API calls will fail, and
4. issue creation via email will fail.
For a list of all the new features and fixes, please see our JIRA Upgrade notes at: [location].
If you have any questions or concerns, please contact the JIRA Upgrade Team at: [email
address].
Thanks,
RECOMMENDATION
Send this notification using JIRA's "Send E-mail" feature.
JIRA Help and Customization Request Response (Lockdown Period)
Thank you for your request. We are preparing to upgrade JIRA on [date], and as such, are not
making configuration changes from [start date] to [end date]. This is to ensure
application integrity. We'll address your request after the upgrade is complete and we're sure
JIRA is stable. Thanks for your patience.
RECOMMENDATION
Create a "lockdown" period of a week or more before your upgrade. Defer any configuration or
customization requests until after the upgrade event.
Communication to Support Teams (NOC, Help Desk, Systems, etc.)
Hello Support teams:

As announced, we are planning a JIRA upgrade that begins [date] at [time] and concludes at
the end of the day on [date].
Our users will experience the following:
• At certain times during the upgrade window, they are blocked from logging in.
o The error message reads "You do not have permission to login." See screenshot
1 below.
o Alternately, a user may also encounter an outage page. See screenshot 2 below.
• Even if a user is able to sneak a quick login, they can expect that any changes made
during the upgrade window will be lost.
• We expect data loss and disconnects from applications that connect through the JIRA
REST API or to the database.
• Finally, any issue creation attempts via email will fail as well.
If you have questions or concerns before or after the event, please contact the JIRA Upgrade
Team at: [email address].
During the upgrade window, you can contact the Release Manager: [name, email, phone, IM]
Thanks,
Image: Blocked Access Message

Image: Sample Outage Page Message
Upgrade Tasks (Production Environment)
Announcement Banner Code
<div style="border: 1px solid #000; background-color: #C5E3BF; padding: 10px;">

<b>The JIRA upgrade has been completed!</b> Please see the <a href="[link location]"
target="_blank">JIRA [version] Upgrade</a> notes to learn about all the new features and
fixes.</div>
Upgrade Status
It is JIRA upgrade day and the conference line is now open! Please join to report progress or
any issues encountered. You can follow upgrade line item completion from the upgrade plan
link below. Additionally, our chat room is open and located at: [location].
Status Call Reminder
Things are going well with the JIRA upgrade and we're on schedule. As planned, we have a
[time] check-in call to discuss status, findings, and plans for regression testing.
User Notification
Post Upgrade End User Notice
Dear JIRA Users,
The JIRA upgrade is complete! All the new features and fixes are in the JIRA Upgrade notes at:
[location]
Please report any problems by filing a JIRA issue or emailing: [email address].
This upgrade was no small feat! Special thanks to the JIRA Upgrade Team and everyone who
made this event possible. Your upgrade team: [names]
Thanks,
Upgrade Team Thank You Message
Dear JIRA Upgrade Team members,
Congratulations on the successful completion of another JIRA upgrade! We appreciate all the
time you spent, planning, testing, and executing this event.
Thanks,
[name]
RECOMMENDATION
Purchase an Atlassian-themed swag item for each upgrade team member as a small token of
appreciation. Visit: swag.atlassian.com
Download this wording at: jirastrategy.com/link/upgrade-wording. Use the code in the


Emergency Rollback
What would you do if an upgrade didn't go in smoothly? What if a feature you rely on wasn't
working? What if the app won't even start up? At what point is it smarter to "undo" the upgrade,
regroup, and try again? You should always have a backup plan. Use this worksheet to devise yours.
Worksheet: Rollback Plan
Hope for the best, but plan for the worst. Use the template below to create your emergency
plan. Customize to fit your needs and environment. Here's an example to get you started.
Primary Rollback Method

Findings and Depend
ID Item Notes Resource
Actions encies
Ex: Task name Implementation details Research ID # Name
x.x outcomes and
implications
1.1 Restore the • The production JIRA none Database
Database database is located at: Team
[location].
• A database dump CRON

job runs every day at
[time].
• The size of the dump is

[size] so the recovery
time is approx. [time]
minutes.
1.2 Restore the • The recovery plan is: none Systems
Application [insert details]. Team
1.3 Verify Complete the following 1.1, 1.2 Upgrade
Stability steps from the Upgrade Team
Plan:
• 4.3 - "Prevent Login"
• 4.6 - "Check Logs"
• 4.14 - "Perform
Production Environment
Regression"
• 4.19 - "Enable Login"
• 5.1 - "Notify Users"
Alternate Rollback Options
What would you do if your primary rollback plan failed? What other emergency restoration methods
are available? Use the worksheet below to record the options.
Worksheet: Alternate Rollback Plan
Option
Type Notes
#
1 Restore the Database from a Have files available and ready to restore the
Previous Dump, Restore Files previous installation, home directories and
from a Previous Snapshot database.
2 Use JIRA's XML Restore Option This method requires write permissions on the
production server.
3 Use XML Export/Re-Import This method requires write permissions on the
Backup production server.
Download these worksheets at: jirastrategy.com/link/rollback-plan. Use the code in the
REST API and Database Users

Upgrades and small changes to the JIRA configuration can impact other users and other applications.
Use this worksheet to compile a list of scenarios and functions others rely on.
Worksheet: REST API and Database Users
The following internal applications use the JIRA REST API or connect to the JIRA database. The
contacts need to be aware of upgrade activities and assist in testing their applications where
needed.
Download this worksheet at: jirastrategy.com/link/api-and-database-users. Use the code in

the “Worksheets, Templates & Companion Materials” section to download it for free.
New Feature List

Compile a simple report of all the new and interesting features so users don't have to read through
release notes, resolved bugs, and announcements. This compilation may already be available as
part of pre-upgrade activities.
RECOMMENDATION
Group new features by user type (e.g. end users, project administrators, application
administrators, and others). This allows users to skip straight to the info most applicable to
them.

RECOMMENDATION
Whenever possible, include a screenshot, from your instance, to visually show how the new
feature looks in the user interface.
Worksheet: New Features
Use the template below to communicate new and interesting features.
Introduction
Great news! On [date] we upgraded JIRA from version [version] to [version]! There are lots of
new features and fixes to improve your JIRA experience. Since our last upgrade, there were
maintenance releases to address bugs, performance, and stability issues. We upgraded many of
our plugins as well. See key features updates below.
User Features
The major new features for all users include:
Insert Feature Title
[screenshot] [feature description, link to documentation]
Project-Level Administrative Features

The major new features for Project Leads and administrators include:
Application-Level Administrative Features

The major new features for application administrators include:
Resources
Help
Have a question? Need help? Spot a problem?
Report issues in the "JIRA Support" JIRA project or email: [email address].
Additional Reading
Include a link to the upgraded version's release notes.
Include a link to the upgraded version's "What's New" video.
Training and Documentation

Include a link to all internal company JIRA training materials.
Upgrade Team
This upgrade was no small feat! Special thanks to everyone who made this event possible. Your
upgrade team:
Application Support Team Systems Team Database Team
[insert photo] [insert photo] [insert photo] [insert photo]
Manager of Internal Application Systems Database
Applications Administrator Administrator Administrator
Download this worksheet at: jirastrategy.com/link/jira-features. Use the code in the “Worksheets,
Automated Testing
How much time does it take to manually test the upgrade mentioned in the "Standard Regression
Testing" section? How much time does it take to manually execute recurring tasks mentioned in the
"Scheduled Maintenance" section? How many times per year do you perform these tests? It saves
time to automate tests that don't absolutely require a human to perform manually. There are plenty
of free and paid applications to automate web application tests. Start by asking your QA team what
they use for their automation needs. They may even be able to help you get set up with sample test
cases.
Automation Set Up
RECOMMENDATION
Create a specific "automation" user so you can track changes made as part of automated
testing.
In general, give this user the lowest necessary level of permissions. Depending on your testing
needs, this user may need admin privileges or need special permissions to specific applications or
projects. Also allow this user read-only access to the database, or business intelligence data, to run
queries.
RECOMMENDATION
Create a specific "AUTOMATION" JIRA project where all automated tests run. You avoid the
need to "undo" changes to real production data, confuse or spam your users, and manually fix
data for failed or incomplete tests.

Test Assets
In addition to a specific test user and test project, create the following assets:
• Sample issues with test data in standard and custom fields
• A saved personal filter, dashboard, and board
• Fill the dashboard with a mix of frequently used standard and add-on provided gadgets
• Create a workflow with standard functions and add-on provided functions
• Configure (or turn off) email notifications in this project
Write Test Cases
A test case for a manual test can be generic, like "Can a new issue be created?" The tester is free to
create any type of issue with any data they choose. A test case for an automated test, however, has
to be very specific. The instruction for the same test case is instead: "Create a new issue in the
AUTOMATION project, of type "Task," with the summary of "Automation Create Test."
Gather your lists of standard regression and scheduled maintenance test cases created in the
sections above.
Step 1: Determine which test cases are suitable for automation and which to manually run.
Step 2: Compile very specific instructions for each test case. Perform the test case manually to see
if you've neglected any necessary data (i.e. a required field.)
Step 3: Determine success criteria for each test. Under what condition does the software know the
test passed?
Step 4: Identify differences between environments. Can a test run the same way in production as
in the test environment?
RECOMMENDATION
For easy automated test maintenance, write test cases that can run the same way in multiple
environments. Use data that's common to both environments and likely to remain available in
the future.
Step 5: Determine the frequency of each test. How often does each test run and when does it
start?
Step 6: Create a final "clean-up" test to remove issues created during the testing process. "Reset"
any updated issues to their original state.
RECOMMENDATION
Don't let the final "clean-up" task run automatically. Manually “sanity” check” the results before
removing all the test data.
Worksheet: Automated Testing
List the standard regression and scheduled maintenance tasks suitable for automation below.
Here's a sample test plan to get you started.
Download this worksheet at: jirastrategy.com/link/automated-testing. Use the code in the

TIP
Add "Review/Update Automated Tests" to your manual maintenance "to do" list!
For additional automation materials, visit the JIRA Strategy Store at: jirastrategy.com/store.
Monitoring
Set up additional software to routinely check the health of your application and database. Monitors
and alerts help the admin team proactively maintain your application. Don't let end users be the
first or only source of trouble reports.
You can leverage monitoring that is likely already set up for other applications. Work with your
system and database administration team to determine the checks and thresholds appropriate for
your organization. Here are some sample checks to get you started.
Checks:
• The application is up and running
• The database is up and running
• HTTP redirects to HTTPS
• The monitor user can successfully login (authentication succeeds and account is not locked)
• HTTP and HTTPS SSL certificates are valid (not expired)
• The mail service is up and running
• The mail queue size is appropriate
• JIRA can connect to other Atlassian apps
• JIRA can connect to the Atlassian Marketplace
• JIRA can connect to the attachment storage location
• Server load levels are acceptable
• Network bandwidth use is acceptable
• Sufficient disk space and memory are available
• Active user, inactive user, REST API, and database connection levels are as expected

• User count is lower than the licensed level
• The license has not expired
• A backup file is present and is of the expected size
• Thread count is appropriate
• No slow queries are impacting the application
• The monitor user can successfully logout
• etc.
RECOMMENDATION
Ask your monitoring team to set up email alerts anytime an alarm is triggered. Even if you
aren't the person to address the detected problem, at least you can be aware that a problem
exists. Ask for notifications of the initial incident report and the system recovery report.
RECOMMENDATION
Brian Jones, Solutions Architect and Dallas, Texas AUG Leader, mentions that if you already
have Bamboo, you can use it to monitor other Atlassian tools. "Our IT Team takes a few hours
to notify us of an outage, so instead we use Bamboo plans to test up-time every 5 minutes. I
have a simple Perl script that will request the site. If it succeeds, the plan passes. If it fails, the
plan fails and notifies someone."
Worksheet: Monitoring
Use the worksheet below to determine and record your alert points.
JIRA Application
Hostname: [host address]
The [team name] monitors the JIRA application and performs the checks listed below.
The monitoring team contact is [name, phone, email].
The user account used to monitor JIRA is [username].

Check Details
Login The monitor user can successfully login (authentication succeeds and account is
not locked)
...
JIRA Database
Hostname: [host address]
The [team name] monitors the JIRA database and performs the checks listed below.
The database team contact is [name, phone, email].
The user account used to monitor the database is [username].

Check Details
Connection The application can connect to the database
...
Download this worksheet at: jirastrategy.com/link/monitoring. Use the code in the “Worksheets,
Incident Log
It's important to log incidents to create a reviewable history, detect patterns, and prevent similar
problems from occurring in the future.
RECOMMENDATION
Track the details of any application incidents (good or bad, planned or unplanned, critical or not)
to gain insights into patterns, performance, and stability.
One company had a recurring problem with re-indexing. Each time a re-index was
attempted, it brought the application down. Since there was no central repository for
recording the incident, the problem kept occurring. There was no effort to capture, share,
and learn from the cause of the problem, its frequency, and the steps taken to remedy it.

WARNING
JIRA shouldn't be your primary storage location for incident details. Downtime will make past details
temporarily unavailable.
Worksheet: Incident Log
Record as many incident details as possible to create a useful historical record. Provide links to
related documentation or trouble reports. Attach any relevant correspondence.
7:00
Date: 01/01/2000 Time: Duration: 10m
PM
Type: Security Severity: Critical Participants: Paul, Application
Administrator
Mary, Systems
Administrator
Title: Server patching caused restart of production server
Details: At noon, we became aware of a critical security patch for the server running
JIRA. [patch number, version] We applied and validated the patch in our test
environment. We scheduled the production change to occur during off-peak
hours, at 7:00 PM EST. This change was approved by the CTO via email.
Resolution: The JIRA server was stopped, the security patch was applied, and the server
was restarted again. The server came up as expected with no errors and
minimal impact to users.
Steps to n/a Root Cause: Out of date server
Diagnose: software.
Steps to n/a Follow-up Actions:
1. Audit operating
Correct:
system versions of all
production servers.
2. Review, test, and

apply critical patches.
3. Create a standard
maintenance
procedure to regularly
check and update
servers.
Download this worksheet at: jirastrategy.com/link/incident-log. Use the code in the “Worksheets,
Year-End Clean-Up
In addition to the regularly scheduled maintenance admin tasks, project and team leads should
regularly review and maintain their projects as well regularly.
Here are some good questions to ask project leads at end of each year (or even more frequently.)
Year-End Clean-Up Questions
1. Is the project still actively used?
2. Is the listed project lead accurate?
3. Are the Component values accurate and useful?
4. Are the Component leads accurate?
5. Are there any unreleased (overdue) versions?
6. Are there any issues that haven't been updated in X days?
7. Are there any unassigned issues or issues awaiting triage?
8. Should issues in the backlog be scheduled or closed?
9. Do team members need to be added or removed from the project?
10. Do shared filters, dashboards, or boards need to be deleted or updated?
11. Does the project's configuration still meet the needs of the team?
12. Are there any special features or customizations you wish your project had?
Year-End Analysis
At the end of each year, it's helpful to record JIRA Support team activities and accomplishments.
This simple action can boost team morale, illuminate recurring issues, help predict future needs, and
determine the road map for the coming year.
Year-End Analysis Questions
1. What major activities occurred?
2. Who participated in the activities?
3. What volume of work did the team accomplish?
▪ How many issues were addressed?
▪ How does the total compare to the previous year?
▪ What types of issues were addressed?
4. How satisfied are end users?
▪ How speedy were requests addressed?

▪ How well were solutions communicated?
▪ How satisfied are end users overall?
5. What were the top accomplishments?
▪ What upgrades or performance improvements were made?
▪ What standard maintenance was performed?
6. What are the top opportunists for next year?
7. What is the roadmap or goals for next year?
8. What data was used to compile this report?
Worksheet: Annual Report
At the end of each year, compile a report of the support team’s accomplishments. Use this
worksheet to compare actions over time and set goals for the coming year.
About the Products
The Atlassian products we use at [company name] include: [list of products]. Support for these
applications is tracked in the JIRA Support project.
About the Support Team
The Atlassian products are supported by members of the [team names].

Application Support Team Systems Team Database Team
[insert photo] [insert photo] [insert photo] [insert photo]
Manager of Internal Application Systems Database
Applications Administrator Administrator Administrator
Support Stats
All stats are as of: [date]
The team completed [total completed] ([percent]%) of [total reported] issues created in [year].
At present, [total] are awaiting triage, [total] are awaiting initial progress, and [total] are being
actively worked. [total] are in the backlog.
Include an Issue Statistics chart, showing the count of issues reported above.
Include any commentary explaining:
• high or low numbers in any category
• performance changes since the previous year
• external factors influencing the totals
Example: This year we added a new team member and were able to complete 50% more
requests than in the year before.
Issue Statistics
Chart Area
[insert Issue Types
chart] We use "Issue Types" to track the type of request.
Our largest type is [type name]. This type is used for [use] and represents
[percent]% of requests.
Example: The general "Task" type represents our largest type (61%.) Since this is
our general "catch all" bucket, users often select it even when a more specific type
is appropriate.
Our second largest type is [type name]. This type is used for [use] and
represents [percent]% of requests.
Include any commentary explaining opportunities for improvement in the upcoming

year.
Example: Better classification of requests filed in the general "Task" type is a user
training and team admin improvement opportunity.
[insert Components
chart] We use "Components" to track the type of support for the request.
Our largest component is [type name]. It is used for [use] and represents
Example: 40% are "Helpdesk" requests which include user access, password reset,
or troubleshooting types of tasks.
Our second largest component is [type name]. It is used for [use] and represents
Include any commentary explaining the numbers or opportunities for improvement

in the upcoming year.
Example: An enhanced focus on application stability in there previous year lead to

a low issue count in the "Application" category
[insert Resolution
chart] We use the "Resolution" standard field to track what action was needed.
[percent]% of requests required action.
[percent]% of requests required no action. (Example: Request was invalid, a

duplicate, not reproducible, or worked as designed.)
Include any additional supporting details.

[insert Other
chart]
Include any other relevant issue data.
Customer Satisfaction
Include any available customer satisfaction details or comments received.
Example: 57% of survey respondents rated our time to resolution as "Awesome."
Example: "Thank you all for completing the recent JIRA upgrade! My team is so excited to use
the new Releases feature to see the health of our current sprint. - James Smith, Development
Manager, January 2, 2016
Team & Individual Performance
If available, provide team performance metrics, like overall time to resolution. If appropriate,
provide individual performance metrics, like items resolved per team member.
Example: Our top performer was [name] who completed 36% of requests and received the most
praise from end users.
Top Accomplishments
Include 3-5 completed initiatives, things the team did particularly well, or milestones reached in
the current year.
Example: We executed a plan to detect and archive inactive projects. This resulted in a 20%
reduction in scheme count and a 32% reduction in database size.
Top Opportunities for Improvement
Include 2-3 areas to improve.
Example: The JIRA Support team needs to establish team goals, regularly review progress, and
start using JIRA Service Desk to better track SLAs.
Roadmap
Set approximate dates for completion of goals and needed activities.
Example:
Completion Target Project, Goal
January Upgrade JIRA
February Deliver JIRA Training for New Employees
All Year Continued Standard Maintenance Activities
See the "Scheduled Maintenance" section.
All Year Continued Support of Daily User Requests
Queries and Sources
Include the JQL or database queries used to compile the above information. Include links to
dashboards or supporting resources.
Download this worksheet at: jirastrategy.com/link/annual-report. Use the code in the “Worksheets,
Part 5: Customization
Part 5 shows ways to customize JIRA so it functions exactly as you need it to. In this section, let’s:
• Set up a plugin selection process so you can make smart decisions about additional features
to install
• Discuss ways to extend JIRA
• Explore a few non-standard ways to use the application
Plugins and Add-ons

There are a plethora of plugins and add-on features available in the Atlassian Marketplace. Visit:
marketplace.atlassian.com. But haphazard installs and free trials can leave behind remnants that
negatively impact the system after the trial ends. You should develop specific procedures for
handling add-ons and customization requests. The procedure should include pre-installation vetting,
installation and trial testing, and uninstall procedures to ensure system functionality and stability.
Best Practices
DO
• Communicate the request process, testing procedure, and other expectations to the
requestor. See the "Plugin and Add-on Vetting Procedure" section. Verify add-on funding
is obtainable or available before installing and testing.
• Involve the requestor in the testing process.
• Always thoroughly test a plugin in a non-production environment first.
• Test against your issue and configuration data.
• Simulate load if possible.
• Check for items left behind after an add-on is uninstalled. Example: Custom fields or
database tables.
• Consider the impact a new add-on has on your maintenance and upgrade procedures.
• Record the add-on request (and vetting results) as you would for any other application
change request.

DON’T
• Install add-ons that duplicate standard product functionality.
• Install more than one add-on at one time, or make major configuration changes before plugin
testing is complete. This makes it hard to isolate the cause of any issues encountered.
• Consider a plugin that doesn't appear well supported or maintained.
Daniel Wester, Chief Product Architect at Wittified Atlassian Add-Ons (an Appfire Company), shares
"as you evaluate add-ons, make sure to review the entire Marketplace entry. Look at the licensing
agreement and the support hours. If there is an issue tracker look through it for activity as well as
general maintenance items. Even if you're comparing a free add-on versus a paid add-on the free
one can become expensive if it's not supported."
Vet Plugins and Add-ons

Worksheet: Plugin and Add-on Vetting Procedure
Post this procedure so end users understand the request process and are prepared to assist with
testing.
Would you like to install an add-on or plugin? Here's an outline of the request procedure.
ID Procedure Responsibility
Step 1 Request a test of the add-on. File an issue in the JIRA • Requestor
Support project. In the issue description, tell us:
• The name of the add-on.
• The plugin's Marketplace URL.

The JIRA Support team will: • JIRA Support Team
1. Ensure the add-on is compatible with our

application type and version.
2. Record the cost for our license level.

Step 2 Get preliminary approval from requestor's leadership. • Management
(There's no sense testing an add-on we can't afford.) If
the test is successful, is leadership prepared to make a
business case and obtain the needed annual funding?
Step 3 Install the add-on in a test environment. • JIRA Support Team
Step 4 Test the add-on, using the pre-defined vetting procedure. • Requestor
(Shown below.)
• JIRA Support Team
For an example, see the results from a previous test here:
[insert example]
Step 5 For successful tests: Obtain a license and make plans to • Management
install in production.
For unsuccessful tests: Uninstall the plugin from the test
environment.
Plugin Installations
Did a user request an add-on installation? The initial step is researching the add-on and answering
the following questions.
Plugin Research
You can begin your research by asking the following questions. Enlist the help of the requestor
where possible.
1. What does the add-on do?
▪ How will it be used at our company?
▪ How many users can use it?
▪ How often will it be used?
▪ Does JIRA already have a standard mechanism (or already installed add-on) to
accommodate the requested feature(s)?
▪ Are there alternative similar add-ons?
2. Is the add-on compatible with JIRA?
▪ Is it compatible with the current JIRA version?
▪ Is it compatible with cloud or server?
▪ Are there any compatibility issues with other installed plugins?
3. Are there any external or internal dependencies?
4. Is the add-on created by Atlassian (a trusted source) or an external source?
▪ What information is available about the external source?
▪ Is contact information available?
▪ Is installation or post-install support available?
5. Does the add-on appear well maintained?
▪ What is the current version number?
▪ What is the date of the most recent update?
▪ How often are updates available?
▪ Do updates appear ongoing?
6. Is the add-on widely used?
▪ Are there favorable reviews?
▪ Do the favorable reviews appear legitimate? Are they written by users, or by the
plugin authors?
▪ Do reviews and support issues mention bugs, performance, or security problems?

7. What is the price and renewal requirement for the license level?
▪ Is there a free trial?
8. Who can help test the plugin? Include the requestor, end users, and application admin users.
9. Does enough (and the right kind of data) exist in the test environment to test the add-on?
RECOMMENDATION
If possible, conduct a code review for add-ons.
Installation Testing
DO
Install and test all add-ons in a test environment first. After installation, explore the following:
1. How does this installation fit into the application upgrade and maintenance schedule?
2. Does the add-on do what's advertised or meet our expectations?
3. Does the add-on behave in an intuitive and usable way?
4. Are there browser incompatibilities?
5. Does this add-on have a feature which could be used maliciously?
6. How did the add-on impact performance? Specifically check UI load times, especially for large
instances.
7. Are errors present in the logs?
8. [Additional add-on test cases]
Trial Testing (If applicable)
If a plugin offers a trail installation then give it a shot. Make sure you run your tests in a test
environment. Keep in mind that trial installations require special attention especially because a
date-based deadline exists. In some cases, vendors and Atlassian experts can extend the life of the
free trial to allow for further testing. Make note of the following:
1. When does the trial begin?
2. When does the trial end?
Uninstall Plugins
Once the free trial or your testing is complete, whichever comes first, remember to uninstall plugins
you have no intent to purchase. This frees up system resources and use of assets (e.g. add-on
specific data storage, logging, custom fields, etc.)
Add-ons should be uninstalled when they are:
• Malfunctioning
• Unmaintained
• No longer used
• No longer meeting needs
• No longer funded
RECOMMENDATION
Before uninstalling an add-on, check for data archival or backup opportunities. After, identify
which assets to manually delete or change. E.g. add-on specific data storage, logging, custom
fields, etc.
Worksheet: Plugin Vetting
Download vetting questions and sample results at: jirastrategy.com/link/vetting-procedure.

Use the code in the “Worksheets, Templates & Companion Materials” section to download it for
free.
RECOMMENDATION
Always check whether add-on features already exist as a standard application function.
Worksheet: Plugin Installation Announcement
Use this worksheet to announce a production install. Communicate what the new add-on does,
how to use it, and how to get additional help.
New JIRA Feature: [plugin title]
[short introduction] In a couple sentences, what does the add-on do? Who can use it? When
was it installed? Who are the testers? What is the procedure for requesting other new add-ons?
[screenshot]: Add one screenshot that encompasses the capabilities of the add-on or the easiest
way for users to access the features.

Capabilities and Access Points
For Users [features available to all users]
For Project-level All of the above plus:
Administrators
[features available to project-level administrators]
For Application-level All of the above plus:
Administrators
[features available to application-level administrators]
Examples
[screenshots and examples of the add-on in action] How is the add-on used?
Use Case: [use case specific to your organization]
Caveats and Bugs
[known caveats or bugs uncovered during vetting] Link to existing bug reports so users can
follow fix progress.
Resources
• Plugin Details: [marketplace URL]
• Documentation: [URL]
• Bugs and Feature Requests: [URL]
[links to internal resources] Where can internal help be obtained? Repeat the procedure for
requesting new add-ons.
Read more about Atlassian's verification program at jirastrategy.com/link/atlassian-verified

and jirastrategy.com/link/cloud-verification.
Noteworthy Add-ons
Here's a collection of loved add-ons to make your job easier.
1. ScriptRunner for JIRA

by Adaptavist
"Enhance and automate JIRA workflows, JQL functions, custom fields, listeners and more
using Groovy"
Visit: jirastrategy.com/link/scriptrunner
This is an amazing collection of automation processes, administrative functions, and scripts.

End users get extra JQL functions, like the ability to search for issues with comments,
attachments, and more. See sample uses in the following sections: Bulk Updating
Resolutions, Duplicate Elements, Former Employee clean up Procedure, Sync Data with
JIRA, and Make a Field Read Only.
RECOMMENDATION
Eric Lemay, JIRA Administrator and Montreal, Canada AUG Leader says: "ScriptRunner for JIRA
opens doors! When I started I couldn't program anything, but with practice, I discovered that I
can automate ANYTHING with this plugin! Also the user impersonation feature is an invaluable
tool for testing configuration changes from the end user standpoint."
2. Bob Swift Atlassian Add-ons (an Appfire company)

Visit: jirastrategy.com/link/bob-swift
Bob Swift Software (an Appfire company) crafted an impressive suite of add-ons for JIRA and
other Atlassian applications. I haven’t met one I didn't like or see a need for. Got a problem?
There's probably a Bob Swift add-on to solve it. I specifically like:
JIRA Command Line Interface (CLI)

"Rich CLI client. Enhanced actions. Deep automation. Ultimate control"
Visit: jirastrategy.com/link/cli
See a sample use in the Duplicate Elements section.
Recommendation: Brian Jones, Solutions Architect and Dallas, Texas AUG Leader
says: "The JIRA CLI tool is the best thing ever! Whether it’s for scripting routine tasks
or importing data, it’s a great tool from Bob Swift."
Run CLI Actions in JIRA

"Execute powerful CLI automation. Right within JIRA"
Visit: jirastrategy.com/link/cli-actions
Create on Transition for JIRA

"Automatically create new 'context-rich' JIRA issues or sub-tasks, right from your
workflow...no coding required!"
Visit: jirastrategy.com/link/create-on-transition
Update on Transition for JIRA

"Update existing JIRA issues using powerful workflow functions"
Visit: jirastrategy.com/link/update-on-transition
3. JIRA Misc Workflow Extensions
by Innovalog
"Workflow conditions, validators and post functions that you can use to implement custom
workflows in JIRA"
Visit: jirastrategy.com/link/jira-misc-workflow-extensions
I simply cannot live without the validators and post functions this amazing plugin provides.
From requiring a comment, to dynamic issue assignment, to auto transitioning other issues -
this plugin has it all. See sample uses in the following sections: Sample Workflow: JIRA
Support, Sample Workflow: Asset Management, Standard Validators, Additional
Validators, Auto Transition Parent Issue, Prevent Child Issues, and Prevent Child Issue
Progress.
4. Quick Subtasks for JIRA

by hasCode.com
"The Quick Subtasks Plugin for JIRA allows you to create multiple sub-tasks using a simple
text syntax"
Visit: jirastrategy.com/link/quick-subtasks-for-jira
This plugin is a great time saver for performing repetitive tasks. Create multiple sub-tasks in
bulk with one action from a template in your user profile, a template in a JIRA project, or a
text file on your computer.
This plugin was used as an example of the Plugin and Add-on Vetting Procedure. Download a
review at: jirastrategy.com/link/quick-subtasks-for-jira. Use the code in the “Worksheets,
5. JIRA Toolkit Plugin

by Atlassian
"Group issues by participant, highlight pending issues, and find high traffic issues"
Visit: jirastrategy.com/link/jira-toolkit-plugin
I especially love the "Message Custom Field" feature. It's a great way to provide users with
instructions on a create, edit, or transition screen. See sample uses in the following
sections: Sample JIRA Support Project Set Up, Message Custom Field, Add User Instruction,
and Add User Instruction Based on Issue ID.
6. Suite Utilities for JIRA

by beecom
"Additional workflow conditions, validators and post functions. A transition summary tab and
custom fields for Google Maps locations"
Visit: jirastrategy.com/link/suite-utilities-for-jira
This plugin lets you do more with workflows. I specifically like the ability to update custom
fields during a workflow transition. See sample uses in the following sections: Sample
Workflow: JIRA Support, Sample Workflow: Approval, Additional Conditions, Additional
Validators, Additional Post Functions, and Duplicate Elements.
TIP
Some plugins come pre-installed in Cloud environments. You may need to enable them from your
"Manage add-ons" admin page.
Extend JIRA
As if JIRA wasn’t robust enough, there are additional ways to extend its functionality. For example,
you can use built-in features to intercept data from email or a web form, connect JIRA with other
applications, and use integration or marketplace (marketplace.atlassian.com) add-ons. Additionally,
you can write your own code or full application. There are endless ways to get data into, out of, or
in sync with JIRA. Here are a few:
Get Data into JIRA
Method 1: Use the built-in “Issue Creation via Email” feature
Objective: Auto-create JIRA issues from email

Use Cases: • Create support requests from external sources
• To track non-JIRA users, contractors, etc.
• To track helpdesk functions
• To report JIRA access issues. For example, if a user can't login, they may
not be able to raise a JIRA issue.
Benefits: • Subsequent email messages append as comments
• Emails automatically attach to the issue
• The email subject becomes the issue's "Summary" and the email body
becomes the "Description"
Requirements: • Access to JIRA’s Admin UI
• A POP or IMAP email address

Sample Use:
Copy: Email Content Image: Resulting JIRA Issue

From: Rachel Wright
Subject: Test Message
This is a test message. If all is well,

this message will result in a new issue
in the DEMO JIRA project. Any
attachments in the email will also be
attached to the JIRA issue.
No need to respond to this message.

It, and the resulting issue in JIRA, can
be deleted.
Thanks,
Rachel Wright

NOTE
The “Issue Creation via Email” feature is simplistic. You cannot populate custom fields (including
required fields), pass a default summary, or set a specific assignee. It's a quick way to get data into
JIRA but not a substitute for the feature-rich issue create action.
Worksheet: JIRA Issue Creation via Email Instructions
You can create JIRA issues via email! Here are the steps.
Step 1: Set up the email address on the mail server

Please coordinate with the corporate email team.
1. What is the desired email address?
▪ This address must be on an internal domain. No external (gmail.com) addresses

should be used!
▪ To avoid spam (and spam issue creation), use a non-guessable address.
o Good example: teamname78462@company.com
o Bad example: technology@company.com
2. Configure the address to accept external email traffic.
3. Configure the address with a password that doesn't expire. Otherwise, JIRA auto-
creation breaks at each password reset interval.
4. Get the mail server's host name, as well as the addresses' username and password from
the email team.
5. Determine who should have access to this mailbox.
▪ What type of access is needed? Example: read emails, full access, "send as,"
etc.
6. Should this address forward mail to any other addresses?
7. What is the retention policy? Example: When can emails older than certain age be
deleted?
Step 2: Set up the email address in JIRA

Please coordinate with the JIRA Support team.
1. Create a JIRA Support issue with the email address from Step 1.
2. Call [phone number] to provide the username and password. For security reasons, don't
enter the password into the JIRA issue!
3. What JIRA project will issues be created in?
4. What issue type should be created? (Choose a type currently used in the specified JIRA
project.)
5. What is the mail server's host name? (See item #4 in Step 1.)
6. Who is the default reporter for new issues? (This can be any existing JIRA user.)
Documentation: jirastrategy.com/link/create-by-email
Download this worksheet at: jirastrategy.com/link/creation-via-email. Use the code in the

Method 2: Use the built in “Issue Collector” feature
Objective: Auto create issues with the JIRA Issue Collector

Use Cases: • Same as the email method above
• Embed a web form in your website or in other applications

Benefits: • Better control of the data submitted from external sources
• Additional customization options

Requirements: • Admin access to a JIRA project
• Ability to embed pre-written HTML or JavaScript into another application

Sample Use:
Atlassian uses JIRA to track interest in their User Group leader positions. Each submission from the
form on their website automatically creates a new JIRA issue.
Image: Issue Collector

You can customize the look of the button, its location on the page, and its label, within the JIRA
Admin UI.
Ideas for Use:

• Collect website feedback from your customers.
• Display the form only to internal users, for bug reporting.
• Initiate support tickets.
Step 1: Set up issue collector

Click the "Issue collectors" link in a project's administrative sidebar. Next, create a new Issue
Collector with the desired settings.
Step 2: Add code snippet to application

• Paste the code snippet into your external application.
• The code provided includes the URL of your JIRA application and a unique number identifying
the specific issue collector.
Sample Code:
<script type="text/javascript"
src="https://[JIRA URL]/s/d41d8cd98f00b204e9800998ecf8427e/en_US7gux2l-
1988229788/6158/35/1.4.1/_/download/batch/com.atlassian.jira.collector.plugin.jira-
issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-
issue-collector-plugin:issuecollector.js?collectorId=[collector ID]"></script>
Step 3: Customize the issue collector

a. Show or hide fields on the create screen.
b. Request entry of a name and email address. If the reporter is a logged in JIRA user, they will
be automatically recognized.
c. Collect the user’s browser details and URL where the feedback was created. (optional)
Documentation: jirastrategy.com/link/issue-collector and jirastrategy.com/link/issue-collector-

advanced
Method 3: Use easy “HTML links” to ease the issue creation process
Objective: Auto-create issues via an HTML Link

Use Cases: • Same as the email method above
• Add a link in your website or in other applications

Benefits: • Let users skip selection of the correct project and issue type
• Collect and pass default data

Requirements: • Access to JIRA’s Admin UI or database (to obtain project and issue IDs)
• Ability to write and embed HTML
Sample Use:
Step 1: Get Project, Issue Type, and Custom Field IDs

• In the Project’s Admin area, hover over the “Edit Project” button to see the project's ID in
the browser’s status bar.
• In the Issue Types Admin area, hover over the “Edit” link to see the type's ID in the
browser’s status bar.
• In the Custom Fields Admin area, hover over the “Edit” link to see the field's ID in the
browser’s status bar.
TIP
You can easily obtain all project, issue type, and custom field IDs from the database.
Step 2: Write HTML and Embed as Desired

• Construct your link with the Project ID and Issue Type ID, as shown in the "simple"
example below. Additionally, you can pre-populate any other field values, as shown in the
"complex" example.
o Simple Link Format:

<a href="https://[JIRA URL]/secure/CreateIssueDetails!init.jspa?pid=[project ID]&
issuetype=[issue ID]">[link text]</a>
o Complex Format:
<a href="https://[JIRA URL]/secure/CreateIssueDetails!init.jspa?pid=[project ID]&
issuetype=[issue ID]&summary=[issue summary]&description=[issue description]&
components=[component ID]&customfield_10010=[field value]">[link text]</a>
• Paste the link code into your website or external application.
Practical Example:
Create a simple "service desk" using a JIRA dashboard. Help users get to the correct create form
without having to select the proper project or issue type.
Image: Help Links

Sample Code:
1. <span style="font-size: 14pt; font-weight: bold;">Need Help?</span><br /><br />
2. <a href="https://yourURL.com/secure/CreateIssueDetails!init.jspa?pid=project-
id&issuetype=type-
id" target="_blank"><strong>I need help computer or software help</strong></a><br />
3. Request assistance from the IT Support team.<br /><hr /><br />
4. <a href="https://yourURL.com/secure/CreateIssueDetails!init.jspa?pid=project-
id&issuetype=type-id" target="_blank"><strong>I need JIRA help</strong></a><br />
5. Request assistance from the JIRA Support team.<br /><hr /><br />
6. <a href="https://yourURL.com.com/secure/BrowseProjects.jspa?selectedCategory=all&
selectedProjectType=all" target="_blank">View all JIRA projects</a>.
TIPS
• Improve the display with a unique icon for each form link. Store images or icons as
attachments in a JIRA issue. In the storage issue, right click the attachment to get the
URL to paste into your code. You can also store images on the JIRA server or another
online application.
• Add HTML links to the JIRA default system dashboard, Confluence, or your company’s
intranet.
RECOMMENDATION
Grab the direct URLs to the most commonly used create forms. (The URL must include
the project ID and the issue type ID.) Place the links in a nicely formatted HTML block in
the default system dashboard or another place users visit for help. Help users get to the
correct create form without having to select the proper project or issue type. This is
especially useful if there are many projects or similar projects. (Example: The Computer
Help Desk project vs JIRA Support project.)
Documentation: jirastrategy.com/link/direct-links
NOTE
Required fields will show "info missing" errors on the create screen. Most users are likely to enter
the needed information and complete the form as usual.
Download this code sample at: jirastrategy.com/link/html-links. Use the code in the “Worksheets,
Create Custom Displays
Method: Build a custom page, connected to JIRA through the REST API
Objective: Create a custom web page, on or off the JIRA server, which displays real time
JIRA data.
Use Cases: • A custom display to suit your needs
• Share issue data in a "read-only" mode
• Share issue data with less technical users

Benefits: • Format the page any way you’d like
o Strip away the visual sidebar and dashboard elements to create a

printer friendly version of issue data.
• Tip: Make the page information configurable so a non-programmer can

change elements (e.g. the query statement.)
Sample Use:
Image: Custom Page
Special Features:
• Uses standard JIRA UI and authentication
• The custom page parses the data and displays custom results
Cons:
• Maintenance of an additional element
• Extra testing for every JIRA upgrade
• Discourages users from accessing JIRA to see the same data
• Printing the page results in quickly out of date information

Sync Data with JIRA
Method: Build a custom application, connected to JIRA through the REST API
Objective: Create a custom application using the REST API

Use Cases: • Collect data in a different application and show it in JIRA
o Example: Collect itemized expenses in a purchasing system and
show the total cost in an associated JIRA issue.
• Trigger actions in a different application via JIRA (or vice versa)

o Example: When a JIRA issue closes, trigger a notice in another
application.
• Update info in a different application and push it to JIRA (or vice versa)
o Example: Link unique record IDs between two systems.
o Example: Keep an initiatives status in sync between two systems.
• Anything else you can imagine!

Benefits: • Reduce data duplication between similar systems
• Fewer JIRA changes or custom fields
• Ability to connect related systems

Considerations: • Share authentication credentials between an application and JIRA.
• Sync authentication timeouts. When access times out in JIRA, it also times
out in the application.
• Mirror issue IDs between applications, i.e. ISSUE-123 refers the same record
in both applications.
• Allow issue ID modification in the browser's address bar like in JIRA.
• Push changes to JIRA as a specific user (or as a generic REST API user)
depending on your needs. JIRA tracks the username and time stamp of the
change.
• Apply standard checks, error handling, and logging.

o Use custom error handling or if-then statements beyond the
capabilities of JIRA.
• Limit the application to specific JIRA Projects, Issue Types, Statuses, etc.
o Which project issues can the application update?
o What shouldn't the application be allowed to do?
▪ Example: If an issue is in the "Closed" status, block the
application from updating it and log an error.
Cons: • Developing and maintaining an additional application and/or database
• Extra testing for every JIRA upgrade
• New lifecycle or process complexity
NOTE
You can push field data to JIRA from an external application, but the fields have to be present on the
Edit screen(s). Restrict user editing of these fields using the behavior aspects of the ScriptRunner
for JIRA add-on. Read more about it in the "Noteworthy Add-ons" section.

Hacks
Hacks can be fun and sometimes they’re a great option if you need a quick and dirty solution to get
the job done. While it's better to use built-in features or install plugins, small "hacks" can quickly
solve problems. Hacks are cool when they work, but they have the potential to negatively impact
your application.
NOTE
RECOMMENDATION
To avoid creating a swamp of your own, you should thoroughly test any type of "hack" before
implementing it. Use a test environment and consider the resulting performance, maintenance,
or upgrade impacts. Work with your web development team to craft the best and most efficient
code for your needs. Always close any markup or scripting tags.
Hack: Formatted Announcement Banner
Use Case: To make a site-wide announcement really stand out. This formatted markup is
useful for unplanned maintenance and to quickly get a user's attention.
Implementation: Add a message across the top of all pages using the "Announcement banner"
function in the admin area. The banner can accommodate plan text, JIRA's own
wiki markup, HTML, CSS, and JavaScript.
Sample Code:
<div style="border: 1px solid #000; background-color: #80207d;
padding: 10px;"><h3 style="color: #ffffff;">
This is the JIRA test instance!</h3></div><br />
Alternatives: • Use a plain text banner message.
• The code example above visually distinguishes between the production and
test instances. Instead of a message, you could change the logo, site title,
and/or site colors using the "Look and feel" settings.
Sample Use:
Image: Formatted Announcement Banner
Image: Alternative - Wiki Formatted Banner and Nav Color Change
(NOTE: In the screenshot below, the navigation bar and message copy are purple.)
WARNING
Always test your code outside of JIRA and close all markup tags. If code errors cause pages to
render incorrectly, you have to remove the banner code from the database. See:
jirastrategy.com/link/remove-banner
Hack: Conditional Announcement Banner
Use Case: Only show the announcement banner for certain projects and issues. This is
useful to alert a sub-set of users to changes in their specific project.
Implementation: Add a message across the top of all pages using the "Announcement banner"
function in the admin area. Use code to limit where the message is displayed.
Sample Code:
1. <style>
2. #copy {border: 1px solid #000; background-
color: #ccf0ff; padding: 10px;}
3. </style>
4.
5. <div id="message"></div>
6.
7. <script>
8. AJS.toInit(function(){
9. setTimeout(function(){
10. if(window.location.href.indexOf('[project key 1]') > -1) {
11. document.getElementById("message").innerHTML =
"<div id='copy'>This project's workflow will be updated on Monday.
<a href=\"[link target]\" target=\"_blank\">Read more</a></div>";
12. } else if(window.location.href.indexOf('[project key 2]') > -
1) {
13. document.getElementById("message").innerHTML =
"<div id='copy'>Training for this project will be held on Tuesday.</div>";
14. }
15. }, 500);
16. });
17. </script>
Notes: Escape quotes in the message copy, as shown in the example above.
Alternative: Put a project-specific message on a project's "Summary" page.
Download this code sample at: jirastrategy.com/link/conditional-banner. Use the code in the
Hack: Remove "None" from Select List

Use Case: Remove the "None" default selection from a custom select list (drop down) field.
Implementation: Navigate to a custom field's configuration page. Note the field's unique ID in
the browser URL. Add the unique ID to the code below and paste it in as the
field's default value.
Sample Code:
1. <script type="text/javascript">
2. AJS.$("#customfield_[12345] option[value='-1']").remove();
3. </script>
Notes: This does not alter to the standard built-in "Priority" select list.
Alternative: Make the field required in the field configuration.
Hack: Change Select List Formatting
Use: Make a select list look more like a Components list.

Sample Code:
2. (function($) {
3. AJS.$("#customfield_[12345] option[value='-
1']").remove(); //Removes the default value "None"
4. function convertMulti(id){
5. if (AJS.$('#'+id+"-textarea").length == 0){
6. new AJS.MultiSelect({
7. element: $("#"+id),
8. itemAttrDisplayed: "label",
9. errorMessage: AJS.params.multiselectComponentsError
10. });
11. }
12. }
13.
14. AJS.toInit(function(){
15. convertMulti("customfield_[12345]");
16. })
17.
18. JIRA.bind(JIRA.Events.NEW_CONTENT_ADDED, function (e, context) {
19. AJS.$("#customfield_[12345] option[value='-1']").remove();
20. convertMulti("customfield_[12345]");
21. });
22. })(AJS.$);
23. </script>
Sample Use:
Image: Alternate Select List Formatting
Download this code sample at: jirastrategy.com/link/select-list. Use the code in the “Worksheets,
Hack: Make a Field Read Only
Use Case: Make a field not editable.

Sample Code:
2. AJS.$("#customfield_[12345]").attr("readonly", true);
3. </script>
Alternative: • Use the field behavior aspects of the ScriptRunner for JIRA add-on.
Read more about it in the "Noteworthy Add-ons" section.
• Put the field on the Create and View screens only, and not the Edit screen.
A user can enter an initial value during issue create action, but cannot edit
the value later.
Hack: Add User Instruction
Requirements: The JIRA Toolkit Plugin. Read more about it in the "Noteworthy Add-ons"
section.
Use Case: Provide instructions or links to additional documentation.
Implementation: Create a custom field of type "Message Custom Field (for edit)." See more
in the "Message Custom Field" section of the "Custom Fields" chapter.
Sample Code:
<div style="border: 1px solid #000; background-
color: #ccf0ff; padding: 10px; margin: 10px;">
Please see the <a href="[link target]" target="_blank">
Request a New JIRA Project</a> documentation.</div>
Alternative: Solve problems through user education.

Sample Use:
Image: Sample User Instruction

Hack: Add User Instruction Based on Issue ID
Requirements: JIRA Toolkit Plugin. Read more about it in the "Noteworthy Add-ons"
section.
Use Case: Instruct a user to file a new issue to report a detected problem. (Instead of
reporting it in an existing issue, trying to reopen an issue, etc.)
Implementation: Create a custom field of type "Message Custom Field (for edit)." See more
in the "Message Custom Field" section of the "Custom Fields" chapter.
Sample Code:
1. <div style="border: solid 1px #cccc00; background-color: #ffffb2;
padding: 5px; width: 750px; margin-left: auto; margin-right: auto;
font-size: 9pt;">
2. <span style="font-size: 14px; font-family: arial; font-weight: bold;">
Wait!</span><br />
3. You've indicated a problem with the implementation of
<span id="message"></span>.<br /><br />
4. <script>
5. // get issue's URL path
6. var path = window.location.pathname;
7. // remove directories from path
8. var ticketID = path.replace("/browse/", "");
9. document.getElementById("message").innerHTML = ticketID;
10. </script>
11. Please log this additional problem as a <b>new Bug</b> in the
<a href="[create form URL]" target="_blank"><b>[project name]</b></a>
JIRA project.<br />
12. </div><br />
Note Read more about obtaining a create form's URL in the "Get Data into JIRA"
section.
Alternative Solve problems through user education. Example: Report bugs or
deficiencies as new issues.
Sample Use:
Image: Sample Dynamic Issue Link
Download this code sample at: jirastrategy.com/link/issue-instruction. Use the code in the
Other Uses for JIRA
In addition to its usefulness as a project management and issue tracking tool, JIRA can be used in
multiple other business and personal capacities. Some creative uses include:
JIRA as a CRM
The Atlassian User Group is where users meet locally to share best practices. The program
itself is well supported and managed, but the program data was stored in multiple
applications. The Atlassian Community Team realized they need to:
• Track groups around the world and their leaders
• Have a single, authoritative system to track program success metrics
• Map user group leaders to their city associate leaders to their city group
• Track on-boarding progress
• Track activity levels for cities and leaders
• Have a historical record.
The team was already using JIRA to fulfill support requests, so we extended it to track groups and
leaders as well. We created a new project with the following configuration:
New JIRA Project

Project Name AUG Community
Project Key COMMUNITY
Project Type Business

Issue Types
Name: City
Type: Epic
Screenshot Details
Workflow Name: City
Short Description: Tracking activity for User

Group city locations
Narrative: On creation, an issue is in the "Open / Untriaged" status. A user clicks the "Make
Active" transition button to move to the "Active" status. Alternatively, a user clicks the "Make
Inactive" transition button to move to the "Inactive" status. A user can move between any of the
three statuses at any time.
• Open: The new group is formed but their first event did not occur yet.
• Active: The date of the group’s first event occurs and team records its date is in the issue.
• Inactive: A group no longer has events or no active leader is in place. The group can be
"active" again at any time.
Image: Sample City Record
Fields
Summary Location (In A consistent Summary format helps with search and sorting.
the format:
"Austin" or
area names
like "Northern
Virginia")
Epic Name Location (In A duplication of the above field used to associate leaders to cities
the format:
"Austin" or
"Ashburn")
Description n/a A place to store notes about the group
Map In the format: Used to create a dynamic map of city locations. (Needs to be a
Location "Austin, useable value in Google Maps.)
Texas",
"Austin, TX",
or "Austin, TX
78701"
Region Area of the Example: Americas, APAC, Australia, EMEA
world
Time Zone Select from List of values: jirastrategy.com/link/time-zones
the list
Distro City Example: northern_virginia@atlassianusergroup.com
distribution list
email address
Joined Date of group Use to track time between formation and first event and overall
formation age of the group
Field shared with "Leader" type

First Event Date of first Use to track time between formation and first event for the group
event
Field shared with "Leader" type
Group Size Select list of Example: 1-25...1001+
ranges
(Example: 1-
20)
City Page URL of city Example: http://aug.atlassian.com/cities/northernvirginia
page
Profiles Links to other Field shared with "Leader" type
profiles
(Confluence,
Facebook,
LinkedIn, etc.)

Name: Leader
Type: Standard
Screenshot Details
Workflow Name: Leader
Short Description: Tracking activity for AUG

Leaders
Narrative: On creation, an issue is in the "Open / Untriaged" status. A user clicks the "Start
Onboarding" transition button to move to the "Onboarding" status. Alternatively, a user can click
"Make Inactive" to move to the "Inactive" status. After onboarding, a user clicks the "Done
Onboarding" transition button to move to the "Active" status. An issue can remain in "Active" status
indefinitely. Alternatively, a user clicks the "Make Inactive" transition button to move to the
"Inactive" status. An issue in "Active" or "Inactive" status can move back to the "Open / Untriaged"
status at any time.
• Open: A new leader completed the interest form.
o The Atlassian Community Team sends a welcome email and records the send date in
the issue.
• Onboarding: Onboarding events are occurring. (This status is purposefully generic, to

represent many types of events.)
o Example: Email account creation, email distribution list creation, granting access to
tools
o The Atlassian Community Team sends access information and records the send date in
the issue.
• Active: A leader is fully on board and has scheduled their first event.
• Inactive: A leader no longer hosts events or has left the program. A leader can be "active"
again at any time.
Image: Sample Leader Record
Fields
Summary Leader Name (In the format: "First Last") A consistent Summary format helps
with search and sorting.
Description n/a A place to store additional notes
about the leader. (Example: Is a
certified JIRA administrator. Likes
cats.)
City Select from the list Auto populated from the "City" issue
type
Company n/a n/a
Company Select list of ranges (Example: 1-100) Selections: 1-99, 100-499, 500-
Size 999, 1000-4999, 5000-
9999, 10000+
Role Role or job title n/a
Address Mailing address n/a
Email In the format: The internal, primary, user group
first.last@atlassianusergroup.com contact address
External In the format: email@domain.com An external, secondary, non-user
Email group contact address
Phone n/a Primary phone number

Mobile Phone n/a Secondary, mobile phone number.
Products Which Atlassian products are you Selections: Confluence, JIRA, JIRA
currently using? Service Desk, etc.
Referral How did you hear about Atlassian User n/a
Groups?
Joined Date of first leader contact Used to track time between first
contact and execution of first event
lead and overall time commitment of
leader.
Field shared with "City" type

Initial Contact Date of first contact by Atlassian n/a
Community Team
First Event Date of first event Used to track time between first
contact and execution of first event
by leader. (This date can be
different from a city's "First Event"
date.)
Field shared with "City" type

Birthday n/a n/a
T-Shirt Size Size selection list Example: XL - Women’s
Profiles Links to other profiles (Confluence, Field shared with "City" type
Facebook, LinkedIn, etc.)
Summit Years Years attended Summit Example: 2009
AtlasCamp Years attended AtlasCamp Example: 2009
Years
Attachment Leader photo Profile or head-shot image
attachment
Asset Tracking
Have you ever had to file an insurance claim? Chances are your insurance company requires asset
documentation. Questions like "When did you buy this?", "How much did it cost?", and "What is the
current condition?" are hard to answer if you don’t keep records. Why not use JIRA to track your
assets, their current location, etc.?
The example below shows the record for the computer I'm using to write this book! I list the name
of my computer as the "Summary," the importance of the asset as the "Priority," the computer’s
location as the "Component," and the purchase date as the "Due Date." In the "Description" field, I
list all specs for the computer, and in the "Attachments" area I include the purchase receipt and a
photo of the item. I added a few custom fields to track the purchase price, condition, quantity, and
even who gets this asset after I die. (Yes, it's a little morbid, but it's simply smart estate planning.)
I can refer to these assets by ID in my will. And if I ever need to provide documentation to my
insurance company, the data is compiled immediately by a simple JIRA query and export.
Image: Sample Asset Record
You can easily leverage this example for more complex business use cases. Why not track your
company assets, from initial request, through purchase and use, all the way through disposal?
Moving Labels
Last time I moved, I used JIRA to track my boxes and their contents. First, I created a "BOX"
project in JIRA. Then I set my Dymo label maker to print labels in the format: BOX-1 through BOX-
50. When I filled a box, I put a label on it, created the corresponding JIRA record, and entered the
contents in the "Description" field. With a simple query, I know that my winter hiking boots are in
BOX-1 with other cold weather gear and that the box is currently in storage. If a box got lost during
the move, I'd know what was in it.

Image: BOX-1 JIRA Issue
Bucket Lists
Like many of you, I have a list of things I want to accomplish in my life (i.e. My "Bucket List.") I also
love to travel and take frequent trips. I use JIRA to track my life's "to do" list, check off items as I
complete them, and record the details of all my trips. This allows me to answer questions like "What
was the name of restaurant in Rome where we ate Cacio e Pepe?", "How many times have I been to
California?”, and "What list item should I tackle next?"
I use dashboards to track my bucket list progress. One of my desires is to visit all states and
territories in the United States. In the dashboard example below, there are 25 US states or
territories in the "To Do" status, meaning I have yet to visit them. The "In Progress" status shows
I've visited 20 states, but there's still something I want to see there before I close that record.
There are 11 states in the "Done" status, meaning I don't have plans to visit that state again. Of
course each state record contains all my trip details like, the travel dates, who I traveled with, and
the places I specifically visited. This comes in handy when someone asks me for sightseeing
recommendations! (I'd never be able to remember all these details on my own.) For example, if
you visit Buenos Aires, you must eat grilled proveletta at Cabana Las Lilas. If you go to Samana, in
the Dominican Republic, you must visit the El Limon Waterfall. You'll travel by mule, swim in a cave
behind the falls, and get to sample the best coffee you’ll ever have anywhere in the world.
Image: US State Visit Progress
Personal Goals
According to Dr. David Kohl, economist and professor emeritus, at Virginia Polytechnic Institute and
State University, people who regularly write down their goals earn nine times more over their
lifetime as those who don't. He says 80% of people in the United States don't have goals, 16% have
goals but don't write them down, less than 4% write down their goals, and fewer than 1% review
them on an ongoing basis. Guess which group I'm in? I write my goals in JIRA each year and track
completion progress. Do I complete all goals each year? Nope! But, at least I have a target.
Image: Personal Goal Dashboard
Other Ideas
• Event Planning - Use JIRA to track your wedding task list, home remodeling project, or book
launch activities.
• Collection & Hobby Tracking
o Atlassian employee, Sarah Goff-Dupont, tracks her wine collection in JIRA to make
sure no bottle is forgotten. Read: jirastrategy.com/link/sommelier
o Systems Administrator, Zack Seibert, similarly manages his craft beer collection.
Read: jirastrategy.com/link/craft-beer
o JIRA user, Damien Lauberton, logs his fishing success. Read:

jirastrategy.com/link/fishing-success
• Home Automation - Atlassian Expert Partner, Praecipio Consulting, created a way to toast
bread and also pour beer with JIRA! See: jirastrategy.com/link/toaster and
jirastrategy.com/link/serve-beer.

Snow globe collections, a favorite movie list, employee appraisals, time off requests - the personal
and professional uses are endless! Do your kids have a weekly chore list? Why not manage it with a
JIRA board? Your kids can learn a new technology skill and get their tasks done. Atlassian produced
this fun "JIRA Jr." video as a spoof, but it's not a bad idea! Watch: jirastrategy.com/link/jirajr
RECOMMENDATION
Next time your organization plans to buy yet another tracking application, consider JIRA instead.
Create a quick proof of concept in your test environment. You'll be the hero, saving your
company thousands in additional expenses.
Part 6: Bonuses
Part 6 contains extra information to help you propel your strategy skills and make your life a bit
easier as a JIRA professional and fanatic. Use this additional section to:
• Train end users and encourage adoption
• Create a template to easily import issue data
• Use queries to access information the database
Training Users
End User Training

No matter what type of end users you have (experienced with issue tracking systems or not,
technical or not, etc.), they all have one thing in common: New users need to get started fast so
they can accomplish the work they were hired to do.
RECOMMENDATION
Initially, provide just the basic amount of training an end user needs right now. Save all the in-
depth and "cool things you can do" information for a subsequent training session.
Create a brief introductory training presentation that answers the following questions:
1. What is JIRA?
2. How do you use JIRA at the company?
3. What other applications link or integrate with JIRA?
4. How does a user receive access?
▪ What is the login URL?
▪ What format are the login credentials?
5. What standard terminology is used?
▪ What is an issue?

▪ What is a unique issue key?
▪ What is a project?
▪ What company-specific wording exists?
6. How do you find and use the Default System Dashboard?
▪ How do you find issues assigned to me? Reported by me?
7. What are the standard elements on every JIRA screen?
▪ Example: Main navigation, Create button, Help menu, etc.
8. How do you search for issues?
▪ How do you to find a single issue or multiple issues?
▪ Example: Quick search, basic, and advanced issue search
9. How do you create a new issue?
10. What are the standard parts of every issue?
▪ Example: Summary, Description, People Fields, Date Fields, etc.
11. What types of projects exist?
▪ Are there any commonly confused projects? (Example: Computer Help Desk project
vs JIRA Support project)
12. How do you determine who owns which project?
13. Where do you go for help or to learn more?
For additional user training materials, visit the JIRA Strategy Store at: jirastrategy.com/store
Top 15 Things End Users Want to Know
As a training aid, I created a page with examples (or links to existing documentation) of topics end
users frequently ask.
RECOMMENDATION
Keep a list of common user questions. Use them to create a FAQ document containing links to
self-help information on each topic.
End users are commonly interested in the following topics:
1. Gaining application access or resetting their password
2. Sharing issues and sharing search results
3. Tagging (@mentioning) other users and watching issues
4. Writing queries (using JQL)
5. Creating filters, dashboards, and boards
6. Creating filter subscriptions
7. Customizing or resetting filter columns
8. Creating issues via email (or using Issue Collectors)
9. Exporting data
10. Adding screenshots and attachments
11. Showing hidden fields and tabs
12. Understanding data in the issue "Activity" section
13. Using labels
14. Linking issues and searching for linked issues
15. Estimating effort and logging time
RECOMMENDATION
Choose a well configured and maintained project to serve as a model for other teams. Post
screenshots that show how the project is set up and how the team uses it to manage their work.
Post links or screenshots of well build dashboards and boards, to give users an idea of the
possibilities.
RECOMMENDATION
Train users how to use standard features rather than making customizations or building new
logic.

RECOMMENDATION
Use the "New Features" documentation in the "Upgrade" section as a training aid.
RECOMMENDATION
Invite your end users to attend a local Atlassian User Group meeting. It's an opportunity to get
free training and get their questions answered in an informative and fun setting. See the
"Atlassian User Groups" section in the "Resources" chapter.
Admin Training Resources

Atlassian provides live online training, recorded training, and hands-on team training as part of
"Atlassian University." Visit jirastrategy.com/link/university for details.
Many Atlassian Expert Partners provide classes as well. Visit the experts directory at
jirastrategy.com/link/experts for providers in your location.
RECOMMENDATION
Give your administrators their own copy of this strategy book!
Get Certified
In early 2016, Atlassian launched their JIRA Administrator
Certification program. Atlassian describes their
certification as a way to "...enhance your credibility,
sharpen your performance, and help you deliver world-
class Atlassian experiences to teams everywhere." The
first step is passing a general scenario-based exam, called
"ACP-100." Then, you're eligible to take additional
advanced tests to showcase specialized skills and keep
your certification current. The first additional test is ACP-
110: "Advanced JIRA Workflows."
I was ecstatic to participate in the certification beta

testing program and become one of the first certified JIRA
Administrators!
My certification badge: jirastrategy.com/link/cert-badge
Experience
Atlassian recommends 2-3 years of JIRA administration experience. When I took the exam, I had
5.5 years of general JIRA user experience and 3.5 years of experience as an administrator. Even
with more than the recommended experience, the exam was challenging. I believe the year count
alone doesn't equate to "experience." There's a large difference between causal application
administration, where you make a project customization every now and then but JIRA basically runs
itself, and deep administration, where you've experienced setting up the application from scratch,
upgrading it, maintaining it, and are working daily in the administrative portion of the application. If
the majority of your time has been spent as a casual administrator, you'll need extra learning and
preparation time.
How to Study
1. Read everything about the exam on Atlassian's web site. Visit: jirastrategy.com/link/cert
▪ Note which JIRA versions the test covers.
2. Read the entire JIRA Administrator's Guide for the versions you'll be tested on. Visit:
jirastrategy.com/link/admin-guide
3. Read the release notes for the versions the test covers.
4. Visit every page in the application's admin UI to remind yourself of the settings and
capabilities.
5. Read the Atlassian-provided exam study guide.
▪ Recommendation: Approach the JIRA Administrator certification exam topics from

multiple angles. For example, if you have a small organization, with a handful of
projects and users, you'll want to consider how a large organization, with hundreds of
projects and thousands of users, would tackle a problem. If your organization uses
the server version, you'll want to consider how a strategy might differ in the cloud
version. Think of scenarios that don't apply to your organization but would be
common among others. Think of areas of your application that aren't set up quite
right and how you'd do it better. It's not enough to understand your application's
intricacies, you need to understand how JIRA is generally intended to be configured.
▪ Recommendation: Form a certification study group. Use the Atlassian-provided

study guide to facilitate in-depth discussions and understanding.
6. Visit both the testing vendor and training center's websites to learn all you can about the test
experience.
▪ For example, you need to bring two forms of ID. You won't be able to take any
belongings into the testing room. (This includes your wallet, phone, and keys.)
▪ Recommendation: Bring a pair of earplugs to your JIRA Administrator certification
exam. They shield you from potential distractions, like noise from adjoining rooms,
your neighbor's pencil taps, and mouse clicks that really stand out in a silent room.
I put extra effort in preparing for the exam. I am very happy I passed, but even if I hadn’t, the prep
time was valuable. I learned new things and explored parts of the application I hadn't touched in a
while. The certification process as a whole made me a better JIRA Administrator.

Bulk Import
The Bulk Import function is a quick way to get data into JIRA. It may be available to all users or
restricted to certain groups. (Restriction settings are located in the Global Permission admin area.)
Use this function when you need to import:
• Many similar issues
• Recurring activities
• Data from other applications
• Data from other JIRA applications (Example: Adding production data to the test environment
or merging two instances.)
RECOMMENDATION
Before importing multiple issues, test importing just a couple issues. Check the results for
missing or incorrectly mapped data. It's much easier to address import problems in a flat file
first. Only some problems can easily be fixed with bulk tools later on. Alternatively, consider
importing into a test environment before importing into production.
Application administrators can access import settings from: Admin > System > External System
Import.
JIRA users can access import settings from the main navigation bar. Go to: Issues > Import
Issues from CSV.
TIPS
• Don't specify an issue key. Let JIRA auto number the issues. This avoids conflicts with
existing issues and issues being created at the same time.
• If you are importing into multiple projects, make sure the intricacies of each project's set up
are considered.
• Some fields should be left blank, to let project-specific rules set the values.
• Make sure any import field (status, custom field, etc) exists in the destination project,
workflow, etc. (Example: You can't import a status that isn't already used in the project's
workflow.)
• Make sure values for any required fields are specified. (Even if the importer allows you to
skip them, it may cause problems in the workflow, not to mention the need for the
information.)
• Import JIRA usernames, not full names.
• Accounts for new users will not be created. You can however map fields (Example: Assignee,
Reporter) to existing active usernames.
• Passwords will not be imported. (Users set a password on their first login attempt.)
• Use JIRA's specific date format. Example: 21/Oct/15
• Use JIRA's specific timestamp format. Example: 21/Oct/15 10:31 AM
• Double check spelling, especially for status names, drop down selections, and any field where
a certain format is expected.
• If importing into in a test environment, or if you'll repeat a similar import again, select "create
a CSV configuration file" in the import wizard. This will record your settings, saving time on
the next import.
Additional tips are available in the documentation. See: jirastrategy.com/link/csv-import
Sample
Here's a data sample from an import file.
Issue Due
Summary Assignee Reporter Description Status Priority
Type Date
Task January jdoe msmith Set up all build Open Major 31/Jan/
Release configurations and 00
Configuration scripts for all
projects deployed
in the current
release. Perform
continuous
installations into
test environments.
Plan and execute
the production
deployment event.
Download this sample file at: jirastrategy.com/link/bulk-import. Use the code in the “Worksheets,

Database Queries
It's often faster to get information directly out of the database than to use JQL (JIRA Query
Language) or the admin UI. Also, the database provides additional information not available in the
admin UI.
JIRA SERVER ONLY
Since database types differ and database structures change between versions, it's not possible to
provide queries guaranteed to work in your environment. Instead, work with your database team to
craft the queries for your specific database setup and query efficiency needs.
Here are the MySQL queries I use often.
Configuration Elements
Use the queries in this section for the "publish a static list" recommendations in the "Issue Types,"
"Statuses," "Resolutions," and "Custom Fields" chapters. Also, use them to check for similar values
before you create new ones.
Item: Issue Types
Use: Get the list of all Issue Types.
Sample SELECT id, pname, description FROM issuetype ORDER BY pname ASC
Query:
Item: Statuses
Use: Get the list of all Statuses.
Sample SELECT id, pname, description FROM issuestatus ORDER BY pname ASC
Query:
Item: Resolutions
Use: Get the list of all Resolutions.
Sample SELECT id, pname, description FROM resolution ORDER BY pname ASC
Query:
Item: Custom Fields
Use: Get the list of all Custom Fields.
Sample SELECT id, cfname, description, defaultvalue FROM customfield

Query: ORDER BY cfname ASC
Projects and Issues

Use the queries in this section to learn about projects, their use, who is using them, and which to
archive.
Item: Project Type
Use: List your mix of software, business, and support-type projects.
Sample SELECT pkey, pname, projecttype FROM project ORDER BY projecttype ASC
Query:
Item: Project Category
Use: List your projects by custom category name.
Sample SELECT p.pkey, p.pname, pc.cname AS "category" FROM

Query: project p, projectcategory pc, nodeassociation na WHERE
na.source_node_entity = 'Project' AND
na.sink_node_entity = 'ProjectCategory' AND
na.source_node_id = p.id AND pc.id = na.sink_node_id
Note: Uncategorized projects will not be returned.
Item: Project Issue Count
Use: Find most active (or inactive) projects. Projects with a static issue count may be
archival candidates.
Sample SELECT pname, count(*) AS "total issues" FROM jiraissue i, project p WHERE
Query: i.project = p.id GROUP BY p.pname, i.project

Item: Project Last Issue ID
Use: Get the highest ID of an issue in a project. The previous query returns current
issue count. The result delta shows how many issues were deleted.
Sample SELECT p.pkey, p.pname, p.lead, p.pcounter AS "last issue id",

Query: MAX(i.UPDATED) AS "last update", MAX(i.CREATED) AS "last create" FROM
jiraissue i, project p WHERE i.project = p.id GROUP BY p.pname ORDER BY
MAX(i.UPDATED) DESC
Item: Project Last Update or Create
Use: Get last issue update or create information. Projects without recent updates or
creates may be archival candidates.
Sample SELECT p.pkey, p.pname, p.lead, MAX(i.UPDATED) AS "last update",

Query: MAX(i.CREATED) AS "last create" FROM jiraissue i, project p WHERE
i.project = p.id GROUP BY p.pname ORDER BY MAX(i.UPDATED) DESC
Item: All Project Details
Use: List each project, its key, issue count, lead, and the last time an issue was
updated.
Sample SELECT i.project AS "ID", min(p.pkey) AS "Key", min(p.pname) AS

Query: "Project", max(p.lead) AS "Lead", min(p.pcounter) AS "Issue Count",
max(i.updated) AS "Last Update" FROM project p INNER JOIN
jiraissue i ON p.id = i.project GROUP BY i.project ORDER BY min(p.pcounter)
Item: All Project Assignees
Use: List the primary users of a project. Spot issues assigned to inactive users and
reassign them.
Sample SELECT DISTINCT(assignee) AS "assignee" FROM jiraissue WHERE

Query: project = [project ID] ORDER BY reporter ASC
Note: Obtain a project's ID from the "project" table or by hovering over the project's
"Edit" link on the "Projects" admin page.
Item: All Project Reporters
Use: List the primary users of a project. Spot issues reported by inactive users and
update the reporter.
Sample SELECT DISTINCT(reporter) AS reporter FROM jiraissue WHERE

Query: project = [project ID] ORDER BY reporter ASC
Item: All Project Reporters - Time Based
Use: List the primary users of a project since a specific date.
Sample SELECT DISTINCT(reporter) AS reporter FROM jiraissue WHERE

Query: project = [project ID] AND created >= "2017-01-01" ORDER BY reporter ASC
Item: Issues Moved to Another Project
Use: A way to see where an issue has moved. Many moves in the same project may
indicate a user training opportunity or a project that has been abandoned by
others.
Sample SELECT * FROM moved_issue_key

Query:
Alternate: SELECT id, oldstring AS "original id", newstring AS "current id" FROM
changeitem WHERE oldstring LIKE "[PROJECTKEY]-%" AND newstring != ''
Note: Issues that haven't been moved are excluded with a null "newstring" condition.
Users and Groups

Use the queries in this section to find users, get user details, view group membership, and
gauge activity.
Item: Inactive Users
Use: Find account details for former users. See the "De-Activate User Accounts"
section for items to address.
Sample SELECT id, display_name, user_name, email_address, created_date FROM

Query: cwd_user WHERE active = 0

Item: No Login
Use: Find users who've never logged in. Disable their account for security purposes and
to stay within your license tier.
Sample SELECT id, display_name, user_name, email_address, created_date, active FROM

Query:
cwd_user WHERE id NOT IN (SELECT user_id FROM cwd_user_attributes WHERE
attribute_name = 'login.lastLoginMillis') ORDER BY display_name ASC
Item: No Login Attempt
Use: Find users who've not attempted to login.
Sample SELECT id, display_name, user_name, email_address, created_date, active FROM

Query:
cwd_user WHERE active = "1" AND id NOT IN (SELECT user_id FROM
cwd_user_attributes WHERE attribute_name = 'login.totalFailedCount') AND
id NOT IN (SELECT user_id FROM cwd_user_attributes WHERE
Item: Failed Login
Use: Find users who've not had a successful login.
Sample SELECT id, display_name, user_name, email_address, created_date,

Query: active FROM cwd_user WHERE active = "1" AND id IN
(SELECT user_id FROM cwd_user_attributes WHERE
attribute_name = 'login.totalFailedCount') AND id NOT IN
(SELECT user_id FROM cwd_user_attributes WHERE
Item: Login Details
Use: Find all login related details.
Sample SELECT u.id, u.display_name, u.user_name, u.email_address, u.created_date, u

Query: .active, a.attribute_name, a.attribute_value FROM
cwd_user u, cwd_user_attributes a WHERE
u.id = a.user_id ORDER BY display_name ASC
Note: Limit the results to one user in the WHERE clause. (Example:
AND a.user_id = [user id]). Last login means a user who has "Remember Me"
checked in their browser. For this scenario, only the "last login" attribute will be
updated. Authentication means a username and password was entered. In this
scenario, both the "last login" and "last authentication" attributes will be updated.
Item: Users per Role per Project
Use: Gauge the impact of deleting or renaming a role. Understand role popularity. Spot
old permissions for users who've left the company.
Sample SELECT project.pkey, projectrole.name AS "role", roletypeparameter AS

Query: "user" FROM project, projectrole, projectroleactor WHERE
project.id = projectroleactor.pid AND
projectroleactor.projectroleid = projectrole.id AND
roletype = 'atlassian-user-role-actor' ORDER BY pkey, role ASC
Item: Most Active Users
Use: See users performing the most actions. (Example: Commenting)
Sample SELECT COUNT(id) AS "actions", author FROM jiraaction GROUP BY

Query: author ORDER BY id ASC
Item: Group List
Use: View all groups. Spot duplicate, similar, or legacy groups to target for clean-up.
Sample SELECT id, group_name, active, created_date, description FROM

Query: cwd_group ORDER BY group_name ASC
Item: Users in Groups
Use: View the list of users per group.
Sample SELECT parent_name AS "group", child_name AS "user" FROM

Query: cwd_membership ORDER BY parent_name, child_name ASC
Item: Users in Specific Groups
Use: View the list of users in a specific group. Audit the application administrators
group as part of maintenance activities. See the "Scheduled Maintenance"
section for details.
Sample SELECT child_name AS "username", directory_id FROM cwd_membership WHERE

Query: parent_name = "[jira-administrators]" ORDER BY username ASC

Item: Group Membership Count
Use: Count the popularity of a specific group.
Sample SELECT COUNT(*) FROM cwd_membership WHERE

Query: parent_name = "[jira-software-users]"
Item: Inactive Users in Groups
Use: Find users who are inactive but still members of a group. Target these for clean-
up.
Sample SELECT u.id, u.user_name, u.directory_id, d.directory_name, m.id,

Query: m.parent_name AS "group" FROM cwd_user u, cwd_membership m, cwd_directory d
WHERE u.active = 0 AND u.user_name = m.child_name ORDER BY u.user_name,
m.parent_name, d.directory_name ASC
Filters and Dashboards

Use the queries in this section to manage the count of records in your filter and dashboard tables.
Item: User Filters
Use: Find saved filters per user. Remove filters for users who've left the company.
Gauge popularity before removing a filter or custom field.
Sample SELECT id, filtername, description, reqcontent, fav_count FROM

Query: searchrequest WHERE username = "[username]"
Item: Similar Filters
Use: Find duplicate filters. Encourage users to share.
Sample SELECT id, filtername, authorname, description, reqcontent, fav_count FROM

Query: searchrequest WHERE filtername LIKE "%[keyword]%"
Item: Filter Subscriptions
Use: Find duplicates and results sent by users who've left the company.
Sample SELECT * FROM filtersubscription ORDER BY username ASC

Query:
Item: Filter Content
Use: Detect specific or common queries. Understand data users are reporting on.
Example: How many users are querying for field X?
Sample SELECT * FROM searchrequest WHERE reqcontent LIKE "%[keyword]%"

Query:
Item: Dashboards
Use: Gauge dashboard popularity. Find and delete (or change ownership of)
dashboards owned by users who've left the company.
Sample SELECT id, pagename, description, username, fav_count FROM

Query: portalpage ORDER BY pagename ASC
Workflows
Use the queries in this section to get additional workflow details.
Item: Find Workflows with Embedded Rules
Use: When it's not feasible to manually check rules for each individual transition in each
workflow.
Sample SELECT id, workflowname FROM jiraworkflows WHERE

Query: descriptor LIKE "%<arg name=\"group\">%" OR descriptor LIKE
"%<arg name=\"hidRolesList\">%" OR descriptor LIKE
"%<arg name=\"hidGroupsList\">%" ORDER BY workflowname ASC
Note: See further explanation in the "Finding Embedded Workflow Behaviors" section.
Item: Workflow Schemes by Project
Use: Gauge scheme popularity. See the project to workflow scheme mapping.
Sample SELECT p.pname AS "project", w.name AS "workflow scheme" FROM

Query: project p LEFT OUTER JOIN nodeassociation n ON p.id=n.SOURCE_NODE_ID AND
n.sink_node_entity = 'WorkflowScheme' LEFT OUTER JOIN workflowscheme w ON
n.sink_node_id = w.id ORDER BY w.name ASC

Add-ons
Use the query in this section to audit or compare your plugin list. See the "Plugin Tracking"
section in the "Merging Applications or Starting Over" chapter.
Item: Add-ons and Plugins
Use: Find additional add-on data, not available in the admin UI.
Sample SELECT * FROM pluginversion ORDER BY pluginname ASC

Query:
Database Specific
Use the queries in this section to get basic information about your database and database users.
Item: Database Tables
Use: Understand how your data is stored. Find information not available in the admin
UI. Detect new tables created by add-ons.
Sample SELECT table_name FROM information_schema.tables WHERE

Query: table_schema="[database name]"
Item: Database User Privileges
Use: See permissions for each database user. Audit database users as part of
maintenance activities. See the "Scheduled Maintenance" section for details.
Sample SELECT * FROM [database name]

Query:
Item: Database Details
Use: See all database settings.
Sample SHOW VARIABLES

Query:
Item: Database Version
Use: Verify database version compatibility before an upgrade event.
Sample SHOW VARIABLES LIKE "%version%"

Query:
Query Resources
Again, the queries above may not work for your database or JIRA version. They are there to give
ideas of additional ways to help you administer your application.
See the following links for database and query documentation:
• jirastrategy.com/link/database-schema
• jirastrategy.com/link/sample-queries
• jirastrategy.com/link/database-schema-crowd
• jirastrategy.com/link/sample-queries-crowd
Download these query samples at: jirastrategy.com/link/database-queries. Use the code in the

Resources
Documentation
Official product documentation is available at: jirastrategy.com/link/official-docs. The
documentation includes information for end users and a guide specifically for administrators. The
documentation is categorized up by application type (e.g. Server or Cloud) and also by version.
MISTAKE
I spent two days reading the documentation for the wrong version. (No wonder things
weren't matching up!)
Support
Official product support is available at: support.atlassian.com
RECOMMENDATION
When requesting Atlassian support, use a role account with a distribution list email address.
This way multiple admin team members can access problem and solution details.
Tips for Requesting Support
1. Before contacting support, check the documentation, answers forum, and previously reported
bugs, for a solution to your problem.
▪ Documentation: confluence.atlassian.com
▪ Atlassian Answers: answers.atlassian.com
▪ Atlassian Bug Reporting & Feature Requests: jira.atlassian.com
2. Determine if you need application support or if instead, you need to log a bug.
3. For Server versions, run support tools like Instance Health, the Log Scanner, and
the Integrity Checker.
4. Make sure your version is still supported.

▪ See the Atlassian Support End of Life Policy at: jirastrategy.com/link/end-support
5. Know your Support Entitlement Number (SEN).
▪ See "Finding your JIRA application Support Entitlement Number (SEN)" at:
jirastrategy.com/link/find-sen
6. Always provide the Atlassian technicians with more detail than you think they need.
▪ For example: What specifically are you experiencing? What do you expect to happen
instead? How can they reproduce the issue? What computer and browser are you
using?
7. Be prepared to attach your diagnostic and configuration information.
▪ See "Create a Support Zip" at: jirastrategy.com/link/support-zip
RECOMMENDATION
Worried about sending sensitive data in your support request? Use the JIRA Anonymiser
feature. More info at: jirastrategy.com/link/anonymising.
Atlassian User Groups

Atlassian Users Groups are where users meet, learn, network, and share best practices. The groups
meet locally, all over the world, on a quarterly or more frequent basis. User Group members are
newbies and veterans who like to “talk shop” about Atlassian software, about Agile development, and
about related business topics. At these events, you can network with your peers, share solutions,
meet Expert Partners, get special content from Atlassian, and enjoy a beer.
Are you passionate about JIRA, Confluence, or any of the Atlassian tools? Are you interested in
learning to use them in new ways? Can you share solutions to common business and software
development problems? Then join a User Group! Membership is free to you; Atlassian picks up the
tab!
Find a user group near you (or start one) at: aug.atlassian.com
Summit Annual User Conference

Summit is the grand Atlassian event of the year. With the palpable enthusiasm of the employees,
the knowledge of the presenters, and the immense networking opportunities, this is the place to
experience all that is Atlassian. Add the next annual event to your calendar now. Visit
summit.atlassian.com for details.

Summit Justification
With all the tech conferences occurring every year, how do you convince your company to send you
to Atlassian Summit?
In your attendance proposal, answer the following questions:
• What do you hope to learn?
o Use specific examples of problems you can solve by attending. Example: "I'll learn
about the new Certification program you were asking about" or "I'll take your question
about X straight to the Support Bar!"
o Use the "continuing education" or training angle. You need to learn something new
this year right?
• What valuable experiences will you gain?
• Who will you network with?
• Add statistics to your pitch.
o Example: How big was last year's event? How many people attended? How many
sessions were there? Who were the speakers and sponsors? (This information is
useful to compare against other events and communicate value.)
Top 5 Justification Reasons
1. You will leave with pages of "new ideas" to bring back to your company.
2. You'll get answers to your questions directly from Atlassian or from companies sharing similar
problems.
3. You'll meet fellow users, Expert Partners (vendors, consultants), and Atlassian employees you
wouldn't normally have access to. (How useful would it be to have some Atlassian employee
business cards?)
4. You'll gain an "insider's view" into upcoming features and changes.
5. It's a marketing opportunity for your company. (You'll hand out your business cards and
wear your company logo shirt, right?)
Budget
The flight and the conference hotel are likely expensive, so you need to prepare your supervisor for
sticker shock. Help soften the blow with a list of things your company won't have to pay for.
For example, do you really need a rental car? Most Summit events are held in cities where parking a
car is challenging and cost prohibitive. If your hotel is close to or in the conference location, skip the
rental car. You'll save hundreds by taking a cab or public transportation between the airport and
hotel. List a big, visual $0 next to that line item.
The "meals" line item can be listed as $0 or almost $0 as well. Atlassian feeds you all the time on
conference days. You won't be spending money on additional food.
Summit Tips
Use this guide to navigate Summit and make the most of your time at the user conference.
Image: Rachel Wright and Friends Enjoy Summit 2016
Before Summit
• Plan which sessions you want to attend, but be flexible. (Continuing your conversation with
that Expert partner or Atlassian employee may be more valuable than attending the next
session.)
• Don’t be a slave to power! Bring an extra battery or portable power source. Consider taking
notes on paper. You won't want to fight for an outlet to recharge devices.
• Be prepared to network! Pack your business cards. Don’t have work business cards? See if
your company has any “generic” cards you can write your info on. Alternatively, have the
Summit, LinkedIn, or other mobile networking app ready.
• Check the weather and the time zone in the conference city. Bring a light jacket as
conference centers tend to be chilly.
• Arrive the day before conference activities start and check in as soon as possible to avoid a
long registration line on the first morning.
• Walk the conference center before it gets busy to see where activities take place. If there's a
venue map, take a phone picture. Identify which vendor booth locations to visit.

During Summit
• Don’t try to work AND attend Summit at the same time. It's too hard to do both well.
Instead, turn on your “out of office” email autoresponder, set the expectation that you’ll be
unavailable, and delegate your tasks to coworkers while you’re away.
• Find the Atlassian User Group area. The user group leader from your city might be at
Summit. No user group in your area? Learn how to start one!
• Get to sessions early to ensure a seat!
• At the event, login to a chat program so you can communicate in real time with your
colleagues also at Summit. Example: "I'm going to the X session next" or "Meet you at noon
in the lobby!"
• Write a quick note on the back of any business card you receive so you’ll remember
how/if/why to follow up later.
• Pace yourself on day one and during Summit Bash! It's a long day and you want to make it
to the party.
• Atlassian feeds you a lot on conference days. You won’t need to spend much money on food.
After Summit
• Try to leave the day after Summit activities conclude. It's no fun leaving early to catch a
flight.
• After Summit, the major session recordings become available online. Don’t worry if two
sessions you want to attend happen at the same time.
• Leave room in your luggage for the return trip. You'll acquire new goodies (i.e. a few new t-
shirts!) Some die hard collectors bring an extra bag or plan to mail back items.
• Share your notes and the most important information with your team members who could not
attend.
Also see Atlassian's expanded "Tips for getting the most out of Summit" at:
jirastrategy.com/link/summit-tips
Worksheet: Summit Notes
I take a lot of notes at the conference including what I learn and what to follow up on. Use this
worksheet to share the most important information with team members who could not attend.
RECOMMENDATION
Use Summit Notes worksheet to communicate the business justification for attending
Summit the following year.
Summit [year]
[dates] - [location]
summit.atlassian.com
Summit is the annual training, support, and networking event for all the Atlassian products we
use including: [product list]
About the Conference
• This year's focus: [theme]
• Attendees: [count]
• Learning sessions: [count]
• Speakers from leading companies like: [company names]
• Sponsors: [count]
Major Announcements
[insert announcements here]
RECOMMENDATION
Insert the top facts and upcoming features for each Atlassian product your company uses.
Session Notes
Record the names of the sessions you attend and any useful notes or takeaways.
Session Date &
[date, time]
Time:
Session Title: [session title]
Notes: [Insert session notes and URLs containing more information. Flag any
specific items to follow up on after the event.]
Contacts
Insert contact details for Atlassian staff or other networking contacts.

Name Title Company Email Phone Details Next Step
Ex: How did Ex: Call in 2
you meet? weeks to
What did you discuss x and y.
discuss?
Rachel Author, Industry info@ (443) Talked about Visit
Wright JIRA Templates jirastrategy.com 317- how to jirastrategy.com
Strategy 3279 maintain a to download all
Admin large JIRA the worksheets
Workbook instance while and templates
in the for this book.
registration
line.
...

Resources
• Summit Site: summit.atlassian.com
• [Insert link to keynote presentation videos and other session materials.]
• [Insert links to "top announcements" blog articles and online coverage.]
• [Insert next year's Summit dates and location.]
Download this worksheet at: jirastrategy.com/link/summit-notes. Use the code in the “Worksheets,
Other Books
These books make excellent companions to the JIRA Strategy Admin Workbook:
Jira 7 Development Cookbook Practical JIRA Administration

by Jobin Kuruvilla by Matt Doar and Mikey Schott
jirastrategy.com/link/jira7-dev-cookbook jirastrategy.com/link/practical-admin
Atlassian Experts
Atlassian provides product support and bug fixes, but when you need more assistance, work with an
Expert Partner. Atlassian's global directory of over 250 experts can help you build a plugin,
configure your application, or assist in your transition to agile. If needed, an Expert Partner may
even log into your application and help you directly. Search for a vendor near you at:
jirastrategy.com/link/experts.
One of Atlassian's top experts, ServiceRocket, compiled a fabulous guide to selecting the right Expert
Partner. Read more: jirastrategy.com/link/select-expert
ServiceRocket's top tips for choosing the right expert are:
• Select an expert who's verified and has a good track record with Atlassian. Verified experts
are in the directory on the Atlassian website.
• Review the experts company structure, capabilities, case studies, reviews, and customer
references.
• Look for an expert who's active in the Atlassian ecosystem. Do they participate in the
answers.atlassian.com forum and respond to problems on jira.atlassian.com? Do they attend
User Groups meetings and the annual Summit user conference?
• Choose an expert that offers multiple services like training, support, and add-on
development. Seek a relationship that complements your current and future needs.
• Look for an expert that has an office location near your time zone.
• Select an expert who offers the most value, not the lowest cost. (You get what you pay for!)
Consulting
Need help digging your application out of the JIRA swamp? Contact Industry Templates, LLC at:
info@industry-templates.com.
Conclusion
Now, it's time for you to make a decision. Will you use the recommendations in this book to ensure
an organized, tidy, and peaceful JIRA garden? Or, will you let your application grow out of control
into a foggy, contaminated, overgrown swamp?
I hope this book gives you more insight into your application, helps get you and your admin team
organized, provides alternate strategies to consider, directs you to further information, and
ultimately helps you perform your administrative duties.
If you have additional strategies to share, I'd love to include them. Start the conversation at:
jirastrategy.com/link/conversation.

Appendix
Recommendations
Download the 152 recommendations and tips at: jirastrategy.com/link/recommendations. Use the
code in the “Worksheets, Templates & Companion Materials” section to download it for free.
Index
Audit ....................... 11, 160, 165, 166, 191, 215, 264, 267
A
Authentication
Add-ons and Plugins Authentication ............................................... 179, 263
Add-ons ....... 12, 16, 22, 73, 86, 89, 104, 105, 106, 107, Single Sign-On .................................................... 9, 43
108, 109, 127, 166, 170, 226, 236, 240, 241
B
Bob Swift Atlassian Add-ons (an Appfire
company)............................................................ 226 Backup ................................................. 162, 179, 195, 207
JIRA Misc Workflow Extensions . 22, 89, 104, 105, Best Practices ...... 9, 10, 11, 12, 39, 66, 70, 76, 113, 116,
107, 108, 109, 227 118, 130, 134, 135, 147, 149, 220
JIRA Toolkit Plugin .......... 16, 22, 126, 227, 240, 241 Board ............................... 7, 8, 7, 8, 9, 23, 25, 52, 124, 132
Plugin Vetting ............................................ 12, 26, 221 Bonuses ............................................................. 13, 3, 252
Quick Subtasks for JIRA.................................... 227 Browse ................................... 54, 137, 139, 144, 174, 175
ScriptRunner for JIRA . 73, 114, 166, 170, 226, 236, Bug .............................. 66, 67, 68, 111, 115, 116, 241, 269
240 Bulk Change .................................................. 11, 73, 156
Suite Utilities for JIRA ..... 22, 86, 89, 104, 105, 106,
C
166, 227
Agile............................................................ 3, 91, 157, 270 Category
Announcement Banner ........ 7, 12, 185, 204, 237, 238 Project .................................................................... 9, 51
Archive................................... 11, 169, 173, 175, 177, 191 Status ..................................................................... 9, 71
Asset ..............................13, 4, 89, 123, 161, 227, 247, 248 Checklist ...................................................... 41, 42, 43, 54
Assignee ...... 16, 18, 22, 28, 54, 56, 60, 63, 103, 106, 113, Clean-Up ......................................... 11, 12, 172, 177, 216
115, 116, 132, 150, 157, 257, 258 Code
Atlassian CSS ........................................................................... 237
Certification ..................................... 4, 5, 13, 255, 271 HTML........................................... 41, 126, 230, 231, 237
Expert Partners .................................... 255, 270, 271 JIRA Query Language (JQL) ..... 4, 11, 51, 74, 164,
Marketplace ................................... 196, 212, 220, 221 169, 170, 176, 177, 217, 226, 254, 259
Summit User Conference............................ 13, 270 XML ............................................... 96, 97, 100, 101, 207
User Groups (AUGs) ..................... 13, 247, 255, 270 Comparison .......................................... 11, 178, 179, 182
Attachment .......................................... 16, 122, 157, 247
Component .. 16, 18, 28, 33, 60, 105, 132, 133, 134, 135, E
157, 216, 247
Editor
Confluence ... 1, 13, 16, 33, 44, 50, 51, 56, 196, 231, 244,
Andre Lehmann .................................................. 5, 50
247, 270
Billy Poggi ................................................................... 6
Contributor
Gregory Van Den Ham .................................. 5, 147
Brian Jones .................................................... 213, 226
Kimmoy Matthews ................................................... 6
Damien Lauberton............................................... 250
Matt Doar ...................................................... 5, 74, 275
Dan Radigan ............................................................ 91
Sheri Breault ............................................................. 6
Daniel Eads .............................................................. 92
Susan Hauth .............................................................. 6
Daniel Wester ....................................................... 221
Email
Dr. David Kohl ...................................................... 250
Email 11, 13, 17, 63, 155, 172, 193, 228, 229, 245, 246,
Eric Lemay ............................................................. 226
273
Hatim Khan ................................................................ 7
Incoming Email..................................... 172, 179, 191
Jobin Kuruvilla .................................................. 7, 275
Mail............................................ 155, 172, 179, 191, 196
Katherine Burstein ................................................ 86
Emergency Escalation .............................. 12, 192, 193
Mariano Goldman .................................................... 7
Environment .............................. 191, 195, 198, 204, 206
Mikey Schott .................................................. 133, 275
Epic ..................................68, 114, 115, 116, 157, 243, 244
Sarah Goff-Dupont.............................................. 250
Event ............... 95, 107, 150, 152, 153, 193, 244, 247, 250
Zack Seibert .......................................................... 250
Example from the Swamp ....9, 12, 25, 33, 34, 40, 44,
Created Date ............................................................. 182 46, 50, 53, 59, 67, 68, 73, 75, 102, 114, 119, 121, 125,
CSS ............................................................................... 237 136, 156, 163, 167, 168, 178, 214, 242
Custom Field Export .................................11, 74, 91, 166, 176, 177, 207
Checkbox ................................................................ 125 Extending JIRA ............................................... 4, 13, 228
Context .................................................... 118, 127, 128
Field Configuration ...... 10, 52, 54, 57, 113, 114, 118, F
120, 121, 123, 128, 134, 164 FAQ ............................................................................... 253
Field Configuration Scheme 10, 52, 123, 128, 134, Filter ............................................................... 34, 265, 266
164 Form ....................................................... 10, 114, 117, 256
Message Custom Field ...16, 17, 126, 127, 227, 240, Future Predictions ................................................... 188
241
Radio Button ......................................................... 125 G
Renderer ......................................... 123, 128, 129, 157 Groups ..... 9, 13, 25, 38, 39, 135, 138, 139, 144, 145, 146,
Required Field ................................................. 10, 120 147, 148, 161, 179, 188, 262, 264, 265, 270, 276
Text Field .......................................................... 17, 125
Customer Survey ....................................................... 19 H
Customization ........................ 12, 3, 16, 35, 63, 201, 220 Hacks............................................ 237, 238, 239, 240, 241
D Hardware ............................................................ 134, 179
HTML .............................................. 41, 126, 230, 231, 237
Dashboard .................................................... 42, 250, 253
Data I
Export ............................. 11, 74, 91, 166, 176, 177, 207 Inactive
Import .....................................13, 74, 91, 177, 207, 257 Project........................................................ 11, 168, 170
Update ............................................................. 9, 73, 75 User .................................................... 24, 191, 262, 265
Database... 12, 13, 2, 69, 71, 74, 120, 139, 169, 175, 177, Incident Log ................................................. 12, 214, 215
179, 182, 188, 191, 198, 200, 206, 207, 208, 214, 217, Issue
259, 267 Activity............................................................. 156, 254
Date Assignee .. 16, 18, 22, 28, 54, 56, 60, 63, 103, 106, 113,
Created Date ......................................................... 182 115, 116, 132, 150, 157, 257, 258
Due Date.. 16, 18, 19, 22, 116, 122, 131, 157, 247, 258 Attachment ...................................... 16, 122, 157, 247
Updated Date ........................................................ 172 Child ............................66, 108, 109, 115, 116, 123, 227
Distribution List .................................................. 32, 155 Issue Collector ...................................................... 230
Due Date...... 16, 18, 19, 22, 116, 122, 131, 157, 247, 258 Issue Type Scheme ................ 9, 52, 67, 68, 69, 163
Duplicate Elements ........................... 11, 165, 226, 227 Parent.......... 66, 105, 107, 108, 109, 115, 116, 123, 227
Priority ...... 13, 16, 18, 76, 122, 157, 167, 239, 247, 258
Reporter .... 63, 103, 106, 113, 119, 122, 139, 146, 147, Notification
148, 150, 157, 257, 258 Notification ... 11, 35, 37, 47, 52, 54, 57, 149, 150, 153,
Resolution ..... 9, 72, 73, 74, 75, 79, 161, 165, 166, 226, 154, 155, 156, 165, 170, 177, 198, 205
259 Notification Scheme . 52, 54, 57, 149, 150, 153, 154,
Status..... 9, 22, 70, 71, 77, 82, 84, 85, 88, 90, 103, 104, 177
105, 108, 109, 155, 169, 186, 200, 204, 258
O
Unassigned................................................. 28, 60, 111
Issue Security Other Books ......................................................... 14, 275
Issue Security ....11, 52, 137, 139, 146, 147, 148, 161 Other Uses for JIRA .......................................... 13, 242
Issue Security Scheme ................ 52, 139, 146, 147 Outage ......................................... 185, 186, 187, 200, 204
J P
JIRA Password ....................................................................... 66
Cloud .. 3, 4, 5, 27, 28, 41, 107, 126, 127, 178, 179, 182, Permission
227, 269 Global ......................................................................... 24
Core .................................................................... 24, 179 Permission .... 10, 39, 52, 54, 56, 57, 87, 101, 103, 104,
Download .................................................................... 4 129, 135, 136, 137, 138, 139, 144, 145, 146, 147, 165,
OnDemand ................................................................. 4 173, 174, 175, 177, 257
Server .................................................................. 3, 4, 5 Permission Scheme ...... 10, 52, 54, 56, 57, 101, 129,
Software ............. 15, 24, 28, 60, 68, 112, 131, 179, 226 135, 136, 137, 138, 146, 147, 173, 174, 175, 177
JIRA Query Language .................................. 4, 11, 259 Plugin ....182, 186, 189, 191, 220, 221, 222, 224, 227, 267
JIRA Service Desk ................3, 13, 15, 24, 46, 217, 247 Priority ..........13, 16, 18, 76, 122, 157, 167, 239, 247, 258
JIRA Support Project ........................ 8, 12, 15, 91, 227 Project ...................................................................... 15, 47
JIRA Support Team ................................... 28, 193, 221 Q
JQL .. 4, 11, 51, 74, 164, 169, 170, 176, 177, 217, 226, 254,
259 Query .....13, 102, 118, 119, 163, 165, 196, 259, 260, 261,
262, 263, 264, 265, 266, 267, 268
L Quick Explanation ..47, 66, 67, 70, 72, 76, 77, 111, 113,
Login 115, 118, 121, 123, 129, 132, 135, 146, 149
Password ................................................................... 66 R
Username ................................................................. 17
Recommendation ... 8, 15, 18, 19, 23, 24, 27, 28, 31, 32,
M 34, 35, 36, 37, 38, 41, 43, 45, 48, 50, 51, 52, 53, 54, 59,
Maintenance 12, 3, 28, 37, 179, 185, 186, 190, 191, 193, 69, 71, 72, 73, 74, 75, 76, 78, 80, 81, 82, 85, 86, 91, 92,
209, 217, 234, 264, 267 93, 94, 96, 100, 102, 110, 120, 125, 129, 133, 136, 138,
Materials 145, 152, 154, 156, 157, 159, 161, 174,176, 177, 182,
Checklist.................................................. 41, 42, 43, 54 183, 187, 190, 192, 195, 196, 201, 205, 207, 208, 209,
Code ....................21, 230, 231, 237, 238, 239, 240, 241 211, 213, 214, 223, 224, 226, 231, 237, 251, 252, 253,
Questions ................. 8, 6, 20, 41, 48, 63, 124, 216, 247 254, 255, 257, 269, 270, 273
Wording ....... 12, 28, 35, 36, 37, 41, 48, 58, 60, 63, 137, Re-index ........................................ 12, 106, 189, 190, 191
147, 150, 155, 170, 187, 198 Reminder ........................................ 35, 37, 199, 200, 204
Worksheet .... 10, 13, 26, 32, 35, 36, 40, 41, 48, 54, 82, Report ........................ 13, 28, 67, 191, 193, 208, 217, 241
84, 124, 137, 139, 144, 145, 146, 147, 148, 150, 157, Reporter ......103, 106, 113, 119, 122, 139, 146, 147, 148,
161, 169, 179, 182, 188, 191, 193, 194, 195, 196, 206, 150, 157, 257, 258
207, 208, 212, 214, 215, 217, 221, 224, 229, 273 Reporting
Merge Applications ............................................ 11, 178 Board ........................... 7, 8, 7, 8, 9, 23, 25, 52, 124, 132
Metrics ....................................................................... 8, 13 Dashboard ................................................ 42, 250, 253
Mistake ................... 27, 69, 94, 95, 96, 102, 172, 185, 269 Filter ........................................................... 34, 265, 266
Monitoring ............................................ 12, 179, 212, 214 Metrics ................................................................... 8, 13
Report .................... 13, 28, 67, 191, 193, 208, 217, 241
N Statistics ........................................... 12, 187, 191, 217
Naming .......................................................................... 82 Tracking... 11, 12, 13, 16, 18, 19, 22, 89, 122, 139, 157,
Network Operations Center (NOC) ... 198, 200, 203 182, 187, 191, 194, 243, 245, 247, 250, 267
Notice ....................................... 2, 173, 174, 175, 201, 205
Resolution .... 9, 13, 16, 19, 21, 22, 23, 70, 72, 73, 74, 75, Active User ....................................................... 24, 264
79, 85, 89, 90, 106, 139, 167, 215, 217 Administrator 4, 5, 8, 2, 7, 25, 26, 28, 50, 60, 81, 136,
Responsibilities ...... 17, 26, 28, 38, 39, 48, 50, 56, 58, 63 161, 179, 208, 215, 217, 226, 250, 255, 256
Role... 8, 35, 36, 38, 39, 103, 104, 136, 139, 145, 147, 148, Advisory Board ........ 7, 8, 7, 8, 9, 23, 25, 52, 124, 132
150, 246, 264 Ambassadors ..................................................... 23, 26
Rollback......................................................... 12, 206, 207 Application Administrator ............. 2, 8, 24, 26, 215
S Avatar ........................................................................ 47
Character User.............................................. 9, 35, 58
Screen.. 10, 18, 22, 52, 82, 84, 85, 90, 113, 114, 115, 116, Database Administrator ........................ 2, 208, 217
126, 157, 161, 164 End User...........................13, 8, 35, 201, 205, 252, 253
Issue Type Screen Scheme ......... 10, 52, 115, 116 External User. 9, 24, 33, 34, 39, 58, 74, 137, 196, 246,
Screen ...... 10, 18, 22, 52, 82, 84, 85, 90, 113, 114, 115, 257
116, 126, 157, 161, 164 Former ....................................................... 34, 170, 226
Screen Scheme .................10, 52, 114, 115, 116, 161 Group ..... 4, 5, 6, 1, 17, 50, 97, 103, 104, 131, 139, 144,
Tabs ...................................................................... 18, 63 145, 174, 207, 227, 230, 242, 243, 244, 255, 264, 265,
Security ...................... 10, 11, 75, 146, 147, 148, 179, 215 270, 273
Special Characters .................................................. 119 Inactive User ................................... 24, 191, 262, 265
Standard Capabilities ............11, 54, 57, 121, 156, 157 Internal User ........................................................... 24
Statistics ............................................... 12, 187, 191, 217 JIRA Core User ....................................................... 24
Status .... 22, 70, 71, 77, 82, 84, 85, 88, 90, 103, 104, 105, JIRA Service Desk User ....................................... 24
108, 109, 155, 169, 186, 200, 204, 258 JIRA Software User ............................................... 24
Story....................................................... 68, 111, 115, 116 New User .................................................................. 40
Strategy .. 1, 2, 9, 5, 47, 53, 112, 179, 212, 253, 273, 275, Other User ............................................................ 9, 43
281 Profile ....................................................................... 247
Sub-task ...... 15, 18, 67, 68, 105, 109, 111, 123, 191, 196 Project Administrator ..................................... 24, 26
Support ... 8, 12, 13, 15, 21, 24, 26, 28, 31, 36, 41, 42, 46, Project Lead ... 8, 23, 27, 28, 31, 32, 33, 47, 54, 56, 57,
48, 49, 51, 60, 63, 66, 68, 77, 91, 92, 124, 155, 162, 170, 60, 63, 78, 135, 150, 168, 169, 208
179, 191, 192, 193, 203, 208, 216, 217, 221, 227, 229, Project Manager ............................................. 2, 8, 48
231, 253, 269, 270, 271 Role ....... 8, 35, 36, 38, 39, 103, 104, 136, 139, 145, 147,
Documentation . 47, 66, 67, 70, 72, 76, 77, 78, 82, 84, 148, 150, 246, 264
110, 111, 113, 115, 118, 121, 123, 128, 129, 132, 135, System Administrator ...................................... 2, 24
146, 149, 152, 208, 224, 229, 230, 231, 269 Test User............................................................... 8, 24
Systems Team ...................193, 198, 200, 206, 208, 217 User Management
T Active Directory ...................................................... 43
Crowd ............................................... 16, 42, 43, 51, 136
Task .... 15, 18, 66, 67, 68, 69, 77, 80, 84, 96, 97, 103, 107, User Management ............................................. 9, 40
111, 115, 116, 123, 206, 211, 217, 258
Username ..................................................................... 17
Terminology..................................................... 8, 9, 4, 46
Testing V
Automated Testing................................ 12, 209, 212 Version... 10, 5, 28, 60, 105, 115, 116, 129, 130, 131, 145,
Regression Testing.............12, 54, 58, 196, 209, 223 157, 161, 179, 182, 194, 267
Test Case ................................................................ 211
Tip .... 41, 48, 49, 80, 81, 107, 124, 170, 171, 212, 227, 231 W
Tracking ...... 11, 12, 13, 16, 18, 19, 22, 89, 122, 139, 157, Warning ................................. 33, 177, 185, 196, 215, 238
182, 187, 191, 194, 243, 245, 247, 250, 267 Workflow
Training ..... 13, 16, 35, 179, 186, 193, 208, 217, 238, 252, Condition....................87, 102, 103, 104, 107, 109, 123
255 Post Function ..... 22, 82, 84, 85, 88, 90, 102, 106, 107,
U 152, 154, 227
Support Workflow .................................................. 77
Unused Elements ....................................... 11, 163, 166 Transition 18, 19, 22, 73, 74, 79, 82, 84, 85, 87, 88, 90,
Updated Date ............................................................ 172 93, 94, 105, 107, 108, 109, 110, 113, 126, 139, 144,
Upgrade ...... 182, 183, 186, 187, 190, 191, 193, 194, 195, 152, 174, 196, 226, 227
198, 199, 200, 201, 203, 204, 205, 206, 208, 217, 255 Transition Behavior ..... 10, 22, 78, 82, 84, 85, 88, 90,
User 96, 101, 102, 103, 104, 105, 107, 171, 266
Transition Buttons ........................................... 87, 93 Worksheet .. 10, 13, 26, 32, 35, 36, 40, 41, 48, 54, 82, 84,
Validator.................................... 87, 104, 105, 108, 109 124, 137, 139, 144, 145, 146, 147, 148, 150, 157, 161,
Workflow Scheme ......10, 52, 77, 111, 112, 162, 163, 169, 179, 182, 188, 191, 193, 194, 195, 196, 206, 207,
266 208, 212, 214, 215, 217, 221, 224, 229, 273
Workflow Templates ....................................... 10, 84 X
XML ................................................... 96, 97, 100, 101, 207
Offer
You may be eligible to receive:
• Updated information and companion materials
• Advance notice of new editions of the book
• Announcements of book related events
Subscribe at: jirastrategy.com/link/notify.
Also check for additional materials and new information in the JIRA Strategy Store at:
jirastrategy.com/store.

Jira Strategy Admin Workbook - Templates For The Application Administrator To Set Up, Clean Up, and Maintain Jira (PDFDrive)

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Jira Strategy Admin Workbook - Templates For The Application Administrator To Set Up, Clean Up, and Maintain Jira (PDFDrive)

Uploaded by

Copyright:

Available Formats

JIRA Strategy

Cover Photo and Design by: Rachel Wright

In 2013, Rachel founded the Northern Virginia Atlassian User Group.

In 2016, she moved on to assist the User Group program as a

Winner, "Community Champion"

Winner, Atlassian User Group "Founder's" Award

Winner, "Play, as a Team" Atlassian

Winner, Atlassian User Group Summit

I’ve made plenty of configuration mistakes; enough to fill a book in fact! I

My favorite thing about JIRA is its flexibility and usability.

I once upgraded my test server and forgot to change the database

Gregory Van Den Ham

My favorite thing about JIRA is that it allows me to centrally manage the

My most interesting experience was when I realized workflow steps were

My favorite part of JIRA is what it accomplishes. It enables teams to build

I always ask my potential clients what do they use to manage their

My favorite part of JIRA is the organization and structure it provides. It’s

JIRA appeals to my eye for design and this book to my instructional

Pledge 1% is an effort spearheaded by Atlassian, Rally for Impact, Salesforce

How I Fell in Love with JIRA ........................................................ 1

Part 1: Setting the Foundation .................................................... 7

Part 2: Project Configuration ....................................................... 45

Part 3: Fix and Clean JIRA Up ...................................................... 160

Part 4: Maintenance..................................................................... 185

Part 5: Customization ................................................................. 218

Part 6: Bonuses ........................................................................... 250

Conclusion .................................................................................... 274

Image: I'm currently in a relationship with JIRA.

Who This Book Is For

This book is written for the:

• full-time Application Administrator for JIRA or the Atlassian product suite;

• Systems Administrator or Database Administrator who supports many different internal

2 | JIRA Strategy Admin Workbook

What You'll Need

2. have an end user's understanding of JIRA functions; and

4 | JIRA Strategy Admin Workbook

Icon Use Notes

Chapter or Section Reference A reference to another section or chapter in the book

Recommendation or Tip Advice or something good to know

Don't Something to avoid

Mistake A mistake I made; something to avoid

Example from the Swamp A real world example to avoid

Warning or Note Something important to know

Worksheets, Templates & Companion Materials

Comments, Feedback, and Questions

6 | JIRA Strategy Admin Workbook

• Create a support system of users who want the application to succeed

• Establish basic standards and determine how you'll enforce them

• Set up a request collection and management strategy

Establish an Advisory Board

2. An Application Administrator who understands the software structure, database schema,

3. A Project Manager, Business Analyst, or Strategist who understands effective processes

4. A VP who's responsible for the work tracked in JIRA.

Role of the Board

8 | JIRA Strategy Admin Workbook

EXAMPLE FROM THE SWAMP

Handle Sensitive Information

1. How do you define sensitive information?

o Passwords, special codes, or secret keys

o Personally identifiable data (like social security numbers, date or place of

o Protected health information (like the health insurance plan an employee

o Employment information (like an employee identification number, citizen

o Credit card or payment data