Jira 8 Essentials Effective project tracking and issue management with enhanced Jira 8.21 and Data Center features Patrick Li BIRMINGHAM—MUMBAI Jira 8 Essentials Copyright © 2022 Packt Publishing All rights reserved. No part of this book may be reproduced, stored in a retrieval system, 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 critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information. Group Product Manager: Alok Dhuri Publishing Product Manager: Harshal Gundetty Senior Editor: Nithya Sadanandan Content Development Editor: Rosal Colaco Technical Editor: Pradeep Sahu Copy Editor: Safis Editing Project Coordinator: Manisha Singh Proofreader: Safis Editing Indexer: Rekha Nair Production Designer: Vijay Kamble Developer Relations Marketing Executives: Deepak Kumar and Rayyan Khan Business Development Executive: Uzma Sheerin First published: June 2015 Second edition: January 2018 Third edition: April 2015 Fourth edition: November 2016 Fifth edition: February 2019 Sixth edition: October 2022 Production reference: 1141022 Published by Packt Publishing Ltd. Livery Place 35 Livery Street Birmingham B3 2PB, UK. ISBN 978-1-80323-265-2 www.packt.com To Johnny and Fanny, my family far away in Sweden. Without your constant belief and support, this will not have been possible through these hard times. – Patrick Li About the author Patrick Li is the cofounder of AppFusions and works as a senior engineer there, specializing in integration solutions with many enterprise applications and platforms, including IBM Connections, Jive, Google Apps, and more. He has worked in the Atlassian ecosystem for over 10 years, developing products and solutions for the Atlassian platform and providing expert consulting services. He has authored many books and video courses covering Jira. He has extensive experience in designing and deploying Atlassian solutions from the ground up and customizing existing deployments for clients across verticals such as healthcare, software engineering, financial services, and government agencies. Contributors About the reviewer Daniel Brvnišťan is an experienced agile product owner focused on Atlassian stack, online channels, and localization, with a passion to make things work. He likes to groom the backlog, implement new tools and disruptively improve processes. Table of Contents Preface xv Part 1: Introduction to Jira 1 Getting Started with Jira Data Center Understanding the Jira platform 4 Introducing Jira Data Center 5 System requirements 7 Hardware requirements 7 Software requirements 8 Installation package options 10 Installing Java 10 Installing and configuring Jira 12 Installing Jira 13 Post-installation configuration 24 2 Using Jira for Business Projects Understanding projects and project types 35 Business projects 37 Jira permissions 37 Creating projects 38 3 Increasing Jira’s memory 25 Changing Jira’s port number and context path 26 Configuring HTTPS 27 Clustering 29 Preparing for clustering 29 Creating JIRA_SHARED_HOME 30 Enabling clustering 30 Adding a node to the load balancer 31 Adding new nodes to the cluster 31 Zero-downtime upgrade 32 Summary 34 35 Project user interfaces 40 Project browser 40 The Summary tab 41 The Issues tab 41 The Versions and Components tabs 42 Project settings 42 viii Table of Contents Importing data into Jira 47 Importing data through CSV 47 Archiving projects and issues 52 The HR project 53 Part 2: Jira in Action 3 Using Jira for Agile Projects Getting an overview of Scrum and Kanban 59 Scrum 60 Kanban 60 Running a project with Scrum in Jira 60 Creating a Scrum project 60 Working with the backlog 62 Prioritizing and estimating work 62 Creating a new sprint 64 Running a sprint 66 Running a project with Kanban in Jira 69 Creating a Kanban project 70 Using the Kanban board 71 4 Working with Issues Understanding issues 85 Jira issue summary 86 Working with issues 88 Creating an issue 89 Assigning issues to users 90 Editing an issue 91 Moving an issue between projects 92 Creating a new project 53 Creating new components 54 Putting it all together 55 Summary 56 59 Enabling a backlog for Kanban 72 Configuring agile boards 74 Configuring columns 74 Adding column constraints 75 Setting up swimlanes 77 Defining quick filters 78 Grooming your backlog 79 Creating a new agile board for your project 80 Including multiple projects on your board 81 Summary 82 85 Sharing issues with other users 95 Deleting an issue 95 Receiving notifications on an issue 96 Casting a vote on an issue 97 Issue linking 98 Linking issues with other issues 98 Linking issues with remote contents 99 Cloning an issue Tracking time 101 Specifying original estimates 102 Logging work 102 Issues and comments 103 Attachments 104 Attaching files 104 Issue types and sub-tasks 105 Creating issue types Deleting issue types 106 5 Field Management 100 Using sub-tasks 107 Issue type schemes 108 Adding issue types to an issue type scheme 108 Issue priorities 109 Creating a priority scheme 110 The HR project 111 Adding new issue types 112 Updating the issue type scheme 112 106 Putting it all together 113 Summary 113 115 115 Field descriptions 134 Table of Contents ix Understanding system fields Understanding custom fields 116 Standard fields 117 Advanced fields 117 Required fields 134 Field visibility 135 Field rendering 135 Field configuration scheme 136 Managing field configuration schemes 137 Adding a field configuration scheme 137 Configuring a field configuration scheme 138 Associating a field configuration scheme with a project 139 Screens 140 The HR project 141 Setting up a custom field 141 Setting up the field configuration 142 Setting up a field configuration scheme 142 Putting it together 143 Summary 144 Understanding field searchers 119 Custom field context 119 Managing custom fields 120 Adding a custom field 121 Editing/deleting a custom field 124 Configuring a custom field 126 Adding custom field contexts 127 Configuring select options 128 Setting default values 129 Optimizing custom fields 130 Field configuration 131 Adding a field configuration 132 Managing field configurations 132 x Table of Contents 6 Screen Management Understanding Jira and screens 145 Working with screens 147 Adding a new screen 148 Adding a field to a screen 149 Deleting a field from a screen 150 Using screen tabs 151 Adding a tab to a screen 152 Editing/deleting a tab 153 Editing/deleting a screen 153 Copying a screen 154 Working with screen schemes 154 145 Issue type screen scheme 158 Associating issue types to screen schemes 159 Editing/deleting an association 160 Editing/deleting an issue type screen scheme 161 Copying an issue type screen scheme 161 Associating an issue type screen scheme with a project 162 Delegating screen management 163 Troubleshooting fields and screens 164 The HR project 165 Setting up screens 166 Setting up screen schemes 167 Setting up issue type screen schemes 167 Putting it together 168 Summary 169 173 Adding a post function to transitions 191 Updating an existing workflow 193 Understanding workflow schemes 195 Creating a workflow scheme 196 Configuring a workflow scheme 196 Assigning an issue type to a workflow 197 Editing or deleting an association 199 Applying a workflow scheme to projects 199 Delegated workflow management 201 Adding a screen scheme Associating screens to issue operations Editing/deleting an association Editing/deleting a screen scheme Copying a screen scheme Part 3: Advanced Jira 7 Workflow and Business Process 155 156 157 157 158 Mapping business processes 174 Understanding workflows 174 Managing workflows 176 Issue statuses 177 Transitions 178 Using the workflow designer 181 Authoring a workflow 183 Adding a trigger to transitions 187 Adding a condition to transitions 188 Adding a validator to transitions 189 8 Emails and Notifications Jira and email Mail servers 210 Working with outgoing mail 211 Disabling outgoing mail Enabling SMTP over SSL 215 Sending a test email 215 Mail queues 216 Viewing the mail queue Flushing the mail queue Manually sending emails 218 Events 220 Working with mail templates 221 Adding a custom event 224 Firing a custom event 225 Notifications 226 Notification schemes 228 9 Securing Jira Managing users ScriptRunner for Jira 203 The HR project 203 Setting up workflows 204 Applying the workflow 206 Putting it together 206 Summary 208 209 209 Adding a notification scheme 229 Managing a notification scheme 229 Assigning a notification scheme 231 Incoming emails 234 Adding an incoming mail server 234 217 Mail handlers 235 218 Adding a mail handler 238 Advanced mail handler 239 The HR project 240 Setting up mail servers 240 Updating workflow post functions 240 Setting up a notification scheme 241 Setting up notifications 241 Putting it together 242 Summary 242 243 244 Managing groups and roles 248 Table of Contents xi Extending a workflow with workflow add-ons 202 JSU 202 Jira Workflow Toolbox (JWT) 203 Jira Misc Workflow Extensions (JMWE) 203 Workflow Enhancer for Jira 203 214 Batching email notifications 232 Troubleshooting notifications 232 Adding a user Enabling public signup Enabling CAPTCHA 247 245 Managing groups 248 246 Managing roles 251 xii Table of Contents User directories Connecting to LDAP 255 257 Troubleshooting permissions 273 Workflow security 275 Password policy 275 Enabling SSO with SAML 276 Enabling JIT provisioning 278 Auditing system changes 279 The HR project 280 Setting up groups 281 Setting up user group association 281 Setting up permission schemes 281 Setting up permissions 282 Putting it together 283 Summary 283 285 Creating a dashboard 306 Configuring a dashboard 307 Changing the ownership of a dashboard 308 Gadgets 309 Placing a gadget on the dashboard 309 Editing a gadget 312 Deleting a gadget 313 The HR project 313 Setting up filters 313 Setting up dashboards 314 Setting up gadgets 314 Putting it together 315 Summary 315 Understanding Jira permissions 261 Application access 261 Global permissions Project permissions Permission schemes Configuring permission schemes 267 Applying a permission scheme 270 Issue security 270 Issue security schemes 271 Configuring an issue security scheme 271 Setting a default security level Applying an issue security scheme 273 10 Searching, Reporting, and Analysis Search interface and options in Jira 286 Issue navigator 286 Quick search 287 Basic search 288 Advanced search with JQL 290 Working with search results 293 Switching result views 293 Customizing the column layout 293 Exporting search results 294 Sharing search results 295 Filters 295 Reports 302 Generating a report 302 Dashboards 305 Managing dashboards 305 262 265 266 273 Table of Contents xiii 11 Jira Service Management Introducing Jira Service Management 317 Installing Jira Service Management 319 Getting started with Jira Service Management 321 Creating a new service desk 323 Branding your customer portal 326 Service desk user types 328 Adding an agent to a service desk 328 Managing service desk customers 329 Adding a collaborator to a service desk 331 Issue types and request types 331 Setting up request types 332 12 Jira and Third Party Apps Atlassian Marketplace and third-party apps 351 Universal Plugin Manager 353 Searching and installing apps from the Atlassian Marketplace 353 Installing apps manually 354 Managing installed apps 356 Configuring the UPM 358 Index Other Books You May Enjoy 317 Organizing request types into groups 332 Setting up fields for request type 333 Setting up a workflow for a request type 335 Service-level agreement (SLA) 337 Setting up an SLA 337 Setting up custom calendars 340 Managing requests with queues 342 Creating a new queue 342 Creating knowledge base articles 343 Process automation 347 Summary 349 351 Extending Jira with apps 361 Extending custom fields with apps 361 Extending workflow with apps 362 Customizing Jira with scripts 364 Better time tracking and reporting 368 Selecting an app and its vendor 370 Summary 371 373 386 Preface Over the years, Jira has grown from a simple bug-tracking system designed for engineers to manage their projects to an all-purpose issue-tracking solution. The term Jira now refers to a suite of products, including Jira Software, Jira Service Management, Jira Core, and others. With this change, each product is more focused on what it does and the value it provides. It is now easier than ever for customers to choose the product best suited to their needs, whether they are running an Agile software development project, a customer support portal, or simply a generic task management system. With the latest Data Center offering, Jira is now the go-to solution for any enterprise that is looking to future-proof its teams with performance, reliability, scalability, and security. In this book, we will cover all the basics of Jira and its core capabilities, as well as advanced features offered by the data center offering. We will also explore third-party apps that add additional features to the Jira platform. Packed with real-life examples and step-by-step instructions, this book will help you become a Jira expert. Who this book is for This book will be especially useful for project managers but it’s also intended for other Jira users, including developers, and in any other industry besides software development, who would like to leverage Jira’s powerful task management and workflow features to better manage their business processes. What this book covers Chapter 1, Getting Started with Jira Data Center, serves as an overall introduction to Jira by going over its high-level architecture. We will cover both new deployments and how to upgrade from an existing deployment. We will also introduce the Jira Data Center offering from Atlassian. This will also serve as the starting point of the project that readers will go through. Chapter 2, Using Jira for Business Projects, covers using Jira for projects that are not based on software development, for example, a generic task management solution. This chapter focuses on the use of the basic features of Jira, which are offered through the Jira Core product, which is bundled with Jira Software. Chapter 3, Using Jira for Agile Projects, covers features that are specific to Jira Software. This chapter focuses on using Jira for software development projects, especially using Agile methodologies such as Scrum and Kanban. xvi Preface Chapter 4, Working with Issues, introduces issues, which are the cornerstone of using Jira. The focus is to make sure users understand issues and what they do. You will also learn how to make each of the features available and customize them beyond the out-of-box settings. Chapter 5, Field Management, introduces fields, and specifically how to use custom fields to customize Jira for more effective data collection. You will learn how to create new custom fields, and how to control field configurations such as visibility and rendering options. Chapter 6, Screen Management, introduces screens. You will learn how to create new screens from scratch and specify which fields (system and custom) will be displayed. We will also cover complex scheme mappings to apply new screens to projects. Chapter 7, Workflow and Business Process, explores the most powerful feature offered by Jira, workflows. The concept of issue life cycles is introduced, and various aspects of workflows are explained. This chapter also explores the relationship between workflows and other various Jira aspects that have been previously covered, such as screens. The concept of Jira apps is also briefly touched upon in the sample project, using some popular apps. Chapter 8, Emails and Notifications, talks about emails and how Jira can use them to send notifications to end users. We will start by explaining how Jira sends out notifications to users, and then how Jira can process incoming emails to create, comment on, and also update issues. Chapter 9, Securing Jira, explains Jira’s security model, starting with how to manage users, groups, and roles. Readers will then learn Jira’s security hierarchy of how permissions are managed. Lastly, we will look at setting up single sign-on using SAML, a common requirement with most enterprise organizations. Chapter 10, Searching, Reporting, and Analysis, focuses on doing more with data collected by Jira, including searching, reporting, and using dashboards. You will also learn how to make this data and reports available outside of Jira, either via email or by displaying them in other applications. Chapter 11, Jira Service Management, introduces Jira Service Management, which allows you to run Jira as a customer support portal. Readers will learn how to use Jira Service Management to run and manage a support queue internally while at the same time communicating effectively with customers. Chapter 12, Jira and Third Party Apps, covers using third-party apps to extend the capabilities of Jira. You will learn how to find, install, update, and manage apps for Jira. We will also look at some popular third-party apps and how they can be used to take Jira to the next level. To get the most out of this book The installation package used in this book is the Windows Installer standalone distribution, which you can get directly from Atlassian at https://www.atlassian.com/software/jira/ download for Jira Software and https://www.atlassian.com/software/jira/ service-desk/download for Jira Service Management. You will also need additional software, including the Java SDK, which you can get from http:// www.oracle.com/technetwork/java/javase/downloads/index.html, and MySQL, which you can get from http://dev.mysql.com/downloads. Software/hardware covered in the book Operating system requirements Jira Software Windows, macOS, or Linux Jira Service Management Java MySQL If you are using the digital version of this book, we advise you to type the code yourself. Doing so will help you avoid any potential errors related to the copying and pasting of code. Experience in XML, Java, or the Groovy programming language will be useful to better understand the code snippets in the book. Any errata related to this book can be found on the following link: https://github.com/ packt-pradeeps/Jira-8-Essentials. Download the color images We also provide a PDF file that has color images of the screenshots and diagrams used in this book. You can download it here: https://packt.link/9C0B9. Conventions used There are a number of text conventions used throughout this book. Code in text: Indicates code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles. Here is an example: “You should see both the New Employee and Termination issue types.” A block of code is set as follows: Preface xvii all-except-attachments *.js *.jsp Any command-line input or output is written as follows: create database jiradb character set utf8; Bold: Indicates a new term, an important word, or words that you see onscreen. For instance, words in menus or dialog boxes appear in bold. Here is an example: “There is a Create another option beside the Create button.” Tips or important notes Appear like this. Get in touch Feedback from our readers is always welcome. General feedback: If you have questions about any aspect of this book, email us at customercare@ packtpub.com and mention the book title in the subject of your message. Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you would report this to us. Please visit www.packtpub.com/support/errata and fill in the form. Piracy: If you come across any illegal copies of our works in any form on the internet, we would be grateful if you would provide us with the location address or website name. Please contact us at copyright@packt.com with a link to the material. If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit authors.packtpub.com. Preface xix Share Your Thoughts Once you’ve read Jira 8 Essentials, we’d love to hear your thoughts! Please click here to go straight to the Amazon review page for this book and share your feedback. Your review is important to us and the tech community and will help us make sure we’re delivering excellent quality content. xx Preface Download a free PDF copy of this book Thanks for purchasing this book! Do you like to read on the go but are unable to carry your print books everywhere? Is your eBook purchase not compatible with the device of your choice? Don’t worry, now with every Packt book you get a DRM-free PDF version of that book at no cost. Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical books directly into your application. The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free content in your inbox daily Follow these simple steps to get the benefits: 1. Scan the QR code or visit the link below https://packt.link/free-ebook/978-1-80323-265-2 2. Submit your proof of purchase 3. That’s it! We’ll send your free PDF and other benefits to your email directly Part 1: Introduction to Jira In this section, you will learn how to set up a Jira instance from scratch, followed by how to use Jira for your business and agile projects. The following chapters are included in this section: • Chapter 1, Getting Started with Jira Data Center • Chapter 2, Using Jira for Business Projects 1 Getting Started with Jira Data Center In this chapter, we will start by providing a high-level overview of Jira, the various products that run on top of the platform, and then introduce Jira Data Center. After that, we will examine the various deployment options and system requirements for hosting Jira Data Center yourself. Finally, we will get our hands dirty by installing our very own Jira Data Center from scratch, both as a standalone and a clustered deployment. In this chapter, we will cover the following topics: • Understanding the Jira platform • Introducing Jira Data Center • System requirements • Installation package options • Installing and configuring Jira • Post-installation configuration • Clustering • Zero-downtime upgrade By the end of the chapter, you will have learned about the Jira platform and the new Data Center product. You will also learn about the system requirements to install Jira, and how a Jira cluster works. Finally, you will have your own Jira instance up and running. 4 Getting Started with Jira Data Center Understanding the Jira platform Jira started as a popular tool used by software development teams to track and manage their projects. As the IT industry changed over the years, Jira has also grown to meet the demands and challenges faced by its users. Today, Jira has transformed from being a single application to a platform with many applications and solutions that can run on top of it, and it provides additional features and capabilities that go beyond issue tracking. Atlassian, the company behind Jira, has several other products that make up the Jira family. These include the following: • Jira Software: This is a product that focuses on software development. It allows project teams to run their software development projects using traditional waterfall and agile methodologies such as Scrum and Kanban. • Jira Work Management: This is a product that is designed for non-software development teams, such as marketing, operations, and legal. It is perfect for general-purpose task management. • Jira Service Management: This is a product for service desk teams. It is designed for running Jira as a support ticketing system, with a simplified user interface for the end users with a focus on customer satisfaction and Service-Level Agreement (SLA) goals. At its core, the Jira platform provides many of its common functionalities for various products, such as user interface customization, workflows, and email notifications, while Jira Software and Jira Service Desk add specialized features on top of it. Of course, being a platform means Jira also allows other third-party developers to develop solutions for it. Atlassian has a huge thriving ecosystem of products and solutions made by partners that add even more features to Jira. We will look at some of these solutions later in this book. In this book, we will primarily focus on Jira Software, but we will also cover all the common features that are shared by all the applications, and how they can be used by them in their specific use cases. For this reason, the term Jira will be primarily used to refer to Jira Software, unless a specific distinction is needed. Now that we have learned about the Jira platform and its various products, it is time to look at the newest member of the Jira family. Introducing Jira Data Center One of the biggest challenges users often face with Jira Server is scalability. When an organization’s Jira deployment grows to thousands of concurrent users and hundreds of thousands of issues, they will often start to experience performance issues, such as slower response times. While each new major release would include performance improvements, customers often had to archive and export old projects to another Jira instance or split up their one big instance into several smaller instances. Some organizations can resolve this problem by migrating to the Jira Cloud offering. However, not everyone can move to the public cloud due to security, regulations, and other reasons, or they prefer to run Jira in their private cloud. This is where Jira Data Center comes in. Jira Data Center is the new offering from Atlassian that replaces the old Jira Server and aims to address challenges that are often faced by organizations that need their Jira deployment to be performant, scalable, highly available, and secure. With Jira Data Center, you can continue to host Jira yourself, with the aforementioned added benefits. Many additional features are added, such as support for Security Assertion Markup Language (SAML), Advanced Roadmaps for planning, and improved administrative functions. Additional information You can find a full list of differences between the old Jira Server and Jira Data Center at https://confluence.atlassian.com/enterprise/jira-server-and- data-center-feature-comparison-953651628.html. So, how does Jira Data Center achieve all these benefits and improvements? Unlike Jira Server, where you have a single instance of Jira running, Jira Data Center allows you to run multiple Jira instances together as a single deployment, called a cluster. The following diagram illustrates a typical Jira Data Center deployment: Introducing Jira Data Center 5 6 Getting Started with Jira Data Center Figure 1.1 – Jira Data Center deployment You will have one or more Jira instances, called nodes, running in a single cluster. All the Jira nodes will connect to the same database and file server, with a load balancer to distribute the traffic across all the nodes. This way, you have more computing power shared across the cluster, and you can add another node to the cluster at any time to add additional capacity. Another good feature of Jira Data Center is that you do not need to run a cluster if you are not ready. You can run your deployment with a single node as a standalone, just as you would with the previous Jira Server. Then, when you need to, you can always convert your deployment into a cluster. Doing so gives you flexibility, as well as all the additional features that have been introduced in Jira Data Center. With a good understanding of Jira Data Center, let’s look at what we will need for deployment. System requirements 7 System requirements Before we can deploy Jira Data Center, we need to look at the hardware and software required for Jira, and how you want your deployment to be. You can deploy Jira in two ways: • Standalone: This is the same deployment as the classic Jira Server, where you have a single Jira instance serving your users. This is the easier option and does not require as many system resources. If you are just getting started, this is the option for you. • Cluster: This is the deployment shown in Figure 1.1, where you can have multiple Jira instances (nodes) running in a cluster, and they all serve your users. If you need scalability, high availability, and other cluster-specific features, this is the option for you. If you are unsure which option to start with, you can always start with the standalone option and switch to a cluster when you need all the features and benefits from a clustered deployment. Now that we know what deployment options are available for Jira, let’s start looking at the hardware and software you will need. Hardware requirements For evaluation purposes, where there will only be a small number of users, Jira will run happily on any server that has a 1.5 GHz processor and 1 GB to 2 GB of RAM. As your Jira usage grows, a typical server will have a quad-core 2 GHz+ CPU and 4 GB of RAM dedicated to the Jira application, and at least 10 GB of hard disk space for your database. For production deployment, as in most applications, it is recommended that you run Jira on its own dedicated server. There are many factors that you should consider when deciding the extent of the resources to allocate to Jira, especially in terms of how Jira will scale and grow in the future. When deciding on your hardware needs, you should consider the following: • The number of active (concurrent) users in the system, especially during peak hours • The number of projects, issues, and comments in the system • The number of configuration items, such as custom fields and workflows At times, it can be difficult to estimate these figures. As a reference, a server running with a 2.0 quad- core CPU and 4 GB of RAM will be sufficient for most instances with around 200 active users. If you start to get into thousands of active users, you will need to have at least 8 GB of RAM allocated to Jira (JVM). Once you have gone beyond a million issues and thousands of active users for a single Jira instance, simply adding raw system resources (vertical scaling) will start to yield diminishing returns. In such cases, it is often better to consider using the Data Center edition of Jira, which offers better scalability by allowing you to have multiple instances clustered together (horizontal scaling), with the added benefit of providing high availability. 8 Getting Started with Jira Data Center Officially, Jira only supports x86 hardware and 64-bit derivatives of it. When running Jira on a 64-bit system, you will be able to allocate more than 4 GB of memory to Jira, which is the limit if you are using a 32-bit system. If you are planning to deploy a large instance, it is recommended that you use a 64-bit system. Software requirements Jira has three major requirements when it comes to software: it needs a supported operating system, a Java environment, and a database to store all of its data. In the following sections, we will discuss each of these requirements and the options that you have to install and run Jira. Additional information You can find the latest information on software requirements online at https://confluence. atlassian.com/adminjiraserver/supported-platforms-938846830.html. Operating systems Jira supports most of the major operating systems, so the choice of which operating system to run Jira on becomes a matter of expertise, comfort, and, in most cases, the existing organization’s infrastructure and requirements. The operating systems supported by Atlassian are Windows and Linux. There is a Jira distribution for macOS, but this is mostly for evaluation purposes only. Amazon Web Services (AWS) and Microsoft Azure are also supported with quick-start templates. With both Windows and Linux, Atlassian provides an executable installer wizard package that bundles all the necessary components to simplify the installation process. There are minimal differences when it comes to installing, configuring, and maintaining Jira on different operating systems. If you do not have any preferences and would like to keep initial costs down, CentOS Linux is a good choice. Java platforms Jira is a Java-based web application, so it needs to have a Java environment installed. This can be a Java Development Kit (JDK) or a Java Runtime Environment (JRE). The executable installer that comes with Windows or Linux includes a JRE. However, if you want to use archive distributions, you will need to make sure that you have the required Java environment installed and configured. Jira requires a minimum version of Java 8. If you run Jira on an unsupported Java version or from an unsupported vendor, you may run into unexpected errors. The following table shows the supported Java versions for Jira: Java Platforms Support Status Table 1.1 – Java platforms You should also keep your Java versions up to date by running the latest patched version of either Java 8 or 11. This will ensure you have the latest bug and security patches to keep your environment secure. Databases Jira stores all its data in a relational database. While you can run Jira with H2 Database, the in-memory database that comes bundled with Jira, it is prone to data corruption. You should only use this to set up a new instance quickly for evaluation purposes, where no important data will be stored. For this reason, you must use an enterprise-level database such as MySQL for production systems. Most relational databases available on the market today are supported by Jira, and there are no differences when you install and configure Jira. Just like operating systems, your choice of database will come down to your organization’s infrastructure/DevOps team’s expertise, experience, and established corporate IT standards. If you run Windows as your operating system, then you probably want to go with Microsoft SQL Server. On the other hand, if you run Linux, then you may want to go with PostgreSQL and MySQL. The following table summarizes the databases that are supported by Jira at the time of writing. It is worth mentioning that both MySQL and PostgreSQL are open source products, so they are excellent options if you are looking to minimize your initial cost: System requirements 9 Oracle JDK/JRE OpenJDK Java 8, Java 11 Database PostgreSQL Microsoft SQL Server Azure SQL Amazon Aurora Support Status PostgreSQL 10, 11, 12 SQL Server 2016, 2017, 2019 PostgreSQL 10, 11, 12 MySQL MySQL 5.7, 8.0 Note that both MariaDB and PerconaDB are not supported Oracle Oracle 12c R2, 18c, 19c This requires the JDBC 19.3 (ojdbc8) driver H2 This is bundled with the standalone distribution, for evaluation purposes only Table 1.2 – Databases 10 Getting Started with Jira Data Center Take special note of the driver requirement for each database. Jira comes bundled with drivers for several of the databases, but some, such as Oracle, will require you to get the driver separately. You need to make sure you get the correct version of the driver to avoid any unexpected errors. With the system and database requirements covered, it is time to move on to Jira itself. Installation package options Jira Data Center comes with several deployment options. The first choice you need to make is where you would like to deploy Jira. If you want to deploy Jira to AWS or Azure, Atlassian provides quick- start templates so that you can get up and running quickly. If you want to deploy Jira to your hardware or other cloud vendors, or simply want to manage how you want the deployment to be, you can use the installation packages available. Jira installation packages come in two flavors: • Executable installer: The executable installer provides a wizard-driven interface that will walk you through the entire installation process. It even comes with a Java installer to save you some time. • TAR.GZ or ZIP archive: The archive package is similar to the executable installer, except it does not have an installation wizard, does not bundle Java, and will not configure Jira to run as a service. You will also need to perform some post-installation steps manually, such as configuring Jira as a service. However, you do get the advantage of learning what goes on under the hood. In our exercise, we will be using the installer package, but we will also cover the post-installation steps so that you have a good understanding of the various configuration options available. We will start by installing Java. Installing Java Since we will be using the installer package that’s bundled with Java, you can skip this section. However, if you are using the archive option, you need to make sure that you have Java installed on your system. Jira 8 requires JRE version 8 as a minimum to run. You can verify the version of Java you have by running the following command in Command Prompt: java -version The preceding command tells you which version of Java is running on your system, as shown in the following screenshot: Figure 1.2 – Java version If you do not see a similar output, then chances are you do not have Java installed. You will need to perform the following steps to set up your Java environment. Start by installing Java on your system: 1. Download the latest Java 8 or 11 from https://www.java.com/en/download/ manual.jsp. Note At the time of writing, the latest version of Java 8 is JDK 8 Update 321. 2. Double-click on the downloaded installation file to start the installation wizard. 3. Select where you would like to install Java. Alternatively, you can simply accept the default values. The location where you install JDK will be referred to as JAVA_HOME for the remainder of this book. 4. Create a new environment variable named JAVA_HOME with the value set to the full path of the location where you installed Java. You can do this as follows: A. Open the System Properties window by going to About your PC from the Windows Start menu. B. Select the Advanced system settings option. C. Click on the Environment Variable button from the new popup: Installation package options 11 12 Getting Started with Jira Data Center Figure 1.3 – The JAVA_HOME environment variable D. Add a new variable (either User or System) called JAVA_HOME and set its value to where you installed Java. Now that you have a good understanding of Jira Data Center, the basic system requirements, and the various installation options, we are ready to deploy our own Jira instances. Installing and configuring Jira We will start by installing Jira as a standalone deployment. We will perform our installation on a Windows platform and use PostgreSQL for the database. If you are planning on using a different platform or database, refer to the vendor documentation on installing the required software for your platform. In this section, you will do the following: • Install a fresh instance of Jira Software • Connect Jira to a PostgreSQL database • Configure the Jira instance to work in a cluster environment We will continue to use this Jira deployment in subsequent chapters and exercises as we build our help desk implementation. Installing and configuring Jira 13 For our deployment, we will use the following: • Jira Software 8.21.0 • PostgreSQL 12.9 • Apache web server • Microsoft Windows Let’s begin by installing Jira! Installing Jira Before we install Jira, here are two important directories we need to mention: • JIRA_INSTALL: This is the directory where the Jira application will be installed • JIRA_HOME: This is the directory that Jira will use to store some of its important configuration and data files We will be referring to those two directories throughout this book. Now, on to the installation. There are generally two steps involved: • Downloading and installing the Jira application • Running through the Jira setup wizard Let’s get started. Obtaining and installing Jira The first step is to download the latest stable release of Jira. You can download Atlassian Jira from https://www.atlassian.com/software/jira/update. The Atlassian website will detect the operating system you are using and automatically suggest an installation package for you to download. If you intend to install Jira on a different operating system from the one you are currently on, make sure that you select the correct operating system package. 14 Getting Started with Jira Data Center As we mentioned earlier, with Windows, there is a Windows installer package and a self-extracting archivepackage.Forthisexercise,wewillusetheinstallerpackage(Windows 64-bit Installer): 1. Double-click on the downloaded installation file to start the installation wizard and click on the Next button to continue: Figure 1.4 – Jira installation step 1 2. Select the Custom Install (recommended for advanced users) option and click on the Next button to continue. Using the custom installation will let us decide where to install Jira and will also provide numerous configuration options, as shown in the following screenshot: Installing and configuring Jira 15 Figure 1.5 – Jira installation step 2 3. Select the directory where Jira will be installed. This will become the JIRA_INSTALL directory. Click on the Next button to continue: Figure 1.6 – Jira installation step 3 16 Getting Started with Jira Data Center 4. Select where Jira will store its data files, such as attachments and log files. This will become the JIRA_HOME directory. Click on the Next button to continue: Figure 1.7 – Jira installation step 4 5. Select where you would like to create shortcuts to the Start menu and click on the Next button to continue. 6. In the Configure TCP Ports step, we need to select the port that Jira will be listening on for incoming connections. By default, Jira will run on port 8080. If 8080 has already been taken by another application, or if you want Jira to run on a different port such as port 80, select the Set custom value for HTTP and Control ports option and specify the port numbers you want to use. Click on the Next button to continue: Figure 1.8 – Jira installation step 6 7. Select whether you would like Jira to run as a service. If you enable this option, Jira will be installed as a system service and can be configured to start automatically with the server; refer to the Starting and stopping Jira section for more details: Installing and configuring Jira 17 Figure 1.9 – Jira installation step 7 18 Getting Started with Jira Data Center 8. For the final step, review all the installation options and click on the Install button to start the installation: Figure 1.10 – Jira installation step 8 9. Once the installation is complete, check the Launch Jira Software in browser option and click on Finish. This will close the installation wizard and open your web browser so that you can access Jira. This may take a few minutes to load as Jira starts up for the first time: Figure 1.11 – Jira installation step 9 That’s it! Congratulations, your Jira is installed and running. Now, let’s learn how to configure it. The Jira setup wizard If you chose the Launch Jira Software in browser option in the last step of the installation wizard, you should see the Jira setup wizard in your browser window. If not, you can browse to http:// localhost: in your browser, where is the number you assigned to Jira in Step 6 of the installation process. The easy-to-use setup wizard that comes with Jira will walk you through the process of completing your Jira setup. Here, you will be able to configure the database connections, default language, and much more. The steps for this are as follows: 1. In the first step of the wizard, we need to select how we want Jira to be set up. Since we are installing Jira for production use, we will select the I’ll set it up myself option, as shown in the following screenshot: Figure 1.12 – Jira configuration step 1 Installing and configuring Jira 19 20 Getting Started with Jira Data Center 2. For the second step, we will need to select the database we want to use. This is where we configure Jira to use PostgreSQL as its database. If you select the Built In option, Jira will use its bundled in-memory H2 database, which is good for evaluation purposes. If you want to use a proper database, such as in our case, you should select the My Own Database option: Figure 1.13 – Jira configuration step 2 Note The Built In option is great for getting Jira up and running quickly for evaluation purposes. After you have selected the My Own Database option, the wizard will expand for you to provide the database connection details. If you do not have the necessary database driver installed, Jira will prompt you for it. Once you have filled in the details for your database, it’s a good idea to click on the Test Connection button to verify that Jira can connect to the database. If everything has been set up correctly, Jira will report a success message. You should be able to move on to the next step by clicking on the Next button. This may take a few minutes as Jira will now create all the necessary database objects. Once this is done, you will be taken to the next step of the wizard. Installing and configuring Jira 21 3. In the third step, you will need to provide some basic details about this Jira instance. Once you have filled in the requisite fields, click on Next to move on to the next step of the wizard: Figure 1.14 – Jira configuration step 3 4. In this step, we need to provide a license key for Jira. If you have already obtained a license from Atlassian, you can paste it into the Your License Key textbox. If you do not have a license, you can generate an evaluation license by clicking on the generate a Jira trial license link. The evaluation license will grant you access to Jira’s full set of features for 1 month. After the evaluation period ends, you will lose the ability to create new issues, but you can still access your data: Figure 1.15 – Jira configuration step 4 22 Getting Started with Jira Data Center 5. Now, you must set up the administrator account for Jira. It is important that you keep the account details somewhere safe and do not lose the password. Since Jira only stores the hashed value of the password instead of the actual password itself, you will not be able to retrieve it. Fill in the administrator account details and click on Next: Figure 1.16 – Jira configuration step 5 Important note This account is important, and it can help you troubleshoot and fix problems later on. Do not lose it! 6. Next, you must set up your email server details. Jira will use the information configured here to send out notification emails. Notifications are a very powerful feature in Jira and one of the primary ways Jira communicates with users. If you do not have your email server information handy, you can skip this step for now by selecting the Later option and clicking on Finish. You can configure your email server settings later, as you will see in Chapter 8, Emails and Notifications: Installing and configuring Jira 23 Figure 1.17 – Jira configuration step 6 Congratulations! You have completed your Jira setup. You should now see the welcome page, and be automatically logged in as the administrator user you created in Step 5. On the welcome page, you will need to set up a few user preferences, such as the default language and profile picture. Follow the onscreen prompts to set up the account. Once you are done, you should be presented with the options to create a sample project, a new project from scratch, or import project data from other sources, as shown in the following screenshot: Figure 1.18 – Jira welcome page With that, Jira is fully configured. We will cover the various features and things you can do with it later in this book, but for now, we will look at some additional management and configuration options for Jira, starting with how to start and stop Jira as a service. 24 Getting Started with Jira Data Center Starting and stopping Jira Since we used Windows Installer, Jira is installed as a Windows service. Therefore, you can start, stop, and restart it via the Windows Services console. In the Services console, look for Atlassian Jira. Here, you will be able to stop and start the application, as shown in the following screenshot: Figure 1.19 – Windows Services If you installed Jira using the archive options, you can start and stop Jira using the scripts provided in the JIRA_INSTALL\bin directory, which are start-jira.sh and stop-jira.sh for Linux, and start-jira.bat and stop-jira.bat for Windows. Now that we know how to start and stop Jira, let’s look at some of the additional configurations, such as allocating memory. Post-installation configuration The post-installation configuration steps are optional, depending on your needs and environment. If you set up Jira for evaluation purposes, you probably do not need to perform any of the following steps, but it is always good practice to be familiar with these as a reference. You will need to restart Jira after making the changes that will be discussed in the next section. Increasing Jira’s memory The default memory setting for Jira is usually sufficient for a small to medium-sized deployment. As Jira’s adoption rate increases, you will find that the amount of memory allocated by default is no longer enough. If Jira is running as a Windows service, as we described in this chapter, you can increase the memory as follows: 1. Find the service name for Jira. You can do this by going to the Windows Services console and double-clicking on the Atlassian Jira service. The service name will be shown in the General tab; for example, JIRA150215215627. 2. Open a new Command Prompt and change the current working directory to the JIRA_ INSTALL\bin directory. 3. Run the following command by substituting the actual service name for Jira: tomcat8w //ES// 4. Select the Java tab, update the Initial memory pool and Maximum memory pool sizes, and click on OK: Figure 1.20 – Jira memory settings 5. Restart Jira to apply the change. Post-installation configuration 25 26 Getting Started with Jira Data Center If you are not running Jira as a Windows service, you need to open the setenv.bat file (for Windows) or the setenv.sh file (for Linux) in the JIRA_INSTALL\bin directory. Then, locate the following lines: Change the value for the two parameters and restart Jira. Normally, 4 GB (4,096 MB) of memory is enough to support a fairly large instance of Jira used by hundreds of users. The initial memory pool or JVM_MINIMUM_MEMORY parameter determines the amount of memory Jira will start with. Usually, the smaller the amount, the faster Jira will start up. The maximum memory pool or JVM_MAXIMUM_MEMORY parameter determines the maximum amount of memory Jira can use. If the two values are not the same, Jira will start up with the minimum amount of memory and grow to the maximum as more and more users start to use Jira. Important note Make sure that you have sufficient physical RAM available before allocating instances to Jira. Changing Jira’s port number and context path As part of the installation process, the installation wizard prompted us to decide which port Jira should listen to for incoming connections. If you accepted the default value, then this will be port 8080. If you change your mind and want to change this setting later, you can do so by locating and opening the server.xml file in a text editor in the JIRA_INSTALL/conf directory. Let’s examine the relevant contents of this file: This preceding line specifies the port for the command to shut down Jira. By default, it is port 8005. If you already have an application that is running on that port (for example, another instance of Jira), you need to change this to a different port. The following line specifies which port Jira will be running on: By default, Jira will be running on port 8080. If you already have an application that is running on that port, or if the port is unavailable for some reason, you need to change it to another available port. The following line allows you to specify the context that Jira will be running under: set JVM_MINIMUM_MEMORY="384m" set JVM_MAXIMUM_MEMORY="768m" By default, the value is empty, which means Jira will be accessible from http:// hostname:portnumber. If you decide to specify a context, the URL will be http:// hostname:portnumber/context. In our example, Jira will be accessible from http:// localhost:8080/jira. Configuring HTTPS By default, Jira runs with a standard, non-encrypted HTTP protocol. This is acceptable if you are running Jira in a secured environment, such as an internal network. However, if you plan to open up access to Jira over the internet, you will need to tighten up security by encrypting sensitive data, such as usernames and passwords that are being sent, by enabling HTTPS (HTTP over SSL). For a standalone installation, you will need to do the following, in order: 1. Obtain and install a certificate 2. Enable HTTPS on your application server (Tomcat) 3. Redirect traffic to HTTPS First, you need to get a digital certificate. This can be obtained from a certification authority, such as VeriSign (CA certificate), or a self-signed certificate that’s been generated by you. A CA certificate will not only encrypt data for you but also identify your copy of Jira to the users. A self-signed certificate is useful when you do not have a valid CA certificate and you are only interested in setting up HTTPS for encryption. Since a self-signed certificate is not signed by a certification authority, it is unable to identify your site to the public and users will be prompted with a warning that the site is untrusted when they first visit it. However, for evaluation purposes, a self-signed certificate will suffice until you can get a proper CA certificate. For this exercise, we will create a self-signed certificate to illustrate the complete process. If you have a CA certificate, you can skip the following steps: 1. Java comes with a handy tool for certificate management, called keytool, which can be found in the JIRA_INSTALL\jre\bin directory if you are using the installer package. If you are using your own Java installation, then you can find it in JAVA_INSTALL\bin. 2. To generate a self-signed certificate, run the following commands from Command Prompt: 3. This will create a KeyStore (if one does not already exist) and export the self-signed certificate (file.cer). When you run the first command, you will be asked to set the password for the KeyStore and Tomcat. You need to use the same password for both. The default password is changeit. You can specify a different password of your choice, but then you have to let Jira/ Tomcat know, as we will see later. Post-installation configuration 27 keytool -genkey -alias tomcat -keyalg RSA keytool -export -alias tomcat -file file.cer 28 Getting Started with Jira Data Center Now that you have your certificate ready, you need to import it into your trust store for Tomcat to use. Again, you will use the keytool application in Java: This will import the certificate into your trust store, which can be used by JIRA/Tomcat to set up HTTPS. To enable HTTPS on Tomcat, open the server.xml file in a text editor from the JIRA_INSTALL/ conf directory. Locate the following configuration snippet: keytool -import -alias tomcat -file file.cer JIRA_INSTALL\jre\lib\security\cacerts This enables HTTPS for Jira on port 8443. If you have selected a different password for your KeyStore, you will have to add the following line to the end of the preceding snippet before the closing tag: keystorePass="" The last step is to set up Jira so that it automatically redirects from a non-HTTP request to an HTTPS request. Find and open the web.xml file in the JIRA_INSTALL/atlassian-jira/WEB-INF directory. Then, add the following snippet to the end of the file before the closing tag: all-except-attachments *. js *.jsp *.jspa *.css /browse/* CONFIDENTIAL Now, when you access Jira with a normal HTTP URL, such as http://localhost:8080/jira, you will be automatically redirected to its HTTPS equivalent – that is, https://localhost:8443/ jira. Clustering 29 Clustering So far, our Jira instance is running in standalone mode, which means it is serving all the requests by itself and is not yet cluster-enabled. Some of the main benefits of running Jira in a cluster are as follows: • Improved performance at scale: By running a cluster with multiple nodes, Jira’s ability to serve concurrent user requests is greatly improved, leading to better response time and overall user satisfaction. • High availability and failover: With multiple nodes running in a cluster, if any individual node becomes unavailable for any reason, other nodes within the cluster can continue to serve your users, thus avoiding downtime. • Zero-downtime upgrade: Usually, when you need to upgrade Jira, there will be downtime involved in the process. When running a Jira cluster, you can upgrade each node individually at a time so that other nodes in the cluster can continue to serve your users. To configure Jira to run in a cluster, you must do the following: 1. Create a shared file home directory for both nodes to access. 2. Add cluster configuration to our current Jira instance. 3. Add another Jira instance to be the second node in our cluster. Technically, you can have a single node cluster, but for this exercise, we will add another node to the cluster so that you can see the cluster in action. 4. Add and configure a load balancer to distribute incoming traffic to both nodes. Now that we know what we need to run Jira in a cluster, let’s start preparing! Preparing for clustering The first step in enabling clustering is to prepare the hardware required. For a Jira cluster, you will have the following components: • Load balancer: This can be any load balancer that supports session affinity (sticky sessions), such as Apache and nginx. • Jira instance node: This will contain separate Jira instances that will be part of the cluster. • Database: This is the same database you are using for your standalone deployment. Note that since all Jira nodes will be sharing the same database, the in-memory H2 database will not work in a cluster. • Shared file drive: The Jira cluster needs to have a shared home directory that all Jira nodes can read and write to. 30 Getting Started with Jira Data Center Ideally, each component listed previously should be running on its own server, so for a two-node cluster, you will need a minimum of three servers and a shared network drive. You can run multiple Jira nodes on the same server, but you should only do this for evaluation purposes, as it diminishes the benefits of having a cluster. When preparing servers for the Jira nodes, you need to ensure the following: • All node servers are located in the same data center or region (for cloud vendors such as AWS and Azure) • You have the same software and hardware specifications, including memory, operating system, and Java version • All nodes are running the same version of Jira • The nodes have been configured to be in the same timezone Creating JIRA_SHARED_HOME The first step is to create a new directory where the cluster can store its data files. We will refer to this directory as JIRA_SHARED_HOME. This can be a network drive that allows all Jira nodes to read from and write to. Copy over the following directories from your standalone Jira instance’s JIRA_HOME directory to the new shared directory: • data • plugins • logos • import • export • caches Enabling clustering The second step is to enable clustering for your first Jira node. This is done by adding a new cluster. properties file to its local JIRA_HOME directory. 1. Shut down your Jira standalone instance. 2. Create a new file called cluster.properties. 3. Add the following lines to the files: # This ID must be unique across the cluster jira.node.id = node1 4. Start Jira. Adding a node to the load balancer With the first cluster node up and running, we can add another node. We need to add this node to the load balancer so that it can start routing traffic to it. The exact configuration will differ, depending on what you use for the load balancer. The following is an example using Apache: Clustering 31 # The location of the shared home directory for all Jira nodes jira.shared.home = /location/to/the/shared/jira_cluster_ home # The following lines are needed if you want to run multiple nodes on the same server ehcache.listener.hostName=localhost ehcache.listener.port=40001 ehcache.object.port = 40021 # Jira node 1 BalancerMember http://jira1.internal.atlassian.com:8080 route=node1 # Jira node 2, add this when we have the 2nd node up and running # BalancerMember http://jira2.internal.atlassian.com:8080 route=node2 # Load Balancer Settings ProxySet lbmethod=byrequests ProxySet stickysession=JSESSIONID Note that for Apache, you will need to enable the proxy_balancer_module module. Adding new nodes to the cluster To add a new node to the cluster, follow these steps: 1. Copy over the JIRA_HOME directory from our existing Jira instance to the new node server. 2. Install a new Jira instance on the new server. 32 Getting Started with Jira Data Center 3. Edit the cluster.properties files and change the jira.node.id value. 4. Add the new node to the load balancer. 5. Start the new Jira node. If you are running the second node on the same server, you will also need to change the port numbers for ehcache.listener.port and ehcache.object.port in the cluster.properties file, and the port numbers in the server.xml file, as mentioned in the Changing Jira’s port number and context path section. And with this, you should have a two-node Jira cluster up and running. Now, if you log into Jira and go to Administration | System | Clustering, you should see both nodes listed, with the node currently serving you highlighted in bold, as shown here: Figure 1.21 – Cluster nodes in Jira On this page, you can see all the nodes in your cluster and their status. This is very useful to help you troubleshoot your cluster if a node becomes unresponsive or is under heavy load. Zero-downtime upgrade As mentioned earlier, when you are running Jira in a cluster, you can perform a zero-downtime upgrade, also known as a rolling upgrade. With a zero-downtime upgrade, you can upgrade each node in the cluster one at a time. When a node is being upgraded, other nodes in the cluster will continue serving your users, so they will not experience any downtime. Performing a rolling upgrade consists of the following steps: 1. Put Jira into Upgrade mode. This will allow the Jira cluster to have nodes with different versions running at the same time. 2. Upgrade each node in the cluster one at a time. 3. Finalize the upgrade once all the nodes have been upgraded. We will start by putting Jira into Upgrade mode: 1. Log into Jira as an administrator. 2. Browse to Administration | Applications | Jira upgrades. 3. Click Put Jira into upgrade mode: Figure 1.22 – Zero-downtime upgrade Once Jira has been put into Upgrade mode, you can shut down a node in the cluster and upgrade it. After a node has been upgraded, you can restart it and repeat this process for other nodes in the cluster. After you have upgraded all the nodes in the cluster, you need to finalize the upgrade by doing the following: 1. Browsing to Administration | Applications | Jira upgrades. 2. Clicking Finalize upgrade. Once you have clicked on Finalize Upgrade, this will complete the upgrade process for your cluster. By doing a rolling upgrade like this, you can upgrade your entire cluster without disrupting your users with downtime. Zero-downtime upgrade 33 34 Getting Started with Jira Data Center Summary Jira is a powerful, yet simple, application, as reflected in its straightforward installation procedures. You have a wide variety of options available so that you can choose how you would like to install and configure your copy. You can mix and match different aspects, such as operating systems and databases, to best suit your requirements. You can run a standalone deployment to get started, and later turn it into a cluster as the adoption of Jira grows in your organization. In the next chapter, we will start to explore various aspects of Jira, starting with projects, and how you can use Jira to manage them for business teams. 2 Using Jira for Business Projects Jira initially started as a bug-tracking system, helping software development teams track and manage the problems/issues in their projects. As the product evolved, people started using Jira for other purposes. Some use it as a general-purpose task management solution, while others use it as a customer support portal. There are also other creative uses for Jira, such as tracking financial portfolio performances. In this chapter, we will take a look at projects and project types while focusing on the most basic Jira project type – business. Then, we will look at the various user interfaces that Jira has for working with projects, both as an administrator and an everyday user. We will also introduce permissions in the context of projects, which we will expand upon later in this book. Since business is the most basic project type, most of the concepts covered in this chapter will apply to the more specialized types. In this chapter, we will cover the following topics: • Understanding projects and project types • Jira permissions • Creating projects • Project user interfaces • Importing data into Jira • The HR project Understanding projects and project types A project is one of the most important concepts when working with Jira. A project can represent anything from a department or a team in an organization to an actual software project or an IT helpdesk. One way to describe a project is that it is a collection of work items, called issues. It helps provide context when users create and work with issues. For example, a software development team will work with issues in a project that has been created for the product they are working on, while a support team will work within a helpdesk project. 36 Using Jira for Business Projects Project types help define the purpose of the project and provide a tailored experience and set of features to the users. For example, a service management project will have features such as service-level agreements (SLAs), while a software development project will provide support for Scrum or Kanban. Each project type also comes with one or more templates, with a set of predefined configurations to help you get started quickly. The following screenshot shows the project types and their templates from an out-of-the-box Jira installation: Figure 2.1 – Create project The list of project types and templates will vary, depending on what features you have installed and enabled for your Jira deployment. We will look at how you can add additional project types later in this book. For now, we will focus on the Business project type since it is the most basic, and most of its features are shared among other project types. Jira permissions 37 Business projects As we have already seen, Jira comes with several project types, depending on what features you have available. The Business project type is available out of the box and its templates mostly focus on enabling users to easily create tasks and track and report on their progress. The first three templates – Project management, Task management, and Process management – all come with predefined configurations such as workflows and fields. You can use them as is or customize them further, based on your needs. There are other types of projects, such as Service management and Software development, though we will cover these later in this book. Jira permissions Before we start diving into projects, we need to understand a little bit about permissions. Permission is a big topic, and we will cover it in detail in Chapter 9, Securing Jira. For now, we will briefly talk about permissions related to creating, browsing, and administering projects. In Jira, there are several levels of permission: • Global permission: Create and delete projects and administer Jira configuration • Project permission: Browse and administer individual projects • Issue permission: Browse individual issues Users with the Jira administrator global permission will be able to create and delete projects. By default, users in the Jira administrator group have this permission, so the administrator user we created during the installation process in Chapter 1, Getting Started with Jira Data Center, will be able to create new projects. We will refer to this user and any other users with this permission as a Jira administrator. For any given project, users with the Administer Projects permission for that project will be able to administer the project’s configuration settings, as we will see later in this chapter. This means that users with this permission will have access to the Project settings interface for a given project. This allows them to update the project’s details and configurations. By default, the Jira administrator will have this permission. If a user needs to browse the contents of a given project, then they must have the Browse Projects permission for that project. This means that the user will have access to the Project Browser interface for the project. By default, the Jira administrator will have this permission. Now that we have covered the basics of Jira permissions, let’s look at how to create a new project in Jira. 38 Using Jira for Business Projects Creating projects The easiest way to create a new project is to select the Create project menu option from the Projects drop-down menu from the top navigation bar. This will bring up the Create project dialog. Note that, as explained previously, you need to be a Jira administrator (such as the user we created during installation) to create projects. This option is only available if you have this permission. From the Create project dialog, select the template you want to use under the Business heading and click on Next. On the next page, Jira will display the predefined configurations for the template you have selected. In our example, we have selected the Project management template, so Jira provides us with two issue types and a very simple workflow with three steps. Click on the Select button to continue, as shown in the following screenshot: Figure 2.2 – Project management – step 1 Note You can change these configurations after the project has been created. For the third and final step, we need to provide details for the new project. Jira will help you validate the details by making sure that the project key is unique and conforms to the required format. After filling in the project details, click on the Submit button to create the new project, as shown in the following screenshot: Creating projects 39 Figure 2.3 – Project management – step 2 The following table lists the information you need to provide when creating a new project: Field Description Name This is a unique name for the project. Key This is a unique identity key for the project. As you type the name of your project, Jira will auto-fill the key based on the name, though you can replace the auto-generated key with one of your own. You will be able to change the key later. The project key will also become the first part of the issue key for issues created in the project. Project Lead The lead of the project can be used to auto-assign issues. Each project can only have one lead. This option will only be available if you have more than one user in Jira. Table 2.1 – Create project dialog information Once you have created the new project, you will be taken to the Project Browser interface, which we will discuss in the forthcoming sections. You may have noticed that in the Create project dialog, there are three additional options at the bottom: • Import a project: This allows you to import data from other sources, such as a CSV file, into a new or existing Jira project. • Create with shared configuration: This allows you to create a new project based on the configurations of an existing project. This is a great way for you to create a project based on a standard set of configurations quickly, as well as to reduce management overhead by reducing the number of different configurations. 40 Using Jira for Business Projects • Create sample data: This allows you to create a new project and populate it with some sample issues so that you can start exploring the various features offered by different project templates. We will cover importing data into a project in the Importing data into Jira section. Creating a project with sample data is a great way to test out a new project template. Project user interfaces There are two distinctive interfaces for projects in Jira. The first interface is designed for everyday users and provides useful information on how the project uses reports, statistics, and agile boards. We will refer to this interface as the Project Browser interface. The second interface is designed for project administrators to control project configuration settings, such as permissions and workflows; we will refer to this interface as the Project Settings interface. After creating a project, the first interface you see will be Project Browser. We will start by looking at this interface before looking at the Project Settings interface. Project browser The Project Browser will vary, depending on the type of project you create. For business projects, it is relatively simple. A few tabs are available from the left-hand panel: Browser View Description Summary This tab displays a quick overview of the project. It comes in two views: an activity view and a statistics view. Issues This is the primary tab you will be working with. It contains a list of issues in the project. You can configure how issues will be included in the list and what data you want to display. Reports This contains several built-in and custom reports that you can generate based on the issues in the project. The types of reports that are available will vary, depending on the project type. Versions This displays a summary of the versions of the project. This tab is only available when versions have been configured. Components This displays a summary of the components and their related issues. This tab is only available when components have been configured for the project. Add link Here, you can add additional links to the left-hand panel, such as important documents related to the project or links to other useful resources. Table 2.2 – Project Browser tabs Let’s look at some of these tabs in greater detail. The Summary tab The Summary tab provides you with a single-page view of the project you are working on. For business projects, it provides an activity view, which will display the latest activities that are happening in the project, and a statistics view, which provides you with several useful breakdowns of the issues within the project. For example, Unresolved: By Assignee lets you know how many open issues have been assigned to each user, allowing the project team to plan their resource allocation, as shown in the following screenshot: Figure 2.4 – The Summary tab The Issues tab The Issues tab, by default, lists all open issues in the project. It also contains several other predefined filters you can use to look for issues. From here, you can select an individual issue and get more information about it, as shown in the following screenshot: Project user interfaces 41 42 Using Jira for Business Projects Figure 2.5 – The Issues tab The Versions and Components tabs The Versions and Components tabs list all the available versions and components that have been configured for this project, respectively. These two views are only visible if the project contains versions and/or components. We will look at how these can be used later. Project settings The Project settings interface is where project administrators can manage the settings and configurations of their projects. For example, you can change the project’s name and key, select what issue types will be available for the project, and manage a list of components within the project. Only users with the Administer Projects permission for a given project will be able to access this interface. To access the Project settings interface, follow these steps: 1. Go to the Project Browser interface for the project you want to administer. 2. Select the Project settings option at the bottom left. If you do not see this option, then you do not have the necessary permission. From the Project settings interface, you will be able to perform the following key operations: • Update project details, such as the project’s name, description, avatar, and type • Manage what users see when working on the project, such as issue types, fields, and screens • Configure the workflows used by the project • Control permission settings and notifications • Manage the list of available components and versions The preceding key operations can be seen in the following screenshot: Figure 2.6 – Project settings As a project administrator, this is where you will be applying customizations to your project; you can find all the options in the left-hand panel. When you create your project, Jira will automatically create these configurations for you, depending on the template you choose. Let’s take a look at each of these options. The Project details tab The first group of options includes Summary, Details, Audit log, Re-index project, and Delete project. Let’s take a look at them in more detail: • Summary: Displays a single-page view of all the current configuration settings for the project. • Details: Allows you to change the project’s general information, including the project key, type, avatar, description, and category. • Audit log: This is a new feature in Jira Data Center that will show you a list of configuration changes that have been made to the project (note that this does not include changes made to issues). It will show you what was changed, when the change happened, and who made the change. • Re-index project: This feature re-indexes the project to update the search index for issues in this project. You should do this when configuration changes have been made to the project, such as new fields being added. • Delete project: This feature deletes the project and all its issues. This operation cannot be undone. Project user interfaces 43 44 Using Jira for Business Projects The Components tab The Components tab is where project administrators can manage the components for their projects. Components can be thought of as subsections that make up the full project. In a business project, components can be various business functions or operations that need to be completed. As shown in the following screenshot, three components have been configured in the current project: Figure 2.7 – Components Components are project-specific in Jira. This means that components from one project cannot be used in a different project. This also allows each project to maintain its own set of components. A component has four pieces of information, as shown in the following table: Field Name Description Description This is the unique name of the component. The description is optional but explains what the component is for. Table 2.3 – Component fields Lead This is an optional field where you can select a single user as the lead for the component. For example, in a software project, this can be the main developer for the component. Default assignee This tells Jira when an issue is created without the assignee being selected. If the issue has a component, then Jira will auto-assign the issue to the selected default assignee. One of the useful features of components is the ability to assign a default assignee to each component. This means that when a user creates an issue with a component and sets the assignee as Automatic, Jira will be able to automatically assign the issue based on the component selected. This is a very useful feature for organizations where members of various teams often do not know each other. Therefore, when it comes to assigning issues at creation time, they often find it difficult to decide who to assign them to. This feature can be set up so that the lead of the component becomes the default assignee. This means that the issues that have been raised can be delegated to other members of the team. Note If the issue has more than one component with a default assignee, the assignee for the first component (in alphabetical order) will be used. The Versions tab Like the Components tab, the Versions tab allows project administrators to manage versions for their projects. Versions serve as milestones for a project. In project management, versions represent points in time. While versions may seem less relevant for projects that are not product-oriented, they can still be valuable when it comes to managing and tracking the progress of issues and work. As with components, versions also have several attributes, as shown in the following table: Project user interfaces 45 Field Name Description Start Date Description This is the unique name of the version. The description is optional but explains what the version is for. This is a date indication that states when work on this version is expected to start. Table 2.4 – Version fields Release Date This is an optional date that will be marked as the scheduled date when the version will be released. Versions that are not released according to the release date will have their dates highlighted in red. Versions are mostly used in software development projects where a software product has a release version. It is less applicable to business projects, but if there is a need to keep track of versions, such as for documents, you can use this tab to keep track of tasks that are related to a specific version. 46 Using Jira for Business Projects Other tabs There are several other tabs in the Project settings interface. We will not explore these tabs in this chapter as they will be covered in separate chapters. We will, however, take a look at what each tab does, as shown in the following table: Tab Description Issue types This tab controls the types of issues that users can create for the project. For example, this may include bugs, improvements, and tasks. Issue types will be covered in Chapter 4, Working with Issues. Workflows This tab controls the workflow issues that we will go through. Workflows consist of a series of steps that usually mimic the existing processes that are in place for the organization. Workflows will be covered in Chapter 7, Workflow and Business Process. Screens Screens are what users see when they view, create, and edit issues in Jira. Screens will be covered in Chapter 6, Screen Management. Fields These are what Jira uses to capture data from users when they create issues. Jira comes with a set of default fields and the Jira administrator can add additional fields as needed. Fields will be covered in Chapter 5, Field Management. Users and roles Project administrators can define roles in the project and assign users to them. These roles can then be used to control permissions and notifications. Roles will be covered in Chapter 9, Securing Jira. Permissions As we have already seen, permissions define who can perform certain tasks or have access to Jira. Permissions will be covered in Chapter 9, Securing Jira. Issue Security Jira allows users to control who can view the issues they have created by selecting the issue security level. Issue security will be covered in Chapter 9, Securing Jira. Notifications Jira can send out email notifications when certain events occur. For example, when an issue is updated, Jira can send out an email to alert all users who have participated. Notifications will be covered in Chapter 8, Emails and Notifications. Table 2.5 – Project settings tabs Importing data into Jira 47 Now that we have looked at both of Jira’s user interfaces, let’s learn how to import data into Jira. Importing data into Jira Jira allows you to import data from other sources, such as other issue tracking systems, and tells you whether the data can be exported in a supported format, such as CSV or JSON. All the importers have a wizard-driven interface that guides you through a series of steps. These steps are mostly identical but have a few differences. Generally speaking, there are four steps when it comes to importing data into Jira, as follows: 1. Select your source data – for example, a CSV file. 2. Select a destination project where the imported issues will go. This can be an existing project or a new project created on the fly. 3. Map fields from the source (for example, CSV) to Jira fields. 4. Map field values from the source to Jira field values. This is usually required for select-based fields, such as the priority field, or select list fields. For fields such as text and number fields, this is not required. Now, let’s see how to import data using a CSV file. Importing data through CSV Jira comes with a CSV importer, which lets you import data in the comma-separated value (CSV) format. This is a very useful tool as most systems can export data in this format. You can also convert an Excel spreadsheet into a CSV file with this tool. Before you can import a CSV file into Jira, you need to make sure you format your data properly. Here is a checklist of items you must verify before importing your data: • Each row must be imported as a single issue, so make sure you have all the values for the issue in a single row. • Each column should map to a corresponding Jira field. This can be either a system field or a custom field. • At a minimum, you will need to have values for the required fields, such as the issue summary. • All date or date-time values need to be in a consistent format. • If a column is to be mapped to a user field, such as assignee, make sure you have the correct username values. • If a column is to be mapped to a selection-based field, such as a select list or a checkbox, make sure you check the spelling of the values. 48 Using Jira for Business Projects Once you have formatted your CSV file, follow these steps to import it into Jira: 1. Select the Import External Project option from the Projects drop-down menu. 2. Click on the CSV option. This will start the import wizard. 3. Now, you need to select the CSV file that contains the data you want to import by clicking on the Choose File button. 4. After you have selected the source file, you can expand the Advanced section to select the file encoding and delimiter that’s used in the CSV file. There is also the Use an existing configuration file option, which we will talk about later in this section. 5. Click on the Next button to proceed, as shown in the following screenshot: Figure 2.8 – CSV File import 6. Next, you need to select the project you want to import your data into. You can also select the Create New option to create a new project on the fly. 7. If your CSV file contains date-related data, ensure that you enter the format that was used in the Date format field. 8. Click on the Next button to proceed, as shown in the following screenshot: Importing data into Jira 49 Figure 2.9 – Map projects 9. Next, you need to map the CSV fields (columns) to the fields in Jira. Not all fields need to be mapped. If you do not want to import data from a particular column, simply do not map the CSV field to a Jira field. 10. For fields that contain data that needs to be mapped manually, such as select list fields, you need to check the Map field value checkbox. This will let you map the CSV field value to the Jira field value so that it can be imported correctly. If you do not manually map these values, they will be copied over as is. For fields such as select lists, new options will be automatically created. 50 Using Jira for Business Projects 11. Click on the Next button to proceed, as shown in the following screenshot: Figure 2.10 – Map fields 12. Finally, you need to map the CSV field value to the Jira field value. This step is only required if you checked the Map field value checkbox for a field in step 10: A. Enter the Jira field value for each CSV field value. B. Once you have mapped the field values, click on the Begin Import button to start the actual import process, as shown in the following screenshot. Depending on the size of your data, this may take some time to complete: Importing data into Jira 51 Figure 2.11 – Map values 13. Once the import process completes, you will get a confirmation message telling you the number of issues that have been imported, as shown in the following screenshot. This number should match the number of records you have in the CSV file: Figure 2.12 – Completed import process On the last confirmation screen, you can click on the download a detailed log link to download the full log file containing all the information for the import process. This is particularly useful if the import was not successful. You can also click on the save the configuration link, which will generate a text file containing all the mappings you have done for this import. If you need to run a similar import in the future, you can use this import file so that you don’t need to manually remap everything again. To use this configuration file, check the Use an existing configuration file option that was shown in step 4. As we can see, Jira’s project importer makes importing data from other systems straightforward. In the next section, we will learn how to archive old projects to help improve performance in Jira. 52 Using Jira for Business Projects Archiving projects and issues As you continue to use Jira, users will notice Jira’s performance starting to degrade over time. Some more noticeable examples include loading the Jira dashboard and searching for issues. Data size is indeed a major factor when it comes to Jira’s performance – the more projects, issues, and related configurations (such as custom fields) that you have, the more data Jira will need to process, and the slower it will be for your end users. The practice of archiving old and unused projects is often the solution to this problem. Before Jira Data Center, archiving a project would require you to either export and then delete the project completely, or hide the project and its issues by removing permissions from users. Both approaches are convoluted and can be error-prone. With Jira Data Center, there is now a built-in archive feature that makes the process simple and reliable. To archive a project, follow these steps: 1. Log into Jira with an administrator account. 2. Browse to Administration | Projects. 3. Select the Archive option for the project you wish to archive, as shown here: Figure 2.13 – Archiving a project 4. Confirm that you want to archive the project when prompted: Figure 2.14 – Archive project – confirmation The HR project 53 Once a project has been archived, it will no longer be listed for end users. Issues from the archived project will not show up in any searches. However, if you have a direct link to the issue, it can still be accessed, though you cannot make any changes to it. By archiving a project, all data related to the project, such as issues, will be removed from Jira’s search index. This will keep the index size low and improve the overall performance. If you need to restore an archived project, follow these steps: 1. Browse to Administration | Projects | Archived projects. 2. Select the Restore option for the project you wish to restore. 3. Go to the restored project and click on the Start project re-index button. Since an archived project will have its data removed from Jira’s search index, you will need to re-index the project before its issues will be displayed in the search results. It is worth noting that one difference between archiving a project and deleting a project is that when you archive a project, any configurations related to the project are still considered to be in use, so you cannot delete them. This is because Jira needs to make sure that when you unarchive the project, all the configurations are still available. The HR project Now that we have seen all the key aspects that make up a project, let’s revisit what you have learned so far and put it into practice. In this exercise, we will set up a project for our human resources (HR) team to help them track and manage employees joining and leaving the company, as well as tasks related to the recruitment process. Creating a new project First, we will start by creating a new project for the HR team. To create the project, follow these steps: 1. Bring up the Create project dialog by selecting the Create project option from the Projects drop-down menu. 2. Select the Task management project template. We can use other templates in the Business project type, but the Task management template is the simplest option and will make future customization easier. 3. Name our new project Human Resource and accept the other default values for Key and Project Lead. 4. Click on the Submit button to create the new project. At this point, you will be taken to the Project Browser interface for the new project. 54 Using Jira for Business Projects Creating new components Now that our new project is in place, we need to create a few components. These components will serve as groupings for our tasks. We need to perform the following steps to create our new components: 1. Click on the Project settings option in the bottom-left corner. 2. From the Project settings interface, select the Components tab. 3. Enter Employee Onboarding for the new component’s name. 4. Provide a short description of the new component. 5. Select a user to be the leader of the component. 6. Click on Add to create the new component. 7. Add a few more components. With projects created with the Business project type, components are not displayed by default, so we will have to manually add the Components field to the appropriate screens. We will cover fields and screens in Chapter 3, Field Management, and Chapter 6, Screen Management, respectively. For now, follow these steps to get our components to display when we create, edit, and view tasks: 1. From the Project Administration interface, select the Screens tab. There should be three screens, as shown in the following screenshot: Figure 2.15 – Project screens 2. Click on HR: Task Management Create Issue Screen. This will open the Configure Screen page, with a list of fields that are currently on the selected screen. 3. Enter and select Component/s in the select field at the bottom of the page; this will add the Components field to the screen. 4. Repeat steps 2 and 3 for HR: Task Management Edit/View Issue Screen. Putting it all together Now that you have fully prepared your project, let’s see how everything comes together by creating an issue, as follows: 1. Click on the Create button from the top navigation bar. This will bring up the Create Issue dialog box. 2. Select Human Resource for Project and Task for Issue Type. 3. Fill in the fields with some dummy data. Note that the Component/s field should display the components we just created. 4. Click on the Create button to create the issue. If everything has been done correctly, you should see a dialog box similar to the following, where you can choose your new project to create the issue in, as well as the new components that can be selected: Figure 2.16 – Create Issue The HR project 55 56 Using Jira for Business Projects You can test out the default assignee feature by leaving the Assignee field set to Automatic and selecting a component; Jira will automatically assign the issue to the default assignee that’s been defined for the component. If everything goes well, the issue will be created in the new project. Summary In this chapter, we looked at one of the most important concepts in Jira – projects – and how to create and manage them. Permissions were introduced, and we looked at three permissions that are related to creating, browsing, and administering projects. We also looked at the very useful project archiving feature introduced in Jira Data Center, and how you can use it to help improve Jira performance by archiving unused projects. We were also introduced to the two interfaces Jira provides for project administrators and everyday users – the Project settings interface and the Project Browser interface, respectively. In the next chapter, we will learn how to create projects using the Software project type to enable Scrum and Kanban to run agile projects. Part 2: Jira in Action In this section, you will learn how to use Jira. You will get acquainted with techniques for handling different issues, exploring fields, creating new screens, managing workflows, and setting up incoming and outgoing email servers. The following chapters are included in this section: • Chapter 3, Using Jira for Agile Projects • Chapter 4, Working with Issues • Chapter 5, Field Management • Chapter 6, Screen Management 3 Using Jira for Agile Projects In the previous chapter, we looked at the basics of the Jira project and used Jira for generic task management. In this chapter, we will focus on using Jira for agile software development projects with Scrum, Kanban, and Kanplan. We will provide a brief overview of each of the agile methodologies and look at how to use Jira for both. In this chapter, we will cover the following topics: • Getting an overview of Scrum and Kanban • Running a project with Scrum in Jira • Running a project with Kanban in Jira • Configuring agile boards • Grooming your backlog • Creating a new agile board for your project • Including multiple projects on your board Getting an overview of Scrum and Kanban Scrum and Kanban are the two agile software development methodologies that are supported by Jira. If you are already familiar with Scrum and Kanban, feel free to skip this section. However, if you come from a more traditional waterfall model and are new to the agile methodologies, then here is a quick overview of them both. I would strongly recommend that you pick up an additional resource to learn more about each of the methodologies. A good place to start is the Atlassian Agile Coach, which can be found at https://www.atlassian.com/agile/about. We will take a quick look at both Scrum and Kanban in this section. 60 Using Jira for Agile Projects Scrum Scrum is different from the waterfall model in that it prescribes the notion of iteration. With Scrum, a project is divided into several iterations, called sprints, each lasting from 2 to 4 weeks, to produce a fully tested and potentially shippable product at the end. At the beginning of each sprint, the product owner and the team come together in what is called a sprint-planning meeting. In this meeting, the scope of the next sprint is decided. This usually includes top-priority items from the backlog, which contains all incomplete work. During each sprint, the team meets daily to review progress and flag any potential problems or impediments, and plans how to address them. These meetings are short, and the goal here is to make sure that everyone on the team is on the same page. At the end of the sprint, the team will come together to review the outcome of the sprint and look at the things they did right and the things that did not go well. The goal is to identify areas of improvement, which will feed into future sprints. This process continues until the project is completed. Kanban Kanban, unlike Scrum, which runs in iterations, focuses more on the actual execution of the delivery. It has a heavy emphasis on visualizing the delivery workflow from start to finish, places limits on different stages of the workflow by controlling how many work items are allowed to be in each stage, and measures the lead time. With Kanban, it is important to be able to visually see the work items going through the workflow, identify areas of inefficiency and bottlenecks, and correct them. It is a continuous process, with work coming in from one end and going out from the other, making sure that things go through as efficiently as possible. Running a project with Scrum in Jira Scrum is the first agile methodology we will look at. With Jira, a Scrum project consists mainly of two components – the backlog where you and your team will do most of your planning, and the active sprint agile board, which your team will use to track the progress of their current sprint. Let’s start with creating a new Scrum project in Jira. Creating a Scrum project The first step to working with Scrum in Jira is to create a project using the Scrum template. Follow these steps to do so: 1. Select the Create project option from the Projects drop-down menu. 2. Choose the Scrum software development template and click Next: Running a project with Scrum in Jira 61 Figure 3.1 – Creating a Scrum project 3. Accept the settings and click Next. 4. Enter the name and key for the new project and click Submit. Once the new Scrum project has been created, you will be taken to the Scrum interface, as shown in the following screenshot: Figure 3.2 – Scrum interface 62 Using Jira for Agile Projects The Scrum interface has the following main sections: • Backlog: This is where all unplanned issues are stored. You can think of it as a to-do list. The product owner and the development team will work together to define the priorities of issues in the backlog, which will then be scheduled into sprints for delivery. • Active sprints: This view shows the sprints that are currently underway and the issues that are part of the sprints. This is what the development team will use on a day-to-day basis to track their progress. • Reports: This view contains several reports that you can generate to view the project’s performance. These reports help you and your team visualize how the project is progressing and provide valuable feedback that you can use in future sprint-planning sessions for improvements. Let’s take a closer look at each of these sections, starting with the backlog. Working with the backlog The backlog is the to-do list of your project and is where you keep all your incomplete features (usually represented as stories) and tasks. When you first start, you may have an empty backlog, so the first step is for the product owner and the team to work together to populate it with stories and tasks that need to be completed. During this step, it works more like a brainstorming session, where the team works together to translate requirements from customers and other stakeholders into actionable stories and tasks. Prioritizing and estimating work Once you have populated the backlog, the next step is to estimate and prioritize the issues so that you can plan and build a schedule of how to complete them. In Jira, prioritizing issues in the backlog means dragging and dropping them up and down in the backlog. To increase the priority of an issue, you can simply drag it higher in the backlog list. While it is usually the product owner’s responsibility to prioritize which features to deliver first, the team should also be involved in this process to make sure that everyone is in sync regarding the direction of the project. Estimating work is a critical part of Scrum, and the success of your sprints heavily depends on how well you and your team can estimate. One thing people often get confused about is that they tend to think of estimation in terms of time – for example, story A will take 5 hours to complete and story B will take 10 hours. While this may seem right at first, what will often end up happening is that people will either work extra hard to make the estimate seem accurate or give big estimates because they are uncertain about the task at hand. This can lead to problems as the project goes on since nobody wants to be known as either the person that cannot give a reliable estimate or the person that is inefficient because they constantly go over the estimates. One way to avoid this pitfall is to use a different approach to estimation called story points, which is the default estimation method in Jira. The idea behind this is to measure and estimate issues based on their complexity, rather than simply the time required to complete them. So, if you start a sprint with a total of 10 story points worth of issues, and at the end of the sprint you are unable to complete all of them, this might indicate that you have been too aggressive and may need to reduce your expectations. Since the estimation is not made based on the time taken, it simply indicates that perhaps the issues are too complex, and you will need to break them down further into more digestible pieces. This helps prevent people from feeling like they are constantly running against the clock and helps you better define and break down tasks into smaller, more manageable chunks. Sometimes, however, you may find it difficult to estimate the complexity of your stories. This is usually a sign that you either do not have enough information about the story or that the story’s scope is too big and needs to be broken down. It is important for the team to realize this and not shy away from going back to ask more questions so that they can fully understand the purpose of the story before providing an estimate. Now that we have determined a way to estimate our issues, we can move on. Entering the estimate is as simple as doing the following: 1. Select the issue to estimate from the backlog. 2. Enter the number of story points into the Estimate field, as shown in the following screenshot: Figure 3.3 – Story points Running a project with Scrum in Jira 63 64 Using Jira for Agile Projects You should not change the estimate once the issue has been added to an active sprint. Changing the estimate mid-sprint can lead to bad estimation during the spring planning phase and future improvements. Creating a new sprint With the backlog populated and issues estimated, the next step is to create a sprint for the team to start working on. Note that you will need to have the Manage Sprints permission to create new sprints. Permissions will be covered in Chapter 9, Securing Jira. To create a new sprint, follow these steps: 1. Go to the backlog of your project. 2. Click on the Create sprint button. 3. Enter a name for the sprint. 4. Select the duration of the sprint and click on the Create button. Generally speaking, you want to keep your sprint short. Between 1 and 2 weeks is usually a good length. 5. Add issues to the sprint by dragging and dropping issues that have been prioritized by the team into the sprint box, as shown in the following screenshot: Figure 3.4 – Creating a sprint Once the team has decided on the scope, it’s time to start the sprint: 1. Click on the Start sprint button. 2. Updating the sprint’s duration is necessary. Click on the Start button to start your sprint, as shown in the following screenshot: Running a project with Scrum in Jira 65 Figure 3.5 – Starting a new sprint You can select the Custom option for the sprint’s duration if you want to specify the end date of the sprint yourself instead of using the auto-calculated date. Once the sprint has been started, you can go to the active sprints view and the team can start working on the delivery. If the Start sprint button is grayed out, this means that you already have an active sprint running and do not have the parallel sprints option enabled, or that you do not have the Manage Sprints permission. Permissions will be covered in Chapter 9, Securing Jira. Normally, you will only have one team working on the project at any given time, but if you have a big team, and people can work on different parts of the project at the same time, you need to enable the Parallel Sprints option: 1. Log into Jira as an administrator. 2. Browse the Jira administration console. 3. Select the Applications tab and then Jira Software configuration. 4. Check the Parallel Sprints option to enable it. With the Parallel Sprints option enabled, you can start multiple sprints at the same time. When running multiple sprints, it is best to keep them separate from each other so that they do not get in each other’s way. A good example is having two sprints focusing on different areas of the project, such as delivery and documentation. 66 Using Jira for Agile Projects When you have parallel sprints, since the active sprint view (see the next section) will only show one sprint at a time, you will need to toggle between the sprints, as shown in the following screenshot: Figure 3.6 – Scrum sprint With a sprint created, let’s take a look at what happens during the sprint. Running a sprint Once the team has prioritized the issues and started a sprint during the sprint-planning meeting, the agile board will switch over to the active sprint view. For normal teams, you will have one active sprint at any given time, and your active sprint board will look as follows: Figure 3.7 – Active sprint board On the Scrum board, each issue is represented as a card, and the board itself is made up of vertical columns that represent the various states an issue can be in, and they are mapped to the workflow that’s used by the project. So, in our example, we have the default workflow with three states – To Do, In Progress, and Done. As we will see later, the project administrator will be able to customize this. Team members move the issue card across the board into the appropriate columns as they work and complete their tasks. The board can also be divided into several horizontal rows called swimlanes. These help you group similar issues and make your board easier to understand. In our example, we are grouping issues into swimlanes based on stories. Just like columns, the project administrator can customize how swimlanes should be defined. When a sprint is underway, it is important to avoid introducing scope creep by adding more issues to the sprint, and it falls on the Scrum master and the product owner to make sure that the team is not distracted or blocked by any impediments. However, from time to time, emergencies that demand certain features or fixes that need to be included do arise, and in these cases, you can add new issues to the active sprint from the backlog view. However, keep in mind that this should not become a common habit, as it is a distraction, and is usually a sign of bad sprint planning or poor communication with stakeholders. For this reason, Jira will prompt you whenever you try to add more issues to an active sprint, as shown in the following screenshot: Figure 3.8 – Sprint scope creep Running a project with Scrum in Jira 67 68 Using Jira for Agile Projects At the end of the sprint, you need to complete the sprint by doing the following: 1. Go to the Scrum board and click Active sprints. 2. Click on the Complete sprint link, as shown in the following screenshot: Figure 3.9 – Complete sprint 3. Click on the Complete button to finish the sprint. Once you have completed a sprint in Jira, any unfinished issues will be placed back into the backlog. Sometimes, you may have other sprints that are planned but not active; in this case, issues that are not completed from the current active sprint can be automatically added to the next available sprint. It can be tempting to extend the sprint for just a few more days because you have just one more issue to complete. While this is not a hard rule, you should generally avoid this and just let the incomplete issue go back to the backlog and reprioritize it during the next sprint meeting. This is because Scrum is an iterative process, and the goal is not to make everyone work as hard as possible but to be able to retrospectively look at what the team did right and/or wrong in the previous sprint and address that in the next sprint. Perhaps the reason for this is because of an inaccurate estimation or incorrect assumptions that were made during requirement gathering. The point here is that the team should view this as an opportunity to improve rather than a failure to be rushed through. Simply extending the current sprint to accommodate incomplete items can turn into a slippery slope where the practice of extending sprints becomes the norm and the root problem is masked. Running a project with Kanban in Jira Now that we have seen how to run projects with Scrum, it is time to look at the other agile methodology Jira supports – Kanban. Compared to Scrum, Kanban can be a simpler methodology to get started with for teams that are new to agile. Unlike Scrum, which has a backlog and requires the team to prioritize and plan their delivery in sprints, Kanban focuses purely on the execution and measurement of throughput. In Jira, a typical Kanban board will have the following differences compared to a Scrum board: • There is no backlog view by default. Since Kanban does not have a sprint-planning phase, your board acts as the backlog. We will see how to enable backlog for Kanban later in this chapter. • There are no active sprints. The idea behind Kanban is that you have a continuous flow of work. • Scrum and Kanban have different types of reports that are specifically designed for each of the methodologies. • Columns can have minimum and maximum constraints. • Columns will be highlighted if the constraints are violated. As shown in the following screenshot, both the SELECTED FOR DEVELOPMENT and IN PROGRESS columns are highlighted because of constraint violations: Figure 3.10 – Kanban board Now that we have seen what a Kanban project looks like in Jira, let’s learn how to create a Kanban project. Running a project with Kanban in Jira 69 70 Using Jira for Agile Projects Creating a Kanban project The first step to working with Kanban in Jira is to create a project with the Kanban template. Follow these steps: 1. Select the Create project option from the Projects drop-down menu. 2. Choose the Kanban software development template and click Next, as shown in the following screenshot: Figure 3.11 – Creating a Kanban project 3. Accept the settings and click Next. 4. Enter the name and key for the new project and click Submit. After you have created a Kanban project, you will be taken to the Kanban board view, which looks very similar to the active sprint view of a Scrum board. Remember, with Kanban, it is as if you are running a sprint that does not end, or that ends when the entire project is completed. Therefore, the agile board itself focuses on helping you and your team to execute the delivery. Using the Kanban board As we mentioned earlier, with Kanban, there is no sprint planning by default, so instead of having a backlog, everything happens on the Kanban board directly. Working with the Kanban board is very simple; newly created issues are added to the first column of the board directly, named BACKLOG (by default), as it acts as your backlog of issues with Kanban. Members of the team will then grab issues from the BACKLOG column, assign the issue to them, and move them through the workflow. During various stages, issues may need to be reassigned to other users – for example, when an issue leaves the development stage and enters testing, it may be reassigned to a test engineer. As more and more issues are completed, you can configure the board to automatically take completed issues off the board after a period or perform a release, which will take all issues in the DONE column from the board (still in the system). The first option is good for teams using Kanban for general task management, and the option to use releases fits better with software development where versions can be released. Let’s look at an example of the Kanban board, as shown in the following screenshot, in which we can see that we have problems in both the In Development and In Testing phases of our process. In Development is highlighted in red, meaning that we have enough work there, which is a sign of a bottleneck. In Testing is highlighted in yellow, which means that we do not have enough work, which is a sign of inefficiency: Figure 3.12 – Kanban board With this, the board can visually tell us where we are having problems, which allows us to focus on these problem areas. The bottleneck in the In Development phase could mean that we do not have enough developers, which causes the inefficiency in the In Testing phase, where our testers are simply sitting around waiting for work to come through. Running a project with Kanban in Jira 71 72 Using Jira for Agile Projects This raises a common question – what should the correct constraints be for my columns? The quick answer is to try and experiment as you go. The long answer is that there is no single correct, silver bullet answer. What you need to understand is that many factors can influence the throughput of your team, such as the size of your team, a team member leaving or joining, and the tasks at hand. In our example, the easy solution would be to lower the limit for both columns, and then we are done. But often, it is just as important for you to find the root cause of the problem rather than trying to simply fix the board itself. Perhaps what you should try to do is get more developers on your team so that you can keep up the pace that is required for delivery. The takeaway here is that the Kanban board can help you pinpoint the areas of a problem, and it is up to you and your team to figure out the cause and find the appropriate solution. Enabling a backlog for Kanban For those of you who come from Scrum, not having a proper backlog may feel uncomfortable, or perhaps as your project grows, having all the new issues being displayed on the Kanban board in the BACKLOG column becomes too unwieldy. The good news is that Jira supports a hybrid methodology of Kanban and Scrum, called Kanplan, which lets you have a backlog for Kanban as well. To add a Scrum-style backlog to your Kanban project, you can simply map the appropriate status into the Kanban BACKLOG column. Follow these steps: 1. Browse your project’s agile board. 2. Click on the Board menu and select the Configure option. 3. Select the Columns option from the left navigation panel. By default, there is a column called BACKLOG. 4. Delete the BACKLOG column. 5. Drag and drop the now unmapped Backlog status from the Unmapped Statuses column on the right to the Kanban backlog on the left, as shown in the following screenshot: Figure 3.13 – Configuring the Kanban backlog With a status mapped in the Kanban backlog column, you will now have a backlog that looks and works just like a Scrum project, and any newly created issues will be added to the backlog since they will be in the backlog workflow status, as shown in the following screenshot: Figure 3.14 – Kanban backlog You can map more than one status to the backlog, and as we will see in Chapter 7, Workflow and Business Process, when we cover workflows in depth, you may have a more complex process, and issues in different statuses can appear in the backlog. Another benefit of having a backlog for Kanban is that if you have hundreds of issues, it is a lot faster and more efficient for Jira to display them this way than on the Kanban board. Since there could be hundreds of issues in your backlog, the backlog view also has a quick search bar that lets you quickly filter and look for the issues you need. If you have your issues assigned to epics and versions, you can also use the EPICS and VERSIONS panel to display the issues that are relevant to the epics and versions you select. Now that we have seen how to use Jira to run both Scrum and Kanban projects, let’s take a look at how to customize our agile board. Running a project with Kanban in Jira 73 74 Using Jira for Agile Projects Configuring agile boards Jira’s agile board is highly customizable, and many of the customization options leverage the core features of Jira, such as workflows. If you are not familiar with them, do not worry – we will cover these at a high level in the context of the agile board and dive into the details of each later in this book. In this section, we will explore these customization options, starting with the board’s column layouts. Configuring columns For both Scrum and Kanban, the board’s columns are mapped to the workflow that’s used by the project, and the default workflow that’s created is very simple. For example, the default Scrum workflow contains three statuses – To Do, In Progress, and Done. However, this is often not enough, as projects will have additional steps in their development cycle, such as testing and review. To add new columns to your board, follow these steps: 1. Browse your project’s agile board. 2. Click on the Board menu and select the Configure option. 3. Select the Columns option from the left navigation panel. 4. Click on the Add column button. 5. Enter the name for the new column and select its category. Generally, your new column will fall into the In Progress category, unless you are replacing the To Do or Done column: Figure 3.15 – Add column Configuring agile boards 75 6. Drag and drop the new column to place it in the correct location within your development workflow. 7. Check the Set resolution checkbox if the column represents the completion of the issue – for example, Done. This will automatically set the issue’s resolution to Done. If you want to be able to choose the resolution value or use a different resolution value when completing an issue, don’t worry – we will cover this in Chapter 7, Workflow and Business Process. For projects that are using the workflows that were created along with your new project (also known as a Simplified Workflow), this is all you need to do to customize your columns, as shown in the following screenshot. If you have an existing workflow and want to adapt your columns to that, then you will learn how to do this when we cover workflows in Chapter 7, Workflow and Business Process. Adding column constraints In the previous section, we mentioned that one of the key aspects of Kanban is to control the amount of work that is sent through. While work constraints are a concept that’s used in Kanban, sometimes, people also adopt it with Scrum. This allows you to use Scrum for planning and Kanban for execution in a hybrid methodology called Scrumban. To set up column constraints for your agile board, follow these steps: 1. Browse your project’s agile board. 2. Click on the Board menu and select the Configure option. 3. Select the Columns option from the left navigation panel. 4. Select how you want the constraint to be calculated in the Column Constraint option. By default, the Kanban board will use the Issue Count option, while the Scrum board will not have any default constraints. 5. Enter the minimum and maximum value for each of the columns you want to apply a constraint to. 76 Using Jira for Agile Projects You do not have to set both the minimum and maximum for a constraint. Consider the example that’s shown in the following screenshot, where we have set the constraint for Selected for Development so that it has at least two issues and no more than 10. For the In Progress column, we have only limited it to no more than five issues, but there is no minimum value, meaning that it can have no issues at all. We also placed a maximum limit of 15 issues for the Done column so that we are alerted when the team has reached the threshold of completed issues and a release needs to be made: Figure 3.16 – Column constraints After you have set the column constraints for your board, every time the constraints are violated, Jira will immediately alert you on your agile board. For example, in the following screenshot, we have two issues in the Selected for Development column, which has a minimum of three issues, so the column is highlighted in yellow. In the In Progress column, we have six issues, and since it has a maximum limit of 5 issues, the column is highlighted in red. Note that while Jira will highlight the columns when a constraint is violated, this does not stop you from breaking the constraints. It is simply a way to alert the team that something has gone wrong in the process and that it needs to be reviewed and corrected: Figure 3.17 – Constraint violation Configuring agile boards 77 Columns help visualize the workflow and status issues. Now, let’s look at how we can group similar issues on the board. Setting up swimlanes As we saw earlier, Jira’s agile board lets you group similar issues together in horizontal rows called swimlanes. Unlike columns, which are mapped to workflow statuses, you can define swimlanes based on any criteria, including custom fields you have added yourself. To set up swimlanes for your board, follow these steps: 1. Browse your project’s agile board. 2. Click on the Board menu and select the Configure option. 3. Select the Swimlanes option from the left navigation panel. 4. Select how you want to define your swimlanes in the Base Swimlanes on field. 5. If you choose the Queries option, you will need to define the query for each swimlane you want to add to the board. There are six options to choose from when choosing how swimlanes will be defined, as shown here: • Queries: Swimlanes will be based on the Jira Query Language (JQL) queries you define. For each swimlane, you need to define the JQL query that will return the issues you want for the swimlane. Issues that match more than one query will only be included in the first swimlane. JQL will be covered in Chapter 10, Searching, Reporting, and Analysis. • Stories: Swimlanes will be based on user stories. Subtasks that belong to the same story will be displayed in the same swimlane. Subtasks will be covered in Chapter 4, Working with Issues. • Assignees: The swimlane will be based on each issue’s assignee. Issues with the same assignee will be grouped in the same swimlane. The sample Scrum board we saw in the Scrum section uses this option. • Epics: Swimlanes will be based on epics that each issue belongs to. Issues in the same epic will be grouped into the same swimlane. • Projects: Swimlanes will be based on the project that each issue belongs to. As we will see later in this chapter, an agile board can include issues from multiple projects. • No Swimlanes: The agile board will not be using swimlanes, so all issues will be grouped in a single row. As shown in the following screenshot, we are using the Queries option and we have defined two swimlanes (and the default Everything Else lane). For the JQL query, we are searching based on a custom field that we have created called Source to determine whether the feature request comes from a customer or as a result of an internal review. Custom fields will be covered in Chapter 5, Field Management. 78 Using Jira for Agile Projects Using queries is the most flexible option when it comes to configuring your swimlanes since Jira’s query language is very powerful and allows you to define any arbitrary rule for them: Figure 3.18 – Configuring swimlanes Defining quick filters By default, your agile board will display all issues. For Scrum, it will be all issues in the sprint, while for Kanban, it will be all issues that have not been released. This can be quite distracting when you have many issues and only want to focus on specific ones. While swimlanes can help with that, having too many issues on the board can still be very noisy. One useful feature that Jira has is that you can create several predefined filters for your board. With these, you can quickly filter out the issues you do not care about and only have the issues that matter to you shown on the board. Note that this means that the other issues aren’t removed from the board – they are simply hidden from view. Jira already comes with two built-in quick filters, called Only My Issues and Recently Updated. You can create your own by following these steps: 1. Browse your project’s agile board. 2. Click on the Board menu and select the Configure option. 3. Select the Quick Filters option from the left navigation panel. 4. Enter a name for the new filter and the JQL query that will return the filtered issues. In the following screenshot, we are creating a new quick filter called Salesforce Label and using the JQL to search for issues with a label called Salesforce: Grooming your backlog 79 Figure 3.19 – Quick filters Now that we have covered all the major components of the agile board for Scrum and Kanban, it is time to take a look at the other important component: your backlog. Grooming your backlog If you are using Scrum or Kanplan, then a big part of your routine will be to groom your backlog. This means making sure that high-priority items are floated to the top and not getting buried. This is a constant exercise and is especially important as you and your team approach the start of a new sprint, in the case of Scrum. With Kanplan, it is just as important to prioritize the tasks so that your team can maintain their throughput and not violate any constraints because of poor planning. Jira’s backlog comes with several handy features to help you avoid turning backlog grooming into a tedious exercise. To prioritize issues in your backlog, you simply move the high-priority issues up and move the low-priority issues down. While this seems very simple, as your backlog grows, it can become tricky to drag an issue from the bottom of a backlog with hundreds of issues to the top – and let’s not forget that newly added issues go to the bottom by default. What you can do in this case is right-click the issue you want to move and select the Top of Backlog option from the Send to menu. This will move the issue to the top of the backlog. You can do this with multiple issues as well by simply holding down the Shift or Ctrl key on your keyboard to select all the issues you want to move and either use the Send to menu or drag and drop, as shown in the following screenshot: 80 Using Jira for Agile Projects Figure 3.20 – Grooming your backlog Backlog grooming is a very important aspect of running a successful Scrum or Kanban project. A well- groomed backlog means the issues in the backlog are being reviewed, defined, and prioritized. Without this, teams will not be able to plan their sprint (in the case of Scrum) and what they should focus on. So, what if you have multiple teams all working on the same project and they all need their own boards? And what if one team uses Scrum and the other team wants to use Kanban? We will look at how you can have multiple boards for your project in the next section. Creating a new agile board for your project When you create a new project using the Scrum and Kanban project template, as described earlier in this chapter, Jira will automatically create an agile board for your project. Along with this default board, you can create additional boards for your project. For example, if you created a Scrum project, and you have two teams working on the project, you can create a new Scrum board for the second team so that each team can work with their own agile boards and not get in each other’s way. Another example is if your second team needs to run their part of the project using Kanban, then you can easily add a new Kanban board to the Scrum project so that each team can use the agile methodology they want for the same project. To add a new agile board to your project, follow these steps: 1. Browse your project’s agile board. 2. Click the current board’s name from the top left-hand corner and select the Create board option. 3. Select the agile board type you want to create and follow the onscreen wizard to create the new board, as shown in the following screenshot: Including multiple projects on your board 81 Figure 3.21 – Adding a new agile board By being able to have multiple boards for your project, you have the flexibility to run your project with multiple teams, each having their own board for their work. Next, we will look at how to include issues from multiple projects on a single board. Including multiple projects on your board By default, when you create a new project, the agile board that’s created will only include issues from the current project. This is usually fine if your project is self-contained; however, there might be cases where you have multiple projects that are related or dependent on each other, and for you to get an overall picture, you need to have issues from all of those projects shown on a single agile board. The good news is that Jira lets you do just this. One thing to understand here is that Jira uses what is called a filter to define what issues will be included on the board. Filters are like saved search queries, and when a project is created, Jira automatically creates a filter that includes all of the issues from the current project. This is why the default agile board that’s created with the project will always display the project’s issues. Filters will be discussed in Chapter 10, Searching, Reporting, and Analysis. So, for you to include issues from other projects on the agile board, all you need to do is update the board by following these steps: 1. Browse your project’s agile board. 2. Click on the Board menu and select the Configure option. 3. Select the General option from the left navigation panel. 82 Using Jira for Agile Projects 4. Click on the Edit Filter Query link for the Saved Filter option if you want to update the filter that is currently being used by the board, as shown in the following screenshot. Usually, only the filter owner can change a filter’s query, but since filters created with the board have the same owner as the board by default, you can edit the query. Alternatively, if you already have a filter that has all the issues you want to include, you can hover over and click on the current filter and then select the new filter to use. Filters will be covered in Chapter 10, Searching, Reporting, and Analysis: Figure 3.22 – Configuring the board filter Since filters need to be shared with users for them to see the issues they return, make sure your filter is shared with the same group of users that the board is set to. Generally, you can just share the filter with the project. Summary In this chapter, we introduced the software project templates that come with Jira and the two main agile methodologies it supports, namely Scrum and Kanban. We talked about how you can run projects in each of the methodologies using Jira and the features it provides. We also looked at some of the customization options that are available for you as the project owner so that you can configure the agile board to fit your needs. We looked at how to customize the board’s columns to better adapt to your team’s workflow and how to use swimlanes to group similar issues Summary 83 together to better organize the layout of your board. We also looked at how to create quick filters to easily filter out irrelevant issues from view so that we can focus on the issues that matter and reduce noise if you have a very busy board. In the next chapter, we will look at issues, the key data you work with in your projects, and what you can do with it. 4 Working with Issues In the previous chapters, we saw how Jira can be used to manage projects for different purposes. A software development organization will use Jira to manage its software development life cycle and track bugs, while a customer services organization may choose to use Jira to track and log customer complaints and suggestions. At its core, issues are what users will be working with in those projects. The issue is one of the fundamental building blocks in Jira – almost all of Jira’s features and concepts revolve around issues. In this chapter, we will explore the different features Jira has for users to work with issues. By the end of this • • • • • • • chapter, you will have learned about the following topics: Issues and how they are used in Jira Creating, editing, and deleting issues Moving issues between projects Voting and watching issues to get notified of changes Advanced issue operations, including uploading attachments and linking issues Managing issue types and issue type schemes Managing priorities and a priority scheme Understanding issues An issue in Jira usually represents a unit of work that users will work on. Depending on how you are using Jira, an issue can also represent other things and concepts in the real world. For example, in a software development project, an issue can be a bug or a story, while in an IT service project, an issue can be an incident or a support request. 86 Working with Issues Despite all the differences in what an issue can represent, there are several key aspects that are common to all issues in Jira, listed as follows: • An issue must belong to a project. • It must have a type, also known as an issue type, which indicates what the issue represents. • It must have a summary. The summary acts like a one-line description of what the issue is about. • It must have a status. A status indicates where along the workflow the issue is at a given time. We will discuss workflows in Chapter 7, Workflow and Business Process. In summary, an issue in Jira represents a unit of work that can be completed by a user, such as a task in a business project, a story in a software development project, or a request in a service desk project. These are all different types of issue. So let’s start by taking a look at issues in more detail. Jira issue summary As we have already discussed, an issue in Jira can be anything in the real world to represent a unit of work or a task to be completed. In this section, we will look at how Jira presents an issue in the user interface for business and software projects. We will cover Jira Service Desk in Chapter 11, Jira Service Management, as it has a different interface. First, let’s look at an issue in detail. The following screenshot shows a typical example of an issue and breaks it down into more digestible sections, followed by an explanation of each of the highlighted sections in a table. This view is often called the issue summary or the View Issue page, as shown here: Jira issue summary 87 Figure 4.1 – Issue summary view Its sections are described as follows: • Project / issue key: This shows the project the issue belongs to. The issue key is the unique identifier of the current issue. This section acts as a breadcrumb for easy navigation. • Issue summary: This is a brief summary of the issue. • Issue export options: These are the various export options for the issue. The options include XML, Word, and Printable. • Issue operations: These are the operations that users can perform on the issue, such as Edit, Assign, and Add comment. These are covered in later sections of this chapter. • Workflow transitions: These are the workflow transitions that are available. Workflows will be covered in Chapter 7, Workflow and Business Process, • Issue details /fields: This section lists issue fields such as issue Type and Priority. Custom fields are also displayed in this section. Fields will be covered in Chapter 5, Field Management. 88 Working with Issues • User fields: This section is specifically for user-type fields, such as Assignee and Reporter. Fields will be covered in Chapter 5, Field Management. • Date fields: This section is specific for date-type fields, such as Created and updated. Fields will be covered in Chapter 5, Field Management. • Attachments: This lists all the attachments in an issue. • Sub-task list: Issues can be broken down into smaller sub-tasks. If an issue has sub-tasks, they will be listed in this section. • Comments: This lists all the comments that are visible to the current user. • Work log: This lists all the time-tracking information your users have logged against the issue. See the Tracking time section for more details. • History: Keeps track of all changes that have occurred for this issue, including the values that are used before and after the change. • Activity: This is similar to History but is formatted in a more user-friendly way. It can also generate an RSS feed for the content. When using Jira with Scrum or Kanban, issues will be shown as cards on the agile board, which has a more concise summary of issues, as shown here: Figure 4.2 – Issue agile card However, when you click on the card, Jira will display detailed information about the issue in a detailed panel. Now that we have seen how issues are presented in Jira, let’s take a look at how you can work with issues. Working with issues As we have already seen, issues are at the center of Jira. In the following sections, we will look at what you, as a user, can do with issues. Note that each of these actions will require you to have specific permissions, which we will cover in Chapter 9, Securing Jira. Creating an issue When creating a new issue, you will need to fill in several fields. Some fields are mandatory, such as the issue’s summary and type, while others are optional, such as the issue’s description. We will discuss fields in more detail in the next chapter. There are several ways in which you can create a new issue in Jira. You can choose either of the following options: • Click on the Create button from the top banner • Press C on your keyboard This will bring up the Create Issue dialog box, as shown in the following screenshot: Figure 4.3 – Create Issue dialog As you can see, there are quite a few fields, and the required fields will have a red asterisk (*) mark next to their names. Working with issues 89 90 Working with Issues The administrator configures what fields will be part of the Create Issue dialog, but your users can customize and make their own Create Issue screen by hiding the optional fields by performing the following steps: 1. Click on the Configure Fields option in the top-right corner. 2. Select the Custom Fields option. 3. Uncheck all the fields you want to hide and check the fields that you want to display, as shown in the preceding screenshot. Make sure you do not hide any required fields, otherwise you will not be able to create new issues. You are only hiding or showing these fields for yourself. Important note Only the Jira administrator can hide and show fields globally for all users. There is a Create another option beside the Create button. By checking this option and then clicking on the Create button, the Create Issue dialog box will stay on the screen and remember the values you have previously entered, such as priorities components, and due dates. This way, you can avoid having to fill in the whole dialog box again and will only have to update the fields that are different, such as Summary. With this feature, you can rapidly create many issues in a much shorter time frame. Tip Apart from manually creating issues this way, you can also use advanced tools, such as the issue importer, Jira’s REST APIs, and emails, to create issues. Assigning issues to users Once an issue has been created, the user that’s normally assigned to the issue will start working on it. Afterward, the user can reassign the issue, for example, to QA staff for further verification. There are many instances where an issue needs to be reassigned to a different user, for example, when the current assignee is unavailable or if issues are created with no specific assignee. Another example is where issues are assigned to different people at different stages of the workflow. For this reason, Jira allows users to reassign issues once they have been created. Go through the following steps to assign an issue: 1. Browse to the issue you wish to assign. 2. Click on the Assign button in the Issue menu bar or press A on your keyboard (you can also use the inline edit feature here). This will bring up the Assign dialog. Working with issues 91 3. Select the new assignee for the issue and optionally add a comment to provide some information to the new assignee. 4. Click on the Assign button, as shown in the following screenshot: Figure 4.4 – Assign issue Once this issue has been reassigned, its Assignee value will be updated to the new user. The new assignee will also receive a notification email alerting them of the assignment. You can also unassign an issue this way by simply selecting the Unassigned option. Unassigned issues do not have an assignee and will not show up on anyone’s list of active issues. Tip You can press I on your keyboard to quickly assign an issue to yourself. Editing an issue There are two ways in which you can edit an issue in Jira: • The first and more traditional way is by clicking on the Edit button or by pressing E on your keyboard. This will bring up the Edit Issue dialog box, along with all the editable fields for the current issue. This allows you to make changes to multiple fields at once. 92 Working with Issues • The second option is called inline editing. With this approach, you will be able to view the issue and edit the field you want on the spot, without having to wait for the edit dialog to load. To edit a field inline, all you need to do is hover your mouse over the value for the field you want to update, click on the Edit (pencil) icon, and start editing, as shown in the following screenshot: Figure 4.5 – Inline editing The fields you can edit are controlled by the screen that’s used for the edit issue operation. Screens will be discussed in Chapter 6, Screen Management. Note that not all fields can be edited; some fields are read-only and some specialized fields may not display when viewing the issue. Moving an issue between projects Once an issue has been created, the issue is associated with the project it is created in. You can, however, move the issue around from one project to another. This may sound like a very simple process, but there are many steps involved and many things that need to be considered: • First, you need to decide on a new issue type for the issue if the current issue type does not exist in the new project. • Second, you will need to map a status for the issue if the target project or issue type uses a different workflow. • Third, you will need to decide on the values for any mandatory fields that exist in the new project but that do not exist in the current project. Sounds like a lot? Luckily, Jira comes with a wizard that is designed to help you address all these things. Go through the following steps to start moving an issue: 1. Browse to the issue you wish to move. 2. Click on the Move option in the More menu. This will bring up the Move Issue wizard. There are essentially four steps in the Move Issue wizard: 1. The first step is to select which project you wish to move the issue to. You will also need to select the new issue type, as shown in the following screenshot. If the same issue type exists in the new project, you can usually continue and use the same issue type: Figure 4.6 – Move Issue step 1 2. The second step allows you to map the current issue to the new project’s workflow, as shown in the following screenshot. If the issue’s status exists in the target project, the wizard will skip this step: Figure 4.7 – Move Issue step 2 3. The third step shows all the fields that exist in the new project but not the current project, as well as those that require a value, as shown in the following screenshot. Again, if there are no fields that require values to be set, this step will be skipped: Working with issues 93 94 Working with Issues Figure 4.8 - Move Issue step 3 4. The fourth and last step shows you the summary of the changes that will be applied by moving the issue from the source project to the target project. This is your last chance to make sure that all the information is correct. If there are any mistakes, you can go back to step one and start over again. If you are happy with the changes, confirm the move by clicking on Move, as shown in the following screenshot: Figure 4.9 – Move Issue step 4 Once the issue has been moved, it will be given a new issue key based on the new project. If you access the issue with its old issue key, Jira will automatically redirect you. Another useful use of the move issue feature is if you need to change the type of the issue. Sometimes the different issue types have very different configurations, such as workflows. In this case, Jira will not let you simply edit the Type field of an issue. What you need to do is use the move feature, but instead, you will select the same project as the target, and select the issue type you want to change to. Working with issues 95 Sharing issues with other users If you want to email an issue to other users in Jira, instead of having to manually copy and paste the issue’s URL in an email, you can use the built-in share feature in Jira. All you have to do is go to the issue you want to share and click on the share icon, as shown in the following screenshot, or press S on your keyboard. Then, select the users you want to share the issue with and click on the Share button, as shown in the following screenshot: Figure 4.10 – Share issue Note If the user you are sharing the issue with does not have access to the issue, they will not be able to see the issue’s details. Deleting an issue You can delete issues from Jira. You might need to delete issues that have been created by mistake or if the issue is redundant, although normally, it is better to close and mark the issue as a duplicate. We will discuss closing an issue in Chapter 7, Workflow and Business Process. 96 Working with Issues Issue deletion is permanent in Jira. Unlike some other applications that may put deleted records in a trash bin that you can retrieve later, Jira completely deletes the issue from the system. The only way to retrieve the deleted issue is by restoring Jira from a previous backup. Go through the following steps to delete an issue: 1. Browse to the issue you wish to delete. 2. Click on the Delete option from the More menu. This will bring up the Delete Issue dialog box, as shown in the following screenshot: Figure 4.11 – Delete Issue 3. Click on the Delete button to remove the issue permanently from Jira. Note that deleting an issue permanently removes it from Jira, along with all its data, including attachments and comments. Receiving notifications on an issue Jira can send automated email notifications about updates regarding issues to users. Normally, notification emails will only be sent out to the issue’s reporter, assignee, and people who have added themselves as watchers of the issue. This behavior can be changed through notification schemes, which we will discuss in Chapter 8, Emails and Notifications. By watching an issue, you will receive email notifications on activities, such as new comments and issue updates. Users watching the issue can also choose to stop watching and thus stop receiving email updates from Jira. You can also add other users as watchers by adding them to the watchers list. To watch an issue, simply click on the Start watching this issue link. If you are already watching the issue, it will change to Stop watching this issue. If you click on the link again, you will stop watching the issue. Important note Jira will automatically add you as a watcher for issues that are created by you and issues you have commented on and updated. Jira also shows you how many people are actively watching the issue by displaying the total watchers next to the watch icon. You can click on the number next to Watchers to see the full list of watchers, and add new users as watchers to the issue, as shown here: Figure 4.12 – Add Watchers Casting a vote on an issue The most straightforward way to express your interest in a Jira issue is to vote for it. For organizations or teams that manage their priorities based on popularity, voting is a great mechanism for collecting this information. An example of this is how Atlassian uses Jira (https://jira.atlassian.com/browse/ JRASERVER-9) as a way to let its customers choose and vote for the features they want to be implemented or bugs to be fixed by voting on issues based on their needs. This allows the product management and marketing team to have an insight into market needs and how to best evolve their offerings. One thing to keep in mind when voting is that you can only vote once per issue. You can vote many times for many different issues, but for any given issue, you have only one vote. This helps prevent a single user from continuously voting on the same issue, which may skew the voting result. You can, however, unvote a vote you have already cast on an issue and vote for it again later; if you choose to do this, it will still only count as one vote. Working with issues 97 98 Working with Issues To vote for an issue, simply click on the Vote for this issue link next to Votes. When you have voted for an issue, the icon will appear colored. When you have not yet voted for an issue, the icon will appear grayed out. Note Note that you cannot vote for issues that you have created. Issue linking Jira allows you to create custom hyperlinks for issues. This allows you to provide more information about the issue. There are two types of links you can create: linking to other issues in Jira or linking to any arbitrary resources on the web, such as a web page. Linking issues with other issues Issues are often related to other issues in some way. For example, issue A might be blocking issue B, or issue C might be a duplicate of issue D. You can add descriptions to the issue to convey this information, or delete one of the issues in the case of duplication, but with this approach, it is hard to keep track of all these relationships. Luckily, Jira provides an elegant solution for this with the standard issue link feature. The standard issue link lets you link an issue with one or more other issues in the same Jira instance. This means that you can link two issues from different projects together (if you have access to both projects). Linking issues in this way is very simple; all you need to know is the target issues to link to. You can link issues by going through the following steps: 1. Browse to the View Issue page for the issue you wish to create a link for. 2. Select Link from the More menu. This will bring up the Link Issue dialog box. 3. Select the Jira Issue option from the left panel. 4. Select the type of issue linking from the This issue drop-down menu. 5. Select the issues to link to. You can use the search facility to help you locate the issues you want. 6. Click on the Link button, as shown in the following screenshot: Issue linking 99 Figure 4.13 – Link issues After you have linked your issues, they will be displayed in the Issue Links section on the View Issue page. Jira will display the target issue’s key, description, priority, and status. Linking issues with remote contents The standard Jira issue link allows you to link multiple issues to the same Jira instance. Jira also lets you link issues to resources, such as web pages on the internet. Using remote issue links is quite similar to the standard issue link; the difference is that instead of selecting another issue, the URL address of the target resource is specified. You can set this up by going through the following steps: 1. Open the Link Issue dialog box. 2. Select the Web Link option from the left panel. 3. Specify the URL address for the target resource. Jira will automatically try and find and then load the appropriate icon for the resource. 100 Working with Issues 4. Provide the name for the link in the Link Text field. The name you provide here will be what is shown for the link when viewing the issue. 5. Click on the Link button, as shown in the following screenshot: Figure 4.14 – Web Link By using issue linking, Jira allows you to add more contextual information to issues. In fact, Atlassian uses this feature extensively when integrating Jira with their other products, such as linking an issue with a Confluence wiki page, and a Bamboo build plan. Cloning an issue When you need to create a new issue and you already have a baseline issue, Jira allows you to quickly create it with the data based on your existing issues by cloning the original one. Cloning an issue allows you to quickly create a new one, with most of its fields populated. For example, you might have two software products with the same bug. After creating a bug report in one project, you can simply clone it for the other project. A cloned issue will have all the fields copied from the original issue; however, it is a separate entity. Further actions performed on either of the two issues will not affect the other. When an issue is being cloned, a Clone link is automatically created between the two issues, establishing a relationship. Cloning an issue in Jira is simple and straightforward. All you have to do is specify a new summary (or accept the default summary with the text CLONE at the front) for the cloned issue by going through the following steps: 1. Browse to the issue you wish to clone. 2. Select Clone from the More menu. 3. Enter a new summary for the newly cloned issue. 4. Check the Clone sub-tasks checkbox if you also want to copy over all the sub-tasks. 5. Check the Clone attachments checkbox if you want to copy over all the attachments. 6. Click on the Clone button. Once the issue has been successfully cloned, you will be taken to the issue summary page for the newly cloned issue. Tracking time Since issues often represent a single unit of work that can be worked on, it is logical for users to log the time they have spent working on it. You can specify the estimated effort that is required to complete an issue, and Jira will be able to help you track its progress. Jira displays the time tracking information of an issue in the Time Tracking panel on the right-hand side, as shown in the following screenshot: Figure 4.15 – Time Tracking Tracking time 101 102 Working with Issues The Time Tracking panel includes the following information: • Estimated: This represents the original estimated effort that’s required to complete the issue, for example, the estimated time required to fix a bug by a developer. • Remaining: This represents the remaining time for the issue to be completed. It is calculated automatically by Jira based on the original estimate and total time logged by users. However, the user logging work on the issue, as described in the following section, can also override this value. • Logged: This represents the total time spent on the issue so far. Specifying original estimates Original estimates represent the anticipated time required to complete the work that’s represented by the issue. It is shown as a blue bar under the Time Tracking section. For you to specify an original estimate value, you need to make sure that the Time Tracking field is added to the issue’s create and/or edit screen. We will discuss fields and screens in Chapter 5, Field Management, and Chapter 6, Screen Management, respectively. To specify an original estimate value, provide a value for the Original Estimate field when you are creating or editing an issue. Logging work Logging work in Jira allows you to specify the amount of time (work) you have spent working on an issue. You can log work against any of the issues, provided you have permission to do so. We will cover permissions in Chapter 10, Searching, Reporting, and Analysis. Go through the following steps to log work against an issue: 1. Browse to the issue you wish to log work against. 2. Select Log Work from the More menu. 3. Enter the amount of time you wish to log. Use w, d, h, and m to specify the week, day, hour, and minute, respectively. 4. Select the date you wish to log your work against. 5. Optionally, select how the remaining estimate should be adjusted. 6. Add a description of the work you have done. 7. Optionally, select who can view the work log entry. 8. Click on the Log button. When you log work on an issue, you have the option to choose how the remaining estimate value will be affected. By default, this value will be automatically calculated by subtracting the amount that has been logged from the original estimate. You can, however, choose from other options that are Issues and comments 103 available, such as setting the remaining estimate to a specific value or reducing it by an amount that is different from the amount of work being logged. Tip You can also click on the + sign in the Time Tracking section to log time. Issues and comments Jira lets users create comments on issues. As we have already seen in the previous section, you will be able to create comments when assigning an issue to a different user. This is a very useful feature that allows multiple users to collaborate so that they can work on the same issue and share information. For example, the support staff (issue assignee) may request more clarification from the business user (issue reporter) by adding a comment to the issue. When combined with Jira’s built-in notification system, automatic email notifications will be sent to the issue’s reporter, assignee, and any of the other users watching the issue. Notifications will be covered in Chapter 8, Emails and Notifications. By default, all logged-in users will be able to add comments to issues they can access. Go through the following steps to add a comment to an issue: 1. Browse to the issue you wish to add a comment to. 2. Click on the Comment button or press M on your keyboard. 3. Type a comment into the textbox. You can preview and set restrictions on who can view your comment. 4. Click on the Add button to add the comment, as shown in the following screenshot: Figure 4.16 – Add comment 104 Working with Issues Once a comment has been added, the comment will be visible in the Comments tab in the Activity section at the bottom. When you are creating comments, you can select who can view your comment using the comment access control. This is very useful if you have external users viewing the issue and you only want to share your comments with internal users. Attachments As we have seen so far, Jira uses fields such as Summary and Description to capture data. This works for most cases, but when you have complex data such as application log files or screenshots, this becomes insufficient. This is where attachments come in. Jira allows you to attach files from your local computer or a screenshot you have taken. Attaching files The easiest way to attach a file to a Jira issue is via the drag and drop action. You can do this by going through the following steps: 1. Browse to the issue you wish to attach a file to. 2. Drag and drop the files you want to attach to the browser. You will see an outline indicating where you can drop the file to attach it to the issue, as shown in the following screenshot: Figure 4.17 – Add attachment Drag and drop is the easiest way to attach files, but if, for some reason, drag and drop does not work, you can also manually select the file and attach it by going through the following steps: 1. Browse to the issue you wish to attach a file to. 2. Select the Attach files option from the More menu. 3. Select and attach the files you want to attach from the file browser. Depending on the file’s type, certain files, such as images and PDFs, can be viewed directly from Jira’s UI without having to download them. Issue types and sub-tasks As we saw earlier, issues in Jira can represent many things, ranging from software development tasks to project management milestones. Issue types are what differentiate one type of issue from another. Each issue has a type (hence the name issue type), which is represented by the Issue type field. This lets you know what type of issue it is and helps you determine many other details, such as which fields will be displayed for this issue. The out-of-the-box issue types are great for software development projects, but they do not necessarily meet the needs of others. Since it is impossible to create a system that can address everyone’s needs, Jira lets you create your own issue types and assigns them to projects. For example, for a help desk project, you might want to create a custom issue type called ticket. You can create this custom issue type and assign it to the Help Desk project and users will be able to log tickets, instead of bugs, in the system. Issue types are managed through the Manage Issue Types administration page. Perform the following steps to access this page: 1. Log in to Jira as a Jira administrator. 2. Browse to the Jira administration console. 3. Select the Issues tab and then the Issue types option. This will take you to the Issue types page. Figure 4.18 – Issue types Issue types and sub-tasks 105 106 Working with Issues The preceding screenshot shows a list of issue types that represent different things an issue can be, including Bug and Epic in software development, and Incident and Change for IT services. So let’s take a look at how to create our own issue types next. Creating issue types There are many use cases for creating your own issue types. The most common use case is when you want your issues to represent something other than the out-of-the-box issue types. Another common use case is to apply different configurations for the issues in a given project. Since most configuration schemes in Jira are based on project and issue types, if you want certain issues in a project to have a different set of fields, you can create a new issue type and apply the configuration scheme to that issue type only. To create a new issue type, take these steps: 1. Browse to the Issue Types page. 2. Click on the Add Issue Type button. 3. Enter the name and description for the new issue type. 4. Select whether the new issue type will be a standard issue type or a sub-task issue type. 5. Click on Add to create the new issue type. Once the new issue type has been created, it will be assigned a default icon. If you want to change the icon, you will need to click on the Edit link for the issue type and then select a new image as its icon. Deleting issue types When deleting an issue type, you must keep in mind that the issue type might already be in use, meaning that issues have already been created with that issue type. So, when you delete an issue type, you will need to select a new one for those issues. The good news is that Jira takes care of this for you. As we can see in the following screenshot, when we delete the Bug issue type, Jira informs us of the existing 10 issues that are of the Bug type. You will need to assign them to a new issue type, such as Defect: Figure 4.19 – Delete Issue Type Using sub-tasks Jira allows only one person (assignee) to work on one issue at a time. This design ensures that an issue is a single unit of work that can be tracked against one person. However, in the real world, we often find ourselves in situations where we need to have multiple people working on the same issue. This may be caused by a poor breakdown of tasks or simply because of the nature of the task at hand. Whatever the reason, Jira provides a mechanism to address this problem through sub-tasks. As we have seen earlier when discussing issue types, a sub-task is simply another issue type. The only difference is that a sub-task must always have a parent issue. For every issue, you can have one or more sub-tasks that can be assigned and tracked separately from each other. Sub-tasks cannot have other sub-tasks. Jira only allows one level of sub-task. Since sub-tasks belong to an issue, you need to browse to the issue first before you can create a new sub-task by going through the following steps: 1. Browse to the issue you wish to create sub-tasks for. 2. Select Create sub-task from the More menu. You will see a familiar Create Issue dialog box; however, one thing you will notice is that, unlike when you are creating an issue, you do not select which project to create the sub-task in. This is because Jira can determine the project’s value based on the parent issue. You will also notice that you can only select issue types that are sub-tasks. Other than these differences, creating a sub-task is no different than creating a normal issue. You can customize the fields that are shown in the dialog box and choose to rapidly create multiple sub-tasks by selecting the Create another option. Once the sub-task has been created, it will be added to the Sub-Tasks section of the parent issue. You will see all the sub-tasks that belong to the issue and their status. If a sub-task has been completed, it will have a green check mark next to it, as shown in the following screenshot: Figure 4.20 – Sub-Tasks Now we have seen how you can manage issue types, we will look at how you can use issue type schemes to group issue types together so they can be applied to a project next. Issue types and sub-tasks 107 108 Working with Issues Issue type schemes Issue type schemes are templates or collections of issue types that can be applied to projects. As we can see in the following screenshot, Jira comes with a default issue type scheme, which is applied to all projects that do not have specific issue type schemes applied. When you create a new project, a new issue type scheme is created for you based on the project template you have selected. The new scheme will also have issue types pre-populated based on the template. As we can see in the following screenshot, we have several issue type schemes, and Jira will list the projects that are using them: Figure 4.21 – Issue type schemes As we will see in later chapters, most configurations in Jira are managed through schemes, such as issue type schemes, field configuration schemes, and workflow schemes. The main advantage of using a scheme is schemes are reused components. In the case of issue type schemes, you can apply the same issue type scheme to one or more projects, and they will all have the same set of issue types. This greatly reduces the administrative and maintenance burden of the Jira administrator by reusing schemes and allows you to establish standards for your configurations. When you create your own issue types, to make them available, you need to add them to the issue type scheme that’s used by your project. Adding issue types to an issue type scheme Go through the following steps to create a new issue type scheme: 1. Browse to the administration console. 2. Select the Issues tab and then the Issue type schemes option. This will bring you to the Issue type schemes page. 3. Click on the Edit link for the issue type scheme you want to add issue types to. 4. Drag the issue types that you want to be part of the scheme from the Available Issue Types list and drop them into the Issue Types for Current Scheme list. Figure 4.22 – Configure issue type scheme 5. Select a Default Issue Type value. Note that this is optional, and you can only select a default issue type after you have selected at least one issue type for the new scheme. 6. Click on the Save button. Once you have created and configured your issue type scheme, you can associate it to one or more projects by clicking on the Associate button, and selecting the projects to apply the scheme to. Issue priorities Priorities help users set the importance of issues. Users can first assign priority values to issues and later use them to sort the list of issues they have to work on, thereby helping the team decide which issues to focus on first. Jira comes with five levels of priorities out of the box, as shown in the following screenshot: Issue priorities 109 110 Working with Issues Figure 4.23 – Priorities You can customize this list by creating your own priorities. To create new priorities, follow these steps: 1. Browse to the administration console. 2. Select the Issues tab and then the Priorities option. 3. Enter a name and description for the new priority. 4. Click on the Select Image link to choose an icon for the priority. 5. Specify a color for the priority. You can either type in the HTML color hex code directly or use the color picker to help you select the color you want. The color that’s chosen here will be used when icon images cannot be displayed, such as when you export issues to a spreadsheet. 6. Click on the Add button. Creating a priority scheme Priority schemes work in a similar way to the issue type scheme feature we looked at earlier. You can create a scheme so that it contains only the issue priorities you need and then apply the scheme to a project. This way, each project can have its own set of priority options. To create and apply a new priority scheme, follow these steps: 1. Browse to the administration console. 2. Select the Issues tab and then the Priority schemes option. 3. Click on the Add priority scheme button. 4. Enter a name for the new priority scheme. 5. Drag the priorities that you want to be part of the scheme from the Available priorities list and drop them into the Selected priorities list. 6. Select a Default priority value. Note that this is optional, and you can only select a default priority after you have selected at least one priority for the new scheme. 7. Click on the Add button, as shown in the following screenshot: Figure 4.24 – Configure priority scheme Once you have created the new priority scheme, you can click its Associate link to apply the scheme to one or more projects. The HR project In this exercise, we will continue our setup for the project we created in the previous chapter. We will add the following configurations to our project: • A set of new issue types that are specific to our HR project • Add our new issue types to the issue type scheme to make them available The HR project 111 112 Working with Issues Adding new issue types Since our project is for the human resources team, we need to create a few custom issue types to augment the default ones that come with Jira. For this exercise, we will create two new issue types, New EmployeeandTermination. The first step, that is, setting up an issue type association, is to create the two issue types that we need, New EmployeeandTermination: 1. Browse to the Issue Types page. 2. Click on the Add Issue Type button. 3. Type New Employee in the Name field. 4. Click on the Add button to create the new issue type. You should now see the new issue type in the table. Now, let’s add the Termination issue type: 1. Click on the Add Issue Type button again. 2. Type Termination in the Name field. 3. Click on Add to create the new issue type. You should see both the New Employee and Termination issue types. However, this will only make our new issue types available—it will not make them the only options when creating a new issue for our project. As you may recall from the previous sections, we need to add the new issue types to the issue type scheme that’s used by our project. Updating the issue type scheme We want to limit the issue types to only New Employee, Termination, and the generic Task for our HR project, but we do not want to affect the other projects that still need to have Bug and other default issue types. Therefore, we need to create a new issue type scheme specifically for our project. We can do this by going through the following steps: 1. Browse to the Issue Type Schemes page. 2. Click on the edit link for our issue type scheme. The default one that’s created by Jira should be called HR: Task Management Issue Type Scheme. 3. Drag the New Employee and Termination issue types from the Available Issue Types panel to the Issue Types for Current Scheme panel. 4. Click on the Save button. Putting it all together With everything created and set up, you can go back and create a new issue to see how it all looks. If everything works out, you should see something like the following screenshot: Figure 4.25 – Sample project As you can see, for the HR project, we now have three issue types available from our issue type scheme: Task, New Employee, and Termination. Summary In this chapter, we looked at what issues are in Jira and explored the basic operations of creating, editing, and deleting issues. We also looked at the advanced operations offered by Jira to enhance how you can manipulate and use issues, such as adding attachments, creating sub-tasks, and linking multiple issues. We then looked at how we can create our own issue types and apply them to projects so the issues we create will better represent the type of tasks we have. In the next chapter, we will look at fields and how we can create our own custom fields to capture additional information from users. Summary 113 5 Field Management Projects are collections of issues, and issues are collections of fields. As we have seen in the earlier chapters, fields capture data, which can then be displayed to users. There are many different types of fields in Jira, ranging from simple text fields that let you input alphanumeric text, to more complicated fields with pickers to assist you with choosing dates and users. An information system is only as useful as the data that goes into it. By understanding how to effectively use fields, you can turn Jira into a powerful information system for data collection, processing, and reporting. In this chapter, we will expand our HR project with these customized fields and configurations, by exploring fields in detail and learning how they relate to other aspects of Jira. By the end of this chapter, you will have learned about the following: • Understanding system and custom fields and searchers • Managing and optimizing custom fields • Adding behaviors to fields with field configurations • Understanding field configuration schemes and how to apply them to projects Understanding system fields Jira comes with several built-in system fields. You have already seen a few of them in the previous chapters. Many of the system fields, such as Project, Issue Type, and Summary, are mandatory by default, and all issues must have values for them, while others, such as assignee and description, are optional. These system fields are often tied directly into different features of Jira so you cannot remove them. 116 Field Management The following table lists the main system fields in Jira: System field Assignee Summary Description Component/s Affects Version/s Fix Version/s Due Date Issue Type Priority Time Tracking Description This specifies the user who is currently assigned to work on the issue. This specifies a one-line summary of the issue. This provides a detailed description of the issue. This specifies the project components the issue belongs to. This specifies the versions the issue effects are found in. This specifies the versions the issue will be fixed in. This specifies the date this issue is due. This specifies the type of issue (for example, Bug and Story). This specifies how important the issue is compared to other issues. This lets users estimate how long the issue will take to be completed. Table 5.1 – System fields Reporter This specifies the user who has reported this issue (most of the time, it is also the person who has created the issue, but not always). Resolution This specifies the current resolution value of the issue (for example, Unresolved or Fixed). While Jira’s built-in fields are enough for basic general uses, most organizations soon find they have special requirements that cannot be addressed simply with the system fields available. In the next section, we will look at how Jira addresses this need by letting you create your own fields, called custom fields. Understanding custom fields One of the key features of Jira is custom fields, which let you add new fields to the system based on your needs. You can add a new user picker field to represent project stakeholders or a date picker field for different key dates. Every custom field is of a certain type that dictates its behavior, appearance, and functionality. Therefore, when you add a custom field to Jira, you are adding a custom field of the selected custom field type. Jira comes with over 20 custom field types that you can use straight out of the box. Many custom field types are identical to the built-in fields, such as Date Picker, which is like the Due Date field. They provide you with simplicity and flexibility that are not available with their built-in counterparts. The upcoming sections break down and list all the standard and advanced Jira custom field types and their characteristics. Standard fields These field types are the most basic field types in Jira. They are usually simple and straightforward to use, such as the Text field, which allows users to input any text: Understanding custom fields 117 Custom field type Labels Number Field Radio Buttons Select List (multiple choice) Select List (single choice) URL Field Advanced fields Description These are input fields that allow tags to be added to an issue. These are input fields that store and validate numeric values. These are radio buttons that ensure only one value can be selected. These are multiple select lists with a configurable list of options. These are single select lists with a configurable list of options. These are input fields that validate a valid URL. Table 5.2 – Standard custom field types Date Picker These are input fields that allow input with a date picker and enforce valid dates. Date Time Picker These are input fields that allow input with a date and time picker and enforce valid date timestamps. Select List (cascading) These are multiple select lists where the options for the second select list are dynamically updated based on the value of the first. Text Field (multi-line) These are multiple-line text areas enabling the incorporation of significant text content. Text Field (single-line) These are basic single-link input fields that allow simple text inputs of fewer than 255 characters. User Picker (single user) These choose a user from the Jira user base through either a pop-up user picker window or auto completion. These fields provide specialized functions. For example, the Version Picker field lets you select a version from the current project. If you have any custom fields from third-party add-ons (such as the ones listed later in this section), they will also be listed here: 118 Field Management Custom field type Description Group Picker (single group) This chooses a user group using a pop-up picker window. Group Picker (multiple group) This chooses one or more user groups using a pop-up picker window. Project Picker (single project) This selects lists displaying the projects that are viewable to the user in the system. Text Field (read only) This is a read-only text field that does not allow users to set their data. It’s only possible to set the data programmatically. User Picker (multiple users) This chooses one or more users from the user base through a pop-up picker window. Version Picker (multiple versions) This chooses one or more versions from the available versions in the current project. Version Picker (single version) This chooses a single version from the available versions in the project. Table 5.3 – Advanced custom field types As you can see, Jira provides you with a comprehensive list of custom field types. In addition, there are many custom field types developed by third-party vendors (available as apps that you can add to your Jira to enhance its functionality). These custom fields provide many specialized functionalities, such as automatically calculating values and retrieving data from databases directly or connecting to an external system. Once you install the plugin, the process of adding custom fields from other vendors is mostly the same as adding custom fields shipped with Jira. The following list shows some examples of apps that provide additional useful custom fields. You can find them on the Atlassian Marketplace at https://marketplace.atlassian.com: • Enhancer Plugin for Jira: This includes several custom fields that will automatically display dates when key events occur for an issue; for example, when the issue was last closed. • Toolkit Plugin for Jira: This provides several useful custom fields, such as showing statistics on users that participate in a given issue and the date when the issue was last commented on. • Elements Connect - external data fields: This provides a suite of custom fields that let you connect to databases, remote files, and web services to retrieve data and display it in Jira. • Electronic Signature for Jira: This lets users electronically sign issues in Jira as they work on them, for example, approving an issue to be closed. • ScriptRunner for Jira: This app allows you to create your own custom fields and define their functionalities with scripts. We will cover more on third-party apps in Chapter 12, Jira and Third Party Apps. So, now we have looked at custom fields, it is time to introduce searchers next. Understanding field searchers For any information system, capturing data is only half of the equation. Users will need to be able to retrieve the data at a later stage, usually through searching, and Jira is no different. While fields in Jira are responsible for capturing and displaying data, it is their corresponding searchers that provide the search functionality. A custom field searcher determines how the data stored by the field will be indexed, and this will have an impact on how you can search its data. For example, a text custom field will index its data as raw text so you can run a fuzzy search such as the text starting with a particular character. A select list custom field, on the other hand, will index its data differently, so you can run searches against a particular option value or a list of option values. If a field does not have a searcher applied, then its data will not be indexed, and you will not be able to search its data. All fields that come with Jira have searchers associated with them by default, so you will be able to search issues according to their summary or assignee, without any further configuration. Some custom fields from third-party add-ons may have more than one searcher available. You can change the default searcher by editing the custom field. Note In the Jira UI, a searcher is referred to as a search template. Custom field context System fields, such as Summary and Issue Type, are global across Jira. What this means is that these fields are available to all issues and projects. Custom fields, on the other hand, can be applied to specific projects and issue types, also known as context. A custom field context is made up of a combination of projects and issue types. When you are working with an issue, Jira will check the project and issue type of the current issue to determine whether there is a specific context that matches the combination. If one is found, Jira will display the custom field with any specific settings, such as selection options. However, if no context is found, the custom field will not be displayed. There are two main reasons to use custom field contexts, customization and performance. Let’s first look at how context can help customize a custom field. Custom field types, such as select lists and radio buttons, have options for end users to choose from. You can customize the list of options for different projects and issue types, or contexts. This allows you to reuse the same custom field for multiple projects, thus reducing duplication. Understanding field searchers 119 120 Field Management The second benefit of using custom field context is performance. If you restrict your custom fields to specific project and issue types, it means when Jira is displaying an issue, it will only need to display custom fields that have contexts for the issue. The fewer custom fields Jira needs to display, the faster the response time will be. In Jira, if no context can be found that matches the project and issue type combination, a custom field does not exist for the issue. We will look at how to set custom field contexts in the Adding custom field contexts section later. What you need to remember now is that when adding a custom field, you need to make sure that it has the correct context setting. Now that we have briefly covered custom field context, let’s take a look at how you can create and manage custom fields. Managing custom fields Custom fields are used globally across Jira, so you will need to have the Jira Administrator global permission to carry out management operations such as creation and configuration. Jira maintains all the custom fields in a centralized location for easy management. Perform the following steps to access the Manage custom field page: 1. Log in as a Jira administrator user. 2. Browse to the Jira administration console. 3. Select the Issues tab and then the Custom fields option: Figure 5.1 – Manage custom fields Managing custom fields 121 On the Custom fields page, all the existing custom fields will be listed. From here, you can see the names of all custom fields, their type, the context they belong to, and the screens they are displayed on. Note that some custom fields, such as Development and Epic Colour, as shown in the preceding screenshot, come with Jira itself, and will have the LOCKED label next to their names. These fields serve special purposes in Jira, so their configurations cannot be changed. User-added custom fields, such as Approvers, do not have this restriction and can be updated at any time. Let’s start by adding a new custom field. Adding a custom field Adding a new custom field is a multistep process, and Jira provides a wizard to help you through it. There are two mandatory steps and an optional step when adding a new custom field. You need to first select the type of custom field. It is very important to choose the correct field type as this cannot be changed later. When you choose the field type, you need to consider how the field will be used, the type of data you want it to store, and how you would search the data. Once you have selected the custom field type, you need to give it a name, followed by options if you are adding a Select List custom field type. The final, optional, step is to decide which screens to add the field to. We will walk you through the process: 1. Browse to the Custom fields page. 2. Click on the Add custom field button. This will bring you to step 1 of the process, where you can select the custom field type. 3. Search and select the custom field type you wish to add and click on Next. This will bring you to step 2 of the process, where you can specify the custom field’s name and options. Note that once a field type has been selected, it cannot be changed after the field is created: 122 Field Management Figure 5.2 – Add custom field step 1 Tip If you do not see the field type you are looking for, select the All option from the left-hand side and then search again. 4. Enter values for the Name and Description fields. If you are creating a selection-based custom field, such as a select list, you will also need to add its select options (you can update this list later): Important note Managing custom fields 123 Figure 5.3 – Add custom field step 2 Even though you can have multiple custom fields with the same name, this is usually not a good practice as it can lead to confusion later and make management difficult. 5. Select the context for the new custom field. You should restrict the context to the specific issue types and projects the custom field will be used for. You can change this context after the custom field is created. Figure 5.4 – Add custom field step 3 124 Field Management 6. Click on the Create button. This will bring you to the final step of the process, where you can specify which screen you would like to add the field to. This step is optional, as the custom field has already been added in Jira. You do not have to add the field onto a screen. We will discuss fields and screens in Chapter 6, Screen Management. 7. Select the screens and click on Update. The following screenshot shows that the newly created field has been added to two screens: Figure 5.5 – Add custom field step 4 Once a custom field has been created, you will see it on the selected screen when you are creating, editing, or viewing issues. Before you start adding new custom fields, you should always first see if there are existing custom fields that have served a similar purpose that you can reuse. For example, if you want to add a select list of departments, there could already be a Department custom field, and all you need to do is to add a new field context so it will have a different list of department options for your project. So, it is always a good practice to keep reusability in mind when adding a new custom field. Always think about how you could reuse existing fields and how a new field could be reused in the future. This will help reduce the number of custom fields and keep your Jira more manageable. Editing/deleting a custom field Once a custom field has been created, you can edit its details at any time. You may already notice that there is a Configure option and an Edit option for each custom field. It may be confusing in the beginning to differentiate between the two. Configure specifies options related to the custom field context, which we will discuss in the following sections. Edit specifies options that are global across Jira for the custom field; these include its name, description, and search templates: 1. Browse to the Custom fields page. 2. Select the Edit option by clicking on the cog icon for the custom field you wish to edit from the list of custom fields. 3. Change the custom field’s details, such as its name or search template. 4. Click on the Update button to apply the changes. When making changes to the search templates for your custom fields, it is important to note that, while the change will take effect immediately, you need to perform a system re-index for Jira to return the correct search results. This is because, for each search template, the underlying search data structure may be different, and Jira will need to update its search index for the newly applied search template. For example, if you have a custom field that did not have a searcher and you have just applied a searcher to it, no results will be returned until you re-index Jira. When you make changes to the search template, Jira will alert you with a message that a re-index will be required, as shown in the following screenshot: Figure 5.6 – Change searcher Jira will notify you that you will need to perform a re-index whenever you have added or modified a custom field, installed a third-party app that contains custom field modules, or made other configuration changes that may impact existing custom fields, as shown here. Since re-indexing can be a costly process that can take a long time to complete for a large Jira instance, you are not required to re-index every time Jira prompts you to do so. Generally, you should perform a re-index in the following situations: • You have changed a custom field’s search template • You have updated a third-party app that has made changes to a custom field that you are using • You have made configuration changes that impact a custom field, such as its context Not performing a timely re-index could lead to incorrect search results being returned and other problems. Managing custom fields 125 126 Field Management To perform a re-index, you can either click on the perform a re-index link from the prompt or go to Jira administration console | System | Indexing. When performing a re-index, you can choose to either run a background re-index or a full (foreground) re-index. A background re-index is slower, but end users can continue to use Jira while the re-index process is taking place. A full re-index is faster, but Jira will be unavailable until the process is completed. In most cases, a background re-index is preferred, but in cases where the search index becomes corrupted, you will need to perform a full re-index. In these cases, you should plan for an outage as users will not be able to use Jira during re-indexing. Tip You should select the background re-index option to avoid any downtime. We will discuss searching and indexing in more detail in Chapter 10, Searching, Reporting, and Analysis. You can also delete existing custom fields, as follows: 1. Browse to the Custom fields page. 2. Select the Delete option by clicking on the tools icon for the custom field you wish to delete. 3. Click on the Delete button to delete the custom field. Once deleted, you cannot get the custom field back, and you will not be able to retrieve and search the data held by that field. If you try to create another custom field of the same type and name, it will not inherit the data from the previous custom field, as Jira assigns unique identifiers to each of them. It is highly recommended to back up your Jira project before you delete the field unless you are absolutely certain you do not need it. Configuring a custom field Now that we have seen how to create and manage custom fields, we can start looking at more advanced configuration options. Different custom field types will have different configuration options available to them. For example, while all custom fields will have the option to specify one or more contexts, selection list-based custom fields will also allow you to specify a list of options. We will look at each of the configuration options in the following sections. To configure a custom field, you need to access the Configure Custom Field page, as follows: 1. Browse to the Custom fields page. 2. Select the Configure option by clicking on the cog icon for the custom field you wish to configure from the list of custom fields. This will bring you to the Configure Custom Field page. The following screenshot shows that the Department custom field has two available contexts: the default configuration scheme, which is applied to Demonstration Project, and the PMO configuration scheme, which is applied only to the Development and Product Management projects: Figure 5.7 – Configure custom field Adding custom field contexts From time to time, you may need your custom fields to have different configurations, depending on what project the issue is located in. For example, if we have a select list custom field called Department, we may want it to have a different set of options based on which project the issue is being created in or even a different default value. Managing custom fields 127 128 Field Management To achieve this level of customization, Jira allows you to create multiple custom field contexts for a custom field. As we have seen already, a custom field context is a combination of issue types and projects. Therefore, in our preceding example, the default and PMO contexts have different options for the Department field. Creating a new custom field context is simple. All you need to do is decide the issue type and project combination that will define the context: 1. Browse to the Configure Custom Field page for the custom field you wish to create a new context for. 2. Click on the Add new context link. This will take you to the Add configuration scheme context page. 3. Enter a name in the new custom field context in the Configuration scheme label field. 4. Select the issue types for the new context under the Choose applicable issue types section. 5. Select projects for the new context under the Choose applicable context section. 6. Click on the Add button to create the new custom field context. Each project can only belong to one custom field context per custom field (global context is not counted for this). Once you select a project for context, it will not be available the next time you create a new context. For example, if you create a new context for Project A, it will not be listed as an option when you create another context for the same custom field. This is to prevent you from accidentally creating two contexts for the same project. After a new custom field context has been created, it will not inherit any configuration values as the default context, such as the Default value and Options from other contexts. You will need to repopulate and maintain the configuration options for each newly created context. Restricting custom field context can also help reduce search index size and help improve performance, especially with data center edition deployment. Configuring select options For custom field types, such as select lists, checkboxes, radio buttons, and their multi-versions, you need to configure their select options before they can become useful to users. Select options are configured and set on a per-custom-field-context basis. This provides the custom field with the flexibility of having different select options for different projects. To configure select options, you need to first select the custom field and then the context that the options will be applied to, as follows: 1. Browse to the Custom fields page. 2. Click on the Configure option for the custom field you wish to configure the select options for. 3. Click on the Edit Options link for the custom field context you wish to apply the options to. 4. Enter option values in the Add New Custom Field Option section, and click on the Add button to add the value. The options will be added in the order in which they are entered into the system. You can manually move option values up and down or click on Sort options alphabetically to let Jira perform the sorting for you. 5. Click on the Done button once you finish configuring the select options: Figure 5.8 – Configure field options You can delete and disable existing options. There is an important difference between the two operations. When you disable an option, Jira will simply not display that option for the field, but issues with that option will still have its value, so when you re-enable the option, the values will be present. However, if you delete the option, it is deleted from Jira completely, including issues that have that option as their values for the field. For this reason, it is usually better to first disable an option and only delete it once you are sure it is no longer needed. Setting default values For most custom fields, you can set a default value so your users will not need to fill them in unless they have special needs. For text-based custom fields, the default values will be displayed as text by default, when the users create or edit an issue. For selection-based custom fields, the default values will be pre-selected options for users. Managing custom fields 129 130 Field Management Just like setting selection options, default options are also set on a per-custom-field-context basis: 1. Browse to the Custom fields page. 2. Click on the Configure option for the custom field for which you wish to configure select options. 3. Click on the Edit Default Value link for the custom field context to which you want to apply the default values. 4. Set the default value for the custom field. 5. Click on the Set Default button to set the default value. Setting the default value will be different for different custom field types. For text-based custom fields, you will be able to type any text string. For select-based custom fields, you will be able to select from the options you add. For picker-based custom fields, such as User Picker, you will be able to select a user directly from the user base. When setting a default value for a field, there are some implications you need to be aware of. If a field has a default value, all issues created will have that value for the field unless explicitly overwritten by users. This could defeat the purpose if the same field is also set as mandatory, since it will always have a value. This can also cause problems when you want to run searches such as all issues that do not have a value for the field, so it is very important to consider whether the default value you are setting is meaningful for your use case. Optimizing custom fields Now that we have seen how to create and manage custom fields, let’s revisit custom field context again. As we have seen, when you create a new custom field, Jira prompts you to set a context for it. However, this is a relatively new feature, and in older Jira versions, custom fields are created with a global context by default. As you add more and more custom fields to Jira, it is a good practice to check and optimize your custom field configurations, especially if you have been running your Jira instance since an older version, as most of your custom fields will likely be using the global context. To help you with that, Jira comes with a custom field optimizer. To run the optimizer, follow these steps: 1. Browse to the Custom fields page. 2. Click on the Optimize link at the top right. 3. Click on the Scan button to run a new scan of your custom fields. Once the scan has been completed, Jira will provide a report on different ways you can better optimize your custom field configurations to help improve your overall Jira performance. Field configuration 131 Figure 5.9 – Optimize custom fields For example, in the preceding screenshot, Jira has identified 10 custom fields that are using the global context, which would have an impact on Jira’s performance. By clicking on the Manage these custom fields link, Jira will list the 10 custom fields identified, and you can apply a context to each of the fields. Field configuration As you have already seen, fields are used to capture and display data in Jira. Fields can also have behaviors, which are defined by field configuration. For each field in Jira, you can configure the behaviors listed here: • Field description: This is the description text that appears under the field when an issue is edited. With field configuration, you can have different description text for different projects and issue types. • Visibility: This determines whether a field should be visible or hidden. • Required: This specifies whether a field will be optional or required to have a value when an issue is being created/updated. When applied to select, checkbox, or radio button custom fields, this will remove the None option from the list. • Rendering: This specifies how the content is to be displayed and what the field looks like when you are editing it. For example, a text-based field can have a default text editor, which will be a simple text-based editor, and a rich-text editor, which allows you to apply different styles to your text. A field configuration provides you with control over each individual field in your Jira, including both system and custom fields. Since it is usually a good practice to reuse the same set of fields instead of creating new ones for every project, Jira allows you to create multiple field configurations, by means of which we can specify different configurations on the same set of fields and apply them to different projects. 132 Field Management You can access the field configuration management page through the Jira administration console: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Field configurations option. This will bring you to the View Field Configurations page. We will be looking at how to manage and apply multiple field configurations in later sections of this chapter. But first, let’s take a close look at how to create new field configurations and what we can do with them. Adding a field configuration Creating new field configurations is simple. All you need to do is specify the name and a short description for the new configuration: 1. Browse to the View Field Configurations page. 2. Click on the Add Field Configuration button. 3. Enter the name and description for the new field configuration. 4. Click on the Add button to create a field configuration. It is always a good practice to adopt a naming convention for your configurations. As we will see later, in the Field configuration scheme section, field configurations are associated with issue types, so you can name your field configurations based on the project and/or issue type they will be applied to, for example,Demonstration Project Bugs Field Configuration 1.0.Wealsoadded a version number, so when you need to make changes to the field configuration, you can increment the version number, leaving a history of changes you can revert to. After a field configuration is created, it is not used until we associate it with a field configuration scheme. We will look at how to do this when we cover field configuration schemes. For now, let’s look at how to manage field behaviors in the field configuration. Managing field configurations Now that we have seen how to create new field configurations, it is time for us to take a closer look at the different configuration options. Firstly, just a quick recap – each field configuration includes all the fields available in Jira, and its behavior is defined according to each field configuration. We will then associate it with a field configuration scheme, which will determine when a field configuration will become active for a given issue. Perform the following steps to access field configuration options: 1. Browse to the View Field Configurations page. 2. Click on the Configure link for the field configuration you wish to configure. This will take you to the View Field Configuration page. On this page, all the fields and their current configuration options that are currently set for the selected field configuration are listed: Figure 5.10 – Manage field configurations As you can see, there are several options you can configure for each field, and depending on the field type, the options may vary. While we will be looking at each of the options, it is important to note that some options will override each other. This is Jira trying to protect you from accidentally creating a configuration combination that will break your system. For example, if a field is set to both Hidden and Required, your users will not be able to create or edit issues, so Jira will not allow you to set a field to REQUIRED if you have already set it to Hidden. A common mistake is when you make a field Required but do not have it on the issue’s Create or Edit screens. When this happens, Jira will still require the user to enter a value for the field even though the field is not on a screen. So, it is important to double-check and make sure all your required fields are placed on the appropriate screens. Field configuration 133 134 Field Management Field descriptions While having a meaningful name for your fields will help your users understand what the fields are for, providing a short description will provide more context and meaning. Field descriptions are displayed under the fields when you create or edit an issue. To add a description for a field, do the following: 1. Browse to the View Field Configuration page for the field configuration you wish to use. 2. Click on the Edit link for the field for which you wish to set a description. 3. Add a description for the field and click on Update. For custom fields, the description you enter here will override the description you provided when you first created them. Required fields You can set certain fields as Required or Mandatory for certain issues. This is a very useful feature as it ensures that critical information can be captured when users create issues. For example, for our support system, it makes sense to have our users enter the system that is misbehaving into a field and make that field compulsory to help our support engineers. You have already seen required fields in action. System fields, such as Summary and Issue Type, are compulsory in Jira (and you cannot change that). When you do not specify a value for a required field, Jira will display an error message underneath the field, telling you that the value is required. When you add a new field into Jira, such as a custom field, it is optional by default, meaning users do not need to specify a value. You can then change the setting to make those fields required: 1. Browse to the View Field Configuration page for the field configuration you wish to use. 2. Click on the REQUIRED/Optional link for the field you wish to set as the mandatory requirement. Figure 5.11 – Required/optional field You will notice that once a field is set to REQUIRED, there will be a small Required Text label in red next to the field name. When you create or edit an issue, the field will have a red (*) character next to its name. This is Jira’s way of indicating that a field is mandatory. Field visibility Most fields in Jira can be hidden from a user’s view. When a field is set to Hidden, users will not see the field on any screens, including issues such as create, update, and view. Perform the following steps in order to show or hide a field: 1. Browse to the View Field Configuration page for the field configuration you wish to use. 2. Click on the Show/Hide link for the field you wish to show or hide, respectively. Once a field has been set to Hidden, it will not appear onscreen and you will not be able to search in it. However, you can still use tools such as scripts to set values for hidden fields. For this reason, hidden fields are used to store data that is used by automated processes. Not all fields can be hidden. System fields, such as Summary and Issue Type, cannot be hidden. When you set a field to Hidden, you will notice that you can no longer set the field as Required. As stated earlier, setting a field to Required will make Jira enforce a value to be entered into the field when you create or edit an issue. If the field is hidden, there will be no way for you to set a value and you will be stuck. This is why Jira will automatically disable the Required option, especially if you have already hidden a field. On the other hand, if you marked a field as Required, when you hide the same field, you would notice that the field is no longer required. The rule of thumb is that field visibility will override required fields. Note A field cannot be both hidden and required. Field rendering Renderers control how a field will be displayed when it is viewed or edited. Some system and custom fields have more than one renderer, and for these fields, you can choose which one to use. For example, for text-based fields, such as Description, you can choose to use the simple text renderer or the more sophisticated wiki-style renderer, which will allow you to use wiki markup to add more styling. Jira ships with four different renderers: • Default text renderer: This is the default renderer for text-based fields. Contents are rendered as plain text. If the text resolves a Jira issue key, the renderer will automatically turn that into an HTML link. • Wiki-style renderer: This is an enhanced renderer for text-based fields. It allows you to use wiki markup to decorate your text content. • Select list renderer: This is the default renderer for selection-based fields. It is rendered as a standard HTML select list. Field configuration 135 136 Field Management • Autocomplete renderer: This is an enhanced renderer for selection-based fields, and it provides an autocomplete feature to assist users as they start typing into the fields. The following table lists all the fields that can have special renderers configured and their available options: Field Description Comment Environment Component Affects version Fix versions Custom field of type Text Field Custom field of type Multi Select Custom field of type Version Picker Available renderers This has a wiki-style renderer and default text renderer. This has a wiki-style renderer and default text renderer. This has a wiki-style renderer and default text renderer. This has an autocomplete renderer and a select list renderer. This has an autocomplete renderer and a select list renderer. This has an autocomplete renderer and a select list renderer. This has a wiki-style renderer and default text renderer. This has an autocomplete renderer and a select list renderer. This has an autocomplete renderer and a select list renderer. Table 5.4 – Field renderers Custom field of type Free Text Field (unlimited text) This has a wiki-style renderer and default text renderer. Perform the following steps to set the renderer for a field: 1. Browse the View Field Configuration page for the field configuration you wish to use. 2. Click on the Renderer link for the field you wish to set a renderer for (if it is available). You will be taken to the Edit Field Renderer page. 3. Select the renderer from the available drop-down list. 4. Click on the Update button to set the renderer. There are other custom renderers developed by third-party vendors. Just like custom fields, these are packaged as add-ons that you can install in Jira. Once installed, these custom renderers will be available for the selection of the appropriate field types. A good example is the JEditor add-on, which provides an advanced rich-text editor for all text- based fields including Description. Field configuration scheme With multiple field configurations, Jira determines when to apply each of the configurations through the field configuration scheme. A field configuration scheme maps field configurations to issue types. This scheme can then be associated with one or more projects. This allows you to group multiple field configurations mapped to issue types and apply them to a project in one go. The project will then be able to determine which field configuration to apply, based on the nature of the issue. For example, for a given project, you can have different field configurations for bugs and tasks. This grouping of configurations into schemes also provides you with the option to reuse existing configurations without duplicating work, as each scheme can be reused and associated with multiple projects. Managing field configuration schemes You can manage all your field configuration schemes from the View Field Configuration Schemes page: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Field Configuration Schemes option. This will bring you to the View Field Configuration Schemes page: Figure 5.12 – Manage field configuration schemes This is the main page where you can add, configure, edit, delete, and copy field configuration schemes. We will start by looking at how to add a new field configuration scheme next. Adding a field configuration scheme The first step in grouping your field configurations is to create a new field configuration scheme. By default, Jira does not come with any field configuration schemes. All the projects will use the system default field configuration. The new field configuration scheme will hold all the mappings between our field configurations and issue types. Field configuration scheme 137 138 Field Management To create a new field configuration scheme, all you need to do is specify the name and an optional description for the scheme: 1. Browse to the View Field Configuration Schemes page. 2. Click on the Add Field Configuration Scheme button. 3. Enter a name and description for the new field configuration scheme. 4. Click on the Add button to create the scheme. Since field configuration schemes are applied to projects, it is good practice to name them according to the projects.Forexample,theschemeforthesalesprojectcanbenamedSales Field Configuration Scheme. You can add a version number after the name to help you maintain changes. Once the new field configuration scheme is created, it will be displayed in the table that lists all the existing schemes. At this time, the scheme is not yet useful as it does not contain any configuration mappings and is associated with a project. Configuring a field configuration scheme Once you have a new field configuration scheme set up, you will be able to add mapping between field configurations and issue types. For each field configuration scheme, one issue type can be mapped to only one field configuration, while each field configuration can be mapped to multiple issue types. The following screenshot shows that the issue types Sub-task, Epic, and Task all have specific field configurations applied and that Default Field Configuration will be applied to all other issue types that are not explicitly mapped, such as Bug or Story: Figure 5.13 – Configure field configuration scheme Field configuration scheme 139 Note One issue type can only be mapped to one field configuration. When a field configuration scheme is first created, Jira creates a default mapping, which maps all unmapped issue types to the default field configuration. You cannot delete this default mapping as it acts as a catch-all condition for mappings that you do not specify in your scheme. What you need to do is add more specific mappings that will take precedence over this default mapping: 1. Browse to the View Field Configuration Schemes page. 2. Click on the Configure link for the field configuration scheme you wish to configure. 3. Click on the Associate an Issue Type with a Field Configuration button. 4. Select the issue type and field configuration from the dialog. 5. Click on the Add button to add the mapping. You can repeat these steps to add more mapping for other issue types. All unmapped issue types will use the Default mapping. Associating a field configuration scheme with a project After you create a new field configuration scheme and establish the mappings, the final step is to associate the scheme with a project for the configurations to take effect. It is important to note that, once you associate the field configuration scheme with a project, you cannot delete it until you remove all the associations so that the scheme becomes inactive again. To associate a field configuration scheme with a project, follow these steps: 1. Browse to the target project’s administration page. 2. Click on the Fields option in the left panel. 3. Select the Use a different scheme option from the Actions menu. 4. Select a new field configuration scheme and click on the Associate button. As shown in the following screenshot, the project is using PMO Field Configuration Scheme, which has four configurations. Three are mapped to specific issue types, and Default Field Configuration is applied to any issue types without an explicit mapping. 140 Field Management Figure 5.14 – Associate field configuration scheme Tip You can click on each of the field configurations to view their details. Screens In order for a field to be displayed when you view, create, or edit an issue, it needs to be placed on a screen. You have already seen this when creating new custom fields. One of the steps in the creation process is to select what screens to add the custom field to. Screens will be discussed further in Chapter 6, Screen Management, so we will not spend too much time understanding them right now. What you need to know for now is that after a field has been added to a screen, you can add it to additional screens or remove it completely. If you are working with just one field, you can configure it here from the field configurations. If you have multiple fields to update, a better approach will be to work directly with screens, as we will see in Chapter 6, Screen Management. The HR project 141 There is a subtle difference between hiding a field in field configuration and not placing a field on a screen. While the end result will be similar where, in both cases, the field will not show up, if you hide a field, you can still set a value for it through the use of default value, workflow post-functions (covered in Chapter 7, Workflow and Business Process), or custom scripts, essentially meaning that the field is there but just hidden. However, if the field is not on the screen, you cannot set its value. Another difference is that hiding a field will hide it for all screens that have the field added, for projects using the field configuration. Now that you have seen how to manage fields in Jira, it is time to expand our HR project. The HR project What we will do this time is add a few new custom fields to help capture some additional useful information. We will also create a customized field configuration specially designed for our HR team. Lastly, we will tie everything together by associating our fields, configurations, and projects through field configuration schemes. Setting up a custom field Since you are implementing a project for HR, and we have created two issue types in the last chapter, New Employee and Termination, for the New Employee issue type, we will add a new custom field called Direct Manager, so when everything is completed, the manager can be notified that their new team member is ready to start. Since the manager is already in the organization, we will be using a User Picker field, so Jira will be able to automatically look up the user for us. For our Termination issue type, we will also add a new custom field called Last Day, so we know when it will be the last day for the employee. For this field, we will use a date picker, so we can keep the date format consistent. To create these custom fields, execute the following tasks: 1. Browse to the Custom fields page. 2. Click on the Add Custom Field button. 3. Select the User Picker custom field type. 4. Name the custom field Direct Manager and click on Create. 5. Select all issue types and the HR project as the context for our new custom field. 6. Select HR: Task Management Create Issue Screen and HR: Task Management Edit/View Issue Screen from the list of screens, and click on Update. 7. Repeat steps 2 to 5, but select the Date Picker field type and call it Last Day. 142 Field Management Setting up the field configuration Now that we have our custom fields ready, the next step is to create a new field configuration so that we can specify the behaviors of our custom fields. What we will do here is set both new custom fields as Required, so when the issues are entered in Jira, users will have to enter a value for them. But the Direct Manager field should only be required when creating a New Employee issue, and not Termination. To do this, we need to create two field configurations: 1. Browse to the View Field Configurations page. 2. Click on the Add Field Configuration button. 3. Name the new field configuration New Employee Field Configuration. 4. Click on the Add button to create a new field configuration. Now that we have our new field configuration, we can start adding configurations to our new custom fields. 5. Click on the Required link for the Direct Manager custom field. 6. Repeat steps 2 to 5 to create a new field configuration called Termination Field Configuration, and make the Last Day field mandatory. Setting up a field configuration scheme We have our custom fields, and have configured the relevant options, created a new field configuration, and set the behavior of our fields. Now it is time to add them to a scheme: 1. Browse to the View Field Configuration Schemes page. 2. Click on the Add Field Configuration Scheme button. 3. Name the new field configuration scheme HR Field Configuration Scheme, as we will be applying this to our HR project. 4. Click on the Add button to create a new field configuration scheme. With the field configuration scheme created, we can associate the field configurations with their appropriate issue types, New Employee and Termination: 1. Click on the Associate an Issue Type with a Field Configuration button. 2. Set the issue type as New Employee and the field configuration as New Employee Field Configuration. 3. Click on the Add button to add the association. 4. Repeat steps 1 to 3 for the Termination issue type and Termination Field Configuration. Putting it together OK, so we have done all the hard work. We created new custom fields, a new field configuration, and a new field configuration scheme; the final step is to put everything together and see it in action: 1. Browse to the Project Administration page for our HR project. 2. Click on the Fields link on the left-hand side and the Use a different scheme option from the Actions menu. 3. Select HR Field Configuration Scheme and click on the Associate button. Alright, we are all done! You can pat yourself on the back, sit back, and take a look at your work in action. Create a new issue of the Termination type in the HR project, and you will see your new custom fields at the bottom of the page. As shown in the following screenshot, both the Direct Manager and Last Day fields are mandatory and an error message is displayed if we do not provide values for them. Figure 5.15 – Create a Termination issue We see the Direct Manager custom field here because both New Employee and Termination issue types use the same set of screens. We will look at how to use separate screens in Chapter 6. We can, however, also use field configuration to hide the field for the appropriate issue type. The HR project 143 144 Field Management Go ahead and create a new Termination issue by filling in the fields. On the View Issue page, you will see your new custom fields displayed, along with the values you provide: Table 5.16 – View termination issue As we can see, by adding our own custom fields in Jira, we are able to customize our intake form (create issue screen) to capture additional data than the out-of-the-box system fields, and we can also make certain fields required to ensure users will always fill them in. Summary In this chapter, we looked at fields in Jira. We also looked at how Jira is able to extend its ability to capture user data through custom fields, and at applying searchers to these fields to make the data they capture searchable. We explored how we can specify different behavior for fields under different contexts through the use of field configurations and schemes. We also briefly introduced screens, which we will delve deeper into in the next chapter. Lastly, we put all these together by adding new custom fields to our HR project. In the next chapter, we will expand on what we learned about fields by formally introducing you to screens, and will show you how combining fields and screens provides users with the most natural and logical forms to assist them with creating and logging issues. 6 Screen Management Fields collect data from users, and you have seen how to create your own custom fields from a wide range of field types to address your different requirements. Indeed, data collection is at the center of any information system, but that is only half of the story. It is just as important to have your fields organized so that users do not feel overwhelmed, and the general flow of fields needs to be logically structured and grouped into sections. This is where screens come in. In this chapter, we will pick up from where we left off in the last chapter and explore the relationship between fields and screens. We will further discuss how you can use screens to customize your Jira to provide users with a better user experience. By the end of the chapter, you will have learned the following: • What screens are and how to create them • How to add fields onto screens • How to break down your screen into logical sections with tabs • The relationship between screens and issue operations • How to link screens with projects and issue types • How to configure project-specific screens as a project administrator Understanding Jira and screens Before you can start working with screens, you need to first understand what they are and how they are used in Jira. Compared to a normal paper-based form, fields in Jira are like checkboxes and spaces that you need to fill in, and screens are like form documents themselves. When fields are created in Jira, they need to be added to screens for them to be presented to users. 146 Screen Management In most cases, screens are associated with issue operations such as creating, viewing, and editing issues. This association is defined in screen schemes. This allows you to have different screens for different operations. Screen schemes are then associated with issue type screen schemes, which, when applied to projects, will map screen schemes to issue types. This lets each issue type in a project have its own set of screens. The only time a screen will be used directly is when it is associated with a workflow transition. In Jira, a workflow defines the various statuses an issue can go through. For example, an issue can go from open to closed. Transitions are the actions that take the issue from one status to the next, and Jira lets you display a screen as part of the action if you choose to. We will cover workflows in Chapter 7, Workflow and Business Process. To help you visualize how screens are used in Jira, Atlassian has provided the following diagram, which summarizes the relationship between fields, screens, and their respective schemes: Figure 6.1 – Screens and schemes Working with screens 147 Now that we have a basic understanding of screens, let’s start looking at how you can create and manage them in Jira. Working with screens While many other software systems provide users with limited control over the presentation of screens, Jira is very flexible when it comes to screen customizations. You can create your own screens and decide what fields are to be placed on them and their order. You can also decide which screens are to be displayed for issue operations. In Jira, you can create and design customized screens for the following operations: • Creating an issue in the Create Issue dialog box • Editing an issue when an issue is being updated • Viewing an issue after an issue is created and is being viewed by users • Transitioning an issue through a workflow Screens are managed centrally from the administration console, which means you need to be a Jira administrator to create and configure screens. Perform the following steps to access the View Screens page: 1. Log in as a Jira administrator user. 2. Browse to the Jira administration console. 3. Select the Issues tab and then the Screens option. This will bring up the View Screens page. The View Screens page lists all the screens that are currently available in your Jira instance. You can select a screen and configure what fields will be on this screen and decide how you will divide a screen into various tabs. For each of the screens listed here, Jira will also tell you what screen scheme each of the screens is a part of and the workflows that are being used. You have probably noticed that for screens that are either part of a screen scheme or workflow, there is no Delete option available, as you cannot delete screens that are in use. You need to disassociate the screen from screen schemes and/or workflows to delete them, as shown in the following screenshot: 148 Screen Management Figure 6.2 – View screens As shown in the preceding screenshot, for each screen you can perform the following operations: • Configure: This configures what fields are to be placed on the screen. It is not to be confused with the Edit operation. • Edit: This updates the screen’s name and description. • Copy: This makes a copy of the selected screen, including its tabs and field configurations. • Delete: This deletes a screen from Jira. This is only available if it is not being used by a screen scheme or a workflow. The screens listed here do not affect Jira Service Desk. We will cover screen and field configuration for Jira Service Desk in Chapter 11, Jira Service Management. Next, let’s take a look at the default screens that come with Jira and how you can create your own screens. Adding a new screen Jira comes with several screens by default (as listed in the following bullet list), and every time you create a new project, a new set of screens is created for the project, based on the template you select. These project-specific screens will all have their names starting with the project key, for example, HD: Task Management View Issue Screen, where HD is the project’s key: • Default screen: This screen is used for creating, editing, and viewing issues • Resolve Issue screen: This screen is used when resolving and closing issues Working with screens 149 • Workflow screen: This screen is used when transitioning issues through workflows (if they are configured to have a screen, such as Reopen Issue) While the default screens and screens automatically created for your projects can cover the most basic requirements, you will soon find yourself outgrowing them, and adjustments will need to be made. For example, if you want to keep certain fields read-only, such as priority so that they cannot be changed after issue creation, you can achieve this by setting up different screens for creating and editing issues. Another example is having different Create and Edit screens for different issue types, such as Bug and Task. In these cases, you will need to create your own screens in Jira using the following steps: 1. Browse to the View Screens page. 2. Click on the Add screen button. This will bring up the Add screen dialog box. 3. Enter a meaningful name and description for the new screen. It is a good idea to name your screen after its purpose, for example, HD: Bug Create Screen, to indicate that it is the screen to create new bug issues for project HD. 4. Click on the Add button to create the screen. At this point, your new screen is blank with no fields on it. Fields in Jira are arranged and displayed from top to bottom in a single column. You have full control of what fields can be added and in what order they can be arranged. The only exception to this is for the View screen. When you are viewing an issue, fields are grouped together by type. For example, user fields such as reporter and assignee are displayed together on the top right-hand side of the page. Also note that for system fields such as Summary and Issue, even if you take them off the screen, they will still be displayed when viewing an issue. For these fields, you cannot change their position on the screen. Adding a field to a screen When you first create a screen, it is of little use. For screens to have items to present to the users, you must first add fields onto the screens: 1. Click on the Configure link for the screen you wish to add fields to. 2. Select the fields you would like to add by typing in the field’s name in the Field name drop- down list. Jira will auto-match the field as you type, as shown in the following screenshot. If you do not see the field you are looking for, make sure it is not already on the screen or on a different tab. Tabs are covered in a later section: 150 Screen Management Figure 6.3 – Adding a field to a screen Fields are added to the bottom of the list. You can reorder the list of fields by simply dragging them up and down. Deleting a field from a screen Fields can be removed from a screen. When a field is taken off, the field will not appear when the screen is presented to the user. There is a subtle difference between deleting a field from a screen and hiding it (as discussed in Chapter 5, Field Management). Although both actions will prevent the field from showing up, by removing the field, issues will not receive a value for that field when they are created. This becomes important when a field is configured to have a default value. When the field is removed from the screen, the issue will not have the default value for the field, while if the field is simply hidden, the default value will be applied. You will also need to pay close attention when deleting fields from a screen, as there is no confirmation dialog. Make sure that you do not delete required fields, such as Summary, from a screen used to create new issues. As seen in Chapter 5, Field Management, Jira will prevent you from hiding fields that are marked as required, but Jira does not prevent you from taking the required fields off the screen. Therefore, it is possible for you to end up in a situation where Jira requires a value for a field that does not exist on the screen. This can lead to very confusing error messages for end users. To remove a field from the screen, do the following: 1. Click on the Configure link for the screen you wish to remove fields from. 2. Hover your mouse over the field you want to delete and click on the X (remove) button. When you delete a field from a screen, existing issues will not lose their value for the field. Once you add the field back, the values will be displayed again. Using screen tabs In most cases, you will be sequentially adding fields to a screen and users will fill them from top to bottom. However, there will be cases where your screen becomes over-complicated and cluttered due to the sheer number of fields you need, or you may simply want to have a way to logically group several fields together and separate them from the rest. This is where tabs come in. If you think of screens as the entire form a user must fill in, then tabs are the individual pages or sections that make up the whole document. Tabs go from left to right, so it is a good practice to design your tabs to flow logically from left to right. For example, the first tab can gather general information, such as the summary and description. Subsequent tabs will gather more domain-specific information, as shown here: Figure 6.4 – Screen tabs Working with screens 151 152 Screen Management Adding a tab to a screen You can add tabs to any screen in Jira. In fact, by default, all screens have a default tab called Field Tab, which is used to host all the fields. You can add new tabs to a screen to break down and better manage your screen presentation, as follows: 1. Browse to the View Screens page. 2. Click on the Configure link for the screen on which you wish to add a new tab. 3. Click on the + button above the field list and enter a name for the tab. 4. Click on the Add button to create the tab. Tabs are organized horizontally from left to right. When you add a new tab to the screen, it is appended to the end of the list. You can change the order of tabs by dragging them left and right in the list, as shown in the following screenshot: Figure 6.5 – Adding a new screen tab You can also move a field from one tab to another by dragging the field and hovering it over the target tab. This will save you time from having to manually remove a field from a tab and then add it to the new tab. Note One thing to keep in mind is that, if there are no fields placed on a tab, the tab will not be displayed. Working with screens 153 Editing/deleting a tab Just like screens, you can maintain existing tabs by editing their names and/or removing them from the screen. Perform the following steps to edit a tab’s name: 1. Browse to the View Screens page. 2. Click on the Configure link for the screen that has the tab you wish to edit. 3. Select the tab by clicking on it. 4. Click on the edit icon and enter a new name for the tab. 5. Click on the Save button to apply the change. When you delete a tab, the fields that are on the tab will be taken off the screen. You will need to re-add or move them to a different tab if you still want those fields to appear on the screen. You cannot delete the last tab on the screen. To delete a tab, perform the following steps: 1. Browse to the View Screens page. 2. Click on the Configure link for the screen that has the tab you wish to edit. 3. Select the tab by clicking on it. 4. Click on the delete icon. Jira will ask you to confirm whether you want to delete the tab and list all the fields present. 5. Click on the Delete button to remove the tab from the screen. Editing/deleting a screen You can edit existing screens by updating their details to help keep your configurations up to date and consistent. Perform the following steps to edit a screen: 1. Browse to the View Screens page. 2. Click on the Edit link for the screen on which you wish to update. This will take you to the Edit Screen page. 3. Update the name and description of the screen. 4. Click on the Update button to apply your changes. To delete an existing screen, it must not be in use by any screen schemes or workflows. If it is associated with a screen scheme or workflow, you will not be able to delete it. You will need to undo the association first. Perform the following steps to delete a screen: 1. Browse to the View Screens page. 2. Click on the Delete link for the screen you wish to remove. This will take you to the Delete Screen page for confirmation. 3. Click on the Delete button to remove the screen. 154 Screen Management By deleting a screen, you do not delete the fields that are on the screen from the system. Copying a screen Screens can sometimes be complex, so creating a new screen from scratch may not be the most efficient method if there is already a similar one available. Just like with many other entities in Jira, you can make a copy of an existing screen, thus cutting down the time that it would otherwise take you to re-add all the fields: 1. Browse to the View Screens page. 2. Click on the Copy link for the screen you wish to copy. 3. Enter a new name and description for the screen. 4. Click on the Copy button to copy the screen. Note When you copy a screen, it will also copy all the tabs a screen has. We have seen how you can create and configure screens; next we will look at how we can apply screens to issue operations, with screen schemes. Working with screen schemes You have seen how we can create and manage screens and how to configure what fields to add to the screens. The next piece of the puzzle is letting Jira know which screen to use for each issue operation. Screens are displayed during issue operations, and a screen scheme defines the mapping between screens and the operations. With a screen scheme, you can control which issue operations the screen displays, as follows: • Create Issue: This screen is shown when you create a new issue • Edit Issue: This screen is shown when you edit an existing issue • View Issue: This screen is shown when you view an issue Just like screens, whenever you create a new project in Jira, a new screen scheme is created specifically for your project, and screens are automatically assigned to these issue operations. The defaults created are usually good enough to get started. However, there will be times when you do not want certain fields to be available for editing once the issue is created. Another example would be when certain fields are not needed during creation because the required information may not be available at the time. Therefore, instead of confusing and/or overwhelming your users, leave those fields out during issue creation and only ask for them to be filled in at a later time when the information becomes available. As you can see, by having different screens for each issue operation rather than having a one-screen- fits-all approach, Jira provides you with a new level of flexibility to control and design your screens. As always, if there are no significant differences between the screens, for example, create and edit, it is recommended that you create a base screen and use the Copy Screen feature to reduce your workload. Just like screens, you need to be a Jira administrator to manage screen schemes. Perform the following steps to manage screen schemes: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Screen Schemes option to bring up the View Screen Schemes page: Figure 6.6 – View Screen Schemes From the View Screen Schemes page, you will be able to see a list of all the existing screen schemes, create and manage their configurations, and view their associations with issue type screen schemes (this will be explained in the Issue type screen scheme section). Let’s start with creating new screen schemes. Adding a screen scheme Usually, you will be using the screen scheme created by Jira for your project. However, there will be cases where you need more than one. For example, if you need to display a different set of screens based on the various issue types you have in your project, you will need to create a new screen scheme for each issue type. Perform the following steps to create a new screen scheme: 1. Browse to the View Screen Schemes page. 2. Click on the Add screen scheme button. Working with screen schemes 155 156 Screen Management 3. Enter a name and description for the new screen scheme. Just like with screens, it is a good idea to adopt a consistent pattern that describes the purpose of the screen scheme, such as DEMO: Bug Screen Scheme. 4. Select a default screen from the list of screens. This screen will be displayed when no specific issue operation is mapped. 5. Click on the Add button to create the screen scheme. At this stage, the new screen scheme is not in use. This means that it is not associated with any issue type screen schemes yet (issue type screen schemes are covered in later sections). The new screen scheme will also use the same screen selected as your default screen for all issue operations. Now, if you want to use the same screen to create, edit, and view, then you are all set; there is no need to perform any further configuration to your screen scheme. However, if you need to have different screens displayed for different issue operations, then you will need to establish this association. When an issue operation does not have an association with a screen, the selected default screen will be applied. If the issue operation is later given in a screen association, then the specific association will take precedence over the general fallback default screen. Associating screens to issue operations Each issue operation can be associated with one screen. Perform the following steps to associate an issue operation with a screen: 1. Click on the Configure link for the screen scheme you want to update. 2. Click on the Associate an issue operation with a screen button. 3. Select an issue operation to be assigned to a screen. 4. Select the screen to be associated to the issue operation. 5. Click on the Add button to create the association. Figure 6.7 – Configure a screen scheme Working with screen schemes 157 As shown in the preceding screenshot, the Create Issue and Edit Issue operations are associated with DEMO: Project Management Create Issue Screen and DEMO: Project Management Edit Issue Screen, respectively. Since we do not have a screen associated with the View Issue operation, the default association, DEMO: Project Management View Issue Screen, will be used. Editing/deleting an association After you create an association for an issue operation, Jira prevents you from creating another association for the same issue operation by removing it from the list of available options. In order to change the association to a different screen, you need to edit the existing association, as follows: 1. Click on the Configure link for the screen scheme you want to update. 2. Click on the Edit link for the association you wish to edit. 3. Select a new screen to associate with the issue operation. 4. Click on the Update button to apply the change. If you decide that one or more existing associations are no longer needed, then you can delete them from the screen scheme by performing the following steps: 1. Click on the Configure link for the screen scheme you want to update. 2. Click on the Delete link for the association you wish to delete. Please note that, unlike other similar operations, deleting an issue operation association does not prompt you with a confirmation page. As soon as you click on the Delete link, your association will be deleted immediately. Editing/deleting a screen scheme You can update the details of existing screen schemes, such as their name and description. In order for you to make changes to the default screen selection, you need to configure the screen scheme, which will be covered in later sections. Perform the following steps to edit an existing screen scheme: 1. Browse to the View Screen Schemes page. 2. Click on the Edit link for the screen scheme you wish to edit. 3. Update the name and description with new values. 4. Click on the Update button to apply the changes. 158 Screen Management Inactive screen schemes can also be deleted. If the screen scheme is active (that is, associated with an issue type screen scheme), then the Delete option will not be present. Perform the following steps to delete a screen scheme: 1. Browse to the View Screen Schemes page. 2. Click on the Delete link for the screen scheme you wish to delete. 3. Click on the Delete button to confirm that you wish to delete the screen scheme. Copying a screen scheme While screen schemes are not as complicated as screens, there will still be times when you would like to copy an existing screen scheme rather than create one from scratch. You might wish to copy the scheme’s screens/issue operations associations, which we will cover in the following section, or make a quick backup copy before making any changes to the scheme. Perform the following steps to copy an existing screen scheme: 1. Browse to the View Screen Schemes page. 2. Click on the Copy link for the screen scheme you wish to copy. 3. Enter a new name and description for the screen scheme. 4. Click on the Copy button to copy the selected screen scheme. Just like creating a new screen scheme, copied screen schemes are inactive by default. Issue type screen scheme Screen schemes group screens together and create associations with issue operations. The next piece of the puzzle is to tell Jira to use our screen schemes when creating, viewing, and editing specific types of issues. We do not directly associate screen schemes to Jira. The reason for this is that Jira has the flexibility to allow you to define this on a per-issue-type level. What this means is that, instead of forcing all issue types in a given project to use the same screen scheme, you can use different screen schemes for different issue types. This extremely flexible and powerful feature is provided through the issue type screen scheme. Just like screens and screen schemes, you need to be a Jira administrator to create and manage issue type screen schemes. Perform the following steps to manage issue type screen schemes: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Issue type screen schemes option to bring up the Issue Type Screen Schemes page: Issue type screen scheme 159 Figure 6.8 – View the issue type screen schemes Just as with a screen scheme, Jira will automatically create an issue type screen scheme when you create your project. Since one project can only have one issue type screen scheme associated with it, usually you will not need to create new ones yourself. However, there might be a time when you want to create a new scheme, such as experimenting with some new configurations while still wanting to keep the existing one untouched in case of a rollback. Perform the following steps to create a new issue type screen scheme: 1. Browse to the Issue Type Screen Schemes page. 2. Click on the Add issue type screen scheme button. 3. Enter a name and description for the new issue type screen scheme. 4. Select a default screen scheme from the list of screen schemes. 5. Click on the Add button to create the issue type screen scheme. That’s right, you guessed it! The new issue type screen scheme is not yet in use. It will only become active once it is applied to one or more projects, which we will look at shortly, but let’s first look at how to associate screen schemes with issue types. Associating issue types to screen schemes Jira determines which screen scheme to use for an issue type by establishing an association between screen schemes and issue types. Each issue type can have only one screen scheme associated with it. However, each screen scheme can be associated with more than one issue type. 160 Screen Management Perform the following steps to add a new association: 1. Click on the Configure link for the issue type screen scheme you wish to configure. 2. Click on the Associate an issue type with a screen scheme button. 3. Select the issue type to add an association. 4. Select the screen scheme to be associated with the issue type. 5. Click on the Add button to create the association: Figure 6.9 – Configure an issue type screen scheme As shown in the preceding screenshot, the Story, Task, and Bug issue types are explicitly associated with DEMO: Project Management Story Screen Scheme, DEMO: Project Management Task Screen Scheme, and DEMO: Project Management Bug Screen Scheme, respectively. All other issue types, such as Sub-task, will be associated with the default DEMO: Project Management Screen Scheme. Editing/deleting an association You can update existing associations such as the default association, which is created automatically when you create a new issue type screen scheme: 1. Click on the Configure link for the issue type screen scheme you wish to configure. 2. Click on the Edit link for the association you wish to edit. 3. Select a new screen scheme to associate it with the issue type. 4. Click on the Update button to apply the change. You can also delete existing associations for issue types if you no longer need them to be explicitly set. However, you cannot delete the default association, since it is used as a catch for all of the issue types that do not have an association defined. This is important because, while you may have created Issue type screen scheme 161 associations for all of the issue types right now, you might add new issue types down the line and forget to create associations for them. To delete an association, perform the following steps: 1. Click on the Configure link for the issue type screen scheme you wish to configure. 2. Click on the Delete link for the association you wish to delete. Just like associations in screen schemes, you will not be taken to a confirmation dialog, and the association will be deleted immediately. Editing/deleting an issue type screen scheme You can make updates to an existing issue type screen scheme’s name and description. To change its screen scheme/issue type association details, you need to configure the issue type screen scheme, which will be covered in later sections. Perform the following steps to update an issue type screen scheme: 1. Browse to the Issue Type Screen Schemes page. 2. Click on the Edit link for the issue type screen scheme you wish to edit. 3. Update the name and description with new values. 4. Click on the Update button to apply the changes. Just as with all of the other schemes in Jira, you cannot delete issue type screen schemes that are in use. You will have to make sure that no project uses it before Jira allows you to delete the scheme. To delete issue type screen schemes, perform the following steps: 1. Browse to the Issue Type Screen Schemes page. 2. Click on the Delete link for the issue type screen scheme you wish to delete. 3. Click on the Delete button to remove the issue type screen scheme. Copying an issue type screen scheme Issue type screen scheme cloning is also available in Jira. You can easily make copies of existing issue type screen schemes. One very useful application of this feature is that it enables you to make backup copies before experimenting with new configurations. Note that copying the issue type screen scheme does not back up the screen schemes and screens that it contains. Perform the following steps to copy an existing issue type screen scheme: 1. Browse to the Issue Type Screen Schemes page. 2. Click on the Copy link for the issue type screen scheme you wish to copy. 3. Enter a new name and description for the issue type screen scheme. 4. Click on the Copy button to copy the selected scheme. 162 Screen Management 5. Newly created issue type screen schemes are inactive by default, while cloned schemes are not used by any projects. The last step to tie the screens, screen schemes, and issue type screen scheme together is to apply the issue type screen scheme to a project. Associating an issue type screen scheme with a project The final piece of the puzzle to put your screens to use is to associate the issue type screen scheme with the project you want to use. Perform the following steps to associate your new issue type screen scheme: 1. Browse to the target project’s administration page. 2. Click on the Screens option from the left panel. 3. Select the Use a different scheme option from the Actions menu: Figure 6.10 – Associate an issue type screen scheme to a project 4. Select the issue type screen scheme from the Scheme select list. 5. Click on the Associate button. Delegating screen management 163 Once you associate the issue type screen scheme with the project, Jira will show you the details of the mapping, as shown in the preceding screenshot. Delegating screen management Managing screen configurations used to be centrally controlled by the Jira administrator. The project administrator can only select what issue type screen scheme to use, but if modifications need to be made for the screens, the Jira administrator will need to be involved. This often creates a bottleneck for simple things, such as adding or removing a field from a screen, especially for large organizations that have many projects but only a few Jira administrators. Jira now has a new feature called Extended Project Administration, which empowers project administrators by allowing them to make changes to screens used by their projects. Extended project administration is controlled via permission settings, which we will cover in Chapter 9, Securing Jira. There are, however, some restrictions for this, as listed here: • The screen must not be a default system screen • The screen must already be used by the project • The screen must not be shared with any other projects or used as a transition screen in workflows • Only fields that already exist in the system can be added to a screen Essentially, this means that you, as a project administrator, can only make changes to screens that are dedicated to a single project. If the screen is shared with multiple projects, you will still need help from a Jira administrator. To make changes to screens for your project as a project administrator, perform the following steps: 1. Browse to the target project’s administration page. 2. Click on the Screens option from the left panel. 3. Expand the issue type and select the screen you want to configure. If the screen can be configured, you should see something similar to the following screenshot, where you have the familiar screen configuration page, but now shown inside the context of a project: 164 Screen Management Figure 6.11 – Delegated screen management Troubleshooting fields and screens As we have seen in this and the previous chapters, many factors can control whether a field should be displayed. It can be very confusing and frustrating when an expected field does not display, as there are many configurations to check, such as screens, field configurations, and more. It is for this reason that Jira has a handy tool that can help you to determine why a field is not displaying for a given issue. To use the field helper tool, do the following: 1. Browse to the issue where you are not seeing the field. 2. Click on the Admin dropdown and then the Where is my field? option: Figure 6.12 – Field helper 3. Select the field you want to check: Figure 6.13 – Field helper result As we can see from the preceding screenshot, the Archiver field is not being displayed on the issue because the field does not have a value for the current issue. So, this will save you time from checking whether the field is added to the screen or if the field configuration has set the field to hidden. The HR project Armed with the new knowledge that you have gathered in this chapter, together with fields from the previous chapter, it is time for you to further customize your Jira to provide a better user experience through presentation. What we will do this time is create new screens and apply them to our HR project. We want to separate the new fields that are showing generic fields from our specialized custom fields designed for handling employee onboarding and termination. We also want to apply the changes to the issues of the New Employee and Termination types only, and not affect the other issue types in the project. As with any changes to be done on a production system, it is critical that you have a backup of your current data before applying changes. The HR project 165 166 Screen Management Setting up screens In Chapter 5, Field Management, you created a few custom fields specifically designed for our HR team. The problem we had is that all of the new fields show up for both the New Employee and Termination issue types, regardless of whether they are applicable, and this is because both issue types use the same set of screens. To address this, we will create two new sets of screens, one for New Employee and one for Termination. The default one can be left for other issue types we have in the project, such as Task. The easiest way to do this will be to clone the existing screens, so we do not have to manually add all of the fields, and avoid forgetting to add a field by accident. To create screens for each issue type, perform the following steps: 1. Browse to the View Screens page and click on the Copy link for HR: Task Management Create Issue Screen. 2. Name the new screen HR: Create/View New Employee Screen. 3. Click on the Copy button to create the screen. Now that we have our new screen, it is time to configure its fields using the following steps. Since this screen is for creating New Employee issues, we do not need the Last Day field: 1. Click on the Configure link of our new HR: Create/View New Employee Screen. 2. Remove the Last Day field by hovering over it and clicking its Remove button. Just to spice things up a bit, we can also create a new People tab and move all people-related fields, such as the Assignee, Reporter, and Direct Manager fields, onto that tab. We created and configured our create screen. Our new edit screen is going to look very similar to this with just a few modifications. Perform the following steps as we want to remove the Issue Type field since we do not want users to change the issue type after it is created: 1. Click on the Copy link for HR: Create/View New Employee Screen. 2. Name the new screen HR: Edit New Employee Screen. 3. Click on the Copy button to create the new screen. 4. Remove the Issue Type field. Repeat the steps to create a new set of screens for the Termination issue type. This time, instead of removing the Last Day field, remove the Direct Manager field from both screens. The HR project 167 Setting up screen schemes With the screens created and configured, we now need to link them up with issue operations, so that Jira will know on which action the new screens will be displayed, using the following steps: 1. Browse to the View Screen Schemes page and click on Add Screen Scheme. 2. Name the new screen scheme HR: New Employee Screen Scheme. 3. Select HR: Create/View New Employee Screen as the default screen. 4. Click on the Add button to create the screen scheme. With our screen scheme in place, it is time to link up our screens with their respective issue operations, as follows: 1. Click on the Associate an Issue Operation with a Screen button. 2. Select HR: Edit New Employee Screen for the Edit Issue operation. Since we assigned HR: Create/View New Employee Screen to Default, this screen will be applied to unmapped operations—Create Issue and View Issue. There are no differences if you choose to explicitly set the mappings for the preceding two operations. We have created the screen scheme for the New Employee issue type. Now repeat the same steps for the Termination issue type. Setting up issue type screen schemes Now, you need to apply the newly created screen scheme to the correct issue type. Since Jira has already created an issue type screen scheme for our project, we just need to configure it to use our new screen schemes for the appropriate issue types, using the following steps: 1. Browse to the Issue Type Screen Schemes page and click on the Configure link for HR: Task Management Issue Type Screen Scheme. 2. Click on the Associate an issue type with a screen scheme button. 3. Select New Employee for Issue Type. 4. Select HR: New Employee Screen Scheme as the screen scheme to be associated. 5. Click on the Add button to create the association. This will ensure that issues of the New Employee type will have your new screens applied, while issues of other types will not be affected. Now, repeat the steps to associate the Termination issue type with its screen scheme. 168 Screen Management Putting it together Since we are reusing the existing issue type screen scheme by associating various issue types with our new screen schemes, we do not need to make any additional changes. However, if you have created a new issue type screen scheme instead, you will need to associate it with the HR project. You can now take a look at your hard work and see your custom screens, fields, and tabs all working nicely together to present you with a custom form for collecting user data. Let’s go ahead and create a new incident and see what your newly customized Create Issue screen will look like, as shown in the following screenshot: Figure 6.14 – HR project result As you can see, the Last Day field is no longer showing on the screen when you create a New Employee issue, and our people-related fields are now showing on the new People tab. If you create a new Termination issue, the Direct Manager field will not display. Summary 169 Summary In this chapter, we looked at how Jira structures its presentation with screens. We looked at how screens are used in Jira via screen schemes, which map screens to issue operations. We also looked at how issue type screen schemes are then used to map screen schemes to issue types. Therefore, for any given project, each issue type can have its own set of screens for create, edit, and view. We also discussed how screens can be broken down into tabs to provide a more logical grouping of fields, especially when your screen starts to have a lot of fields on it. Together with custom fields, which we saw in the previous chapter, we can now create effective screen designs to streamline our data collection. In the next chapter, we will delve into workflows, one of the most powerful features in Jira. Part 3: Advanced Jira In the final section of this book, you will get exposure to some advanced features of Jira. You will explore the Jira security model; understand and learn about the search, report, and analysis functions; and look at Jira Service Desk, which allows Jira to be run as a support portal. The following chapters are included in this section: • Chapter 7, Workflow and Business Process • Chapter 8, Emails and Notifications • Chapter 9, Securing Jira • Chapter 10, Searching, Reporting, and Analysis • Chapter 11, Jira Service Management • Chapter 12, Jira and Third Party Apps 7 Workflow and Business Process In the previous chapters, we learned some of the basics of Jira and how to customize its data collection and presentation with custom fields and screens. In this chapter, we will dive in and take a look at workflows, one of the core and most powerful features of Jira. A workflow controls how issues in Jira move from one status to another as they are being worked on, often passing from one assignee to another. Unlike many other systems, Jira allows you to create your own workflows to resemble your processes. By the end of this chapter, you will have learned the following: • What a workflow is and what it consists of • The relationship between workflows and screens • What statuses, transitions, conditions, validators, and post functions are • How to create your own workflow with the workflow designer • How to associate a workflow with projects Specifically, we will look at the following topics: • Mapping business processes • Understanding workflows • Managing workflows • Using the workflow designer • Authoring a workflow • Updating an existing workflow • Understanding workflow schemes • Applying a workflow scheme to projects 174 Workflow and Business Process • Delegated workflow management • Extending a workflow with workflow add-ons • The human resources (HR) project Mapping business processes It is often said that a good software system is one that adapts to your business and not one that requires your business to adapt to the software. Jira is an excellent example of the former. The power of Jira is that you can easily configure it to model your existing business processes through the use of workflows. A business process flow can often be represented as a flow chart. For example, a typical approval flow may include tasks such as approval submission, approval review, and—finally—approval or rejection of the request, where the user needs to follow these tasks in sequential order. You can easily implement this as a Jira workflow. Each task will be represented as a workflow status, with transitions guiding you on how you can move from one status to the next. In fact, when working with workflows, it is often a good approach to first draft the logical flow of the process as a flow chart and then implement it as a workflow. As we will see, Jira provides many tools to help you visualize your workflows. Now that we have briefly seen how you can map a normal business process to a Jira workflow, it is time to take a closer look at the components of a workflow and how you can create your own workflows. Understanding workflows A workflow is what Jira uses to model business processes. It is a flow of statuses (steps) that issues go through one by one, with paths between the statuses (transitions). All issues in Jira have a workflow applied, based on their issue type and project. Issues move through workflows from one status (for example, Open) to another (for example, Closed). Jira allows you to visualize and design workflows as a diagram, as shown here: Understanding workflows 175 Figure 7.1 – Jira workflow The preceding diagram shows a simple workflow in Jira. The rectangles represent the statuses, and the arrow lines represent transitions that link statuses together. As you can see, this looks a lot like a normal flow chart depicting the flow of a process. Also, notice that statuses have different colors. The color of a status is determined by the category it belongs to. There are three categories—To Do (gray), In Progress (blue), and Done (green). Categories help you to easily identify where along the workflow an issue is by using color as an indicator. Issues in Jira, starting from when they are created, go through a series of steps identified as issue statuses, such as In Progress and Closed. These movements are often triggered by user interactions. For example, when a user clicks on the Start Progress link, the issue is transitioned to the In Progress status, as shown in the following screenshot: 176 Workflow and Business Process Figure 7.2 – Transition options for issue There is a definitive start of a workflow, which is when an issue is first created, but the end of a workflow can sometimes be ambiguous. For example, in the default workflow, issues can go from OPEN to CLOSED to REOPENED and back to CLOSED. By convention, when people talk about the end of a workflow, they are usually referring to a status named CLOSED or the status where issues are given a resolution. Once a resolution is given, the issue comes to a logical end. Several built-in features of Jira follow this convention; for example, issues with resolutions set will not be displayed on the Assigned to Me list on the home page. For this reason, when you close an issue, you should either prompt the user to select a resolution value by having it on a screen or automatically set the resolution value via a post function (post functions are covered later in this chapter). When you reopen an issue, you should also clear the resolution value from the issue, and this is usually done automatically via a post function as well. Important note When work for an issue is completed, it should be given a resolution. Managing workflows Workflows are controlled and managed centrally from the Jira administration console, so you need to be an administrator to create and configure workflows. To manage workflows, perform the following steps: 1. Log in to Jira as a Jira administrator. 2. Browse to the Jira administration console. 3. Select the Issues tab and then the Workflows option. This will bring up the View Workflows page: Managing workflows 177 Figure 7.3 – Workflow list page From the View Workflows page, you will be able to manage all the available workflows and create new workflows. The page is divided into two sections, Active and Inactive. Active workflows are being used by projects, and inactive ones are not. By default, the Inactive section is collapsed, so the page will only display active workflows. The preceding screenshot shows both the sections being expanded. Jira comes with a default read-only workflow called jira, mostly used to remain backward compatible with existing projects, and this is applied to projects that do not have any specific workflow applied. For this reason, you cannot edit or delete this workflow. New projects will have their own workflows created based on the template selected. These project-specific workflows will have their names start with theprojectkey,followedbytheproject’stemplate,suchasHR: Task Management Workflow. Issue statuses In a Jira workflow, an issue status represents a state in the workflow for an issue. It describes the current status of the issue. If we compare it to a flow chart, the highlighted rectangle indicates the current status of the issue along the process. Just as a task can only be in one stage of a business process, an issue can be in only one status at any given time; for example, an issue cannot be both open and closed at the same time. 178 Workflow and Business Process There is also a term called step, which is the workflow term for statuses. Since Jira has simplified its workflow administration, step and status can be used interchangeably. For consistency, we will be using the term status in this book, unless a separation needs to be made in special cases. Transitions Statuses represent stages in a workflow, and the path that takes an issue from one status to the next is known as a transition. A transition links two statuses together. A transition cannot exist on its own, meaning it must have a start and finish status and can only have one of each. This means that a transition cannot conditionally split off to different destination statuses. Transitions are also one-way only. This means that if a transition takes an issue from status A to status B, you must create a new transition if you want to go back from status B to status A. Transitions have several components. These are set out here: • Conditions: Criteria must be met before a transition is available (visible) for users to execute. These are usually used to control permissions around how users can execute a transition. • Validators: These are the verifications that must pass before a transition can be executed. They are usually used together with transition screens. • Post functions: These are additional functions to be performed as part of the transition process. • Transition screen: This is an optional screen to be displayed when a user is executing a transition. It is usually used to capture additional information as a part of the transition. • Triggers: If you have integrated Jira with other development tools such as Bitbucket or GitHub, triggers can automatically execute a transition when an event happens, such as the creation of a new branch or when someone makes a code commit. Important note A common trick is to create a transition that links back to itself. Since a transition can have its own screen and execute some business logic via post functions, you can use this kind of transition as a trigger in the user interface (UI) to show a screen or run a post function without having to create complex customizations. Each of the first three components defines the behavior of transitions, allowing you to perform pre- and post-validations, as well as post-execution processing on transition execution. We will discuss these components in depth in the following sections. Triggers As described earlier, Jira needs to be integrated with one of the following systems before you can start using triggers: • Atlassian Bitbucket • Atlassian FishEye/Crucible • GitHub Triggers will listen for changes from the integrated development tools, such as code commits, and when these happen, the trigger will automatically execute the workflow transition. Note that all permissions are ignored when this happens. Conditions Sometimes, you might want to have control over who can execute a transition or when a transition can be executed. For example, a transition to authorize an issue should be restricted to users in the managers group so that normal employees will not be able to authorize their own requests. This is where conditions come in. Conditions are criteria that must be fulfilled before the user is allowed to execute a transition. If the conditions on transitions are not met, the transition will not be available to the user when viewing the issue. The following table shows a list of conditions that are shipped with Jira; other conditions can be added via third-party add-ons: Condition Description Managing workflows 179 Code Committed Condition This allows a transition to execute only if the code has/has not (depending on configuration) been committed against this issue. Hide Transition from User This will hide the transition from all users, and it can only be triggered by post functions. This is useful in situations where a transition will be triggered as part of an automated process rather than manually by a user. No Open Reviews Condition This allows a transition to execute only if there are no related open Crucible reviews. Only Assignee Condition This only allows the issue’s current assignee to execute the transition. Only Reporter Condition This only allows the issue’s reporter to execute the transition. Permission Condition This only allows users with the given permission to execute the transition. 180 Workflow and Business Process Condition Description User Is In Group This only allows users in a given group to execute the transition. Table 7.1 – Workflow conditions Validators Validators are similar to conditions, but they validate certain criteria before allowing a transition to complete. While conditions will hide a workflow transition from the user if its criteria are not met, validators will allow the user to see the transition but not allow the transition to execute if its criteria are not met. The most common use case for validators is to validate the user input during a transition. For example, you can validate if the user has entered data for all fields presented on the workflow screen. The following table shows a list of validators that come shipped with Jira; other validators can be added via third-party add-ons: Validator Description Sub-Task Blocking Condition This blocks the parent issue transition depending on all its subtasks’ statuses. Unreviewed Code Condition This allows a transition to execute only if there are no unviewed changesets related to this issue. User Is In Group Custom Field This only allows users in a given group custom field to execute a transition. User Is In Project Role This only allows users in a given project role to execute a transition. Permission Validator This validates that the user has the selected permission. This is useful when checking whether the person who has executed a transition has the required permissions. User Permission Validator This validates that the user has the selected permission where the OSWorkflow variable holding the username is configurable. This is obsolete. Table 7.2 – Workflow validators Using the workflow designer 181 Post functions As the name suggests, post functions are functions that occur after (post) a transition has been executed. This allows you to perform additional processes once you have executed a transition. Jira makes heavy use of post functions internally to perform a lot of its functions. For example, when you transition an issue, Jira uses post functions to update its search indexes so that your search results will reflect the change in issue status. If a transition has failed to execute (for example, failing validation from validators), post functions attached to the transition will not be triggered. The following table shows a list of post functions that come shipped with Jira, and other post functions can be added via third-party add-ons: Post function Assign to Lead Developer Assign to Reporter Notify HipChat Update Issue Field Description This assigns the issue to the project/component lead developer. This assigns the issue to the reporter. This sends a notification to one or more HipChat rooms. This updates a system field such as Summary to a given value. Table 7.3 – Workflow post functions Assign to Current User This assigns the issue to the current user if the current user has the assignable user permission. Create Perforce Job Function This creates a Perforce job (if required) after completing the workflow transition. Trigger a Webhook If this post function is executed, Jira will post the issue content in JavaScript Object Notation (JSON) format to the Uniform Resource Locator (URL) specified. We have looked at all the main components in a workflow. In the next section, we will look at how to design a workflow using the workflow designer tool. Using the workflow designer Jira comes with a simple-to-use drag and drop tool called the workflow designer. This helps you create and configure workflows. If you are familiar with diagramming tools such as Microsoft Visio, you will feel right at home. There is also another older option, called text mode, available. However, since the designer is easier and has more features, we will focus on using the designer in this book. 182 Workflow and Business Process Important note As your workflow becomes more complicated, text mode can be a better option to manage statuses and transitions in the workflow. The workflow designer is shown in the following screenshot. You have the workflow layout in the main panel and a few controls on top, namely the Add status and Add transition buttons. Note that the Diagram option is selected. If you click on the Text option, Jira will change to the old authoring tool: Figure 7.4 – Workflow designer From the workflow designer, you can drag and rearrange statuses and transitions. Clicking on each will open up its property window, as shown in the following screenshot, where the Resolve Issue transition is selected: Authoring a workflow 183 Figure 7.5 – Editing a workflow From here, we can view and update its properties, such as conditions and validators. If you have a complex workflow and the property window covers part of your workflow, you can either zoom out to reduce the size of the workflow diagram or drag the diagram around the page. Authoring a workflow So, let’s take a look at how to create and set up a new workflow in Jira. To create a new workflow, all you need is a name and description, so let’s get started: 1. Browse to the View Workflows page. 2. Click on the Add Workflow button. 3. Enter a name and description for the new workflow in the Add Workflow dialog. 4. Click on the Add button to create the workflow. The newly created workflow will only contain the default Create and Open statuses, so you will need to configure it by adding new statuses and transitions to make it useful. Let’s start by adding new statuses to the workflow using the following steps: 1. Click on the Add status button. 2. Select an existing status from the drop-down list. If the status you need does not exist, you can create a new status by entering its name and pressing the Enter key on your keyboard. 184 Workflow and Business Process 3. Check the Allow all statuses to transition to this one option if you want users to be able to move the issue into this status regardless of its current status. This will create a global transition, which is a convenient option, so you do not have to manually create multiple transitions for the status. Important note If the global status is not representing a Done or Closed status, it is often a good idea to add a Clear Resolution post function to make sure the resolution field is always cleared when the issue is transitioned into the status. 4. Click on the Add button to add the status to your workflow, as illustrated in the following screenshot. You can repeat these steps to add as many statuses as you want to your workflow: Figure 7.6 – Adding a status Important note Try to reuse existing statuses, if possible, so that you do not end up with many similar statuses to manage. Now that the statuses are added to the workflow, they need to be linked with transitions so that issues can move from one status to the next. There are two ways to create a transition, as follows: • Click on the Add transition button • Select the originating status and then click and drag the arrow to the destination status Both options will bring up the Add Transition dialog, as shown in the following screenshot: Figure 7.7 – Add Transition dialog From the preceding screenshot, you can choose to either create a new transition with the New Transition tab or use an existing transition with the Reuse a transition tab. When creating a new transition, you will need to configure the following settings: • From status: This is the originating status. The transition will be available when the issue is in the selected status. • To status: This is the destination status. Once the transition is executed, the issue will be put into the selected status. • Name: This is the name of the transition. This is the text that will be displayed to users. Since transitions are actions performed by users, it is usually a good idea to name your transitions starting with a verb, such as Close Issue. • Description: This is an optional text description showing the purpose of this transition. This will not be displayed to users. • Screen: This is an optional intermediate screen to be displayed when users execute the transition. For example, you display a screen to capture additional data as part of the transition. If you do not select a screen, the transition will be executed immediately. The following screenshot shows a workflow screen: Authoring a workflow 185 186 Workflow and Business Process Figure 7.8 – Transition screen If you want to reuse an existing transition, simply click on the Reuse a transition tab, From status and To status, and Transition to reuse, as shown in the following screenshot: Figure 7.9 – Reuse a transition tab Important note Note that Jira will only list valid transitions based on the To status selection. Authoring a workflow 187 You might be wondering when you should create a new transition and when you should reuse an existing transition. The big difference between the two is that when you reuse a transition, all instances of the reused transition (also known as the common transition) will share the same set of configurations, such as conditions and validators. Also, any changes made to the transition will be applied to all instances. A good use case for this is when you need to have multiple transitions with the same name andsetup,suchasClose Issue;insteadofcreatingseparatetransitionseachtime,youcancreate one transition and reuse it whenever you need a transition to close an issue. Later on, if you need to add a new validator to the transition to validate additional user input, you will only need to make the change once, rather than multiple times for each Close Issue transition. Another good practice to keep in mind is to not have a dead-end state in your workflow—for example, by allowing closed issues to be reopened. This will prevent users from accidentally closing an issue and not being able to correct the mistake. One thing people often overlook is that you can change the status an issue is transitioned to when it is first created. By default, an issue is placed in the Open status as soon as it is created. While this makes sense for most cases, you can actually change that. For example, you might want all your issues to be in a Waiting status and transition to Open only after someone has reviewed them. You can also make changes to the default Create Issue transition. By doing so, you can influence the issue creation process. For example, you can add a validator to it for additional checking before an issue is allowed to be created, or add a post function to perform additional tasks as soon as an issue is created. Now that we have seen how to add new statuses and transitions to a workflow, let’s look at adding triggers, conditions, validators, and post functions to a transition. Adding a trigger to transitions You can only add triggers to transitions if Jira is integrated with at least one of the supported development tools. With triggers, you can automate some of your development-operations (DevOps) flow, such as automatically transitioning an issue into an In Review status when a pull request (PR) is created. To add triggers, perform the following steps: 1. Select a transition you want to add triggers to. 2. Click on the Triggers link. 3. Click on the Add trigger button. If you do not have any integrated development tools, this button will be disabled, as indicated in the following screenshot: 188 Workflow and Business Process Figure 7.10 – Add trigger button 4. Select a trigger you want to add and click on the Next button. 5. Confirm the trigger source is detected and click on the Add trigger button. Adding a condition to transitions New transitions do not have any conditions by default. This means that anyone who has access to the issue will be able to execute the transition. Jira allows you to add any number of conditions to the transition. Here’s how to do this: 1. Select a transition you want to add conditions to. 2. Click on the Conditions link. 3. Click on the Add condition link, as shown in the following screenshot. This will bring you to the Add Condition To Transition page, which lists all the available conditions you can add: Figure 7.11 – Add condition link 4. Select a condition you want to add. 5. Click on the Add button to add the condition. Authoring a workflow 189 6. Depending on the condition, you may be presented with the Add Parameters To Condition page where you can specify configuration options for the condition. For example, the User Is In Group condition will ask you to select a group to check against, shown as follows: Figure 7.12 – Configuring a condition Newly added conditions are appended to the end of the existing list of conditions, creating a condition group. By default, when there is more than one condition, a logical AND operator is used to group the conditions. This means that all conditions must pass for the entire condition group to pass. If one condition fails, the entire group fails, and the user will not be able to execute the transition. You can switch to using a logical OR operator, which means only one of the conditions in the group needs to pass for the entire group to pass. This is a very useful feature as it allows you to combine multiple conditions to form a more complex logical unit. For example, the User Is In Group condition lets you specify a single group, but with the AND operator, you can add multiple User Is In Group conditions to ensure that the user must exist in all the specific groups to be able to execute the transition. If you use the OR operator, then the user will only need to belong to one of the listed groups. The only restriction to this is that you cannot use both operators for the same condition group. Important note One transition can only have one condition group, and each conditional group can only have one logical operator. Adding a validator to transitions As with conditions, transitions by default do not have any validators associated. This means that transitions are completed as soon as they are executed. You can add validators to transitions to make sure that executions are only allowed to be complete when certain criteria are met. Use the following steps to add a validator to a transition: 1. Select a transition you want to add conditions to. 2. Click on the Validators link. 190 Workflow and Business Process 3. Click on the Add validator link, as shown in the following screenshot. This will bring you to the Add Validator To Transition page, which lists all the available validators you can add: Figure 7.13 – Add validator link 4. Select a validator you want to add. 5. Click on the Add button to add the validator. 6. Depending on the validator, you may be presented with the Add Parameters To Validator page where you can specify configuration options for the validator. The following screenshot shows an example from the Fields required validator: Figure 7.14 – Configuring validators Similar to conditions, when there are multiple validators added to a transition, they form a validator group. Unlike conditions, you can only use a logical AND condition for the group. This means that in order to complete a transition, every validator added to the transition must pass its validation criteria. Transitions cannot selectively pass validations using a logical OR condition. The following screenshot shows a validator (the Fields required validator from Suite Utilities for Jira (JSU); refer to the Extending a workflow with workflow add-ons section) being placed on the transition, which validates whether the user has entered a value for the Resolution Details field: Figure 7.15 – Issue Fields required validator Adding a post function to transitions Transitions, by default, are created with several post functions. These post functions provide key services to Jira internal operations, so they cannot be deleted from the transition. These post functions perform the following operations: • Set the issue status to the linked status of the destination workflow step • Add a comment to an issue if one is entered during a transition Authoring a workflow 191 192 Workflow and Business Process • Update the change history for an issue and store the issue in the database • Re-index an issue to keep indexes in sync with the database • Fire an event that can be processed by the listeners As you can see, these post functions provide some of the basic functions such as updating a search index and setting an issue’s status after transition execution, which is essential in Jira. Therefore, instead of letting users manually add them in and risk the possibility of leaving one or more out, Jira adds them for you automatically when you create a new transition, as described in the following steps: 1. Select a transition you want to add post functions to. 2. Click on the Post Functions link. 3. Click on the Add post function link, as illustrated in the following screenshot, and select a post function you want to add: Figure 7.16 – Add post function link 4. Click on the Add button to add the post function. 5. Depending on the post function, you may be presented with an Add Parameters To Function page where you can specify configuration options for the post function. The following screenshot shows an example from the Update Issue Field post function: Updating an existing workflow 193 Figure 7.17 – Configuring post function When a transition is executed, each post function is executed sequentially as it appears in the list, from top to bottom. If any post function in the list encounters an error during processing, you will receive an error, and the remaining post functions will not be executed. Since post functions are executed sequentially and some of them possess the ability to modify values and perform other tasks, their sequence of execution often becomes very important. For example, if you have a post function that changes the issue’s assignee to the current user and another post function that updates an issue field’s value with the issue’s assignee, obviously the update assignee post function needs to occur first, so you need to make sure that it is above the other post function. You can move the position of post functions up and down along the list by clicking on the Move Up and Move Down links. Note that not all post functions can be repositioned, such as the Re-index issue and Fire event issue post functions. They are locked in their positions to ensure data integrity is maintained in Jira. Updating an existing workflow Jira lets you make changes to both active and inactive workflows. However, with active workflows, there are several restrictions, as outlined here: • Existing workflow steps cannot be deleted • The associated status for an existing step cannot be edited • If an existing step has no outgoing transitions, it cannot have any new outgoing transitions added If you need to make these changes, you will have to either deactivate the workflow by removing the associations of the workflow with all projects or create a copy of the workflow. 194 Workflow and Business Process Important note You can always make a copy of the active workflow, make your changes, and then swap the original with the copied workflow in your workflow scheme. When editing an active workflow, you are actually making changes to a draft copy of the workflow created by Jira. None of the changes you make will be applied until you publish your draft. Publishing a draft is a very simple process. All you have to do is this: 1. Click on the Publish Draft button. You will be prompted if you would like to first create a backup of the original workflow. It is recommended that you create a backup in case you need to undo your changes. 2. Select either Yes or No to create a backup of the current workflow before applying the changes. This is a handy way to quickly create a backup if you have not made a copy already. If you do choose to create a backup, it is a good idea to name your workflow with a consistent convention (forexample,basedonaversionsuchasSales Workflow 1.0)tokeeptrackofthechanges. 3. Click on the Publish button to publish the draft workflow and apply changes, as shown in the following screenshot: Figure 7.18 – Publish workflow Important note Do not forget to publish your draft after you have made your changes. Now that we have covered how to create a workflow, we will look at how to map a workflow to an issue type next. Understanding workflow schemes While workflows define and model business processes, there still needs to be a way to tell Jira the situations in which to apply the workflows. As with other configurations in Jira, this is achieved through the use of schemes. As we have seen in the previous chapters, schemes act as self-contained, reusable configuration units that associate specific configuration options with projects and, optionally, issue types. A workflow scheme establishes the association between workflows and issue types. The scheme can then be applied to multiple projects. Once applied, the workflows within the scheme become active. To view and manage workflow schemes, perform the following steps: 1. Log in to Jira as a Jira administrator user. 2. Browse to the Jira administration console. 3. Select the Issues tab and then the Workflow schemes option. This will bring up the Workflow schemes page, as shown in the following screenshot: Figure 7.19 – Workflow schemes page The Workflow schemes page shows each scheme’s workflow association. For example, in the preceding screenshot, we can see that for ISM: Insight ITSM Workflow Scheme, the Incident issue type is assigned to ISM: Insight ITSM Incident Workflow, while the Change issue type is assigned to ISM: Insight ITSM Change Workflow. Understanding workflow schemes 195 196 Workflow and Business Process Creating a workflow scheme When a new project is created, a new workflow scheme will be created automatically for the project, so normally, you will not need to create new workflow schemes. However, there might be times— such as when experimenting with changes to the workflow—when you still want to keep existing configurations untouched as a backup. To create a new workflow scheme, perform the following steps: 1. Browse to the Workflow schemes page. 2. Click on the Add workflow scheme button. This will take you to the Add Workflow Scheme dialog. 3. Enter a name and description for the new workflow scheme. For example, you can choose to name your workflow after the project/issue type it will be applied to. 4. Click on the Add button to create the workflow scheme. You will be taken back to the Workflow schemes page once the new scheme has been created, and it will be listed in the table of available workflow schemes. When you first create a new workflow scheme, the scheme is empty. This means it contains no associations of workflows and issue types, except the default association called Jira Workflow (jira). What you need to do next is configure the associations by assigning workflows to issue types. Important note You can delete the default Jira Workflow (jira) association after you have added an association yourself. Configuring a workflow scheme Workflow schemes contain associations between issue types and workflows. After you have created a workflow scheme, you need to configure and maintain the associations as your requirements change. For example, when a new issue type is added to the projects using the workflow scheme, you may need to add an explicit association for the new issue type. To configure a workflow scheme, perform the following steps: 1. Browse to the Workflow schemes page. 2. Click on the Edit link for the workflow scheme you want to configure. This will take you to the workflow’s details page, as shown in the following screenshot: Figure 7.20 – Configuring a workflow scheme From this page, you will be able to see a list of existing associations, create new associations for issue types, and delete associations that are no longer relevant. Assigning an issue type to a workflow Issue types and workflows have a many-to-one relationship. This means each issue type can be associated with one and only one workflow. One workflow can be associated with multiple issue types. This rule is applied on a per-workflow scheme basis, so you can have a different association of the same issue type in a different workflow scheme. When you add a new association, Jira will list all the issue types and all available workflows. Once you have assigned a workflow to the issue type, it will not appear in the list again until you remove the original association. Among the list of issue types, there is an option called All Unassigned Issue Types. This option acts as a catch-all option for issue types that do not have an explicit association. This is a very handy feature if all issue types in your project are to have the same workflow; instead of mapping them out manually one by one, you can simply assign the workflow to all with this option. This option is also important as new issue types are added and assigned to a project; they will automatically be assigned to the catch-all workflow. If you do not have an All Unassigned Issue Types association, new or unassigned issue types will be assigned to use the default basic jira workflow. As with normal issue types, you can have only one catch-all association. Important note If all issue types will be using the same workflow, use the All Unassigned Issue Types option. Understanding workflow schemes 197 198 Workflow and Business Process There are two ways to assign a workflow to an issue type. If you want to add an issue type to one of the existing associations, perform the following steps: 1. Browse to the workflow scheme’s details page for the workflow scheme you want to configure by clicking on its Edit link. 2. Click on the Assign link for the association you want to add an issue type to. 3. Select issue types to add from the Assign Issue Type to Workflow dialog. 4. Click on the Finish button. If you want to create a new association from scratch, perform the following steps: 1. Browse to the workflow scheme’s details page for the workflow scheme you want to configure. 2. Select the Add Existing option from the Add Workflow menu. This will bring up the Add Existing Workflow dialog, as shown in the following screenshot: Figure 7.21 – Adding a workflow to the workflow scheme 3. Select a workflow to use and click on the Next button. 4. Select issue types to associate with the workflow and click on the Finish button, as illustrated in the following screenshot. If you select an issue type that is already assigned, it will be removed from the old assignment and added to the currently selected workflow: Applying a workflow scheme to projects 199 Figure 7.22 – Assigning a workflow to an issue type Editing or deleting an association Once you have associated an issue type with a workflow in a scheme, you cannot add a new association for the same issue type. There is also a No edit option to change the association. What you need to do is to delete the existing association and create a new one using the following steps: 1. Browse to the workflow scheme’s details page for the workflow scheme you want to configure. 2. Click on the Remove link for the association you want to remove. Once an association is deleted, you will be able to create a new one for the issue type. If you do not assign a new workflow to the issue type, the workflow with the All Unassigned Issue Types option will be applied. Applying a workflow scheme to projects Workflow schemes are inactive by default after they are created. This means there are no projects in Jira using the workflow scheme. To activate a workflow scheme, you need to select a scheme and apply it to the project. 200 Workflow and Business Process When assigning a workflow scheme to a project, you need to follow four basic steps, as outlined next: 1. Browse to the project administration page for the project you want to apply the workflow scheme to. 2. Select the Workflows option from the left panel. 3. Click on the Switch Scheme button. 4. Select a new workflow scheme to use and click on the Associate button. On the confirmation page, depending on the differences between the current and new workflow, you will be prompted to make migration decisions for existing issues. For example, if the current workflow has a status called Resolved and the new workflow does not (or it has something equivalent but with a different identifier (ID)), you need to specify the new status to place issues that are currently in the Resolved status. Once mapped, Jira will start migrating existing issues to the new status, as illustrated in the following screenshot: Figure 7.23 – Mapping workflow statuses The steps are set out here: 1. Select new workflow statuses for existing issues that are in statuses that do not exist in the new workflow. 2. Click on the Associate button to start the migration. Delegated workflow management 201 Once the migration starts, Jira will display a progress bar showing you the progress. Depending on the number of issues that need to be migrated, this process may take some time. It is recommended to allocate a time frame to perform this task as it can be quite resource-intensive for large instances. Delegated workflow management Just as we saw in Chapter 6, Screen Management, project administrators have also been empowered to make changes to workflows that are used only by their own projects, instead of having to rely entirely on the Jira administrator. There are, however, some restrictions to this, as outlined here: • Only existing statuses can be used in the workflow • If the status is already used by an issue in the project, the status cannot be deleted from the workflow • Transition properties, conditions, validators, and post functions cannot be updated • The workflow must not be shared with any other projects • Workflows can only be updated in diagram mode This allows you to make changes such as adjusting statuses and transition flow to workflows that are dedicated to a single project, which would normally be the case since new workflows are automatically created with each new project. To make changes to workflows for your project as a project administrator, perform the following steps: 1. Browse to the target project’s administration page. 2. Click on the Issue types option from the left panel. 3. Select a workflow for the issue type you want to edit and click on the Edit button. 4. Click on the Publish button once you are done with your changes. You can see an overview of this in the following screenshot: 202 Workflow and Business Process Figure 7.24 – Delegated workflow administration Now we have covered all the out-of-the-box workflow features in Jira, let’s take a look at some of the third-party apps you can use to extend what you can do with workflows. Extending a workflow with workflow add-ons There are a number of very useful add-ons that will provide additional components such as conditions, validators, and post functions. The following sections present some of the most popular workflow- related plugins. JSU You can find a number of very useful conditions, validators, and post functions with this add-on. For example, the Update Issue Field post function that ships with Jira allows you to update any issue fields such as priority and assignee when a workflow transition completes. The JSU add-on complements this by providing a very similar Update Any Issue Field post function that handles custom fields. There are many other useful components such as the Copy Value From Other Field post function, which will allow you to implement some amazing logic with your workflow. It is a must-have add-on for any Jira instance. You can find out more at https://marketplace.atlassian.com/ apps/5048/jsu-suite-utilities-for-jira. The HR project 203 Jira Workflow Toolbox (JWT) As the name suggests, this is a workflow toolbox with a rich set of workflow conditions, validators, and post functions intended to fill many gaps when developing complex workflows. For example, it provides a condition and validator that allows you to specify checking rules with regular expressions (regexes). You can find out more at https://marketplace.atlassian.com/apps/29496/ jira-workflow-toolbox. Jira Misc Workflow Extensions (JMWE) This is another plugin with an assortment of conditions, validators, and post functions. Normal post functions let you alter the current issue’s field values. This plugin provides post functions that will allow you to set a parent issue’s field values from subtasks, along with many other features. You can find out more at https://marketplace.atlassian.com/apps/292/jira-misc- workflow-extensions. Workflow Enhancer for Jira This contains a variety of validators and conditions around comparisons of the value of a field with another field, and lets you set up validation logic to compare dates, numeric, and Boolean values; you can find out more at https://marketplace.atlassian.com/apps/575829/ workflow-enhancer-for-jira. ScriptRunner for Jira This is a very useful and powerful add-on that allows you to create your own custom conditions, validators, and post functions by writing scripts. This does require you to have some programming knowledge and a good understanding of Jira’s application programming interface (API). You can find out more at https://marketplace.atlassian.com/apps/6820/scriptrunner- for-jira. The HR project We have seen the power of workflows and how we can enhance the usefulness of Jira by adapting to everyday business processes. With our HR project, we have already defined two issue types to represent the onboarding and dismissal of an employee; both of these use the same default workflow with two steps: To Do and Done. So, we will now customize the workflow to represent a real-world HR process. Our requirements for the business process would then include the following: • The New Employee and Termination issue types will use a customized workflow, while the Task issue type will continue to use the existing one 204 Workflow and Business Process • For the Termination issue type, we will add two additional steps: one to conduct an exit interview, and one to ensure that all necessary company assets are returned • Ensure that only authorized personnel can transition the issue through the various statuses of the workflow The easiest way to implement these requirements would be to create a new workflow and add the extra process steps as new statuses. We will first do this to get our workflow structure in place. Later on, we will also look at how we can use other features in Jira and incorporate them into our workflow to make it more robust. Setting up workflows The first step is to create a new workflow for our Termination issue type since we still want to keep the existing workflow for the Task issue type. The easiest way to get started is to clone the current workflow to save us some time. Follow the next steps to do that: 1. Browse to the View Workflows page. 2. Click on the Copy link for the HR: Task Management Workflow workflow. 3. Name the new workflow HR: Termination Workflow. 4. Click on the Copy button to create our workflow. The next step is to add in the extra status we need. Make sure that you are in the workflow designer by selecting the Diagram option, then proceed as follows: 1. Click on the Add status button. 2. Enter the name for our new status as In Exit Review, set the Category type to In Progress, and click on Add. You will need to hit the Enter key on your keyboard since we are creating a new status. 3. Click on the Create button to create the workflow status. 4. Repeat steps 2 and 3 to create a new status called Collecting Assets. Now that we have our statuses added to our workflow, we need to connect them in the workflow with transitions. For now, we will make the workflow go in a sequence in the order of To Do | In Exit Review | Collecting Assets | Done. Let’s start by creating a transition going from To Do | In Exit Review, as follows: 1. Click on the Add transition button. 2. Select To Do as the From status. 3. Select In Exit Review as the To status. 4. Name the new transition Conduct Exit Review. 5. Select Workflow Screen for Screen. 6. Click on the Add button to create the transition. 7. Repeat steps 1 to 6 to create two more transitions, linking In Exit Review to Collecting Assets, and Collecting Assets to Done. 8. With the new transitions in place, we will also want to remove the existing transitions between To Do and Done so that people cannot skip the process steps. Your workflow will look something like the one shown in the following screenshot. You can rearrange the elements in the workflow to make the diagram flow more naturally: Figure 7.25 – HR workflow The next customization we will do is to make sure that only authorized personnel can transition the issue along the workflow. For now, we will set it so only members of the jira-administrators group can transition an issue after it is created. Once we cover Chapter 9, Securing Jira, we can change this security setting. Proceed as follows: 1. Click on the Conduct Exit Review transition and click on Conditions from the Transition property section. 2. Click on the Add condition button to bring up the Add Condition To Transition page. 3. Select the User Is In Group option. 4. Select the jira-administrator group. The HR project 205 206 Workflow and Business Process 5. Click on Add to add the condition to the transition. 6. Repeat steps 1 to 5 on the remaining transitions. Using the Users Is In Group option will ensure that only users in the selected group— jira- administrator in this case—will see the transition with the condition applied to it. Applying the workflow With our workflow in place and set up, we need to let Jira know the issue types that will be using our new workflow. Since we already have a workflow scheme in place for our project, we just need to associate the appropriate issue type with the workflow. Here’s how to do this: 1. Browse to the Workflow schemes page. 2. Click on the Edit link for HR: Task Management Workflow Scheme. 3. Click on the Add Workflow menu and select the Add Existing option. 4. Select our new HR: Termination Workflow option and click on the Next button. 5. Select a Termination issue type. 6. Click on Finish to create an association. 7. Click on the Publish button to apply the change. This associates our new workflow with the Termination issue type specifically created for our HR project and leaves the default workflow for the others. Putting it together With our new workflow in place, we can now create a new Termination issue and start testing our implementation. Since we need to simulate a scenario where an unauthorized user cannot transition an issue after it is created, we need to create a new user. We will look at user management and security in Chapter 9, Securing Jira. For now, we will simply add a new user to our system, as follows: 1. Browse to the Jira administration console. 2. Select the Users management tab and click on the Users link. 3. Click on the Create user button to bring up the Create New User dialog. 4. Name the new user john.doe (John Doe). 5. Set a password and email address for this new user. 6. Uncheck the Send Notification Email option. 7. Check the Jira Software option for Application access. 8. Click on the Create button to create the user. Now, log in to Jira as a new business user, john.doe, and create a new Termination issue. After you create the issue, you will notice that you cannot execute any transitions. This is because you (john.doe) are not in the jira-administrators group. The administrator user we created in Chapter 1, Getting Started with Jira Data Center, is in the jira-administrators group, so let’s log in as the administrator. Once logged in as the administrator, you will see our new transition, Conduct Exit Review, as shown in the following screenshot: Figure 7.26 – HR workflow transition 1 You will also see that, if you create a new task in the HR project, the task issue will continue to use the default workflow. With the current workflow set up, everything happens in sequential order. However, sometimes, you might need things to happen in parallel. For example, in the collecting assets step, there might be multiple assets to be collected for various teams, such as a laptop for IT and a key card for security. It will be a lot more efficient if you can perform them at the same time and be able to track them individually. One way you can do this is by creating subtasks for each asset under the issue (remember—an issue can only be assigned to one person), and then assigning the subtasks to the relevant team such as IT and security so that they can chase up with the employee to retrieve the asset. You can then set a condition on the Done transition to make sure that all subtasks are completed before they can be executed. This can be expanded upon to have the asset collection and exit interview as subtasks so that both can happen at the same time, and you can create different subtask issue types to differentiate them, as covered in Chapter 4, Working with Issues. Your Termination issue may look something like this: The HR project 207 208 Workflow and Business Process Figure 7.27 – HR workflow transition 2 In this example, the Done transition will only be available when all subtasks are completed. This can be achieved by adding the Sub-Task Blocking Condition type to the Done issue transition. Summary In this chapter, we looked at how Jira can be customized to adapt to your organization. At the heart of this powerful feature is a robust workflow system that allows you to model Jira workflows based on existing business processes. We also looked at the various components within a workflow, how to perform validations, and how postprocessing provides a level of process automation. In the next chapter, we will look at how we can combine the power of a workflow and its event-driven systems to facilitate communication through Jira notifications and the email system. 8 Emails and Notifications So far, you have learned how to use and interact with Jira directly from its web interface through a browser. We will now take a look at how Jira uses emails as a notification mechanism to alert you of updates. One powerful feature of Jira is its ability to create new issues, add comments to issues, and update issue details through emails. This provides you with a whole new option for how you and your users can interact with Jira. In this chapter, we will cover the following topics: • Jira and email • Mail servers • Mail queues • Events • Notifications • Batching email notifications • Troubleshooting notifications • Incoming emails • The HR project Jira and email Emails have become one of the most ubiquitous communication tools in today’s world. Businesses and individuals rely on emails to send and receive information around the world almost instantly. Therefore, it should come as no surprise that Jira is fully equipped and integrated with email support. 210 Emails and Notifications Jira’s email support comes in several flavors: • First, Jira sends emails to users about changes that have been made to their issues, such as adding comments, so people working on the same issue can be kept on the same page • Second, Jira can poll mailboxes for emails and create issues and comments based on the content of the email • The last feature is the ability for users to create and subscribe to filters to set up feeds in Jira (we will discuss filters in Chapter 10, Searching, Reporting, and Analysis) These features open up a whole new dimension to how users can interact with Jira. In the following sections, we will look at what you need to do to enable Jira’s powerful email support, as well as explore the tools and options at your disposal so that you can configure Jira and email in a way that suits you. Mail servers For Jira to communicate with emails, you need to configure or register your mail servers in Jira. There are two types of mail servers you need to configure: • Outgoing: This is used by Jira to send emails out to users. Jira supports SMTP mail servers. • Incoming: This is used by Jira to retrieve emails from users. Jira supports POP and IMAP servers. The following diagram shows how Jira interacts with various mail servers: Figure 8.1 – Mail servers Mail servers 211 We will start with outgoing mail servers to see the different options we have to configure Jira to send emails to users, customize the email’s contents, enable SSL for additional security, and finally, send a test email. Working with outgoing mail To configure the outgoing SMTP server, you will need the Jira system administrator’s global permission (the user that was created during the initial setup is a system administrator). Perform the following steps to manage the outgoing mail server: 1. Log in to Jira as a Jira system administrator. 2. Browse to the Jira administration console. 3. Select the System tab and then the Outgoing mail option. This will bring up the Outgoing mail page: Figure 8.2 – The Outgoing mail page Note You can only have one outgoing mail server in Jira. There are two ways to add an outgoing mail server in Jira. Both options have some common configuration parameters that you will need to fill in. The following table shows these parameters: 212 Emails and Notifications Field Name Description Description This specifies a name for the mail server. This specifies a brief description of the mail server. From address This specifies an email address that outgoing emails will appear to have come from. Email prefix This specifies a prefix that will appear with all the emails sent from Jira. This allows your users to set up filter rules in their mail clients. The prefix will be added to the beginning of the email subject. Service Provider Here, you can select from one of the three predefined mail providers – that is, Google, Yahoo!, or the custom SMTP server. Host Name This specifies the hostname of your mail server (for example, smtp. example.com). SMTP Port This specifies the port number that your mail server will be running on. This is optional; if left blank, the default port number of 25 will be used. Username This is used to authenticate against the mail server if required. Note that mail servers may require authentication to relay emails to non-local users. Password This is used to authenticate the user against the mail server if required. Table 8.1 – Outgoing mail server configuration JNDI Location This is the JNDI lookup name if you already have a mail server configured for your application server. Refer to the following section for details. For the rest of the parameters, depending on the option you select to set up your mail server, you only need to fill in the appropriate details. Configuring an SMTP server The first option is to select from one of the built-in service providers and specify the mail server’s details. For example, if you have an SMTP mail server running, you can select the Custom option from the Service Provider field and specify the host and port number. This is the approach most people will use as it is straightforward. With this approach, the administrator fills in the mail server’s host information, such as the hostname and port number. To do so, follow these steps: 1. Browse to the Outgoing mail page. 2. Click on the Configure new SMTP mail server button. 3. Enter the general details of your mail server, including the name, description, from address, and email prefix. 4. Select the type of mail server from the Service Provider field. 5. Enter the mail server’s connection details. 6. Click on the Test Connection button to verify the configuration. 7. Click on the Add button to register to the mail server: Mail servers 213 Figure 8.3 – The Add SMTP Mail Server page 214 Emails and Notifications Note Jira comes with support for Google and Yahoo! mail services. You can select these options in the Service Provider field if you are using these services. Configuring an SMTP server with JNDI The second option is to use the Java Naming and Directory Interface (JNDI). This approach is slightly more complicated as it requires configuration on the application server itself, and it requires you to restart Jira. If you are using the standalone distribution, which uses Apache Tomcat, the JNDI location will be java:comp/env/mail/JiraMailServer. You will also need to specify the mail server details as a JNDI resource in the server.xml file in the JIRA_INSTALL/conf directory. A sample declaration is shown in the following code snippet. You will need to substitute some values with the real values for some of the parameters in the code of your mail server’s details: You will need to restart Jira after saving your changes to the server.xml file. Disabling outgoing mail If you are running a test or evaluation Jira instance, or testing changes that you have made to your configurations, you might not want to flood your users with test emails. The easiest way for you to disable all outgoing emails is by just clicking on the Disable outgoing mail button. This will stop Jira from sending all emails as a result of issue updates. Once you are ready to send emails again, you can click on the Enable outgoing mail button. Note Disabling outgoing mail will only prevent Jira from sending out notification emails based on notification schemes. Mail servers 215 Enabling SMTP over SSL To increase security, you can encrypt the communication between Jira and your mail server if your mail server supports SSL. Two steps are involved in enabling SSL over SMTP in Jira: 1. The first step is to import your mail server’s SSL certificate into Java’s trust store. You can do this with Java’s keytool utility. On a Windows machine, run the following command in the Command Prompt: 2. The second step is to configure your application server to use SSL for mail communication. The following declaration is for Apache Tomcat, which is used by Jira standalone. We can use the same configuration file and only need to add two additional parameters: keytool -import -alias mail.yourcompany.com -keystore $JAVA_HOME/jre/lib/security/cacerts -file yourcertificate Once you have imported your certificate and configured your mail server, you will have to restart Jira. Sending a test email It is always a good idea to send a test email after you configure your SMTP mail server to make sure that the server is running and that you have set it correctly in Jira. Here is how to go about it: 1. Browse to the Outgoing mail page. 2. Click on the Send a test email link for your SMTP mail server. 3. Click on the Send button to send the email. Jira will autofill the To address based on the user you have logged in as. 216 Emails and Notifications If everything is correct, you will see a confirmation message in the Mail log section and receive the email in your inbox. If there are errors, such as an error with the mail server connection, then the Mail log section will display these problems. This is very useful when troubleshooting any problems with Jira’s connectivity with the SMTP server: Figure 8.4 – Testing the outgoing mail server In the preceding screenshot, you can see that the test email delivery has failed, and the error is because Jira was unable to connect to the configured SMTP server. We have now looked at how you can add an outgoing SMTP mail server in Jira, and send out test emails. In the next section, we will look at Jira’s mail delivery mechanism. Mail queues Most emails in Jira are not sent immediately when an operation is performed. Instead, they are placed in a queue, which Jira will process periodically. This is very similar to the real-life scenario where mail is placed in mailboxes and picked up every day by postal workers. In this section, we will take a look at Jira’s mail queue, and how to use it to help identify and troubleshoot if outgoing emails are stuck. Viewing the mail queue Normally, you do not need to manage the mail queue. Jira automatically places emails into the queue and processes them periodically. However, as an administrator, there may be times when you wish to inspect the mail queue, especially to troubleshoot problems related to Jira notification emails. Sometimes, emails can get stuck, and inspecting the mail queue will help you identify these problems and fix them. Perform the following steps to view the content of the mail queue: 1. Browse to the Jira administration console. 2. Select the System tab and then the Mail queue option: Figure 8.5 – The Mail queue page This page provides you with a one-page view of the current emails in the queue that are waiting for delivery. There are two queues – Mail queue and Error queue: • The Mail queue tab contains all the emails that are pending delivery. If Jira can successfully deliver these emails, they will be removed from the queue. Any items listed in red indicate that Jira has unsuccessfully attempted to send those emails. Jira will retry 10 times, and if still unsuccessful, these items will be moved to the error queue. • The Error queue tab contains emails that cannot be delivered by Jira. You can choose to resend all the failed items in the error queue or delete them. Mail queues 217 218 Emails and Notifications Flushing the mail queue While Jira automatically flushes the mail queue, you can also manually flush the queue if you want to send out emails immediately. When you manually flush the queue, Jira will try to send all the emails that are currently in the queue. Perform the following steps to manually flush the mail queue: 1. Browse to the Mail queue page. 2. Click on the Flush mail queue button If Jira is successful in sending emails, you will see the queue shrink and the items disappear. If some emails fail to be delivered, those items will be highlighted in red. The mail queue is used when Jira automatically sends out emails, as we will see in the next section. When you manually send out emails in Jira, those emails are sent out immediately. Manually sending emails Sometimes, you, as the administrator, may need to send out emails containing important messages to your users. For example, if you are planning some maintenance work that will take Jira offline for an extended period, you may want to send an email to all Jira users to let them know of the outage. Jira has a built-in facility where you can manually send out emails to specific groups of users. There are two options when manually sending emails – you can send them in groups or by projects. When sending them in groups, all you need to do is select one or more groups in Jira, and all users that belong to the selected groups will receive the email. Users belonging to more than one group will not receive duplicated emails. When sending emails by projects, you need to select one or more projects and then the project roles. We will discuss project roles in more detail in the next chapter, but for now, you can think of them as groups of users within projects. For example, you can send emails to all users that are part of Demonstration Project rather than all users in Jira. To send emails to users in Jira, perform the following steps: 1. Browse to the Jira administration console 2. Select the System tab and then the Send email option 3. Choose whether you want to send to users by Project Roles or Groups 4. Enter the email’s Subject and Body content 5. Click on the Send button to send the email to all users in the selected project roles/groups Manually sending emails 219 The following screenshot shows an example of sending maintenance outage notification emails to everyone by selecting the jira-software-users group, which every Jira Software user is a member of by default: Figure 8.6 – The Send email page Note Since Jira does not provide a What You See Is What You Get (WYSIWYG) editor for composing emails, you may want to draft an email and send it to yourself before sending it out to everyone. Now that we have seen how to configure an outgoing mail server in Jira and send emails, let’s take a deeper look at how Jira automates email notifications when users perform actions on issues. 220 Emails and Notifications Events Jira is an event-driven system. This means that when an action occurs (for example, when an issue is created), Jira will fire off a corresponding event. This event is then picked up by components that are designed to listen to the event. These are called listeners. When a listener picks up an event, it will perform its duty, such as keeping issues up to date with changes or sending an email to users who are watching the issue. This mechanism allows Jira to process operations asynchronously. The advantage of this model is operations, such as sending emails, are separated from Jira’s core functions, such as issue creation. If there is a problem with the mail server, for example, you will not want this problem to prevent your users from creating issues. There are two types of events in Jira: • System events: These are internal events that are used by Jira, and they usually represent the main functionalities in Jira. They cannot be added, edited, or deleted. • Custom events: These are events that are created by users. They can be added and deleted, and they are fired through workflow post functions. As an administrator, you will be able to get a one-page view of all the events in Jira. You just need to do the following: 1. Browse to the Jira administration console. 2. Select the System tab and then the Events option. This will bring up the View Events page: Figure 8.7 – Issue events Events 221 Each event is associated with a template, which is often referred to as a mail template. These templates define the content structure of emails when notifications are sent. For system events, you cannot change their templates (you can change the template file’s content, however). For custom events, you can choose to use one of the existing templates or create your own mail template. In the following sections, we will look at how to create and register custom mail templates, create a new custom event to use the new template, and fire the new event when actions are performed on an issue. After that, we will look at how to tie events to notifications so that we can tell Jira who should receive notification emails for the event. Working with mail templates Mail templates are physical files that you create and edit via a text editor. Jira has a set of default templates for all the system events. Instead of modifying them directly, Jira lets you upload your modified version of the templates and override the default. For us to create a new mail template, we can also look at these existing templates and use them as a starting point. You can download the default templates by following these steps: 1. Browse to the Jira administration console 2. Select the System tab and then the Email templates option 3. Click on the Download .zip button This will download all the default templates in a .zip file. Once you unzip it, you will see two main directories – email and email-batch. The email directory is what we will focus on for now, as it contains all the mail templates for the event. Inside the email directory, you will see the following subdirectories: • css directory: Contains CSS files to apply styles to the email • html directory: Contains templates when Jira is sending out emails as HTML • includes directory: Contains common content that is shared between one or more templates • subject directory: Contains templates that are used to generate the email’s subject • text directory: Contains templates when Jira is sending out emails as plain text As we can see, for a given mail template used by the issue event, there are at least three components – subject, HTML, and text. So, if you want to add a new template for a custom event, you will need to create those three files and place them in those directories accordingly. And if you want to modify an existing mail template, make sure you make your changes to all the necessary files, usually in both the HTML and text directories. 222 Emails and Notifications While creating new mail templates, it is a good practice to name your template files after the issue event, for example, issueescalated.vm. This will help future users understand the purpose of those templates. Mail templates use Apache’s Velocity template language (http://velocity.apache. org). For this reason, creating new mail templates will require some understanding of HTML and template programming. If your templates only contain static text, you can simply use standard HTML tags for your template. However, if you need to have dynamic data rendered as part of your templates, such as the issue key or summary, you will need to use the Velocity syntax. A full explanation of Velocity is beyond the scope of this book. The following paragraph provides a quick introduction to creating simple mail templates for Jira. You can find more information on Velocity and its usage in Jira mail templates at https://confluence.atlassian.com/adminjiraserver0822/customizing- email-content-1142237912.html. In a Velocity template, all the text will be treated as normal. Anything that starts with a dollar sign ($), such as $issue, is a Velocity statement. The $ sign tells Velocity to reference the item after the sign, and, when combined with a period (.), you can retrieve the value specified. For example, the following code in a template will get the issue key and summary from the current issue, separated by a - character: $issue.key - $issue.summary This will produce content similar to DEMO-1 - This is a demo issue. Jira provides a range of Velocity references that you can use to create mail templates. These references allow you to access data such as the issue being updated and the user triggering the event. You can find a comprehensive list at https://developer.atlassian.com/server/jira/platform/ jira-templates-and-jsps/#email-templates. Now that you have a basic understanding of how Velocity works, you need to create a template for the mail subject. The following code shows a typical subject template: $eventTypeName: ($issue.key) $issue.summary When the template is processed, Jira will substitute the actual values for the event type (for example, issue created), issue key, and issue summary. Therefore, the preceding example would produce content similartoIssue Escalated: HD-11: Database server is running very slow. Then, you need to create a template for the actual email content. Here, you need to create a text and HTML version. The following code shows a simple example of a text-based template, which displays the key for the escalated issue: Before Jira sends out the email, the preceding text will be processed, where all Velocity references, such as $issue.key, will be converted into proper values; for example, DEMO-1. Once you have either updated or created your mail templates, you will need to upload them to Jira. Here’s how to do that: 1. Zip up your mail templates 2. Browse to the Jira administration console 3. Select the System tab and then the Email templates option 4. Click on the Upload .zip button and upload the .zip file you created 5. Click on the Apply button once Jira has verified your template’s content Once the updated templates have been uploaded, it can take up to 5 minutes for the changes to take effect. If you are simply modifying existing templates, then that is all you need to do, but if you are adding new templates, you will need to register them with Jira. To register your new templates, locate and open the email-templates-id-mappings.xml file in the /atlassian-jira/WEB-INF/classes directory in a text editor. Add a new entry to the end of the file before closing the tag, as follows: Events 223 Hello, The ticket $issue.key has been escalated and is currently being worked on. We will contact you if we require more information. Regards Support team. Example Custom Event issueevent 224 Emails and Notifications Here, we have registered a new custom mail template entry. The details of this are shown in the following table: Parameter Description name This is a human-readable name for Jira to display. Table 8.2 – Email template ID mapping parameters After creating your templates and registering them in the mapping file, you will have to restart Jira for the changes to be picked up. The new templates will be available when we create new events, which we will discuss in the following section. Adding a custom event Jira comes with a comprehensive list of system events that are focused on issue-related operations. However, there will be times when you will need to create custom-designed events that represent specialized business operations, or when you simply need to use a custom email template. Perform the following steps to add a new custom event: 1. Browse to the View Events page. 2. Enter a name and description for the new event in the Add New Event section. 3. Select the mail template for the new event. If you have registered a new mail template, you can select it for the event. 4. Click on the Add button to create a new event: id This is the unique ID for the template. You need to make sure that no other template mapping has the same ID. template These are the mail template filenames for subject, text, and HTML. All three template files must be named as specified here. type This is the template type. For events that are generated from an issue, the value will be issueevent. Events 225 Figure 8.8 – The Add New Event page With that, we have added a new event to Jira and assigned a custom email template to it. We will look at how we can fire our new event in the next section. Firing a custom event Unlike system events, with custom events, you need to tell Jira when it can fire a custom event. Custom events are mostly fired by workflow transitions. Recall from Chapter 7, Workflow and Business Process, that you can add post functions to workflow transitions. Almost all of Jira’s transitions will have post functions that fire appropriate events. It is important to understand that just because an event is fired does not mean that there needs to be something to listen to it. If you skipped Chapter 7, Workflow and Business Process, or still do not have a good understanding of workflows, now would be a good time to go back and revisit that chapter. Perform the following steps to fire a custom event from a workflow post function: 1. Browse to the View Workflows page. 2. Click on the Edit link of the workflow that will be used to fire the event. 3. Click on the transition that will fire the event when executed. 4. Click on the Post Functions tab. 226 Emails and Notifications 5. Click on the Edit button for the post function that reads Fire a event that can be processed by the listeners: Figure 8.9 – Firing an issue event 6. Select the custom event from the drop-down list. 7. Click on the Update button to apply any changes to the post function. 8. Publish the workflow. Now, whenever the workflow transition is executed, the post function will run and fire the selected event. With events covered, in the next section, we will look at how we can configure Jira to listen for these events and send out notifications accordingly. Notifications Notifications associate events (both system and custom) to email recipients. When an event is fired and picked up, emails will be sent out. Notification types define the recipients of emails. For example, you can set them to only send emails to a specific user or all members from a given user group. You can add multiple notifications to a given event. Notifications 227 Jira ships with a comprehensive list of notification types (that is, the recipients) that will cover many of your needs. The following table lists all the notification types that are available and how they work: Notification Type Current Assignee Reporter Current User Project Lead Component Lead Single User Group Project Role All Watchers Description This is the current assignee of the issue. This is the reporter of the issue (usually the person who created the issue). This is the user who fired the event. This is the lead of the project that the issue belongs to. This is the lead of the component that the issue belongs to. This states any user that exists in Jira. This states that all users belong to the specified group. This states that all users belong to the specified project role. This states that all users are watching this issue. Single Email Address This states any email address. User Custom Field Value This states the users specified in the user-type custom field. For example, if you have a User Picker Custom Field called Recipient, the user that’s selected in the custom field will receive notifications if they have access to the issue. Group Custom Field Value This states all users that belong to the group in the group-type custom field. For example, if you have a Group Picker Custom Field called Approvers, all users from the group (with access to the issue) that are selected in the custom field will receive notifications. Figure 8.3 – Notification types As you can see, the list includes a wide range of options, from issue reporters to values contained in custom fields. Anything that can be represented as a user such as Project Lead, or contains user values such as User Custom Field Value, can be chosen to receive notifications. If a user belongs to more than one notification for a single event, Jira will make sure that only one email will be sent so that the user does not receive duplicates. For a user to receive notifications, the user must have permission to view the issue. The only exception to this is when using the single email address option (we will discuss security in Chapter 9, Securing Jira). If the user does not have permission to view the issue, Jira will not send a notification email. 228 Emails and Notifications So, now that can create custom events, create and modify mail templates, and control when events are fired, we will look at how to add notifications to events so that users can start receiving emails via a notification scheme. Notification schemes A notification scheme is a reusable entity that links events with notifications. In other words, it contains the associations between events and their respective email recipients. In this section, we will cover notification schemes and how you can use them to send out notification emails when an event occurs in Jira. To manage notification schemes in Jira, follow these steps: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Notification Schemes option. This will bring up the Notification Schemes page: Figure 8.10 – The Notification Schemes page From this screen, you can see a list of all the notification schemes and the projects that are currently using them. Jira comes with a generic default notification scheme. The default scheme is set up with notifications set for all the system events. This allows you to quickly enable notifications in Jira. The default setup has the following notifications: • Current Assignee • Reporter • All Watchers Notifications 229 You can modify the default notification scheme to add your own notification rules, but as you grow your Jira adoption, it is a better idea to create a new scheme from scratch or copy the default scheme and make your modifications there. Adding a notification scheme Unlike other schemes such as the workflow scheme, where Jira will create one whenever a new project is created, all new projects will be set to use the Default Notification Scheme option. So, if you want to create notifications that are specific to your project, you will have to create a new notification scheme. Perform the following steps to create a new notification scheme: 1. Browse to the Notification Schemes page 2. Click on the Add notification scheme link at the bottom 3. Enter a name and description for the new notification scheme 4. Click on the Add button to create the notification scheme When you create a new notification scheme, you create a blank scheme that can be configured later so that you can add your own notification rules to it. You must configure its notification rules before applying the scheme to projects after you create a new notification scheme; otherwise, no notifications will be sent out. We will look at how to configure notification rules later in this chapter. Managing a notification scheme Notification schemes contain notifications that are set on events in Jira. A notification determines who will receive an email when the corresponding event is fired. Perform the following steps to add a new notification: 1. Click on the Notifications link for the notification scheme you wish to configure. 2. Click on the Add Notification link or the Add link for the event you wish to add a notification for. Both actions will bring you to the Add Notification page. If you click on the Add link, the Events selection list will preselect the event for you. 3. Select the events you want to add the notification type to. 4. Select the notification type from the available options. 5. Click on the Add button. For example, the following screenshot shows setting up a notification for Jira to send out emails to the project lead when issues are created and updated: 230 Emails and Notifications Figure 8.11 – The Add Notification page Once added, the notification will be listed against the events that have been selected. You can continue adding notifications for the events by repeating the same steps. Note You can select multiple events to add a notification type to. When notifications are no longer required for certain events, you can also have them removed. To remove notifications, you will need to do so one by one, per event: 1. Browse to the Edit Notifications page for the notification scheme you wish to configure 2. Click on the Delete link for the notification you wish to remove 3. Click on the Delete button to confirm the removal After you remove a notification, users affected by that notification will stop receiving emails from Jira. However, you need to pay attention to your configurations, as there may be other notifications for the same event that will continue to send emails to the same user. For example, if you created two notifications for the issue-created event – one set to a single user, John (who belongs to the jira- administrator group), and another set to the jira-administrator group – and your goal is to prevent emails from being sent to the user, John, you will need to remove both notifications from the event instead of simply using the Single User option. Assigning a notification scheme When new projects are created, they are automatically assigned to use the default notification scheme. If you want your project to use a different scheme, you will need to go to the Notifications section of your project’s administration console: 1. Browse to the project administration page for the project you want to apply the notification scheme to. 2. Select the Notifications option from the left panel: Figure 8.12 – Associating a notification scheme 3. Select Use a different scheme from the Actions menu. 4. Select the notification scheme to use. 5. Click on the Associate button. Notifications 231 232 Emails and Notifications As soon as a notification scheme is applied to the project, it will take effect immediately, and you will see emails being sent out for the events that have been configured in the scheme. Like any other schemes in Jira, notification schemes can be assigned to multiple projects so that they can share the same notification behavior. With so many notifications, users can often get overwhelmed by the number of emails Jira will send out. In the next section, we will take a look at how we can help reduce the number of notification emails users receive by batching them together. Batching email notifications One common complaint users have about Jira’s email notifications is their frequency. Every change that’s made to the same issue will trigger an email to be sent, and for a busy team that’s constantly updating issues, such as adding comments, this can very quickly cause a storm of emails being sent that flood users’ inboxes. To help alleviate this challenge, Jira 8 has introduced the feature of batch email notifications. The way this works is as follows – all changes that are made to a given issue in the past 10 minutes will be batched into a single summary email, so the user will only receive one email for these changes instead of one per change. This helps significantly reduce the amount of clutter that’s generated as a result of frequent updates that are made to issues. To enable email batching, follow these steps: 1. Browse to the Jira administration console 2. Select the System tab and then the Batching email notifications option 3. Check the Batching email notifications option to enable it As this is a new feature that was added in Jira 8, improvements are being planned for future releases, such as adding support for including custom field values in the summary email and having a customizable batching option. Now that we have covered email notifications, we will see the tools provided by Jira to help us troubleshoot issues related to notifications. Troubleshooting notifications Often, when people do not receive notifications from Jira, it can be difficult and frustrating to find the cause. The two most common causes of notification-related problems are either outgoing mail server connectivity or misconfiguration of the notification scheme. Troubleshooting outgoing mail server problems is quite simple. All you have to do is try to send out a test email, as described in the Sending a test email section. If you receive your test email, then there will be no problems with your outgoing mail server configuration and you can focus on your notification configurations. Troubleshooting notifications is not as straightforward since there are several things that you will need to consider. To help with this challenge, Jira has a handy feature called Notification helper. The Notification helper feature can save the Jira administrator time by helping them pinpoint why a given user does or does not receive notifications. All the administrator has to do is tell the helper who the user is, which issue (or an example issue from a project) the user will or will not be receiving notifications for, and the event that is triggering the notification. Follow these steps: 1. Browse to the Jira administration console 2. Select the System tab and then the Notification helper option 3. Specify the user that will or will not receive notifications in the User field 4. Specify the issue to test with 5. Select the type of notification event 6. Click on the Submit button The Notification helper feature will then process the input and report whether the user is expected to receive notifications, and why, based on the notification scheme settings: Troubleshooting notifications 233 Figure 8.13 – The Notification helper page 234 Emails and Notifications As you can see from the preceding screenshot, the user, Alana Grant, is currently not receiving notifications for the DEMO-4 issue when it is being updated because the notification is set up to have only the Current Assignee receive emails, and Alana Grant is not the assignee. Now that we have looked at how Jira can send out email notifications and how you can troubleshoot them when you do not receive emails, in the next section, we will look at how to send emails to Jira to create issues and comments. Incoming emails We have seen how to configure Jira to send emails to notify users about updates on their issues. However, this is only half of the story when it comes to Jira’s email support. You can also set up Jira so that it periodically polls mailboxes for emails and creates issues based on the emails’ subject and content. This is a very powerful feature with the following benefits: • It hides the complexity of Jira from business users so that they can log issues more efficiently and leave the complexity to the IT team. • It allows users to create issues, even if Jira can only be accessed within the internal network. Users can send emails to a dedicated mailbox for Jira to poll. In this section, we will look at how to add incoming mail servers for Jira to poll emails, and then create mail handlers to create issues and/or comments from the emails. Adding an incoming mail server For Jira to retrieve emails and create issues from them, you need to add the POP/IMAP mail server configurations to Jira. POP and IMAP are mail protocols that are used to retrieve emails from the server. Email clients, such as Microsoft Outlook, use one of these protocols to retrieve your emails. Unlike outgoing mail servers, Jira allows you to add multiple incoming mail servers. This is because while you only need one mail server to send emails, you may have multiple mail servers or multiple mail accounts (on the same server) that people will use to send emails to. For example, you might have one that’s dedicated to providing support and another one for sales. It is usually a good idea to create separate mail accounts to make it easier when you’re trying to work out which email can go into which project. For this reason, adding POP/IMAP mail servers can be thought of as adding multiple mail accounts in Jira. Perform the following steps to add an incoming mail server: 1. Browse to the Jira administration console 2. Select the System tab and then the Incoming mail option 3. Click on the Add POP/IMAP Mail Server button Incoming emails 235 4. Enter a name and description for the mail server 5. Select the type of mail service provider – for example, if you are using your own hosted mail service or one of the recognized cloud providers such as Google 6. Specify the hostname of the POP/IMAP server if you are using your own (custom provider) 7. Enter the username/password credentials for the mail account 8. Click on the Save button to create the POP/IMAP mail server: Figure 8.14 – The Add mail server page Note You can have multiple incoming servers. Mail handlers Mail handlers are what Jira uses to process retrieved emails. Each mail handler can process emails from one incoming mail server and periodically scan for new emails. Jira ships with several mail handlers, each with its own features. In the following sections, we will discuss each of the handlers in detail. Creating a new issue or adding a comment to an existing issue Creating a new issue or adding a comment to an existing issue mail handler (also known as the create and comment handler in previous versions of Jira) is the most used mail handler. It will create new issues from the received emails and also add comments to existing issues if the incoming email’s subject contains a matching issue key. If the subject does not contain a matching issue key, a new issue is created. The following table lists the parameters that are required when creating the mail handler: 236 Emails and Notifications Parameter Issue Type Description This is the issue type for newly created issues. Project This is the project in which issues will be created. This is not used for commenting where the email subject will contain the issue key. Strip Quotes If this is present in the parameters, quoted text from the email will not be added as part of the comment. Catch Email Address This specifies whether Jira is to only handle emails that are sent to the specified address. Bulk This specifies how to handle autogenerated emails such as those that are generated by Jira. It is possible to create a loop if Jira sends emails to the same mailbox where it also picks up emails. To prevent this, you can specify one of the following: Ignore: This is used to ignore these emails Forward: This is used to forward these emails to another address Delete: This is used to delete these emails altogether Generally, you can set it to forward. Forward Email If this is specified, then the mail handler is unable to process an email message it receives. An email message indicating this problem will be forwarded to the email address specified in this field. Create Users If the email is sent from an unknown address, Jira will create a new user based on the email’s from address and randomly generate a password. An email will be sent to the from address informing the new Jira account user. Default Reporter This specifies the username of a default reporter, which will be used if the email address in the From field of any of the received messages does not match the address associated with that of an existing Jira user. Notify Users Uncheck this option if you do not want Jira to notify new users that are created, as per the Create Users parameter. CC Assignee Jira will assign the issue to the user that’s specified in the To field first. If no user can be matched from the To field, Jira will then try the users in the CC and then the BCC list. CC Watchers Jira will add users in the CC list (if they exist) as watchers of the issue. Table 8.4 – Mail handler configuration Incoming emails 237 Adding a comment with the entire email body This mail handler extracts text from an email’s content and adds it to the issue with a matching issue key in the subject. The author of the comment is taken from the From field. It has a set of parameters that are similar to the create and comment handler. Adding a comment from the non-quoted email body Adding a comment from the non-quoted email body is very similar to the full comment handler, but it only extracts non-quoted text and adds them as comments. Text that starts with > or | is considered to be quoted. It has a set of parameters that are similar to the create and comment handler. Creating a new issue from each email message Creating a new issue from each email message is quite similar to the create and comment handler, except this will always create a new issue for every received email. It has a set of parameters that are similar to the create and comment handler. Adding a comment before a specified marker or separator in the email body Adding a comment before a specified marker or separator in the email body is a more powerful version of the comment handlers. It uses regular expressions to extract text from email contents and adds them to the issue: Parameter Description Split Regex This regex expression is used to extract contents. There are two rules for the regex expression: Rule 1: It must start and end with a delimiter character, usually with / Rule 2: It cannot contain commas; for example, /-{}{}{}{}{}\s*Original Message\s*{}-/ or /_____________*/ Table 8.5 – Regex mail handler configuration 238 Emails and Notifications Adding a mail handler You can set up as many mail handlers as you want. It is recommended that you create dedicated mailboxes for each project where you wish to allow Jira to create issues from emails. For each account, you will need to create a mail handler. The mailbox you set up needs to be accessible through POP or IMAP. Perform the following steps to add a mail handler: 1. Browse to the Incoming Mail page. 2. Click on the Add incoming mail handler button. 3. Provide a name to the new mail handler. 4. Select an incoming mail server or Local Files. 5. Specify how long Jira will wait to poll the mailbox for new emails (in minutes). You will want to keep this long enough to allow enough time for Jira to process all the emails, but not too long as you may end up having to wait for a long time to see your emails converted into issues in Jira. 6. Select the type of handler you want to add. 7. Click on the Next button: Figure 8.15 – Adding a mail handler – step 1 Depending on the handler type you select, the next screen will vary. On the next screen, you will need to provide the required parameters for the mail handler, as described in the preceding section. The following screenshot shows an example configuration dialog box, where new issues will be created in the IT support project as Task types: Incoming emails 239 Figure 8.16 – Adding a mail handler – step 2 You can always use the Test button to test out your configuration. Jira provides helpful hints if there are problems. Advanced mail handler The default mail handlers that come with Jira are often enough for simple email processing needs. If you need to have more control or need special processing logic for your incoming emails, you can create custom mail handlers. However, creating new mail handlers requires you to have programming knowledge; a better option is to use an add-on called Enterprise Email Handler for Jira (JEMH). With JEMH, you can set up advanced email routing, additional email-triggered operations such as updating an issue based on your email content, an audit of received/processed emails, and more. You can find out more about JEMH at https://marketplace.atlassian.com/apps/4832/ enterprise-email-handler-for-jira-jemh. 240 Emails and Notifications The HR project Users will often want to get progress updates on their issues after they have logged them. So, instead of business users having to ask for updates, we will proactively update them through our newly acquired knowledge – that is, Jira notifications. In Chapter 5, Field Management, we added a custom field called Direct Manager, which allows users to add the manager of the new employee or leaving employee so that they can be kept in the loop. The other customization we made in Chapter 7, Workflow and Business Process, was adding new transitions to the workflow. We need to make sure that those transitions fire the appropriate events and also send out notifications. In summary, we need to do the following: • Send out notifications for the events that are fired by our custom workflow transitions • Send out notifications to users that are specified in our Direct Manager custom field While you can achieve both using other Jira features, such as adding users as watchers to the issue and reusing existing Jira system events, this exercise will explore the options that are available to you. In later chapters, you will see that there are other criteria to consider while deciding on the best approach. Setting up mail servers The first step of enabling email communication, as you may have guessed, is to register mail servers in Jira. If you are using the standalone distribution of Jira, it is recommended that you add your mail server by entering the host information. Follow these steps: 1. Log in to Jira as a Jira administrator. 2. Browse to the Jira administration console. 3. Select the System tab and then the Outgoing mail option. 4. Click on the Configure new SMTP mail server button. 5. Enter your mail server information. If you do not have a mail server handy, you can sign up for a free Gmail account and use that for testing purposes. After adding your mail server, you can try sending yourself a quick test email to check whether Jira can access your server successfully. Updating workflow post functions In Chapter 7, Workflow and Business Process, we created a few new workflow transitions. Now, we need to update these new transitions to make sure they fire the appropriate events: 1. Browse to the View Workflows page. 2. Click on the Edit link for HR: Termination Workflow. The HR project 241 3. Click on any transitions other than Done. 4. Update the post function to fire the Issue Updated event rather than the Generic Event. 5. Repeat this for all other transitions except the Done transition. 6. Publish the draft workflow. You can save a backup copy in case you want to revert. We are using the Issue Updated event because it reflects the fact that the issue is being updated; also, the event is tied to more appropriate email templates. We can, of course, also create a new custom event and email templates and make the post function fire the custom event instead. Setting up a notification scheme Now, you need to have a notification scheme so that you can start adding notifications to your events. We will base our notification scheme on the default scheme to help us get things set up quickly: 1. Select the Issues tab and then the Notification schemes option 2. Click on the Copy link for the Default Notification Scheme option 3. Click on the Edit link of the copied notification scheme 4. Rename it HR Notification Scheme and click on Update This will create a new notification scheme with the basic notifications pre-populated. All you need to do now is modify the events and add your own notification needs. Setting up notifications There are two rules you need to follow to add notifications. First, you need to add notifications for your custom events so that emails will be sent out when they are fired. Second, you will want users that are specified in the CC list custom field to also receive emails along with the assignee and reporter of the issue: 1. Click on the Notifications link for HR Notification Scheme 2. Click on the Add notification link 3. Select the Issue Updated event type 4. Select User Custom Field Value for the notification type and select Direct Manager from the drop-down list 5. Click on the Add button Nice and easy. With just a few clicks, you have added the Direct Manager custom field to the notification scheme. So, now, regardless of who is put into the field, the user will receive notifications for issue updates. 242 Emails and Notifications Putting it together The last step, as always, is to associate your scheme with projects for activation: 1. Browse to the HR project’s administration page 2. Select the Notifications option from the left panel 3. Use a different scheme in the Actions menu 4. Select the new HR Notification Scheme we just created 5. Click on the Associate button With just a few clicks, you have enabled Jira to automatically send out emails to update users with their issue’s progress. Not only this, but you have tied in the custom fields you created from earlier chapters to manage who, along with the issue assignee and reporter, will also get these notifications. So, let’s put this to the test: 1. Create a new Termination issue in the HR project. 2. Select a user for the Direct Manager custom field. It is a good idea not to select yourself since the reporter will get notifications by default. Also, make sure that the user that’s selected has a valid email address. 3. Transition the issue so that it moves along the workflow. 4. You will receive emails from Jira within minutes. If you do not receive emails from Jira, check your mail queue and check whether the mail is being generated. Then, follow the steps provided in the Troubleshooting notifications section of this chapter. Summary In this chapter, we looked at how Jira can stay in touch with its users through emails. Indeed, with today’s new gadgets, such as smartphones and tablets, being able to keep users updated with emails is a powerful feature, and Jira has a very flexible structure in place to define the rules on who will receive notifications. We also very briefly mentioned some of the security rules about who can receive notifications. Jira performs security checks before sending out notifications for two very good reasons – first, there is no point in sending an email to a user who cannot view the issue; second, you will not want unauthorized users viewing the issue and receiving updates that they won’t know anything about. In the next chapter, we will look into the security aspects of Jira and how you can secure your data to prevent unauthorized access. 9 Securing Jira In the previous chapters, you learned how to store data in Jira by creating issues. As you can see, as an information system, Jira is all about data. It should come as no surprise to you that security plays a big role in Jira, to ensure that only the right people will get access to your data. This is achieved by providing a flexible and robust way for you to manage access control. It is able to integrate with your existing security practices, such as a password policy, and allows both centrally controlled permissions and delegating and empowering your project owners and users to manage permissions for their own projects. By the end of this chapter, you will have learned about the following: • Managing users, groups, and project roles • User directories and how to connect Jira to the Lightweight Directory Access Protocol (LDAP) • General access control in Jira • Managing project- and issue-level permission settings • How to troubleshoot permission problems • Configuring Jira with Security Assertion Markup Language (SAML) single sign-on (SSO) and just-in-time (JIT) user provision Specifically, we will look at the following topics: • Managing users • Managing groups and roles • User directories • Understanding Jira permissions • Issue security • Troubleshooting permissions 244 Securing Jira • Workflow security • Password policy • Enabling SSO with SAML • Auditing system changes • The human resources (HR) project Before we delve into the deep end of how Jira handles security, let’s first take a look at how Jira maintains user and group memberships. Managing users Each user needs to have an account for them to access Jira unless it is configured to allow anonymous access (refer to the Permission schemes section in this chapter for details). Each user is identified by their unique username. The user browser is where you will be able to see a list of all the users in Jira, including their usernames, email addresses, last login attempt, and which user directory they belong to. The user browser also provides you with search capabilities. You will be able to search for users that fit the criteria, such as by username, full name, email address, and group association. Perform the following steps to access the user browser: 1. Browse to the Jira administration console. 2. Select the User management tab and then the Users option, to take you to a screen like this: Figure 9.1 – User browser Managing users 245 By default, the results will be paginated to show 20 users per page, but you can change this setting to show up to 100 users per page. When dealing with large deployments having hundreds of users, these options will become very useful to quickly find the users you need to manage. Other than providing the ability for you to effectively search for users, the user browser also lets you add new users to Jira and manage a user’s group/role associations. Adding a user Jira lets you add new users in several ways, such as the following: • Direct creation by the Jira administrator • Invitation from the Jira administrator to create an account • Synchronization of user accounts from an external user repository, such as LDAP • By signing up for an account if the public signup option is enabled The first three options have centralized management, whereby only Jira administrators can create and/or manage user accounts. These options are most applicable to private Jira instances designed to be used by an organization’s internal users. The last option allows users to sign up for accounts by themselves. This is most useful when you run a public Jira instance, where manually creating user accounts is not scalable enough to handle the volume. We will be looking at how to enable the public signup option and integrate with LDAP in the User directories section later. For now, we will examine how administrators can create user accounts manually. Here’s how to do this: 1. Browse to the User Browser page. 2. Click on the Create user button. 3. Enter a unique username for the new user. Jira will let you know if the username is already taken. 4. Enter the password, full name, and email address of the user. If you do not enter a password, a random password will be generated. In this case, you should select the Send notification email option so that the new user can reset their password. 5. Select which applications in Jira the new user will have access to. For example, if you are running Jira software, you should check the Jira Software option. Doing so will consume one license seat count. 6. Click on the Create user button to create a new user. 246 Securing Jira Alternatively, administrators can also choose to invite users so that they can create their accounts themselves. This is different than the public signup option since only recipients of invitations will be able to create accounts. For this feature to work, you will need to have an outgoing mail server configured, as invitations will be sent as emails. Perform the following steps to invite users to sign up: 1. Browse to the User Browser page. 2. Click on the Invite users button. 3. Specify the email addresses of the people you wish to invite. You can invite multiple people at once. 4. Click on the Invite users button to send out invitations. Enabling public signup If your Jira setup is public (for example, an open source project), then creating user accounts individually, as explained earlier, would become a very demanding job for your administrator. For this type of Jira setup, you can enable public signup to allow users to create accounts by themselves. Perform the following steps to enable public signup in Jira: 1. Browse to the Jira administration console. 2. Select the System tab and then the General configuration option. 3. Click on the Edit Settings button. 4. Select Public for the Mode field. 5. Click on the Update button to apply the change. Once you have set Jira to run in Public mode, users will be able to sign up and create their own accounts from the login page, as illustrated in the following screenshot: Figure 9.2 – Public signup As you will see in the Application access section later in this chapter, once a user signs up for a new account, they will automatically join groups with the Jira user’s global permission. If you have set Jira to run in Private mode, then only the administrator will be able to create new accounts. Enabling CAPTCHA If you are running Jira in Public mode, you run the risk of having automated spam bots creating user accounts on your system. To counter this, Jira provides the CAPTCHA service, where potential users will be required to type a word represented in an image into a text field. Perform the following steps to enable the CAPTCHA service: 1. Browse to the Jira administration console. 2. Select the System tab and then the General configuration option. 3. Click on the Edit Settings button. 4. Select On for the CAPTCHA on signup field. 5. Click on the Update button to apply the change. Now, when someone tries to sign up for an account, Jira will present them with a CAPTCHA challenge that must be verified before the account is created, as illustrated in the following screenshot: Figure 9.3 – CAPTCHA Managing users 247 248 Securing Jira In addition to managing users, we also need to review how groups and roles are managed in Jira. Let’s go through this in the next section. Managing groups and roles Groups are a common way of managing users in any information system. A group represents a collection of users, usually based on their positions and responsibilities within the organization. In Jira, groups provide an effective way to apply configuration settings, such as permissions and notifications, to users. Groups are global in Jira, which is something that should not be confused with project roles (which we will discuss later). This means that if you belong to the jira-administrators group, then you will always be in that group regardless of which project you are accessing. You will see in later sections how this is different from project roles. Managing groups As with the user browser, the group browser allows you to search, add, and configure groups within Jira. Here’s how to access this: 1. Browse to the Jira administration console. 2. Select the User management tab and then the Groups option. This will bring up the Group Browser page, as illustrated in the following screenshot: Figure 9.4 – Group Browser page Managing groups and roles 249 Jira comes with a few default groups. These groups are created automatically when you install Jira. For Jira software, we have the following groups: Group Description Table 9.1 – Default groups Other Jira applications, such as Jira Service Desk, will have different sets of default groups. Adding a group Other than the three groups that come by default with Jira, you can create your own groups. It is important to note that once you create a group, you cannot change its name. Therefore, make sure that you think about the name of the group carefully before you create it. Follow these steps to create a group: 1. Browse to the Group Browser page. 2. Enter a unique name for the new group in the Add group section. 3. Click on the Add group button to create this new group. After a group is created, it will be empty and will have no members; you will need to manually add users to the group. Editing group memberships Often, people move around within an organization, and your Jira setup needs to be kept up to date with such movement. In the group browser, there are two ways to manage group memberships. The first option is to manage the membership on a per-group level, and the second option is to manage several groups at the same time. These options are actually similar, so we will cover them at the same time. Perform the following steps to manage individual groups: 1. Browse to the Group Browser page. 2. Click on the Edit members link for the group you wish to manage members of. This will bring you to the Bulk Edit Group Members page. jira- administrators Administrators of Jira. By default, this group lets you access the administration console. jira-software- users By default, members of this group will have access to the Jira Software application. 250 Securing Jira You will notice that both options will take you to the same page. The difference is that if you chose the individual group option, Jira will auto-select the group to update, and if you chose the bulk edit option, then no groups will be selected. However, regardless of which option you choose, you can still select one or all of the groups to apply your changes to, as described in the following screenshot: Figure 9.5 – Group members Perform the following steps to update the membership in one or more groups: 1. Browse to the Bulk Edit Group Members page. 2. Select one or more groups to update. 3. Select users from the middle box and click on the Remove selected users button to take users out of the groups. 4. Specify users (by typing usernames) in the right-hand side box and click on the Add selected users button to add users to the groups. Deleting a group If a group has become redundant, you can remove it from Jira by following these steps: 1. Browse to the Group Browser page. 2. Click on the Delete link for the group you wish to remove and click on Delete again to permanently remove the group. Once you remove a group, all users who previously belonged to it will have their group associations updated to reflect the change. However, if you have other configurations using the group, it can have a negative impact if you are not careful. For example, if you are restricting the Create Issue project permission to only a group called developers in your permission scheme, by deleting the developers group, nobody will be able to create issues in projects using the permission scheme. Important note Be very careful when deleting a group, as it might be used in other configurations. Managing roles As you have seen, groups are collections of users and are applied globally to all projects in Jira. Jira also offers another way of grouping users, which is applied on the project level only. Similar to users and groups, project roles are maintained by the Jira administrator through the Project Role Browser page. There is a slight difference, however, because since project roles are specific to projects, Jira administrators only define which roles are available in Jira and their default members. Each project’s administrators (discussed in later sections) can further define each role’s membership for their own projects, overriding the default assignment. We will first look at what Jira administrators can control through the Project Role Browser page and then look at how project administrators can fine-tune the membership assignment later. Managing groups and roles 251 252 Securing Jira Perform the following steps to access the Project Role Browser page: 1. Browse to the Jira administration console. 2. Select the System tab and then the Project roles option. This will bring up the Project Role Browser page, as illustrated in the following screenshot: Figure 9.6 – Project Role Browser page Adding a project role To start creating your own project roles, you will first need to add the role as a Jira administrator, and then each project administrator will be able to add users to it. Perform the following steps to create a new project role: 1. Browse to the Project Role Browser page. 2. Enter a unique name for the new project role in the Add Project Role section. 3. Click on the Add Project Role button to create this project role. Once you add a new project role, it will appear for every project. Managing default members You can assign default members to project roles so that newly created projects will have project roles assigned to them. Default members are an efficient way for Jira administrators to assign project role members automatically, without having to manually manage each new project as it comes in. For example, by default, users in the jira-administrators group will have the Administrators project role. This not only increases the efficiency of the setup by creating a baseline for new projects but also offers the flexibility to allow modifications to the default setup to cater to unique requirements. Perform the following steps to set default members for a project role: 1. Browse to the Project Role Browser page. 2. Click on the Manage Default Members link for the project role you wish to edit. The following screenshot shows that the Developers project role has two default users (Alana Grant and David Pereira) and a default group (jira-software-users): Figure 9.7 – Default role members On this page, you will see all the default members assigned to the selected project role. You can assign default memberships based on individual users or groups. Perform the following steps to add a default user/group to a project role: 1. Click on the Edit link for the default member option (either the user or group). 2. Use the user picker/group picker function to select users/groups you wish to assign to the project role. 3. Click on the Add button to assign the role. The following screenshot shows that the jira- software-users group is the default group for the Developers project role, and the contract-developers group is to be added: Managing groups and roles 253 254 Securing Jira Figure 9.8 – Adding a default role member Once added, any new projects created will have the specified users/groups assigned to the project role. It is important to note that changes to default memberships are only applied to new projects. Existing projects will not retrospectively have the new default members applied. Assigning project role members As you have seen, Jira allows you to assign default members to projects when they are created. This might be sufficient for most projects when they start, but changes will often need to be made due to staff movement during the project life cycle. While it is possible for the Jira administrator to continue maintaining each project’s membership, it can easily become an overwhelming task, and in most cases, since project roles are specific to each project, it makes sense to delegate this responsibility to the owner of each project. In Jira, an owner of a project is someone with the Administer Projects permission. By default, members of the Administrators project role will have this permission. We will see how to manage permissions in Jira in the Project permissions section later. As a project administrator, you will be able to assign members to various project roles for your project. You can assign roles from the project administration page, as follows: 1. Browse to the project administration page for the project you want to update. 2. Select the Users and roles option from the left-hand panel. 3. Click on the Add users to a role link. 4. Start typing the user’s username or the group’s name. Jira will auto-search for results as you type. 5. Click on the Add users to a role button once you have found the user/group you want to add. You can see an overview of this in the following screenshot: User directories 255 Figure 9.9 – Adding a role member Tip You should use groups instead of individual users where possible to help with future maintenance. The users and groups assigned to a project role will be for the current project only. Each project administrator can configure this for their own projects. In this way, you can maintain project role memberships separately for each project. User directories You might be wondering how and where Jira stores users and groups. User directories are what Jira uses to do this. A user directory is backed by a user repository system, such as LDAP, a database, or a remote user management system, such as Atlassian Crowd. Out of the box, Jira comes with a default internal directory that stores user and group information in the database. You can have multiple user directories in Jira. This allows you to connect your Jira instance to multiple user repositories. For example, you can have an LDAP directory for your internal users and the Jira internal directory using the database for external users. An example is given in the following screenshot, where we have three user directories configured. The first user directory is the built-in Jira internal directory running on the Jira database. The second user directory is connected to Microsoft Active Directory (AD) in read-only mode. The last user directory is connected to Atlassian Crowd, user identity management software from Atlassian: 256 Securing Jira Figure 9.10 – User directories As a Jira administrator, you can manage user directories by performing these two steps: 1. Browse to the Jira administration console. 2. Select the User management tab and then select the User Directories option. From there, you can see a list of user directories you currently have configured in Jira, add new directories, and manually synchronize with the remote user repository. When adding a new user directory, you need to first decide on the directory type. There are several different user directory types within Jira, as outlined here: • Jira internal directory: This is the built-in default user directory when you first install Jira. With this directory, all the user and group information is stored in the Jira database. • AD/LDAP: This is used when you want to connect Jira to an LDAP server. With this directory, Jira will use the backend LDAP to query user information and group membership. This is also known as an LDAP connector and should not be confused with internal and LDAP authentication directories. • Internal with LDAP authentication: This is also known as a delegated LDAP. With this directory type, Jira will only use LDAP for authentication and will keep all user information internally in the database (retrieved from LDAP when the user successfully authenticates for the first time). This approach can provide better performance. Since LDAP is only used for authentication, this avoids the need to download larger numbers of groups from LDAP. • Atlassian Crowd: If you are also using Atlassian Crowd, a user management and SSO and identity management solution, you can use this directory type to connect to your crowd instance. With this option, you can also configure your Jira instance to participate in the SSO session. Note that Jira Data Center has SSO support built in, so Atlassian Crowd is not required. • Atlassian Jira: Jira can act as a user repository for other compatible applications. If you have another Jira instance running, you can use this directory type to connect to the other Jira instance and for user information. When you have multiple user directories configured for Jira, there are a few important points to keep in mind. The order of the user directories is important, as it will directly affect the order Jira will use to search for users and apply changes to users and groups. For example, if you have two user directories and both have a user called admin with different passwords, this will have the following effects: • When you log in to Jira with the admin username, you will be logged in as the admin user from the first user directory that is able to validate the password, in the order of listed directories. • After logging in, you will be granted group membership from the directory that has validated your password. Any other directories will be skipped. • If you make a change to the admin user, such as changing the full name, then the changes will only be applied to the first directory Jira has write access to. Another important point to remember when working with user directories is that you cannot make changes to the user directory when you are logged in with a user account that belongs to the said directory. For example, if you are logged in with an LDAP account, then you will not be able to make changes to Jira’s LDAP user directory settings, since there is the potential for the new change to actually lock you out of Jira. Important note Always have an active administrator user account ready in the default Jira internal directory—for example, the account created during the initial setup. This will provide you with an administrator account that can help you fix user directory problems, such as the preceding scenario. If you have a user account with the same name in the other user directory, then the internal directory should also be the first one in the list. Connecting to LDAP Jira supports a wide range of LDAP servers, including Microsoft AD and OpenLDAP. If a particular LDAP is not listed as one of the options, then we also have a Generic Directory Server option. User directories 257 258 Securing Jira When using the AD/LDAP connector directory type, you can choose to connect with one of the following permission options: • Read only: Jira cannot make any modifications to the LDAP server. • Read only, with local groups: Information retrieved from LDAP will be read-only, but you can also add users to groups created within Jira. These changes will not be reflected in LDAP. • Read/Write: Jira will be able to retrieve and make changes to the LDAP server. The Read only option is the most common option, as information technology (IT) teams often centrally manage LDAP servers and changes are not allowed. With this option, Jira will only need read access to user data stored in LDAP to verify user credentials and group membership. If you only want to use LDAP as a user repository and for authentication, but still want to have the flexibility to update group membership without having to get the LDAP team involved, then the Read only, with local groups option will be the best fit. Lastly, the Read/Write option should be avoided, as propagating changes to LDAP, such as group membership, can have an unforeseen impact on other systems also relying on the same LDAP server. To connect your Jira setup to LDAP, all you have to do is add a new user directory, as follows: 1. Browse to the User Directories page. 2. Click on the Add Directory button and select either Microsoft Active Directory or LDAP from the Directory Type select list, and then click on Next. 3. Provide your LDAP server information. Since every LDAP is different, the exact parameters that are required will vary. At a minimum, you need to provide the following information: Parameter Name Hostname Base DN LDAP Permissions Description This is the name of the user directory. This is the hostname of your LDAP server. This is the root node for Jira to search for users and groups. This helps you choose whether Jira should be able to make changes to LDAP. Directory Type This is where you select the flavor of your LDAP. This will help Jira to prefill some of the parameters for you. Port This is the port number of your LDAP server. Jira will prefill this based on your directory type selection. User directories 259 Parameter Description Password This is the password that Jira will use to connect to LDAP. Table 9.2 – User directory parameters You can see these sections completed in the following screenshot: Username This is the username that Jira will use to connect to LDAP for user and group information. Figure 9.11 – Adding an LDAP user directory 260 Securing Jira Apart from the preceding parameters, there are additional advanced settings, such as User Schema Settings and Group Schema Settings. After filling in the form, you can click on the Quick Test button to verify that Jira is able to connect to your LDAP server and authenticate with the username and password provided. Note that this does not test for things such as user lookup. If the initial quick test is successful, then you can go ahead and click on the Save and Test button. This will add the user directory and take you to the test page, where you can test the settings with a proper user credential (this will be different than the one used by Jira to connect to LDAP), as illustrated in the following screenshot: Figure 9.12 – Test LDAP user directory Understanding Jira permissions 261 After the new user directory is added, Jira will automatically synchronize with the LDAP server and pull in users and groups. Depending on the size of your LDAP server, this may take some time to complete. After the initial synchronization, Jira will periodically perform incremental synchronization for any changes every 60 minutes. Understanding Jira permissions Jira manages its permissions in a hierarchical manner. Each level is more fine-grained than the one above it. For a user to gain access to a resource (for example, to view an issue), they need to satisfy all applicable permissions, as follows: • Application access: This defines the groups that will have access to the various applications in Jira (for example, Jira Software) • Global permission: This permission controls access rights functions, such as overall administration • Project-level permission: This permission controls project-level permissions—for example, creating and editing issues • Issue-level security: This permission controls view access to each individual issue We will now look at each of the permission levels and how you can configure them to suit your requirements, starting from access to the Jira application. Application access As we have explained in Chapter 1, Getting Started with Jira Data Center, the Jira product family includes several applications and you can have them all running together—for example, you can have Jira Software and Jira Service Management running in the same instance. Access to each of the running applications is controlled via the Application access feature. To manage application access, perform the following steps: 1. Browse to the Jira administration console. 2. Select the Applications tab and then the Application access option. 3. Select a group to grant access to the application. If you check the Default option of the group, new users will be added to the group when created. You can see an overview of this in the following screenshot: 262 Securing Jira Figure 9.13 – Application access You can only assign groups with application access. Once a group is assigned access to an application, all active users in the group will be granted access. Note that each user in the group will also consume a license seat for the application. Global permissions Global permissions, as the name suggests, control permissions that are applied globally, such as administrator-level access. Similar to application access, global permissions are applied to groups rather than individual users. The following table lists all permissions and what they control in Jira: Global permission level Description Jira System Administrators This gives permission to perform all Jira administration functions. This is akin to the root mode in other systems. Jira Administrators This gives permission to perform most Jira administration functions that are not related to system-wide changes (for example, to configure the Simple Mail Transfer Protocol (SMTP) server and to export/restore Jira data). Browse Users This gives permission to view a list of Jira users and groups. This permission is required if the user needs to use the User Picker/ Group Picker function. Create Shared Object This gives permission to share filters and dashboards with other users. Understanding Jira permissions 263 Global permission level Description Manage Group Filter Subscriptions This gives permission to manage group filter subscriptions. Filters will be discussed in Chapter 10, Searching, Reporting, and Analysis. Bulk Change This gives permission to perform bulk operations, including the following: • Bulk edit • Bulk move • Bulk delete • Bulk workflow transition Browse Archive This gives permission to browser projects and issues that have been archived. Table 9.3 – Global permissions Jira System Administrators versus Jira Administrators For people who are new to Jira, it is often confusing when it comes to distinguishing between the Jira System Administrators and Jira Administrators global permission. For the most part, they are very similar, and they can carry out most of the administrative functions in Jira. The difference is that Jira administrators cannot access functions that can affect the application environment or network, while a Jira system administrator has access to everything. While it can be useful to separate these two, in most cases, it is not necessary. By default, the jira- administrators group has both Jira System Administrators and Jira Administrators permissions. The following list shows examples of system operations that are only available to people with the Jira System Administrators permission: • Configuring SMTP server details • Configuring the Concurrent Versions System (CVS) source code repository • Configuring listeners • Configuring services • Configuring where Jira stores index files • Importing data into Jira from an Extensible Markup Language (XML) backup • Exporting data from Jira to an XML backup • Configuring attachment settings 264 Securing Jira • Accessing Jira license details • Granting/revoking Jira System Administrators global permission • Deleting users with Jira System Administrators global permission Configuring global permissions Global permissions are configured and maintained by Jira administrators and Jira system administrators, as follows: 1. Browse to the Jira administration console. 2. Select the System tab and then the Global permissions option to bring up the Global Permissions page, as shown in the following screenshot: Figure 9.14 – Global Permissions page Important note Users with the Jira Administrators global permission cannot grant themselves the Jira System Administrators global permission. Granting global permissions Global permissions can only be granted to groups. For this reason, you will need to organize your users into logical groups for global permissions to take effect. For example, you will want to have all your administrators belong to a single group, such as the jira-administrators group so that you can grant them administration permission. Here’s how to do this: 1. Browse to the Global Permissions page. 2. Select a permission you wish to assign from the Add Permission section. Project permissions 265 3. Choose the group to be given the permission. 4. Click on the Add button to add the assignment. The Group drop-down list will list all the groups in Jira. It will also have an extra option called Anyone on the web. This option refers to all users, including those that are not needed to log in to access Jira. You cannot select this option when granting the Jira Users permission, as they are required to log in, and Anyone refers to a non-logged-in user. For a production system, it is recommended to take care when granting any global permission to Anyone (non-logged-in users), as this can lead to security and privacy concerns. For example, by granting Anyone as the global permission for Browse Users, anyone with access to your Jira instance will be able to get your registered users’ information. Revoking global permissions Global permissions can also be revoked. Both Jira system administrators and Jira administrators can revoke global permissions, but Jira administrators cannot revoke the Jira System Administrators global permission. Perform the following steps to delete a global permission from a group: 1. Browse to the Global Permissions page. 2. Click on the Delete link for the group you wish to remove from the global permission. 3. Click on the Delete button to revoke the global permission for the group. Jira has built-in validation rules to prevent you from accidentally locking yourself out by mistakenly removing the wrong permissions. For example, Jira will not let you delete the last group from Jira System Administrators global permissions, as doing so effectively prevent you from adding yourself back (since only Jira system administrators can assign/revoke global permissions). Project permissions The next level of permission control is project permissions. Jira defines a list of permissions that covers the different operations a user can perform within the context of a project, such as creating new issues and adding comments to issues. Unlike application access and global permissions, which only allow you to use groups, project permissions have a lot more options when it comes to determining who to grant permissions to. A list of project permissions is set out here: • Application access: This is for any user that has been granted access to the application • Reporter: This is the user who submitted the issue • Group: These are all users that belong to the specified group • Single user: This is any user in Jira • Project lead: This is the lead of the project 266 Securing Jira • Current assignee: This is the user currently assigned to the issue • Project role: These are all users that belong to the specified role • User custom field value: This user is specified in a custom field of the type User Custom Field • Group custom field value: These are users within a specified group in a Group Custom Field type Since you will likely have many projects, Jira lets you define your permissions once and apply them to multiple projects, with permission schemes. Permission schemes Permission schemes are collections of associations between permissions and users. Each permission scheme is a reusable, self-contained entity that can be applied to one or more projects. As with most schemes, permission schemes are applied on the project level. This allows you to apply fine-grained permissions for each project. Just as with project roles, Jira administrators oversee the creation and configuration of permission schemes, and it is up to each project’s administrator to choose and decide which permission scheme to use. This way, administrators are encouraged to design their permissions so that they can be reused based on the common needs of their organization. With meaningful scheme names and descriptions, project administrators will be able to choose a scheme that will fit their needs the best instead of requesting a new set of permissions to be set up for each project. There is, however, some level of freedom for project administrators when it comes to configuration workflows and screens used by their own projects, as we have already seen in earlier chapters covering those two topics. If the permission scheme has the Extended project administration option enabled, then any projects using that permission scheme will allow project administrators to make changes without having to rely on a Jira administrator. We will first look at how Jira administrators manage and configure permission schemes and then at how project administrators can apply them in their projects. Perform the following steps to start managing permission schemes: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Permission schemes option to bring up the Permission schemes page, as illustrated in the following screenshot: Project permissions 267 Figure 9.15 – Permission schemes page On the Permission schemes page, you will see a list of all the permission schemes. From there, you will be able to create new schemes and edit and delete existing schemes, as well as configure each scheme’s permission settings. Configuring permission schemes Unlike other schemes, such as workflow schemes, Jira does not create a project-specific permission scheme when you create a new project, but rather, it uses a preconfigured scheme called the Default Permission Scheme. If your project needs to have its permission configuration changed, you can either update the permissions in the Default Permission Scheme (which would apply the changes to all other projects using it) or create a separate permission scheme for your new project. Since there are many permissions in a permission scheme, it is often much easier and more efficient to clone the Default Permission Scheme or another existing permission scheme as the base for your new permission scheme and then make the necessary changes, instead of creating a new scheme from scratch. Once you have decided to either update an existing permission scheme or have created a new permission scheme, you can then proceed to update its permission settings, as follows: 1. Browse to the Permission Schemes page. 2. Click on the Permissions link for a permissions scheme you wish to configure. 268 Securing Jira On this page, you will be presented with a list of project-level permissions, along with short descriptions for each, and the users, groups, and roles that are linked to each of the permissions. This is your one-page view of permission settings for projects, and you will also be able to control who will have access to each of the actions defined by the permissions listed. You can see an overview of this page in the following screenshot: Figure 9.16 – Configuring a permission scheme To grant permissions to one or more users, do the following: 1. Click on the Grant permission button or the Edit link for a specific permission. 2. Select permissions you wish to grant to the user. 3. Select who to grant the permission to. Click on the Show more link to see more options. 4. Click on the Grant button to grant the selected permission, as illustrated in the following screenshot: Project permissions 269 Figure 9.17 – Grant permission page As you can see, unlike global permissions, which only allow you to grant permissions to groups, there are many options available. While each option has its uses, you need to consider how you can maintain your permissions in the long run. For example, although it might be tempting to use the Single user option to quickly grant permission to a user who is requesting access quickly, this can easily become a maintenance nightmare if not careful. The most common options are Group and Project Role. Out of these two, Project Role is often the most flexible option, as it allows each project’s administrator to add users or groups to roles with permissions. Groups, on the other hand, often require either the Jira administrator or, in the case of LDAP, another IT administrator to add and remove users from individual groups. Other options, such as User custom field value, are a very flexible way to allow end users to control access. For example, you could have a custom field called Editors, and set up your Edit Issues permission to allow only users specified in the custom field to be able to edit issues. The custom field does not have to be placed on the usual view/edit screens for the permission to be applied. For example, you can have the custom field appear on a workflow transition called Submit to Manager. Once the user has selected the manager, only the manager will have permission to edit the issue. 270 Securing Jira Revoking permissions is as simple as granting them. Here’s how you can do this: 1. Browse to the Edit Permissions page for the permission scheme you wish to configure. 2. Click on the Remove link for the permission you wish to revoke, and click on Remove again. When you are trying to revoke permissions to prevent users from gaining access to certain things, you need to make sure no other options are granted the same permission that might be applied to the same user. For example, if you have both the Single user and Group options set for the Browse Projects permission, then you will need to make sure that you revoke the Single user option and also make sure that the user does not belong to the Group option selected so that you do not have a loophole in your permission settings. Applying a permission scheme Once you have your permission scheme configured, you can apply the scheme to your projects. There really is nothing special involved here. Permission schemes are applied to projects in the same way as notification and workflow schemes. Follow these next steps for instructions on how to configure these: 1. Browse to the project administration page you want to apply the permission scheme to. 2. Select the Permissions option from the left-hand panel. 3. Select the Use a different scheme option from the Actions menu. 4. Select a permission scheme you want to use. 5. Click on the Associate button. Permission schemes are applied immediately, and you will be able to see the permissions take effect. Issue security We have seen how Jira administrators can restrict general access to Jira with application access and global permissions, and what project administrators can do to place permissions on individual projects through permission schemes. Jira allows you to take things to yet another level to allow ordinary users to set the security level on issues they are working with, with issue security. Issue security allows users to set view permissions (but not edit them) on issues by selecting one of the preconfigured issue security levels. This is a very powerful feature, as it allows the delegation of security control to the end users and empowers them (to a limited degree) to decide who can view their issues. On a high level, issue security works in a similar way to permission schemes. The Jira administrator will start by creating and configuring a set of issue security schemes with security levels set. Project administrators can then apply one of these schemes to their projects, which allows users (with the Set Issue Security project permission) to select security levels within the scheme and apply them to individual issues. Issue security schemes As explained earlier, the starting point of using issue security is issue security schemes. It is the responsibility of the Jira administrator to create and design security levels so that they can be reused as much as possible. Jira does not come with any predefined issue security schemes, so you will have to create your own from scratch. Perform the following steps to create a new issue security scheme: 1. Browse to the Jira administration console. 2. Select the Issues tab and then the Issue security schemes option to bring up the Issue Security Schemes page, as illustrated in the following screenshot: Figure 9.18 – Issue Security Schemes page 3. Click on the Add issue security scheme link. 4. Enter a name and description for the new scheme. 5. Click on the Add button to create a new issue security scheme. Since an issue security scheme does not define a set of security levels like a permission scheme, you will need to create your own set of security levels right after you create your scheme. Configuring an issue security scheme Unlike permission schemes, which have a list of predefined permissions, with issue security schemes, you need to define all the security levels you need. Each security level represents the level of security that users need to meet before Jira will allow them access to the requested issue. Note that even though they are called security levels, it does not mean that there are any forms of hierarchy among the set of levels you create. Issue security 271 272 Securing Jira To add new security levels to your issue security scheme, proceed as follows: 1. Browse to the Issue Security Schemes page. 2. Click on the Security Levels link for the issue security scheme you wish to configure. This will take you to the page shown here: Figure 9.19 – Issue security levels 3. Enter a name and description for the new security level in the Add Security Level section. 4. Click on the Add Security Level button. You can add as many security levels as you like in a scheme. One good practice is to design and name your security levels based on your team or project roles (for example, Developers only). As with permission schemes, once you have your security levels in place, you will need to assign who will have access to each of the security levels. Users assigned to the security level will have permission to view issues with the specified security level. Proceed as follows: 1. Click on the Add link for the security level you wish to assign users to. 2. Select an option you wish to assign to the security level. 3. Click on the Add button to assign users. Troubleshooting permissions 273 Just as with permission schemes, it is better to use options such as Project Role and Group, as they are more flexible and do not tie the security level to individual users, allowing you to control permission with options such as group association. Setting a default security level You can set a security level to be the default option for issues if none is selected. This can be a useful feature for projects with a high-security requirement to prevent users (with the Set Issue Security permission) from forgetting to assign a security level for their issues. Follow these next steps: 1. Browse to the Edit Issues Security Levels page. 2. Click on the Default link for the security level you want to set as default. Once set as default, the security level will have Default next to its name. Now, when the user creates an issue and does not assign a security level, the default security level will be applied. Applying an issue security scheme Just as with permission schemes, project administrators apply issue security schemes to projects. Applying an issue security scheme is similar to applying a workflow scheme, where there is an intermediate migration step involved. This is to ensure that existing issues with set issue security levels can be successfully migrated over to the new security levels in the scheme. Proceed as follows: 1. Browse to the project administration page you want to apply the workflow scheme to. 2. Select the Issue Security option from the left-hand panel. 3. Select the Use a different scheme option from the Actions menu. 4. Select a permission scheme to use. 5. Click on the Next button to move to step 2 of the process. 6. Select a new security level to apply to an existing issue that may be affected by this change. 7. Click on the Associate button to apply the new issue security scheme. Now that we have seen how to apply permissions to projects and issues, let’s take a look at how you can troubleshoot problems you might encounter due to incorrect permission settings. Troubleshooting permissions Just as with notifications, it can be very frustrating to troubleshoot permission settings. To help with this, Jira also provides a Permission Helper tool to assist administrators with pinpointing settings that prevent users from accessing certain features. 274 Securing Jira The Permission Helper tool works similarly to the Notification Helper tool. Here’s how you can use it: 1. Browse to the Jira administration console. 2. Select the System tab and then the Permission helper option. 3. Specify the user having access problems in the User field. 4. Specify the issue to test with. 5. Select the permission the user does not have (for example, Edit Issues). 6. Click on the Submit button. You can see an overview of the process in the following screenshot: Figure 9.20 – Permission helper page Workflow security 275 As shown in the preceding screenshot, the user Alana Grant cannot edit issue DEMO-4 because she does not have the required Internal Only issue security level defined by the issue security scheme used by the project and is not in the Developers project role needed by the permission scheme. Workflow security The security features we have looked at so far are not applied to workflows. When securing your Jira setup, you will also need to consider who will be allowed to perform certain workflow transitions— for example, only users in the Managers group will be able to execute the Authorize transition on issues. For you to enforce security on workflows, you will have to set it on each transition you have by adding workflow conditions. Refer to Chapter 7, Workflow and Business Process, which discusses workflows and conditions in more detail. Password policy In most cases, unless you are using an SSO solution, you will be using a username and password combination to log in to Jira, so you will want users to choose strong passwords that cannot be easily guessed. If your organization is already enforcing a password policy and centrally managing authentication, such as via LDAP, then all you have to do is integrate Jira with it and you are good to go. However, if this is not the case, Jira comes with the ability for you to set a password policy to make sure your users do not choose simple, guessable passwords. To set up a password policy for Jira, perform the following steps: 1. Browse to the Jira administration console. 2. Select the System tab and then Password Policy. 3. Choose from one of the available options, with the Custom option allowing you to specify your own requirements. 4. Click on the Update button to apply the policy. After you have applied your new password policy, existing user passwords will not be affected. However, if users try to change their own password, or if you are creating a new user account, Jira will make sure the password meets the requirements of the policy and will display an error message if the requirements are not met, as illustrated in the following screenshot: 276 Securing Jira Figure 9.21 – Password policy Next, let’s look at how to enable SSO with SAML. Enabling SSO with SAML If your organization uses SAML for SSO, you can also configure Jira to participate in the SAML session so that your users will not need to log in to Jira every time they try to access the application. Also, if you have configured your SAML identity provider (IdP) with two-factor authentication (2FA) for additional security, Jira gets that benefit as well. The one pre-requisite for enabling SAML SSO with Jira is that you must run Jira on Hypertext Transfer Protocol Secure (HTTPS). If you have not configured your Jira setup to do so, please refer to Chapter 1, Getting Started with Jira Data Center, for details. To enable SAML SSO with Jira, proceed as follows: 1. Browse to the Jira administration console. 2. Select the System tab and then Authentication methods, which will take you to the page shown here: Figure 9.22 – Authentication methods page 3. Click on the Add configuration button. 4. Enter a name for the configuration. It is a good practice to name it after the IdP and authentication method—for example, Okta SAML. 5. Select the authentication method—in this case, SAML. After you have selected SAML as the authentication method, you will need to enter the details for your SAML configuration. The SAML configurations will be provided by your SAML-compliant IdP, such as Microsoft Azure AD, Okta, and Ping Identity. You will also need to provide Assertion Consumer Service URL and Audience URL (Entity ID) values to your IdP in order to register Jira as an application or service provider (SP). Lastly, you need to enter a value for Login button text. This is what will be displayed to the end users when they try to log in, so it should be something meaningful—for example, Log in with SSO. After you have entered all your configurations, click on the Save configuration button. Once you have added your SAML configuration, it will be shown as a login option on the login page, as illustrated in the following screenshot: Enabling SSO with SAML 277 278 Securing Jira Figure 9.23 – SAML authentication Important note There is an option to hide the username and password option by toggling the Show on login page option for the default username and password authentication method. Enabling JIT provisioning With SAML SSO, you can automatically create user accounts for new users when they first log in to Jira via SSO. Any subsequent logins will also automatically update the user account’s details, keeping the user’s Jira account and account in the IdP in sync. This is useful when you only want to create accounts on demand or are not synchronizing with your user directory such as LDAP to pull all your accounts into Jira. To enable JIT provisioning, proceed as follows: 1. Select the Edit option for your SAML authentication method. 2. Toggle on the JIT provisioning option. 3. Enter the SAML attributes that should be used for the user’s display name, email, and groups. These are provided by your SAML IdP. 4. Save your configuration. Once JIT provisioning is enabled, when a new user logs in to Jira via SAML SSO, Jira will create a new account based on the attributes provided by the SAML response. The account will also be updated every time the user logs in. Auditing system changes When you have more than one Jira administrator managing your Jira instance, it can often lead to a too many cooks situation, or you simply would like to keep track of who made which changes and when. Jira tracks and records many changes to many of the key system features and provides you with a full audit log of all the activities that are going on. This helps you diagnose problems and also perform a security audit in your system. To access the audit log, follow these steps: 1. Browse to the Jira administration console. 2. Select the System tab and then the Audit log option. As we can see from the following screenshot, the audit log keeps a track of changes such as custom fields, project roles, and more. You can filter the audit log based on the date and type, the person who made the change, and other options to help you narrow down the search: Figure 9.24 – Audit log You can also configure how and what Jira should track for the audit log. By going to the Settings option, you can select how long you want to keep the audit logs and what you want to track, as shown here: Auditing system changes 279 280 Securing Jira Figure 9.25 – Audit log settings By default, Jira tracks all the items under the Coverage heading at a base level. If you want Jira to track more details for a particular item, simply change the Coverage level option to either Advanced or Full. The HR project In the previous chapters, you configured your Jira to capture data with customized screens and fields and processed the captured data through workflows. What you need to do now is secure the data you have gathered to make sure that only authorized users can access and manipulate issues. Since your HR project is used by the internal team, what you really need to do is put enough permissions around your issues to ensure that the data they hold does not get modified by other users by mistake. This allows us to mitigate human errors by handling access accordingly. To achieve this, you need to have the following requirements: • You should know who belongs to the HR team • Restrict issue assign operations to only the user that has submitted the ticket and members of the HR team • Do not allow issues to be moved to other projects • Limit the assignment of tickets to the reporter and members of the HR team The HR project 281 Of course, there are a lot of other permissions we can apply here; the preceding four requirements will be a good starting point for us to build on further. Setting up groups The first thing you need to do is to set up a new group for your help desk’s team members. This will help you distinguish normal Jira users from your help desk staff. Follow these steps to do this: 1. Browse to the Group Browser page. 2. Name the new group hr-team in the Add Group section. 3. Click on the Add group button. You can create more groups for other teams and departments for your scenario here. Since anyone can log a ticket in your project, there is no need to make that distinction. Setting up user group association With your group set up, you can start assigning members of your team to the new group, as follows: 1. Browse to the Group Browser page. 2. Click on the Edit members link for the hr-team group. 3. Select users with the user picker or simply type in usernames separated by a comma. This time, let’s add our admin user to the group. 4. Click on the Add selected users button. Setting up permission schemes The next step is to set up permissions for our HR project, so you need to have your own permission scheme. As always, it is more efficient to copy the Default Permission Scheme as a baseline and make your modifications on top, since we are only making a few changes here. Proceed as follows: 1. Browse to the Permission Schemes page. 2. Click on the Copy link for Default Permission Scheme. 3. Rename the new permission scheme HR Permission Scheme. 4. Change the description to Permission scheme designed for HR team projects. Now that we have our base permission scheme set up, we can start on the fun part—interpreting requirements and implementing them in Jira. 282 Securing Jira Setting up permissions The first thing you need to do when you start setting up permissions is to try to match existing Jira permissions to your requirements. In our case, we want to do the following: • Restrict who can assign issues • Restrict who can be assigned to an issue • Disable issues from being moved Looking at the existing list of Jira permissions, you can see that we can match the requirements with the Assign Issues, Assignable Users, and Move Issues permissions, respectively. Once you work out which permissions you need to modify, the next step is to work out a strategy to specify users that should be given the permissions. Restricting the Move Issue options is simple. All you have to do is remove the permission for everyone, thus effectively preventing anyone from moving issues in your project. The next two requirements are similar, as they are both granted to the reporter (the user that submitted the ticket) and our new hr-team group. Follow the next steps: 1. Browse to the Permission Schemes page. 2. Click on the Permissions link for HR Permission Scheme. 3. Click on the Grant permission button. 4. Select both the Assign Issues and Assignable Users permissions. 5. Select the Reporter option. 6. Click on the Add button. 7. Repeat the steps and grant the hr-team group both permissions. By selecting both permissions in one go, you have quickly granted multiple permissions to users. Now, you need to remove all users granted with the Move Issues permission. There should be only one granted at the moment, Any logged in user, but if you have more than one, you will need to remove all of them. Here’s how you can do this: 1. Browse to the Permission Schemes page. 2. Click on the Permissions link for HR Permission Scheme. 3. Click on the Remove link for all users that have been granted the Move Issues permission. That’s it! You’ve addressed all your permission requirements with just a few clicks. Summary 283 Putting it together Last, but not least, you can now put on your project administrator’s hat and apply your new permission scheme to your HR project, as follows: 1. Browse to the project administration page for your HR project. 2. Click on the Permissions option and select your new HR permission scheme. 3. Click on the Associate button. By associating the permission scheme with your project, you have applied all your permission changes. Now, if you create a new issue or edit an existing issue, you will notice that the list of assignees will no longer include all the users in Jira. Summary In this chapter, we looked at how we can integrate Jira with user repositories, such as LDAP, through user directories, and Jira’s user management options with groups and project roles. Though they are very similar, groups are global, while project roles are specific to each project. We also covered how Jira hierarchically manages permissions. We discussed each permission level in detail and how to manage them. By using the different permission control options Jira provides, we design our permission controls to better manage user access to projects and issues. In the next chapter, we will take a different approach and start looking at another powerful use for Jira—getting your data out through reporting. 10 Searching, Reporting, and Analysis From Chapter 2, Using Jira for Business Projects, to Chapter 6, Screen Management, we have looked at how Jira can be used as an information system to gather data from users. In Chapter 7, Workflow and Business Process, and Chapter 8, Emails and Notifications, we discussed some of the features that Jira provides to add value to the gathered data through workflows and notifications. In this chapter, we will look at the other half of the equation—getting the data out and presenting it as useful information to the users. By the end of this chapter, you will have covered the following topics: • Utilizing the search interface in Jira • Learning about the different search options available in Jira • Getting to know about filters and how you can share search results with other users • Generating reports in Jira • Sharing information with dashboards and gadgets Specifically, this chapter will explore the following topics: • Search interface and options in Jira • Working with search results • Filters • Reports • Dashboards • Gadgets • The HR project 286 Searching, Reporting, and Analysis Search interface and options in Jira As an information system, Jira comes loaded with features and options to search for data and present the search results to end users. Jira comes with three options to perform searches: • Quick/text search: This allows you to search for issues quickly through simple text-based search queries • Basic/simple search: This lets you specify issue field criteria via intuitive UI controls • Advanced search: This lets you construct powerful search queries with Jira’s own search language, Jira Query Language (JQL) However, before we start looking into the details of all the search options, let’s first take a look at the main search interface that you will be using in Jira while performing your searches. Issue navigator The issue navigator is the primary interface through which you will be performing most of your searches in Jira. You can access it by clicking on the Issues menu in the top menu bar and then selecting the Search for issues option. The issue navigator is divided into several sections: • The first section is where you will specify all of your search criteria, such as the project you want to search and the issue type you are interested in • The second section displays the results of your search • The third section includes the operations that you can perform on the search results, such as exporting them into various formats • The fourth and last section lists a number of preconfigured and user-created filters When you access the issue navigator for the first time, you will be in the Basic Search mode. The following screenshot shows the issue navigator in this mode: Figure 10.1 – Issue navigator In basic search, as you can see, you specify your search criteria with UI controls, selecting values for each field. Note If you previously visited the issue navigator and chose to use a different search option, such as advanced search, then Jira will remember this and open up advanced search instead. Quick search This first search option we will look at is the quick search functionality, which allows you to perform quick simple searches based on the text contained in the issue’s summary, description, or comments. This allows you to perform quick text-based searches on all issues in Jira. The quick search function has several additional features to let you perform more specialized searches with minimal typing, through smart querying. Jira has a list of built-in queries, which you can use as your quick search terms to pull up issues with a specific issue type and/or status. Some useful queries are included in the following table (you can find a full quick search reference at https:// confluence.atlassian.com/jiracoreserver/quick-searching-939937704. html): Search interface and options in Jira 287 288 Searching, Reporting, and Analysis Smart query Issue key (for example, HD-12) myormy open bugs overdue Result Takes you directly to the issue with the specified issue key Displaysallissuesthatareassignedtothecurrentlylogged-inuser Displays all issues that are due before today Table 10.1 – Smart query Project key (for example, HD) Displays all issues in the project specified by the key on the Issue Navigator page Issues with a particular status (for example, open) Displays all issues with the specified status Issues with a particular resolution (for example, resolved) Displays all issues with the specified resolution You can combine these queries to create quick yet powerful searches in Jira. For example, the following query brings back all the resolved issues in the Help Desk project, where HD is the project key: HD resolved Running a quick search is much simpler than either basic or advanced searches. All you have to do is type in either the text you want to search with or the smart query in the Quick Search box in the top-right corner, and press Enter on your keyboard. As you can see, the goal of a quick search is to allow you to find what you are looking for in the quickest possible way. With a smart query, you are able to perform more than just simple text-based searches. It is important to note that quick search is case-sensitive. For example, searching with My instead of my will become a simple text search rather than issues that are assigned to the currently logged-in user. Basic search This is also known as simple search. The basic search interface lets you select fields you want to search with, such as issue status, and specify values for these fields. With basic search, Jira will display a list of searchable fields, and prompt you for the possible search values for the selected field. This is very handy for fields such as Status, and select list-based custom fields, as you do not have to remember all the possible options. For example, as shown in the following screenshot, we are searching for issues in the Demonstration project with a status of To Do. To help you with that, Jira will list all available statuses for you to select: Figure 10.2 – Basic search While working with the Basic Search interface, Jira will have the default fields of Project, Issue Type, Status, and Assignee visible. You can add fields to the search by clicking on the More drop-down option and then selecting a field you want to use in the search. Perform the following steps to construct and run a basic search: 1. Browse to the Issue Navigator page. If you do not see the basic search interface and the Basic link is showing, click on it to switch to basic search. 2. Select and fill in the fields in the basic search interface. You can click on More to add more fields to the search criteria. Note Jira will automatically update the search results every time you make a change to the search criteria. When working with basic search, one thing to keep in mind is that the configurations applied to the selected project and issue type such as workflow statuses and context of the custom fields are all taken into consideration. (Please see Chapter 5, Field Management, for field configuration.) For example, if a custom field is set to be applicable to only specific projects and/or issue types, you have to select a project and issue type as part of your search for the custom field to show up. Search interface and options in Jira 289 290 Searching, Reporting, and Analysis Advanced search with JQL Basic search is useful and will fulfill most of the user’s search needs. However, there are still some limitations. One such limitation is that basic search allows you to perform searches based on inclusive logic but not exclusive logic. For example, if you need to search for issues in all but one project, you will have to select every project except for the one to be excluded since the basic search interface does not let you specify exclusions. This is where advanced search comes in. With advanced search, instead of using a field selection-based interface, you will be using what is known as JQL. JQL is a custom query language developed by Atlassian. If you are familiar with the Structured Query Language (SQL) used by databases such as MySQL, you will notice that JQL has a similar syntax; however, JQL is not the same as SQL. One of the most notable differences between JQL and SQL is that JQL does not start with a SELECT statement. A JQL query consists of a field followed by an operator, and then by a value such as assignee = john or a function (which will return a value) such as assignee = currentUser(). You cannot specify which fields to return from a query with JQL, which is different from SQL. You can think of a JQL query as the part that comes after the WHERE keyword in a normal SQL SELECT statement. The following table summarizes the components in JQL: JQL component Description Keyword Keywords in JQL are special reserved words that do the following: Join queries together, such as AND Determine the logic of the query, such as NOT Have special meaning, such as NULL Provide specific functions, such as ORDER BY Operator Operators are symbols or words that can be used to evaluate the value of a field on the left and the values to be checked on the right. Examples include the following: Equals: = Greater than: > IN: When checking whether the field value is in one of the many values specified in parentheses JQL component Description Search interface and options in Jira 291 Field Fields are Jira system and custom fields. When used in JQL, the value of the field for issues is used to evaluate the query. Functions Functions in JQL perform specific calculations or logic and return the results as values that can be used for evaluation with an operator. Table 10.2 – JQL components Each JQL query is essentially made up of one or more components. A basic JQL query consists of the following three elements: • Field: This can be an issue field (for example, a status) or a custom field. • Operator: This defines the comparison logic (for example, = or >) that must be fulfilled for an issue to be returned in the result. • Value: This is what the field will be compared to; it can be a literal value expressed as text (for example, Bug) or a function that will return a value. If the value you are searching for contains spaces,youneedtoputquotesaroundit—forexample,issuetype = "New Feature". Queries can then be linked together to form a more complex query with keywords such as logical AND or OR. For example, a basic query to get all the issues with a status of Done will look similar to this: status = Done A more complex query to get all issues with a Resolved status, a Bug issue type, and which are assigned to the currently logged-in user, will look similar to this (where currentUser() is a JQL function): issuetype = Bug and status = Resolved and assignee = currentUser() Discussing each and every JQL function and operator is out of the scope of the book, but you can get a full reference by clicking on the help icon in the advanced search interface. A full JQL syntax reference can be found at https://confluence.atlassian.com/jiracoreserver0822/ advanced-searching-1141970390.html. You can access the advanced search interface from the Issue Navigator page, as follows: 1. Browse to the Issue Navigator page. 2. Click on the Advanced link on the right if you are not in advanced mode already. 3. Construct your JQL query. 4. Click on the Search button or press the Enter key on your keyboard. 292 Searching, Reporting, and Analysis As JQL has a complex structure and it takes some time to get familiar with, the advanced search interface has some very useful features to help you construct your query. The interface has an autocomplete feature (which can be turned off from the General Configuration setting) that can help you pick out keywords, values, and operators to use. It also validates your query in real time and informs you whether your query is valid, as shown in the following screenshot: Figure 10.3 – Advanced search You can switch between basic and advanced search by clicking on the Basic/Advanced link while running your queries, and Jira will automatically convert your search criteria into and from JQL. In fact, this is a rather useful feature and can help you learn the basic syntax of JQL when you are first starting up, by first constructing your search in basic and then seeing what the equivalent JQL is. Tip Switching between simple and advanced search can help you get familiar with the basics of JQL. You need to take note, however, that not all JQL can be converted into basic search since you can do a lot more with JQL than with the basic search interface. The Basic/Advanced toggle link will be disabled if the current JQL cannot be converted to the basic search interface. Now that we have seen how to perform searches in Jira, we will look at different ways we can use and work with the search results, starting with the various features and operations available directly from the issue navigator. Working with search results 293 Working with search results The issue navigator is capable of more than letting you run searches and presenting you with the results. It also has other features that allow you to do the following: • Display search results in different view options • Export search results in different formats • Select columns you want to see for issues in the results • Share your search results with other people • Create and manage filters We will explore each of these features in the following sections. Switching result views The issue navigator can display your search results in two different views. The default view is Detail View, where issues from results are listed on the left-hand side, and the currently selected issue’s details are displayed on the right. This view allows you to select and view detailed content of an issue, as well as edit the issue. The second view is List View, where issues are listed in a tabular format. The issue’s field values are displayed as table columns. As you will see later, you can configure the table columns as well as the way they are ordered. You can switch between the two views by selecting options from the Views menu next to the Basic/Advanced option. Customizing the column layout If you are using the List View option to display your search results, you can configure the field columns to be displayed. In Jira, you can customize your issue navigator for all your personal searches and also on a per-search level with filters (which we will discuss later in this chapter). If you are an administrator, you can set a default column layout for all users (which can be overwritten by each user’s own column layout settings). Perform the following steps to customize your global issue navigator’s column layout: 1. Browse to the Issue Navigator page. 2. Change your result view to List View. 3. Select the Columns drop-down menu and a column layout option, as shown here: 294 Searching, Reporting, and Analysis Figure 10.4 – Configuring search columns The following options can be used to lay out columns: • My Defaults: This column layout will be applied to all your searches • Filter: This column layout will be applied only to the current filter • System: This column layout will be applied to all searches To add or remove a field column, simply check or uncheck the field from the list. To reorder the column layout, you can drag the columns left or right to their appropriate locations. Exporting search results From the issue navigator, Jira allows you to export your search results to a variety of formats, such as MS Word and CSV. Jira is also able to present your search results in different formats, such as XML or print-friendly pages. When you select formats such as Word or Excel, Jira will generate the appropriate file and let you download it directly. Perform the following steps to export your results to a different format: 1. Browse to the Issue Navigator page. 2. Execute a search. 3. Select the Export drop-down menu in the top-right corner. 4. Select a format you wish to see your search results in, as shown: Working with search results 295 Figure 10.5 – Exporting search results Depending on the format you select, some formats will be on screen (for example, printable), while others will prompt you with a download dialog box (for example, Excel). Sharing search results After completing a search, you may want to share the results with your colleagues. Now, you can tell your colleagues to run the same search or, as we will see later in the chapter, save your search as a filter and then share it with other people. Alternatively, a more convenient way is to use the built-in share feature, especially if this is a one-off share. To share your current search results, all you have to do is click on the Share button in the top-right corner and type in the user’s name or an email address (if they are not Jira users). You can add multiple users or email addresses so that you can share this with more than one person. You can also add a quick note, letting people know why you are sharing the search results with them, and Jira will send out emails to all selected users and email addresses. Filters After you have run a search query, sometimes it is useful to save the query for later use. For example, you may have created queries for several projects, listing all the open bugs and new features in each project that are to be completed by a certain date so that you can keep an eye on their progress. Instead of recreating this search query every time you want to check up on the statuses, you can save the query as a filter that can be reused at a later stage. You can think of filters as named search queries that can be reused. 296 Searching, Reporting, and Analysis Other than being able to quickly pull up a report without having to recreate queries, saving search queries as filters provides you with other benefits: • Sharing saved filters with other users • Using the filters as a source of data to generate reports • Using the filters for agile boards (see Chapter 3, Using Jira for Agile Projects) • Displaying results on a dashboard as a gadget • Subscribing to the search queries to have results emailed to you automatically A few things to keep in mind when creating and using filters as the data source for gadgets and agile boards are noted here: • When you are creating a filter for agile boards, make sure you select relevant projects as part of your search query. • When you are creating a filter for gadgets and agile boards, make sure you share the filter with the same group of users that has access to the gadgets and boards. Otherwise, they will not see any results. We will explore all of the advanced operations you can perform with filters, and explain some of the new terms and concepts, such as dashboards and gadgets, in later sections. However, let’s look at how we can create and manage filters first. Creating a filter To create a new filter, you will first have to construct and execute your search query. You can do this with any of the three available search options provided in Jira, but please note that the search result must bring you to the Issue Navigator page. If you are using the quick search option and search by issue key, you will not be able to create a filter. Once you have executed your query, regardless of whether it brings back any result, you will be able to create a new filter based on the executed search, as follows: 1. Browse to the Issue Navigator page. 2. Construct and execute a search query in Jira. 3. Click on the Save as button at the top. 4. Enter a meaningful name for the filter. 5. Click on the Submit button to create the filter. Once you have created the filter, all your search parameters will be saved. In the future, when you rerun the saved filter, Jira will retrieve the updated results based on the same parameters. Take note that you need to click on the New filter button to start a new search if you have created a filter. Since the issue navigator remembers your last search, if you were working with an existing filter without starting a new search, you would, in fact, be modifying the current filter instead. Managing filters As the number of created filters grows, you will need a centralized location to manage and maintain them. You can access the Manage Filters page through the issue navigator, as follows: 1. Browse to the Issue Navigator page. 2. Click on the Find filters link on the left-hand side. You can also access the Manage Filters page by going through the top navigator bar. 3. Bring up the drop-down menu from Issues. 4. Click on the Manage filters option at the bottom of the list. The Manage Filters page displays the filters that are visible to you in three main categories, as set out in the tabs to the left, along with an option to search for existing filters: Figure 10.6 – Manage Filters page • Favorite: This option lists filters with a gray star next to their names. These filters will be listed in the Issues drop-down menu. You can mark a filter as a favorite by clicking on the star directly. • My: This option lists the filters that are created by you. • Popular: This option lists the top 20 filters that have the most people marking them as favorites. • Search: This option searches for existing filters that are shared by other users. The preceding screenshot also shows that both the All PPM issues and Due this week (DEMO) filters are marked as favorites. Working with search results 297 298 Searching, Reporting, and Analysis Sharing a filter After creating a filter, you can update its details such as name and description, sharing permission, and search parameters. By default, newly created filters are not shared, which means they are only visible to you. To share your filters with other users, perform the following steps: 1. Browse to the Manage Filters page. 2. Click on the Edit option for the filter you wish to share. 3. Select a group/project role to share the filter with and click Add. 4. Click on the Save button to apply the changes. This is shown in the following screenshot: Figure 10.7 – Sharing a filter Working with search results 299 Note Make sure you click on the Add link after you have chosen a group or a project to share a filter with. For you to be able to share a filter, you will also need to have the Create Shared Object global permission (please refer to Chapter 9, Securing Jira, for more information on global permissions). When you share your filter, you can choose who will have view permission, which means being able to see and run your filter (search results are still controlled by project and issue permissions), and who will be able to make modifications to your filter. As we will see later, Jira administrators can also change the ownership of filters that are shared. Subscribing to a filter You have seen in Chapter 8, Emails and Notifications, that Jira is able to send out emails when certain events occur to keep the users updated. With filters, Jira takes this feature one step further by allowing users to subscribe to a filter. When you subscribe to a filter, Jira will run a search based on the filter and send you the results in an email. You can specify a schedule of when and how often Jira should perform this. For example, you can set up a subscription to have Jira send you the results every morning before you come to work so that when you open up your mail inbox, you will have a full list of issues that require your attention. To subscribe to a filter, you will need to be able to see the filter (either created by you or shared with you by other users). Here’s how you can do this: 1. Browse to the Manage Filters page. 2. Locate the filter you wish to subscribe to. 3. Click on the Subscribe link for the filter. 4. Select a recipient of the subscription. Normally, this will be you (Personal Subscription). You can also create subscriptions for other people by selecting a group. 5. Check the Email this filter, even if there are no issues found option if you wish to have an email sent to you if there are no results returned from the filter. This can be useful to make sure that the reason you are not getting emails is not due to other errors. 6. Specify a frequency and time when Jira can send you emails. 300 Searching, Reporting, and Analysis This is shown in the following screenshot: Figure 10.8 – Subscribe filter 1. Click on the Subscribe button. This will create a subscription and take you back to the Manage Filters page. The Subscribe link will increment the number of subscriptions; for example, 1 Subscription. 2. Click on the 1 Subscription link to verify the subscription has been created correctly. 3. Click on the Run now link to test your new subscription. You should see something like this on your Subscription screen once you are done: Figure 10.9 – Viewing subscriptions Working with search results 301 Deleting a filter You can delete a filter when it is no longer needed. However, since you can share your filters with other users and they can create subscriptions, you need to keep in mind that the filter might be used by an agile board or in other places, as well as the fact that you may impact other users if the filter is shared. Luckily, when you delete a filter, Jira will inform you if other people are using the filter. Here’s how you can do this: 1. Browse to the Manage Filters page. 2. Click on the Delete link for the filter you wish to remove. This will bring up the Delete Filter confirmation dialog box. 3. Make sure that the removal of the filter will not impact other users. 4. Click on the Delete button to remove the filter. Jira will inform you if the filter is being used by Jira or if there are users subscribed to it. You can click through to see a list of subscribers, and then decide to either proceed with deleting the filter and letting the other users know or leave the filter in Jira. Changing the ownership of a filter Usually, Jira only allows the filter’s owner to make changes to it unless the right to edit is given to other users. This is usually not a problem for private filters, but when a filter is shared with other users or used for agile boards or dashboard gadgets, this can be problematic when the owner leaves the organization. For this reason, the Jira administrator is able to change the ownership of a shared filter. Perform the following steps to change a filter’s ownership: 1. Browse to the Jira administration console. 2. Select the System tab and then the Shared filters option. 3. Search for the filter you wish to change ownership of. 4. Click on the Change Owner option. 5. Search for and select a user that will be the new owner. 6. Click on the Change Owner button. This is shown in the following screenshot: 302 Searching, Reporting, and Analysis Figure 10.10 – Changing filter ownership Filters are a very useful feature in Jira—not only can you use them to access previous searches and share them with others, as we will see in later sections, but Jira also lets you run reports and create dashboards based on your filters. Let’s have a look. Reports Apart from JQL and filters, Jira also provides specialized reports to help you get a better understanding of the statistics for your projects, issues, users, and more. Most reports in Jira are designed to report on issues from a specific project; however, some reports can be used globally across multiple projects, with filters. Generating a report All Jira reports are accessed from the Browse Project page of a specific project, regardless of whether the report is project-specific or global. The difference between the two types of reports is that a global report will let you choose a filter as a source of data, while a project-specific report will have its source of data predetermined based on the project you are in. When generating a report, you will often need to supply several configuration options. For example, you may have to select a filter that will provide the data for the report, or select a field to report on. The configuration options vary from report to report, but there will always be hints and suggestions to help you work out what each option is. Perform the following steps to create a report; you will first need to get to a project’s browse page: 1. Select a project you wish to report on. 2. Click on the Reports option from the left panel. 3. Select a report you wish to create. The types of reports available will vary depending on the project type. 4. Specify configuration options for the report. 5. Click on the Next button to create the report. Jira comes with a number of reports that are specifically designed around reporting on agile projects, such as the Burndown Chart, as well as the basic set of charts that come with Jira Core, such as Average Age Report and Pie Chart Report. The types of reports available to you depend on the type of project. Scrum and Kanban projects will have reports under the Agile category, as shown in the following screenshot: Figure 10.11 – Reports Let’s create a pie chart report, as follows: 1. We will first select the type of report to be generated by selecting it from a list of available report types that come with Jira, as shown in the following screenshot: Figure 10.12 – Selecting a report Reports 303 304 Searching, Reporting, and Analysis 2. We will then configure the necessary report parameters. In this case, you need to specify whether you are generating a report based on a project or an existing filter; by default, the current project will be preselected. You also need to specify which issue field you will be reporting on, as you can see from the following screenshot: Figure 10.13 – Configuring the report 3. Once you have configured the report and clicked on the Next button, Jira will generate a report and present it on the screen, as shown in the following diagram: Figure 10.14 – Generated report The report type determines the report’s layout. Some reports have a chart associated with them (for example, Pie Chart Report), whereas other reports will have a tabular layout (for example, Single Level Group By Report). Some reports will even have an option for you to export their content into formats such as Microsoft Excel (for example, Time Tracking Report). Reports are run on a specific project and are run on demand. Jira also lets you create dashboards that can display data across multiple projects and can be dynamically updated to always show the latest data. Dashboards The dashboard is the first page you see when you access Jira. Dashboards host mini-applications known as gadgets, which provide various data and information from your Jira instance. Jira is able to present many of its features, such as filters and reports, on the dashboard using these gadgets, so it is a great way to provide users with a quick one-page view of information that is relevant or of interest to them. When designing a dashboard, you should always consider the target audience and choose the most appropriate gadgets for the job. For example, a dashboard for the management might have more charts, while a dashboard for a support team can make use of more list-style gadgets. Managing dashboards When you first install Jira, the default dashboard you see is called the System Dashboard, and it is preconfigured to show some useful information, such as all issues that are assigned to you. Here’s how you can manage dashboards: 1. Since everyone shares the system dashboard, you as a normal user cannot make changes to it, but you can create your own dashboards. Each dashboard’s functions are configured independently. 2. Bring down the drop-down menu from Dashboards. 3. Select the Manage Dashboards option. This will bring you to the Manage Dashboards page, as shown in the following screenshot: Figure 10.15 – Manage Dashboards page Dashboards 305 306 Searching, Reporting, and Analysis From this page, you can edit and maintain dashboards created by you, search dashboards created and shared by others, and mark them as favorites so that they will be listed as tabs for easy access. When a dashboard is marked as a favorite by clicking on the star icon in front of its name, the dashboard will be accessible when you click on the Dashboards link on the top menu bar. If you have more than one favorite dashboard, each will be listed in the tab and you can select which one to display. Creating a dashboard The default System Dashboard cannot be changed by normal users, so if you want to have a personalized dashboard displaying information that is specific to you, you will need to create a new dashboard. Perform the following steps to create a new dashboard: 1. Browse to the Manage Dashboards page. 2. Click on the Create new dashboard button. 3. Enter a meaningful name and description for the new dashboard. 4. Select whether you wish to copy from an existing dashboard or start with a blank one. This is similar to creating a new screen from scratch or copying an existing screen. 5. Select whether or not the new dashboard will be a favorite dashboard (for easy access) by clicking on the star icon. 6. Select whether you wish to share the dashboard with other users. If you share your dashboard with everyone by choosing the Everyone option, then users that are not logged in will also be able to see your dashboard. 7. Click on the Add button to create the dashboard. The following screenshot shows how you can create a new dashboard from scratch (blank dashboard) and allow view access to all members of the Hummingbird project, and allow edit access to members of the hummingbird-managers group: Dashboards 307 Figure 10.16 – Creating a new dashboard For you to be able to share a dashboard, you will also need to have the Create Shared Object global permission (please refer to Chapter 9, Securing Jira, for more information on global permissions). Once you have created the new dashboard, you will be taken immediately to it. As the owner of the new dashboard, you will be able to edit its layout and add gadgets to it. We will be looking at these configuration options in the next section. Configuring a dashboard All custom-created dashboards can be configured once they have been created. As the owner, there are two aspects of a dashboard you can configure: • Layout: This describes how the dashboard page will be divided • Contents: This describes the gadgets that are to be added to the dashboard 308 Searching, Reporting, and Analysis Setting a layout for the dashboard You have to be the owner of the dashboard (created by you) to set the layout. Setting a dashboard’s layout is quite simple and straightforward. If you are the owner, you will have the Edit Layout option in the top-right corner while you view the dashboard. Jira comes with five layouts that you can choose from. These layouts differ in how the dashboard page’s onscreen real estate is divided. By default, a new dashboard has a second layout that divides it into two columns of equal size. Perform the following steps to set a layout for a dashboard: 1. Bring up the drop-down menu from Dashboards. 2. Select a dashboard you wish to edit the layout for. 3. Click on the Edit Layout option in the top-right corner. This will bring up the Edit layout dialog. 4. Select a layout to which you wish to change, as follows: Figure 10.17 – Selecting a dashboard layout A layout selected from the dialog box will be immediately applied to the dashboard. Any existing contents will automatically have their size and positions adjusted to fit the new layout. After you have decided on your dashboard’s layout, you can start adding contents, known as gadgets, onto your dashboard. We will cover gadgets later in this chapter. Changing the ownership of a dashboard As with filters, the Jira administrator can change the ownership of a dashboard to a different user, in case the original user has left the organization. Perform the following steps to change a dashboard’s ownership: 1. Browse to the Jira administration console. 2. Select the System tab and then the Shared dashboards option. 3. Search for a dashboard you wish to change ownership of. 4. Click on the Change Owner option. 5. Search for and select a user that will be the new owner. 6. Click on the Change owner button, as shown in the following screenshot: Figure 10.18 – Changing dashboard ownership Gadgets Gadgets are like mini-applications that live on a dashboard in Jira. They are similar to widgets in most of the smartphones we have today or portlets in most portal applications. Each gadget has its own unique interface and behavior. For example, the Pie Chart gadget displays data in a pie chart, while the Assigned to Me gadget lists all the unresolved issues that are assigned to the current user in a table. Gadgets are another way for you to use search filters, by visually presenting the results to end users. Jira comes with many useful gadgets out of the box, and you can add more gadgets to Jira from third-party apps. We will cover how to install and manage third-party apps in Chapter 12. Let’s start by looking at how to add a gadget to your dashboard. Placing a gadget on the dashboard All gadgets are listed in the gadget directory. Jira comes with a number of useful gadgets, such as the Assigned to Me gadget that you see on the System Dashboard. The following screenshot shows the gadget directory, listing all bundled gadgets in Jira: Gadgets 309 310 Searching, Reporting, and Analysis Figure 10.19 – Gadget directory Perform the following steps to place a gadget onto your dashboard: 1. Bring up the drop-down menu from Dashboards. 2. Select a dashboard you wish to add a gadget to. 3. Click on the Add Gadget option in the top-right corner. This will bring up the Gadget Directory window. 4. Click on the Load all gadgets link to make all gadgets appear. You only need to do this for the first time when you load the gadget directory. 5. Click on the Add gadget button for the gadget you wish to add. 6. Close the dialog to return to the dashboard. Depending on the gadget you selected, some gadgets will require additional options to be configured. For these gadgets, you will be presented with their configuration screen on the dashboard. Fill in the options and click on the Save button. Let’s look at the following screenshot of the configuration screen for the Filter Results gadget: Gadgets 311 Figure 10.20 – Configuring a gadget On the configuration screen, you can select a search filter to display and control the number of results to show and the fields to include. One common parameter is the Auto refresh option, where you can decide how often the gadget can refresh its content or stay static if you leave it unchecked. Whenever you refresh the entire dashboard, all gadgets will load the latest data, but if you stay on the dashboard for an extended period of time, each gadget can automatically refresh its data, so the content will not become stale over time. When you add a gadget, it’s usually added to the first available spot on the dashboard. This sometimes might not be where you want to display the gadget on the dashboard, and in other cases, you might want to move the existing gadgets around from time to time. As the owner of the dashboard, you can easily move gadgets on a dashboard by dragging and dropping them to the desired location. 312 Searching, Reporting, and Analysis Editing a gadget After configuring your gadget when you first place it on your dashboard, the gadget will remember this and use it to render its content. You can update the configuration details or even its look and feel, as follows: 1. Browse to the dashboard that has gadgets you wish to update. 2. Hover over a gadget and click on the down arrow button in the top-right corner of it. This will bring up the gadget configuration menu. 3. Click on the Edit option. 4. This will change the gadget into its configuration mode. 5. Update the configuration options. 6. Click on the Save button to apply the changes. You can see an example of what this might look like here: Figure 10.21 – Editing a gadget The preceding screenshot shows the Edit menu for the Assigned to Me gadget. Some gadgets will have a Refresh option. Since gadgets retrieve their data asynchronously through AJAX, you can use this option to refresh the gadget itself without refreshing the entire page. The Edit, Delete, and Color options are only available to the owner of the dashboard. The HR project 313 Deleting a gadget As the owner of the dashboard, you can remove existing gadgets from the dashboard when they are no longer needed. When you remove a gadget from a dashboard, please note that all the other users who have access to your dashboard will no longer see it. Perform the following steps to delete a gadget: 1. Browse to a dashboard that has gadgets you wish to delete. 2. Hover over the gadget and click on the down arrow button in the top-right-hand corner of it. This will bring up the gadget configuration menu. 3. Click on the Delete option. 4. Confirm the removal when prompted. Once removed, the gadget will disappear from the dashboard. If you choose to re-add the same gadget at a later stage, you will have to reconfigure it again. This covers searches, reports, and dashboards in Jira. In the next section, we will build a custom dashboard for our HR project. The HR project In our previous chapters and exercises, we built and customized a Jira project to collect data from users. What we need to do now is process and present this data back to the users. The goal we are trying to achieve in this exercise is to set up a dashboard for our HR team that will have useful information such as statistics and issue listings, which can help our team members to better organize themselves to provide better services to other departments. Setting up filters The first step is to create a useful filter that can be shared with the other members of the team and that also acts as a source of data to feed our gadgets. We will use the advanced search to construct our search. Proceed as follows: 1. Browse to the Issue Navigator page. 2. Click on the Advanced link to switch to advanced search with JQL. 3. Typeproject = HR and issuetype in ("New Employee", Termination) and resolution is empty order by priority codeintheJQLsearchquery. 4. Click on the Search button to execute the search. 5. Click on the Save as button to bring up the Save Filter dialog. 314 Searching, Reporting, and Analysis 6. Name the filter Unresolved HR Tasks and click on the Submit button. 7. Share the filter with the hr-team group set up in Chapter 9, Securing Jira, by clicking on the Details link next to the Save as button. This filter searches for and returns a list of unresolved issues of the New Employee and Termination type from our HR project. The search results are then ordered by their priority so that the users can determine the urgency. As you will see in the later steps, this filter will be used as the source of data for your gadgets to present information on your dashboard. Setting up dashboards The next step is to create a new dashboard for your helpdesk team. What you need is a dashboard specifically for your team so that you can share information easily. For example, you can have a dashboard displayed on a large overhead projector showing all high-priority incidents that need to be addressed. Perform the following steps to do this: 1. Browse to the Manage Dashboards page. 2. Click on the Create new dashboard button. 3. Name the new dashboard Human Resources. 4. Select a blank dashboard as your base. 5. Check the new dashboard as a favorite. 6. Share the dashboard with the hr-team group. 7. Click on the Add button to create the dashboard. In our example, we will use the two default column layouts for your new dashboard. Alternatively, you are free to experiment with other layouts and find ones that best suit your needs. Setting up gadgets Now that you have set up your portal dashboard page and shared it with the other members of the team, you need to start adding some useful information to it. One example would be to have all unresolved incidents that are waiting to be processed on the dashboard display. Jira has an Assigned to Me gadget that shows all issues that are assigned to the currently logged-in user, but what you need is a global list irrespective of the assignee of the incident. Luckily, Jira also has a Filter Results gadget that displays search results based on a search filter. Since you have already created a filter that returns all unresolved tasks in your HR project, the combination of both will nicely solve your problem. Proceed as follows: 1. Browse to the Human Resources dashboard you have just created. 2. Click on the Add Gadget option in the top-right corner. Summary 315 3. Click on the Add gadget button for the Filter Results gadget. 4. Select the Unresolved HR Tasks filter you created. 5. Add any additional fields you wish to add for the Columns to display option. 6. Enable Auto refresh and set the interval to 15 minutes. 7. Click on the Save button. This will add a new Filter Results gadget to your new dashboard, using your filter as the source of data. The gadget will auto-refresh its contents every 15 minutes, so you will not need to refresh the page all the time. You can add some other gadgets to the dashboard to make it more informative and useful. Some other useful gadgets include the Activity Stream and Assigned to Me gadgets. Putting it together This is pretty much all you have to do to set up and share a dashboard in Jira. After you have added a gadget to it, you will be able to see it in action. The great thing about this is that, since you have shared the dashboard with others on the team, they will be able to see the dashboard too. Members of the team will be able to search for your new dashboard or mark it as a favorite to add it to their list of dashboards. You do have to keep in mind that if you are using a filter as a source of data for your gadget, you have to share the filter with other users too; otherwise, they will not be able to see anything from the gadget. Summary In this chapter, we covered how users can search and report on the data they have put into Jira, which is an essential component of any information system. Jira provides a robust search facility by offering many different search options to users, including quick, simple, and advanced searches. You can save and name your searches by creating filters that can be rerun at later stages to save you from recreating the same search again. Jira also allows you to create configurable reports on projects or results brought back from search filters. Information can be shared with others through a dashboard, which acts as a portal for users to quickly have a glance at the data kept in Jira. In the next chapter, we will look at the other application in the Jira family, Jira Service Desk, which helps to change Jira into a fully functional service desk with powerful features, such as the customer portal and SLA management. 11 Jira Service Management Jira was originally designed to be a tool to help developers track software bugs, and, over time, it evolved into a general-purpose, task-tracking tool that can be used by all organizations, thanks to its flexibility and extensibility. For this reason, many organizations started to use Jira as a service desk tool by leveraging its powerful workflow feature, and this has gained tremendous popularity. Recognizing this unique use case and its potential, a new product called Jira Service Management, from Atlassian, was born. Jira Service Management is a purpose-built solution that sits on top of the Jira platform, transforming it into a fully-fledged service desk solution with unique capabilities. In this chapter, we will cover the following topics: • Introducing Jira Service Management • Installing Jira Service Management • Getting started with Jira Service Management • Service desk user types • Issue types and request types • Service-level agreements (SLAs) • Managing requests with queues • Creating knowledge base articles • Process automation Introducing Jira Service Management In the previous chapters, we explored Jira’s core features, including workflows, custom fields, and screens. It is not hard to see how you can implement Jira Software as a service desk by creating new custom fields, screens, and workflow schemes. While Jira is certainly capable of handling the requirements of a service desk, there are still several things to be desired. 318 Jira Service Management For example, the user interface is often too complicated and confusing for business users to simply create a support ticket. Despite our best efforts, there are still way too many options on the screen, most of which are not useful in a service desk environment. Another example is the lack of ability to set up any sort of SLA to ensure a consistent quality of service. This is where Jira Service Management comes in. It addresses all the out-of-the-box shortcomings of Jira by providing a clean, intuitive, and user-friendly interface for both the end customers and the support team. It also provides many features that you can expect from a service desk solution. As shown in the following screenshot, Jira Service Management lets you serve your customers in four easy steps: Figure 11.1 – Jira Service Management As shown here, Jira Service Management simplifies the process of raising a service request to fulfill that request by providing a unique experience for users of different personas. Installing Jira Service Management There are two ways you can get Jira Service Management. The first option is to install it in an existing Jira Core or Jira Software instance that you possess. This is the easiest approach as it does not require you to provision additional hardware and lets you leverage what you already have. It also makes it easy for your agents to collaborate with other teams to help resolve customer requests. These are the steps you should follow to install Jira Service Management: 1. Log in as a Jira administrator user. 2. Browse to the Jira administration console. 3. Select the Applications tab. 4. Click on the Try it for free button under Jira Service Management from the right-hand panel: Figure 11.2 – Trying and installing Jira Service Management 5. Accept the user agreement and follow the onscreen instructions to complete the installation. Installing Jira Service Management 319 320 Jira Service Management The second option is to install Jira Service Management as a standalone application. Use this option if you do not have a Jira Software instance already running, or if you would like to keep your software issue tracking system and support system separate. Users from both instances can still collaborate to resolve customer requests as in option one, with a few extra steps to set up. These are as follows: 1. Create an application link between the two Jira instances. 2. Integrate both Jira instances with the same user repository, such as LDAP, to ensure that you have the same set of user details in both systems. To install Jira Service Management as a standalone application, you can refer to Chapter 1, Getting Started with Jira Data Center, as the installation steps are mostly identical. When it comes to deciding which option to pick, there are several factors you should consider: • Cost: If you want to deploy a standalone instance of Jira Service Management, there will be the initial cost of hardware and software, as well as maintenance after the system goes live. • Complexity: This can go either way. On the one hand, a standalone deployment adds complexity as you have more servers to look after, but on the other hand, having a combined deployment, you are adding complexity to the configurations of your system. So, you will need to balance this by looking at what in-house expertise is available. Do you have a team that is handling all the infrastructure and can take on more servers? Do you have an experienced Jira administrator that can look after a combined Jira instance? • Security: When Jira Service Management is deployed standalone, it is separate from your other Jira instances. This makes accidental data leaks due to misconfigurations and other mistakes less likely. This is especially important if your service management projects are publicly accessible and your software projects are internal only; you will need to be extra careful to ensure data security if both public and private projects are in the same instance. • Scalability: This is another factor that can easily be overlooked. If you deploy Jira Service Management into the same instance as Jira Software, you need to make sure the added load from your service management projects can be handled by your current hardware, especially if you allow public access to your projects. • Maintenance: As you start using Jira Service Management, you will likely make customizations and add third-party apps, which can add complexity at upgrade times. If Jira Service Management is a standalone deployment, then any customizations will be localized to that deployment only. But if you have a combined deployment, you will need to ensure all customizations and apps are compatible with the version you want to upgrade to. As we can see, there are many factors to consider here when deciding on your deployment model. The good news is that you can always merge or split your deployment later so that you are not stuck with your decision forever. However, this can be a very involved process, especially for large deployments, so it is recommended to plan out your vision for how you will use Jira in the long term. Getting started with Jira Service Management Before we start using Jira Service Management, it is important to understand and familiarize ourselves with the key terminology, as follows: • Agents: These are members of your service support team that will be working on customer requests. They are users that can perform actions such as editing, assigning, and closing requests. • Customers: These are the end users that will be raising support requests at your service desk. These can be customers of your product or colleagues from other departments needing IT support. • Customer portal: This is the main landing page for your customers. It is a simple, clean, and easy-to-use front interface for your service desk, without all the extra noise from the standard Jira interface, as shown in the following screenshot: Figure 11.3 – Customer portal Getting started with Jira Service Management 321 322 Jira Service Management • Queues: These are like Jira filters that show you a subset of issues that meet a certain criterion. Service desk agents use queues to prioritize and pick out requests to work on. • Requests: These are what your end users (not agents), such as customers, submit to Jira Service Management. Under the hood, they are just normal Jira issues. However, using the term request is less confusing in the context of a service desk environment. In short, requests are what your customers see, and issues are what agents see. • Service desks: These are where customers will raise their requests. Under the hood, a service desk is a Jira project of the Service Desk project type. Please refer to Chapter 2, Using Jira for Business Projects, for more information on project types. As shown in the following screenshot, when customers interact with requests, the user interface is very different from what agents will see. It is a much simpler UI that only displays key information about the request, such as its description and status. Customers cannot make changes to the request details after the request is submitted, and can only add new comments or attachments to the request: Figure 11.4 – Request view Getting started with Jira Service Management 323 The key information regarding service desks is as follows: • Request type: This represents the different types of requests customers can make. These can be anything, including a problem report, help request, or general inquiry. When you create a new request type, Jira creates a new issue type behind the scenes. One major feature of the request type is that it allows you to specify a user-friendly name for it. While the actual issue type is called a Problem Report, you can rename it and display it as Submit a problem report instead. • Service desk: This is what agents will be working from. Each service desk has a front, customer- facing portal. Behind the scenes, a service desk is a Jira project controlled by Jira permissions, workflows, and other schemes. • SLA: An SLA defines the quality of service that is being guaranteed to your customers. In Jira Service Management, SLAs are measured in time, such as response time and the overall time taken to resolve issues. Creating a new service desk The first step to start working with Jira Service Management is to create a new service desk project. Since, under the hood, a service desk is a Jira project with a new user interface, the easiest option is to create a new project using one of the Service project templates. To create a new service desk, perform the following steps: 1. Select the Create project option from the Projects drop-down menu. 2. Choose a project template, such as IT Service Desk, from the Service project type box, and click on Next. 3. Enter the name and key for the new service desk project and click Submit: 324 Jira Service Management Figure 11.5 – Creating a service desk project Alternatively, you can use an existing Jira project and convert it into a service desk. All you have to do is update the project’s type by following these steps: 1. Browse to the project settings page for the project you want to turn into a service desk. 2. Select the Details option from the left panel. 3. Change the Project type option to Service and click on Save details: Getting started with Jira Service Management 325 Figure 11.6 – Changing the project type Features that are exclusive to a project type will be lost when you switch a project’s type. Once your service desk has been created, you will be taken to your service desk user interface, as shown in the following screenshot: Figure 11.7 – Jira Service Management UI Every service desk has two interfaces. One will be used by you, as the admin, and members of your support team, known as agents. The second interface is called the customer portal, which is what customers will see and use to create requests and interact with agents. As you make configuration changes for your service desk, you can always preview the change by clicking on Customer channels and then the Visit the portal link from the left navigation panel, which will show you what the customer portal will look like. 326 Jira Service Management Note The URL shown under the customer portal is what your customers should use to access your service desk. Branding your customer portal You can brand your customer portal for your service desk with the following options: • Help center name: This is the overall name for your help center. Think of this as the name for your Jira instance. • Customer portal name: This is the name of a specific service desk portal. • Customer portal introduction text: This is the welcome text that will be displayed for a specific service desk portal. • Customer portal logo: This is the logo for a specific service desk portal. The following screenshot illustrates each of these items on a sample customer portal: Figure 11.8 – Customized portal To configure a specific customer portal’s branding, perform the following steps: 1. Browse to the project settings page of the service desk you want to brand. 2. Select Portal settings from the left-hand panel. 3. Enter a name and welcome text in the Name and Introduction text fields, respectively. 4. Check the Use a custom logo for this Customer Portal option and upload a logo for your customer portal. The configuration settings look as follows: Figure 11.9 – Portal configuration Getting started with Jira Service Management 327 328 Jira Service Management Now that we have seen how to create a service desk and brand its customer portal, let’s take a look at the different user types Jira Service Management has. Service desk user types Jira Service Management introduces several new user types. Under the hood, these user types are mapped to new project roles created by Jira Service Management when it is installed: • Agent: These are members of the service desk team that work on requests. Agents are added to the Service Desk Team project role. • Collaborator: These are the members from other business functions; they are not members of your service desk team. However, they can help solve customer problems. A good example would be product domain experts or engineers. Collaborators are added to the Service Desk Team project role. • Customer: These are end users that will be submitting requests through your help desk portal. Customers are added to the Service Desk Customers project role. • Organization: These are groups of customers. For example, an organization can represent a company, and all employees of that company will be part of the organization. Requests can be limited to being only sharable among customers of the same organization. Adding an agent to a service desk Agents are Jira users who will be working on customer requests in Jira Service Management. These are usually members of your support team. Agents consume the Jira Service Management licenses. To add an agent to a service desk, do the following: 1. Browse to the service desk you want to add an agent to. 2. Click on the Invite team option in the left-hand panel. 3. Search and add users you want to invite as an agent (member) of your service desk team. You can select and add more than one agent. Click on the Invite x people button: Service desk user types 329 Figure 11.10 – Adding an agent When you’re adding an agent to a service desk, you can select an existing user in Jira, which will grant the user access to the service desk. If the user you want to add as an agent does not exist, you can also create a new Jira account and add them as an agent in a single step by typing in the user’s email address. An email will be sent out with a link to set their password. New user accounts created in this way will be automatically added to the jira-servicedesk-users group and Service Desk Team project role. Refer to Chapter 9, Securing Jira, for more information on groups and roles. Managing service desk customers Customers are end users who will be creating requests through your customer portal. You can manually invite customers or allow them to sign up themselves. Jira Service Management requires customers to have an account to submit requests. The good news is that customers do not consume the Jira Service Management licenses, so you can have as many customers as you want. When a customer raises a request with your service desk, the request may contain sensitive information that is specific to the customer. Your service desk may also serve customers from different organizations. Therefore, you need to manage how requests and their associated data are shared and accessed. 330 Jira Service Management The first step is to decide who can be customers of your service desk, and also how requests from one customer can be shared with another: 1. Browse to the project administrator page for the service desk where you want to manage customer permissions. 2. Select the Customer permissions option from the left-hand panel. 3. Choose who can raise requests in your service desk as customers under the Who can raise requests? section. By default, anyone with an account can raise requests, but you can narrow it down to specific users that are added to your service desk. 4. Choose how requests can be shared under the Who can customers share requests with? section. Usually, you only want customers to be able to share request information within their own organizations. 5. Click on the Save button to save your changes. If you have narrowed your customer’s permissions to only allow specific customers to raise requests at your service desk, you will need to add/invite them. To invite a customer to a service desk, perform the following steps: 1. Browse to the service desk where you want to add a customer. 2. Select the Customers option from the left-hand panel. 3. Click on the Add customers button. 4. Enter the email addresses of customers to invite and click on the Add button, as shown: Figure 11.11 – Adding customers Issue types and request types 331 Emails will be sent out to customers with details on how to access the customer portal and steps to create an account if necessary. If your service desk serves customers from multiple organizations, you can create these organizations and add customers to them. By having customers grouped in their own organizations, you can control how requests can be shared among different customers. Adding a collaborator to a service desk Collaborators are Jira users who are not part of your support team (not agents) but have expert knowledge and understanding in the domain area that can assist agents in diagnosing and solving customer requests. In Jira Service Management, collaborators are users in the Service Desk Team project role, but not in the jira-servicedesk-users group, and adding a user as a collaborator is an easy way to grant that user access to your service desk project. Collaborators do not consume Jira Service Management licenses. To add a collaborator to your service desk, follow these steps: 1. Browse to the project administrator page for the service desk you want to add a collaborator to. 2. Select the Users and roles option from the left-hand panel. 3. Click on the Add users to a role button. 4. Search for and select the users to add, choose the Service Desk Team role, and click on the Add button. When making a user a collaborator, you are simply giving the user permission to access your service desk so that they can view, comment, and add attachments to the request. Issue types and request types Jira uses issue types to define the purpose of issues, while Jira Service Management uses request types for the same purpose. Behind the scenes, each request type is mapped to an issue type. The one key difference between the two is that a request type is what is shown to the customers, and often has a more descriptive name. For example, an issue type is called an Incident, and the corresponding request type will be called a Report System Outage. You can think of request types as issue types with a more informative display name. As we will see later in this section, another key feature of request types is that you can organize them into groups to help your users find what they need. 332 Jira Service Management Setting up request types To create a new request type for your service desk, do the following: 1. Browse to the project settings page for the service desk where you want to create a new request type. 2. Select the Request Types option from the left-hand panel. 3. Select the group this request type should belong to from the left. We will talk about groups later in this section. 4. Enter a name for the request type. You can be as descriptive as possible here so that your customers can easily understand its purpose. 5. Click on the image under Icon to select a new icon for the request type. 6. Select the issue type that the request type is mapped to. 7. Enter an optional description. This description will be displayed underneath the request name to help your customer decide what type of request to create. 8. Click on the Create request type button to create the new request type: Figure 11.12 – Create request type You can reorder the request types by dragging them up and down the list. The order you set in the list will be reflected on the customer portal. Make sure you put some thought into this so that the list flows logically. For example, you can order them alphabetically or by placing the most common request types at the top. Organizing request types into groups As the number of request types grows, you can group similar request types into groups. Therefore, when customers visit the portal, all the request types will be organized logically, making navigation much easier. For example, as shown in the following screenshot of a customer portal, we have six request type groups, where five come with Jira Service Management’s project templates; the sixth, Sample Request Group, is custom. When clicking on Sample Request Group, we also have the three custom request types: Figure 11.13 – Custom request type and group As we saw earlier in this section, a request type can be added to one or more groups. You can select one of the existing groups, or create a new group, by simply typing in the new group’s name. When a request type belongs to two or more groups, it will be displayed when each of the groups is selected in the portal. Setting up fields for request type Jira Service Management lets you set up different field layouts for each request type. The important thing to note here is that, when you are setting up fields for Jira Service Management, you are not creating new custom fields (as you would in Jira Software). You are simply adding and removing existing fields in the request form when customers create a new request. You can think of this as adding fields to screens. If you want to add a field that does not exist yet, you will have to create a new custom field first, as described in Chapter 5, Field Management, and then make it available in the request form. Just as with request types, Jira Service Management allows you to provide a custom display name to the field, independent of the actual field’s name. This means that the field can be more informative when displayed to customers. For example, for the Jira Summary field, you can give it a display name of What is the problem you are having?. As the display name is independent of the field’s name, your existing filters and search queries will continue to work as-is. Setting up fields for request type 333 334 Jira Service Management To set up field layouts for a request type, follow these steps: 1. Browse to the project settings page for the service desk you want to set up field layouts for. 2. Select the Request Types option from the left-hand panel. 3. Click on the Edit fields link for the request type you want to set up fields for. This will list all the fields that are currently displayed when customers create a new request: Figure 11.14 – Adding a field to the request form 4. Click on the Add a field button and select an existing field (both system and custom) to add to the request type. 5. Click on the field’s Display name to change what customers will see when the field is displayed. This does not change the field’s actual name in Jira – it only makes the display more user-friendly. 6. Change the field’s mandatory requirement by clicking on the Required column. Note that you cannot change this value if it is grayed out. An example of this is the Summary field. After you have set up your field layout for the request type, you can click on the View this request form link at the top to see a preview of the result. As shown in the following screenshot, we added the Due Date field to the form, but it is now displayed as When do you need this by?: Setting up a workflow for a request type 335 Figure 11.15 – The field displayed in the request form One thing to keep in mind is that this field layout is specific to each request type, so if you have multiple request types that share the same field layout, you will need to configure each individually. Setting up a workflow for a request type Just as with fields, you can also control how workflow statuses are displayed in Jira Service Management. Note that you cannot change the actual workflow, but you can make the workflow less confusing to your customers so that they know exactly how their requests are progressing. To set up the workflow for a request type, perform the following steps: 1. Browse to the project settings page for the service desk you want to set up a workflow for. 2. Select the Request types option from the left-hand panel. 3. Click on the Edit fields link for the request type you want to set up a workflow for. 336 Jira Service Management 4. Select the Workflow Statuses tab. This will list all the workflow statuses that are available in the workflow, as shown in the following screenshot: Figure 11.16 – Customizing the workflow As shown in the preceding screenshot, the actual Jira workflow status names are listed in the left- hand column. For each of the statuses, you can choose to give it a different display name that will be shown to customers. For example, In Progress is a normal Jira workflow status, and represents that the request is currently with a support agent. We can change it to Under investigation, and this is what will be displayed when a customer is viewing the issue. Note You are not changing the workflow itself. You are simply making it more user-friendly for your customers. Service-level agreement (SLA) 337 Service-level agreement (SLA) An SLA defines the agreement between the service provider (your organization) and the end user (your customer) in terms of the aspects of the service provided, such as its scope, quality, or turnaround time. In the context of a support service, an SLA will define different response times for different types of support requests. For example, severity 1 requests will have a response time of 1 hour, while severity 2 requests will have a response time of 4 hours. Jira Service Management lets you define SLA requirements based on response time. You can set up the rules on how response time will be measured, and the goals for each rule. Setting up an SLA Jira Service Management‘s SLA is divided into two components: the time measurement and goals to achieve. Time can be measured for a variety of purposes. Common examples include overall time taken for request resolution and response time to customer requests. To set up an SLA metric, follow these steps: 1. Browse to the project settings page for the service desk you want to set up the SLA on. 2. Select the SLAs option from the left-hand panel and then click on the Create SLA option. For any SLA, you will need to define when the clock will start counting and when it will stop counting, with an option to pause during the process. Jira provides many options for choosing when to start and stop the clock. Most common options include when a request enters or leaves a workflow status; other options include when a value is set on a field, such as assignee or resolution. A simple example would be for Jira Service Management to start counting as soon as the request is created. Every time an agent requests further information from the customer, the count will be paused until the customer responds. Once the request is finally closed off, the count will be stopped. The following steps show how to set up an SLA time measurement for a simple example: 1. For the Start column, we will select the Issue Created option, indicating that it can start counting as soon as the request is created. 2. For the Pause on column, we will select the Status: Waiting for customer option, indicating that the counting can be paused when the request enters the Waiting for customer workflow status. 3. For the Stop column, we will select the Entered Status: Canceled, Entered Status: Closed, and Resolution: Set options, indicating that the counting will be stopped once the request is canceled, closed, or a resolution is set. 338 Jira Service Management As shown in the following screenshot, for each of the three columns, you can select more than one condition: Figure 11.17 – SLA example 1 This allows you to set up multiple entry points to start and stop time. An example of this usage would be to measure response time. For example, perhaps you need to guarantee that an agent will respond to a new request within an hour. If the request is sent back to the customer for further information, a response time of 1 hour is also required as soon as the customer updates the request with the requested information. The following points show how to set up the time measurement for this SLA: • For the Start column, we will select both the Issue Create and Entered Status: In Progress options. Therefore, we will start counting when the issue is first created, and also when it is put back for our agents to work on. • For the Stop column, we will select both the Entered Status: Waiting for Info and Entered Status: Closed options. Counting will stop when an agent sends the request back to the customer for more information or when it is closed for completion. The difference between the two examples here is that, in the second example, we do not pause time counting when the request enters the Waiting for customer status. Instead, we stop counting completely. This means that when the request enters the Waiting for customer status, the current counting cycle ends, and when the request enters the In Progress status, a new counting cycle will begin, as shown in the following screenshot: Service-level agreement (SLA) 339 Figure 11.18 – SLA example 2 Once we have defined how time should be measured, the next step is to set up the SLA goals. The SLA goals define the amount of time allowed for each of the scenarios we have just set up. If we take the aforementioned response time example, we may set up our goals like so: Figure 11.19 – SLA goals 340 Jira Service Management In our example, we have defined that for requests whose priority has been set to Highest, the response time will be 1 hour (1h); High and Medium requests will have a response time of 4 and 8 hours, respectively. Everything else will be responded to within 12 hours. As you can see, there are several components when it comes to defining an SLA goal, as follows: • Issues: These are the issues/requests that will have the goal applied to them. Use JQL to narrow down the selection of issues. • Goal: This is the time value for the goal. You can use the standard Jira time notation here, where 3h means 3 hours, 45m means 45 minutes, and 2h30m means 2 hours and 30 minutes. • Calendar: These define the working days and hours the SLA will be applied to. For example, 24/7 Calendar means that time will be counted every hour of every day. As we will see later, you can create your own custom calendars to define your working days, hours, and even holidays. When defining SLA criteria, we will need to use JQL. Just like doing an advanced search, Jira Service Management provides syntax autocomplete to help us validate our queries, as shown in the following screenshot: Figure 11.20 – SLA goal criteria Next, we will look at how to create and configure calendars for an SLA. Setting up custom calendars As we have seen, when setting up an SLA, you can select a calendar that defines the working days and hours, which can be counted toward the goal. Jira Service Management comes with Default 24/7 calendar and Sample 9-5 calendar, which will only count the time between 9 A.M. and 5 P.M. from Monday to Friday. You can create custom calendars so that they include different working hours, time zones, and holidays. To create a custom calendar for your service desk, follow these steps: 1. Browse to the project settings page for the service desk you want to add a calendar for. 2. Select the SLAs option from the left-hand panel. 3. Click on the Calendar option, and then click on the Add calendar button. 4. Enter a name and description for the new calendar and configure the options. Jira Service Management lets you configure your calendar with the following options: • Time zone: This sets the time zone that will be used for the calendar • Working days: This sets the days that can be counted toward the SLA • Working hours: These are the hours of each working day that can be included in the SLA • Holidays: This adds holidays, such as Christmas, so that they’re excluded from the SLA As shown in the following screenshot, we have set up our calendar so that we have a working time between 9 A.M. and 5 P.M., Tuesday to Friday. This means that Monday, Saturday, and Sunday are excluded when calculating SLA metrics: Figure 11.21 – SLA calendar working days Service-level agreement (SLA) 341 342 Jira Service Management We have also added Christmas Day and New Year’s Day as holidays so that the SLA will not be applied on those days: Figure 11.22 – SLA calendar holidays When adding holidays, you can check the Repeat yearly option if the holiday will always fall on the same day every year, such as Christmas Day, so that you do not need to manually add them each year. Managing requests with queues Queues are lists of requests with predefined criteria for agents to work through. You can think of them as Jira filters. They help you and your teams organize incoming requests into more manageable groups so that you can prioritize them. Jira Service Management uses Jira’s search mechanism to configure queues. Refer to Chapter 10, Searching, Reporting, and Analysis, for more details on Jira search options. Creating a new queue When you first create a service desk, several default queues are created automatically for you. This includes an Assigned to me queue that lists all unresolved requests that are assigned to the currently logged-in user and a queue for each request type. You, as the service desk administrator, can create new queues for your team. To create a new queue, follow these steps: 1. Browse to the service desk you want to add a queue for. Note that queues are not managed in the project settings console. 2. Select the Queues option from the left-hand panel and click on the New queue option from the Switch Queues drop-down menu. 3. Enter a name for the queue. It should reflect its purpose and the types of requests that will be in it. 4. Use the UI controls to create the search criteria. If you are familiar with JQL or need to use exclusion logic in your query, you can click on the Advanced link and use JQL directly. 5. Select the fields that will be displayed when the queue is showing the issue list. Click on the More option to find more fields to add. You can also drag the fields left and right to rearrange them. You can select the fields that will display the most useful information. 6. Click on the Create button to create the queue, as shown in the following screenshot: Figure 11.23 – Creating a new queue As shown in the preceding screenshot, when you make changes to your search criteria and field selection, there is a preview area at the bottom that will show you the result of your search and the field layout. Creating knowledge base articles As your team works diligently to solve problems for your customers, nuggets of knowledge will start to accumulate over time. These include things such as common questions customers face, and the steps taken to troubleshoot them. Jira Service Management allows you to extract this information and create a knowledge base, which helps customers find solutions themselves. Out of the box, Jira Service Management only supports Atlassian Confluence for knowledge base creation, but it is possible to use other tools via third-party add-ons. Creating knowledge base articles 343 344 Jira Service Management To integrate Jira Service Management with Confluence, you will have to create an application link between Jira and Confluence. If you have already done this, feel free to skip to the next section. To create an application link for Confluence, perform the following steps: 1. Browse to the Jira administration console. 2. Select the Applications tab and the Application links option from the left-hand panel. 3. Click on the Create link button. 4. Select the Atlassian product option, enter the fully qualified URL to your Confluence instance, and click on the Continue button, as shown in the following screenshot: Figure 11.24 – Creating an application link with Confluence 5. Follow the onscreen wizard to complete the linking process. Once the application link has been created with Confluence, we can use it for Jira Service Management. Each service desk will need to be individually integrated with a Confluence space. To set up a Confluence knowledge base for a service desk, follow these steps: 1. Browse to the project settings page of the service desk you want to set up a Confluence knowledge base for. 2. Select the Knowledge base option from the left-hand panel. 3. Check the Link to a Confluence space option. Creating knowledge base articles 345 4. Select the linked Confluence space (it may be named something other than Confluence) from the Application dropdown. 5. Select the Confluence space where the knowledge base article will be created. If you do not have a space already, click on the Create a knowledge base space link. 6. Click on the Link button to complete the integration setup, as shown in the following screenshot: Figure 11.25 – Adding a knowledge base Note You can link one service desk to one Confluence space. After the integration is in place, when an agent views a request, the create an article option will become available. Clicking on that will allow the agent to create a new knowledge base article in the preconfigured Confluence space, as shown in the following screenshot: 346 Jira Service Management Figure 11.26 – Creating a knowledge base article From the customer’s perspective, a new search box will be available on the customer portal (for a service desk, with the knowledge base feature enabled). Customers will be able to search to see whether any information is already available concerning their problems. As shown in the following screenshot, when searching for File, the service desk returns a knowledge article from past requests. If this is what the customer is looking for, it will save valuable time for both the customer and the agent: Figure 11.27 – Searching for a knowledge base article You can further fine-tune this by selectively enabling the request types that should have a knowledge base enabled – for example, you may only want to enable Support or Inquiry request types but not Incidents. In the next section, we will look at how you can automate certain tasks for your service desk. Process automation When running a service desk, many mundane and repetitive tasks can end up wasting a lot of your team’s time. For example, after a request has been closed, if the customer subsequently adds a comment, the request needs to be reopened, so it will be placed back into the queue for agents to work on again. Normally, this would require either an agent to manually reopen the request, or you, as the Jira administrator, to configure the workflow used by your service desk project to automatically reopen the request. This can be tedious for the agents, and overwhelming for you, if there are many service desk projects that require this kind of automation. The good news is that Jira Service Management has a process automation feature that greatly reduces some of this repetitive tasks and allows each service desk owner (users with the Administer Projects permission) to set up the automation rules, as shown in the following screenshot: Figure 11.28 – Process automation rules Follow these steps to set up automation rules: 1. Browse to the project settings page of the service desk you want to set up automation rules for. 2. Select the Automation option from the left-hand panel. 3. Click on the Add rule button to create a new automation rule. 4. Select one of the pre-made automation rule templates from the dialog box, or select the Custom rule option from the list to create one from scratch. Process automation 347 348 Jira Service Management 5. Enter a name for the new automation rule. 6. Configure the automation rule and click on Save. There are several things to consider when configuring your automation rule. Firstly, each rule is made up of three parts called WHEN (trigger), IF (condition), and THEN (action), as shown in the following screenshot. The way to think about this is that your rule should read something like this – when something happens on a request, if the criterion is met, then execute the following actions. So, if we take the example of a customer adding comments to a closed request, the rule may be something like this – when a comment is added, if the request is in the Closed status, then transition the request to Re-opened: Figure 11.29 – Creating a new process automation rule Summary 349 You can configure these components of the automation rule by clicking on the UI elements representing each component. There are a few points to keep in mind when designing your rule: • You can only have one WHEN, which acts as the entry point for the rule. However, it can have multiple triggers, so each rule can be triggered by more than one action. • You can have more than one IF (that is, an ELSE IF), so you can set up multiple criteria to evaluate when the rule is triggered. • You can only have one THEN, which can have multiple actions to execute. Other options include the following: • Whether the rule should be run as the user who triggered it or a dedicated user set for the service desk project. Since not all actions can be run by the user who triggers them, especially if the user is a customer, it is safer to use the project’s default option. • Whether the rule can be triggered by another automation rule. This is very useful as it allows you to chain multiple rules together to automate your process. However, you need to be careful and make sure you do not have rules that will trigger off each other and get stuck in a loop. Summary In this chapter, you learned how to use Jira Service Management to transform Jira into a powerful service desk solution. Jira Service Management is based on many of Jira’s out-of-the-box features, such as a workflow engine and search query (JQL), and provides a brand new user interface to remove the friction caused by the old Jira interface. This makes the overall experience a lot more pleasant for customers. We looked at how you can customize the branding for your customer portal, as well as how to group request types, which can help your customers to better navigate around. We also explored using SLAs to help measure metrics for your support team. Lastly, we looked at ways you can set up automation rules to help your support process run more efficiently. In the next chapter, we will take a deeper look into how you can extend Jira’s features and capabilities using third-party apps. 12 Jira and Third Party Apps As we have seen in previous chapters, Jira is a highly customizable product that allows you to customize many of its features to better suit your needs. Of course, no product is perfect, and despite Jira’s rich set of features, there are still gaps within the product that cannot fulfill everyone’s needs. Recognizing that they cannot do this alone, Atlassian allows Jira to be extended by others, including partners, independent software developers, and customers, through Jira’s highly extensible app infrastructure. In this chapter, you will learn about the following topics: • Apps and what they are • Atlassian Marketplace • Installing and managing apps after they are installed • Using apps to extend Jira’s features and capabilities Atlassian Marketplace and third-party apps In the context of Jira, an app is a separate software package that can be installed into Jira to extend its capabilities. An app often consists of multiple modules, such as custom fields, reports, and workflow post functions. You would often hear people talk about apps, add-ons, and plugins. In the context of Jira, all three refer to the same thing, so in this book, we will use the term app. But if you see the terms plugin or add-on mentioned, we are really talking about the same thing. Most apps are registered and listed on the Atlassian Marketplace, at https://marketplace. atlassian.com. The Marketplace lets you, as the end user, browse and search for apps, read user reviews, and get documentation and contact details for the app vendor. For example, when searching for apps that can integrate with Slack, we can see the following apps on the Marketplace: 352 Jira and Third Party Apps Figure 12.1 – Atlassian Marketplace Jira apps on the Marketplace can be free or paid for. Paid apps are charged based on your Jira’s user tiers. Each paid app listed on the Marketplace will have a Pricing tab that will explain its pricing structure, as shown here: Figure 12.2 – App pricing Apps also have different levels of availability for the hosting type. Some apps will support all three options of Cloud, Data Center, and Server, while others may only support one or two. It is important to check whether the app you are interested in supports your hosting type. This is especially important for a Data Center deployment; if you install the Server version of the app, it may lead to unexpected behaviors and errors. Universal Plugin Manager 353 One useful feature of the Marketplace is that if the app supports Data Center or Server, you can download the app directly from the site. This is not something you will need to do normally; as we will see later in this chapter, Jira is natively integrated with the Marketplace by default, so you can find and install apps directly from inside Jira. But if Jira is unable to connect to the Marketplace due to network or security reasons, you can manually download the app and install it. Now that we have a brief overview of Atlassian Marketplace, let’s look at how you can use Jira to find, install, and manage apps next. Universal Plugin Manager The Universal Plugin Manager (UPM) is the main tool you will use to find, install, and manage apps for your Jira instance. The UPM is integrated with the Atlassian Marketplace by default, so if your Jira instance has an outbound internet connection, you will be able to search and install apps directly from the UPM. There are two main interfaces for the UPM: • Find apps – This interface allows you to search for third-party apps from Atlassian Marketplace directly and install them in your Jira. • Manage apps – This interface allows you to manage the apps that are installed in your Jira. You can manage, disable, update, and uninstall the apps. We will look at each of the interfaces and how you can use them to install, update, and manage third- party apps in Jira. Searching and installing apps from the Atlassian Marketplace If your Jira instance has an outbound internet connection and has an Atlassian Marketplace connection enabled, you can search and install apps from the UPM directly. This is the easiest way to install apps into Jira, as UPM will make sure to download the latest compatible version of the app. To install an app from the Atlassian Marketplace using the UPM, follow these steps: 1. Browse to the Jira administration console. 2. Select the Manage apps tab and then the Find new apps option. 3. Search for the app you are looking for in the Search the Marketplace textbox. You can also use the various controls to browse and filter your search results. 4. Click on the Install button to install the app if it is free, or the Free trial button if the app is a paid app, as shown here: 354 Jira and Third Party Apps Figure 12.3 – Finding apps in the UPM If the app is free, clicking on the Install button will let Jira download and install the app for you. If the app is a paid app, Jira will install the app and walk you through the process of generating a trial license. Once installed, the app will be ready to go. Some sophisticated apps may require further configuration before you can use them; in these cases, you can use the Manage apps interface. Installing apps manually If for some reason, Jira is unable to connect to the Atlassian Marketplace, or if the app you want to install is not on the Marketplace, you can manually install the app from the Manage apps interface. To install an app manually, follow these steps: 1. Browse to the Jira administration console. 2. Select the Manage apps tab and then the Manage apps option. 3. Click on the Upload app option: Figure 12.4 – Manually installing an app 4. Select the app you want to install from the dialog box, and click Upload: Figure 12.5 – Upload app Tip You can upload and install the app by either selecting the app’s file directly or via a URL to the app archive file. Universal Plugin Manager 355 356 Jira and Third Party Apps When you are installing apps manually this way, you need to make sure that you are installing a version of the app that is compatible with the version of your Jira and is of the right hosting type. Each app on the Atlassian Marketplace has a version list that shows the app’s compatibility, so make sure you download the correct app version. If you install an incompatible app, in most cases, it will be automatically disabled and you can simply uninstall it, but sometimes it could lead to more serious problems that could bring your Jira instance down. Managing installed apps All installed apps are listed in the Manage apps interface of the UPM. You can access the Manage apps interface by selecting the Manage apps option. The Manage apps interface will list all user-installed apps by default, as shown here: Figure 12.6 – UPM Manage apps By default, only user-installed apps are displayed. This is because many of Jira’s core features are also implemented as apps, so this will help to keep the list short. You can toggle the type of apps to display all apps in the system. You can click on an app in the list to expand and view its details. This will show you a lot of useful information about the installed app and allow you to manage it: • Buy now – If the app is a paid app and you have not yet purchased a license, you can click on the Buy now button to purchase it. • Configure – If the app requires additional configuration after installation, it will usually have a Configure button. Clicking on that will take you to the app’s main configuration page. • Uninstall – This will uninstall the app from your Jira instance. Note that for some apps, uninstalling may also delete any data that is related to the app. When in doubt, you should disable the app first. • Disable/Enable – This will disable or enable the app. Once disabled, the app is still installed in Jira, but its features will not be available. • Update – If there is a newer version of the app available on the Marketplace, you can click on the Update button to automatically update the app. However, before you update an app, you should always check whether the newer version is compatible with your environment. Sometimes, new versions may have new requirements on Java, databases, and other system components. • Version – The version of the app you have installed. This is a very important piece of information, and vendors will always ask for this when troubleshooting problems. • Documentation – This link will take you to the app’s documentation on the vendor’s website. • Support and issues – This link will take you to the support portal of the vendor for you to request support. It can also take you to the vendor’s website with details on how to request support. • Enabled modules – This will list all the modules an app contains when expanded. Usually, all modules are enabled by default after installation. You can selectively disable certain modules within an app. You may want to do this to limit certain functions from your users, or as per instructions given by the vendor’s support staff as part of the troubleshooting process. Note that this is for advanced users, as if you disable the wrong modules, it could lead to the app not functioning correctly or even the loss of data. Universal Plugin Manager 357 Figure 12.7 – Managing apps 358 Jira and Third Party Apps Configuring the UPM Other than installing and uninstalling apps, the UPM has several other useful features that can help you manage and troubleshoot problems. At the bottom of the UPM, there are four options: Figure 12.8 – Configuring the UPM We will look at each of the options closely in the next sections, starting with the audit log. Audit log Jira keeps track of when an app is installed, uninstalled, or updated. This is a very useful tool if you need to run periodic audits on changes that happen in a system. Oftentimes, apps are installed and after a while, people forget who installed the app or whether the app is still being used. This is especially a problem if the app is an expensive paid app. By reviewing the audit log, you can find out who initially installed the app or last updated it. As shown below, we can see the Tempo Timesheets app was installed on September 20, 2022. Figure 12.9 – Audit log Note Note that the audit log will be purged periodically; the default is after 90 days. Jira update check As you start to install third-party apps into Jira, upgrading Jira to newer versions, especially major versions, would start to become more complex, as you would need to make sure the apps you are using are compatible with the version of Jira you are upgrading to. This can sometimes be a cumbersome task, especially if you have a lot of apps installed. The Jira update check tool from the UPM helps to make this easier for you by automatically checking all the apps you have and generating a compatibility report, as shown here: Figure 12.10 – Jira update check Simply select the Jira version you are targeting, and click on the Check button. As shown in the preceding report, we have three apps that are listed as compatible and one that is not, but there is an updated version available that is compatible. Note that this tool only works for apps that are on the Atlassian Marketplace; apps that are not on the Marketplace cannot be checked with this tool. Universal Plugin Manager 359 360 Jira and Third Party Apps Settings The Settings option lets you control how the UPM will work. For example, if you want the UPM to be able to connect to the Atlassian Marketplace to download and install apps directly. For some organizations, due to security reasons, you may not want to allow this, so you can disable this option. Another common option is to allow end users to request apps they want to be installed. Jira will then send an email to Jira administrators of the request, and this helps to reduce friction between users and administrators. The following screenshot shows the settings you can change for the UPM: Figure 12.11 – UPM settings Enter safe mode The last option is to put Jira into safe mode. When Jira is placed into safe mode, all user-installed apps are disabled. This is a very useful tool when troubleshooting problems. Often when something is not working correctly in Jira, it can be challenging to pinpoint exactly what the root cause is, especially if you have many apps. In these cases, the method of elimination would be the best option; by putting Jira into safe mode and re-enabling apps one at a time, you can narrow down the cause of the problem, if it is caused by an app. Note that when you put Jira into safe mode, all the third-party apps will be disabled, which can sometimes be detrimental to your end users. So, make sure you communicate this before enabling safe mode. Extending Jira with apps Now that we have seen how to find and install third-party apps, we will look at some of the common use cases where you can extend Jira’s core features with apps. In this section, we will make use of some of the popular apps available on the Atlassian Marketplace to illustrate how you can use apps to extend Jira. Extending custom fields with apps In Chapter 5, Field Management, we introduced custom fields and looked at the out-of-the-box field types Jira provides. With third-party apps, we can extend the list of options even further. So far, most fields we have seen so far are primarily used to capture and display data, but custom fields can do far more than that. In this section, we will be looking at the Electronic Signature for Jira app. As the name suggests, the Electronic Signature for Jira app allows users to capture electronic signatures when changes are made to issues, usually as part of a workflow transition. This is especially useful during approval processes, such as for CFR 21 Part 11 compliance, where signatures are required and need to be recorded for audit purposes. The app provides this functionality by adding a new custom field called Electronic Signature. You can add this field to your Jira once the app is installed. Figure 12.12 – Add electronic signature custom field Extending Jira with apps 361 362 Jira and Third Party Apps After you have added the field to Jira, make sure you place it onto screens where electronic signatures need to be verified and captured. For example, the screen used for the Approved workflow transition. With the field on the screen, when you transition the issue, you will see the field asking you to enter your Jira credentials. If the correct credentials are entered, the workflow transition can complete, and the signature will be recorded for the issue. Figure 12.13 – Validating the electronic signature As we can see, while the primary purpose of any field is to capture and store data, apps can contain useful custom fields that have very different functions. Extending workflow with apps In Chapter 7, Workflow and Business Process, we looked at using Jira workflows and their components for your projects. Jira comes with many useful components such as conditions, validators, and post functions, but for you to unleash the full power of Jira’s workflow, you would need to use some third-party apps. In this section, we will look at some of the popular apps and the useful workflow components they provide. The app we will look at is the JSU Automation Suite for Jira Workflows (JSU). This app comes with several useful workflow components. A very common Jira use case is to make a field required only during certain workflow transitions. For example, when a user is creating an issue, the user may not know the due date for the issue so leaves it blank. When the issue is picked up by someone and transitions to In Progress, a due date will be needed, so we will want to make sure the user enters a due date value before the issue can be transitioned. The JSU comes with a Fields Required (JSU) validator that can check to make sure a value is provided for selected fields before the workflow transition can complete. As shown next, we have added the Fields Required (JSU) validator and selected the Description and Due Date fields to be required: Figure 12.14 – Add validator So now, if an issue is transitioned to the In Progress status without providing a value for Description or Due Date, error messages will be displayed: Figure 12.15 – Field required validator Extending Jira with apps 363 364 Jira and Third Party Apps Obviously, for this to work, you need to make sure you apply a screen to the workflow transition and put all the required fields onto the screen. Another useful feature JSU provides is the ability to automatically set a value to any fields in Jira as part of a workflow transition. Out of the box, Jira comes with a post function that allows you to set a value for some system fields such as Assignee and Resolution. This lets you automate some tasks, such as automatically assigning the issue to yourself when you move it to In Progress or clearing the issue’s resolution when it is reopened. But often, users would want to set a value to other fields, especially custom fields. JSU provides such a post function that not only allows you to set a value for any fields but also comments, and even updates the fields for other issues. As an example, we have added the Update Any Issue Field (JSU) post function to the workflow transition. We configured the post function to update the Assignee field for all subtasks under the issue to the current user (specified as %%CURRENT_USER%%). So now, if an issue is transitioned to the In Progress status, all its subtasks will have their assignee automatically assigned to the user performing the transition. Figure 12.16 – Add post function Third-party apps such as JSU come with many useful workflow conditions, validators, and post functions you can use to enrich what you can do with workflows. Customizing Jira with scripts The apps we have looked at so far are all prepackaged, purpose-built solutions that are designed to provide specific functions. These are great as they provide solutions for common problems people would have or features that everyone needs. However, sometimes you have requirements that are not covered by any apps that are available on the Atlassian Marketplace. Now you can create a custom app for that, but often you simply need a custom field that captures or displays data in a specific way, or a workflow validator that has some specialized business logic. In these cases, you can use an app called ScriptRunner. ScriptRunner is an app that brings scripting capabilities into Jira. If you know how to write Groovy scripts, ScriptRunner will let you create custom fields, workflow components such as validators, and post functions defined by your own Groovy scripts. This way, you can implement these components with your own business logic, without having to go through the process of creating a full-blown app. In this section, we will take a look at the ScriptRunner app and how you can use it to create your own custom field. Once you have installed the ScriptRunner app, there will be a new ScriptRunner tab when you go to the Jira administration console. As we can see, ScriptRunner comes with many different options for you to create scripts, including some built-in scripts. Since we are focusing on creating our own custom field in this section, we will be looking at Fields. Figure 12.17 – ScriptRunner To create a custom script field, select the Fields option, and then the Custom Script Field option, as shown here: Figure 12.18 – Custom Script Field Customizing Jira with scripts 365 366 Jira and Third Party Apps Now that we have chosen to create a scripted field, we need to provide some basic details for our field as well as the script itself. In our example, we will be creating a simple field that will display the number of comments an issue has: 1. Enter a name for our field, such as Number of comments. 2. Select a template for our field. This will determine what our field will look like. For our example, we will choose the Number Field template. 3. Enter the following script that will be run when the field is displayed. With ScriptRunner, you can load your scripts either as inline code or from a file. Inline code is easy to work with but saving your code to a file makes things easier to maintain, as you can keep your code files in a code repository for better change tracking. In our example, we will use the inline option: import com.atlassian.jira.component.ComponentAccessor def commentManager = ComponentAccessor. getCommentManager() def numberOfComments = commentManager.getComments(issue). size() return numberOfComments ? numberOfComments as Double : null 4. Enter an issue key into the Preview Issue Key textbox and click on the Preview button. This will test our script against the issue. 5. Click on the Add button to create our custom field. Customizing Jira with scripts 367 Figure 12.19 – Adding a custom script field 368 Jira and Third Party Apps Once our custom script field is created, we need to make sure the field is applied to the correct context and added to the necessary fields. Once we have done that, you should see the field displaying the number of comments an issue has: Figure 12.20 – Custom script field result Since the script is run every time the field is rendered, its values will be automatically updated. If you want the value in the field to be searchable, make sure to assign a search template to it. Since our field displays a number, we can use either the number searcher or the number range searcher. Better time tracking and reporting In Chapter 4, Working with Issues, we briefly looked at how users can track their time spent against the issue they are working on. It is a very useful feature, and many organizations use this to keep track of their project’s progress. However, Jira’s out-of-the-box time tracking is rather rudimentary, and it is not very easy to get a report on the hours logged. Once again, apps to the rescue! When it comes to time tracking and reporting, there are several options available, depending on your needs. If all you want is a better tool to get visibility into the hours logged by your users and create time tracking reports, then the Worklogs - Time Tracking and Reports app is perfect for you. Once installed, there will be a new Worklogs option at the top. Clicking that option will take you to the Worklogs report view provided by the app: Better time tracking and reporting 369 Figure 12.21 – Time tracking report From here, you can select the project, users/groups, date range, and many other options to generate a report on the time tracking data entered by your users. As shown previously, for the month of September, two users have logged time on two different projects. You can change the table report view to pie and bar charts, as well as export the report to an Excel spreadsheet. This is a very useful tool that complements the out-of-the-box time tracking feature. Now if you want something more powerful and robust, you might want to look into the Tempo Timesheets - Jira Time Tracking (Tempo) app. The Tempo app takes the basic time tracking feature in Jira and takes it to a whole new level. After you have installed Tempo, there will be a new Tempo option at the top. Clicking that option will list Tempo’s different features. Tempo comes with all the features you would want for tracking time and generating reports on the data. For example, each user can view their own logged time both in a Calendar and Timesheet view, as shown next. This is a great tool for users to keep track of their time logging as well as generate a report at the end of each month for billing purposes: Figure 12.22 – Tempo 370 Jira and Third Party Apps Tempo also allows you to create saved reports on the time tracking data that can be reused at a later time, similar to saved filters. For example, you can create a report for each of your projects, and send that to your clients as part of your regular project progress update. Apart from regular time tracking and reporting, Tempo also has advanced features such as allowing users to submit their timesheets for approval, organizing users into teams for better resource management and planning, tracking across multiple teams and projects by setting up accounts, and more. Selecting an app and its vendor Now that we have seen what third-party apps are and how they can be useful to you, you might want to go to the Atlassian Marketplace and find as many useful apps as you can and install them into your own Jira instance. This is actually very dangerous and is often how people find themselves in difficult situations, such as during Jira upgrades. As useful as third-party apps are, care must be taken when choosing and installing them. When choosing to install an app, there are several important factors to consider and you must do your due diligence: • Is the app well maintained and supported? It does not matter whether an app is really good, as if it is not maintained and supported, you will not be able to get any help when you run into problems or need to upgrade Jira later. Take a look at the reviews from other users, see whether the app has a good track record of supporting multiple versions of Jira, and see whether the vendor has a support channel. You can find out all this information on the app’s page on the Atlassian Marketplace. • Does the app have a cloud migration pathway? If migrating to Atlassian Cloud is something you would consider in the future, it is important to see whether the app has both an equivalent cloud version, as well as a migration pathway available. This will make your life a lot easier when you do decide to go to the cloud. • Does the app conflict with any other apps you may have already installed? Sometimes, apps from different vendors will conflict with each other, and you may not find out about this until it is installed and running. In some cases, the app vendors may be aware of these conflicts and would have that as part of their documentation, but this is not always the case. For this reason, it is important that you test out the new app in a staging environment before installing it in production. As we can see, care must be taken when choosing an app for your Jira, especially if the app will serve an important function for your organization. It is common that an app will become so important that your users cannot live without it. So it is just as important that you choose the right app vendor as the app itself. A good vendor will be there ready to support you when you run into problems and bugs, need to upgrade to a new version of Jira, and if you choose to migrate to the cloud. Summary 371 It is often a good idea to keep an inventory of the apps you have installed and how they are being used. Keep that up to date and have regular reviews, as you do not want to keep apps that you no longer need, especially if the app is a paid app. If you have multiple Jira administrators, make sure to let each know when an app is added or removed, so if there is a problem, nobody is caught off guard. Summary In this chapter, we looked at third-party apps, what they are, and what they can do. We looked at the Atlassian Marketplace, from where you can search for apps that might be useful to you. We also learned how to use the Universal Plugin Manager to install and manage apps, and some of its additional features to help troubleshoot problems in Jira, especially if the problem is related to apps. We also looked at some popular apps and how to use them to extend Jira’s capabilities, such as adding new custom field types and workflow post functions, so you can do more with Jira. Lastly, we looked at some important factors to consider when choosing what app to install. Jira is a great tool, and third- party apps help to make this tool even better, but you must make sure you choose the right app for you to ensure your long-term success. A Active Directory (AD) 255 Administer Projects 37 agents 321, 328 adding, to service desk 328, 329 agile boards column constraints, adding 7577 columns, configuring 74, 75 configuring 74 creating, for project 80 multiple projects, including 81, 82 quick filters, defining 78, 79 swimlanes, setting up 77 Altassian Marketplace 351 Jira apps 352, 353 reference link 351 third-party apps 351 Amazon Web Services (AWS) 8 application programming interface (API) 203 custom fields, extending with 361, 362 Jira, extending with 361 selecting 370 workflow, extending with 362-364 Index Assigned to me queue 342 Atlassian Jira download link 13 B backlog enabling, for Kanban 72, 73 grooming 79, 80 basic search 288 constructing 289 business processes mapping 174 Business project 37 C CAPTCHA service 247 cluster 5 node, adding to 31, 32 clustering 29 enabling 30 preparing for 29, 30 collaborator 328 adding, to service desk 331 column constraints adding 75-77 apps 374 Index columns configuring 74, 75 Command Prompt 10 comma-separated value (CSV) data, importing into Jira through 47-51 common transition 187 Concurrent Versions System (CVS) 263 conditions 179 adding, to transitions 188, 189 context 119 customer portal 321 branding 326, 327 customers 321, 328 custom event 220 adding 224, 225 firing 225, 226 custom fields 116 adding 121-124 advanced fields 117, 118 configuring 126 context 119 contexts, adding 127, 128 default values, setting 129, 130 deleting 126 editing 124, 125 extending, with apps 361, 362 managing 120 optimizing 130, 131 select options, configuring 128, 129 standard fields 117 managing 305, 306 ownership, changing 308 Default Permission Scheme 267 delegated LDAP 256 delegated workflow management 201, 202 development-operations (DevOps) flow 187 E Electronic Signatures 118 email notifications batching 232 emails 209, 210 advanced mail handler 239 incoming 234 incoming mail server, adding 234, 235 mail handler 235 mail handler, adding 238, 239 sending, manually 218, 219 Enhancer Plugin for Jira 118 Enterprise Email Handler for Jira (JEMH) reference link 239 events 220, 221 custom events 220 system events 220 types 220 existing workflow updating 193-195 Extensible Markup Language (XML) 263 F field configuration 131 adding 132 behaviors 131 descriptions 134 managing 132, 133 renderers 135, 136 D dashboard 305 configuring 307 creating 306 gadget, placing on 309-311 layout, setting 308 Index 375 required fields 134 visibility 135 field configuration scheme 137 associating, with project 140 adding 137, 138 associating, with project 139 configuring 138, 139 managing 137 field helper tool using 164, 165 fields setting up, for request type 333-335 field searchers 119 Fields Required (JSU) validator 363 files attaching 104 filter 81, 296 creating 296 deleting 301 managing 297 ownership, changing 301, 302 sharing 298, 299 subscribing to 299, 300 G gadget 308, 309 deleting 313 editing 312 placing, on dashboard 309-311 global permissions 262 configuring 264 granting 264, 265 Jira System Administrators, versus Jira Administrators 263 revoking 265 group adding 249 deleting 251 managing 248, 249 membership, editing 249, 250 request types, organizing into 332 H human resources (HR) project 53, 165, 240, 313 components, creating 54 creating 53 custom field, setting up 141 dashboards, setting up 314 field configuration scheme, setting up 142, 143 field configuration, setting up 142 filters, setting up 313 gadgets, setting up 314, 315 group, setting up 281 implementing 206-208, 283 issue, creating 55, 56 issue types, adding 112 issue type scheme, updating 112 issue type screen schemes, setting 167 mail servers, setting up 240 notification scheme, setting up 241 notifications, setting up 241 permission, setting up 282 permission scheme, setting up 281 requisites 280 scheme, associating for activating 242 screen schemes, setting 167 screens, settings 166 summarizing 168 termination issue, creating 143, 144 user group association, setting up 281 workflow post functions, updating 240, 241 workflows, setting up 204-206 376 Index Hypertext Transfer Protocol issue events 220 issue navigator sections 286 issue priorities 109 scheme, creating 110, 111 issue security 270 default security level, setting 273 scheme 271 scheme, applying 273 scheme, configuring 271-273 issue status 177 issue summary 86 issue types 86, 331 adding, to issue type schemes 108 attaching 105, 106 creating 106 deleting 106 issue type schemes 108 issue types, adding to 108, 109 issue type screen scheme 146 associating, with project 162, 163 association, deleting 161 association, editing 160 copying 158, 159, 161 editing/deleting 161 J Java installing 10-12 Java Development Kit (JDK) 8 Java Naming and Directory Interface (JNDI) used, for configuring SMTP server 214 Java Runtime Environment (JRE) 8 Jira 145, 209, 210 cluster deployment 7 configuring 12, 13, 19-23 I Secure (HTTPS) 276 configuring 27, 28 identity provider (IdP) 276 incident 331 incoming mail server adding 234, 235 information technology (IT) 258 inline editing 92 installation package options 10 archive package 10 executable installer 10 Java, installing 10-12 issue 35, 85 archiving 52, 53 assigning, to users 90, 91 cloning 100, 101 comments, creating 103, 104 creating 89, 90 deleting 95, 96 editing 91, 92 key aspects 86 linking 98 linking, with other issues 98 linking, with remote contents 99, 100 moving, between projects 92-94 notifications, receiving 96, 97 sharing, with other users 95 summary 86-88 tracking time, displaying 101, 102 vote, casting on 97, 98 working with 88 work, logging 102 Index 377 context path, modifying 26, 27 custom fields, extending with apps 361, 362 customizing, with scripts 364-366, 368 data, importing 47 data, importing through CSV 47-51 extending, with apps 361 hardware requirements 7 installation package options 10 installing 12-19 memory, increasing 25, 26 obtaining 13-19 port number, modifying 26, 27 project, running with Kanban 69 project, running with Scrum 60 screens, using in 146, 147 standalone deployment 7 starting 24 stopping 24 system requirements 7 vendor 370 workflow, extending with apps 362-364 Jira administrators 37 versus Jira System Administrators 263 Jira Data Center 5, 6 Jira Misc Workflow Extensions (JMWE) reference link 203 Jira permissions 37, 261 application access 261, 262 global permissions 262 levels 37 Jira platform 4 functionalities 4 Jira Query Language (JQL) components 290 field element 291 operator element 291 queries 77 using, for performing advanced searches 290-292 value element 291 queries 77 jira-servicedesk-users group 329 Jira Service Management 4, 317-319 agents 321 customer portal 321 customer portal, branding 326, 327 customers 321 factors, for selecting installation type 320 installing 319, 320 knowledge base articles, creating 343-347 process automation 347, 348, 349 queues 322 requests 322 service desk, creating 323-325 service desks 322 JIRA_SHARED_HOME creating 30 Jira, software requirements 8 databases 9, 10 Java platforms 8, 9 operating systems 8 reference link 8 Jira System Administrators versus Jira Administrators 263 Jira Workflow Toolbox (JWT) 203 Jira Work Management 4 JIT provisioning enabling 278, 279 JSU Automation Suite, for Jira Workflows 362 reference link 203 just-in-time (JIT) 243 378 Index K Kanban 60 backlog, enabling 72, 73 overview 59 used, for running project 69 Kanban board 71 using 71, 72 versus Scrum board 69 Kanban project creating 70 Kanplan 72 L Lightweight Directory Access Protocol (LDAP) 243 listeners 220 load balancer node, adding to 31 M mail handler 235, 238 comment, adding before specified marker 237 comment, adding from non-quoted email body 237 mail servers 210 in Jira, types 211 outgoing mail, disabling 214 setting up 240 SMTP, enabling over SSL 215 test email, sending 215, 216 types 210 working, with outgoing mail 211, 212 mail templates 221 working with 221-224 N node 6 adding, to cluster 31, 32 adding, to load balancer 31 Notification helper 233 notifications 226, 228 receiving, on issue 96, 97 setting up 241 troubleshooting 232-234 types 227 notification scheme 228, 229 adding 229 assigning 231, 232 managing 229-231 setting up 241 O organization 328 outgoing mail disabling 214 working with 211 working with 211, 212 outgoing SMTP server configuring 212-214 configuring, with JNDI 214 comment, adding to existing entire email body 237 comment, adding to existing issue 235 new issue, creating from each email message 237 new issue, creating to existing issue 235 separator, adding in email body 237 mail queue 216 flushing 218 viewing 217 Index 379 P password policy 275, 276 permission troubleshooting 273, 275 Permission Helper tool 273 working 274 permission scheme 266, 267 applying 270 configuring 267-270 performing 266 post functions 181 adding, to transitions 191-193 post-installation configurations, Jira context path, modifying 26, 27 HTTPS, configuring 27, 28 memory, increasing 25, 26 port number, modifying 26, 27 project archiving 52, 53 creating 38-40 types 35, 36 user interfaces 40 project permissions 265 operations 265 permission scheme 266 permission scheme, applying 270 permission scheme, configuring 267 permission schemes 267 Project Role Browser page 251 accessing 252 Project settings interface 42, 43 Components tab 44, 45 details tab 43 tabs 46, 47 Versions tab 45 project, user interfaces Issues tab 41 project browser 41 project browser interface 40 Project settings interface 42, 43 Summary tab 41 Versions and Components tabs 42 pull request (PR) 187 Q queues 322 creating 342, 343 requests, managing with 342 quick filters defining 78, 79 Quick search 287, 288 R regular expressions (regexes) 203 renderers Autocomplete renderer 136 default text renderer 135 Select list renderer 135 Wiki-style renderer 135 report 302 generating 302-305 Report System Outage 331 requests 322 managing with queues 342 request type 323, 331 fields setting up for 333-335 organizing into groups 332 setting up 332 workflow setting up for 335, 336 380 Index role default members, managing 253, 254 managing 248, 251 project role, adding 252 project role members, assigning 254, 255 rolling upgrade steps 32 S scalability 5 screen 140, 141, 146 adding 148, 149 and fields, troubleshooting 164, 165 copying 154 deleting 153 editing 153 field, adding to 149, 150 field, deleting from 150 tab, adding to 152 tab, editing/deleting 153 working with 147, 148 screen management delegating 163 screen schemes 146 adding 155 association, editing/deleting 157 copying 158 deleting 158 editing 157 issue types, associating 159, 160 screens, associating to issue operations 156 working with 154, 155 screen tabs using 151 ScriptRunner for Jira 118, 364, reference link 203 scripts Jira, customizing with 364-368 Scrum 60 backlog, working with 62 overview 59 sprint, creating 64-66 sprint, running 66-68 used, for running project in Jira 60 work, estimating 62-64 work, prioritizing 62-64 Scrumban 75 Scrum board versus Kanban board 69 Scrum interface sections 62 Scrum project creating 60, 61 search interface and options 286 basic search 288 issue navigator 286, 287 JQL, using 290 Quick search 287, 288 search results column layout, customizing 293, 294 exploring 294 filters 295 result views, switching 293 sharing 295 working with 293 search template 119 Security Assertion Markup Language (SAML) 5, 243 used, for enabling single sign-on (SSO) 276, 277 service desk 322, 323 agent, adding to 328, 329 collaborator, adding to 331 creating 323-325 service desk customers managing 329-331 Service Desk Team project role 328-331 service desk user types agent 328 collaborator 328 customer 328 organization 328 custom calendars, setting up 340-342 example 337, 338 goal criteria 340 goals 339, 340 setting up 337 Service-Level Agreement (SLA) 4, 36 service provider (SP) 277 Simple Mail Transfer Protocol (SMTP) enabling, over SSL certificate 215 simple search 288 Simplified Workflow 75 single sign-on (SSO) 243 enabling, with SAML 278 enabling, with Security Assertion Markup Language (SAML) 276-278 sprint-planning meeting 60 sprints 60 SSL certificate SMTP, enabling over 215 standard issue link feature 98 status 86 step 178 story points 63 system changes auditing 279, 280 system events 220 system fields 115, 116 T Tempo app 369, 370 test email sending 215, 216 text mode 181 third-party apps on Altassian Marketplace 351-353 selecting 370 time tracking report 368-370 Toolkit Plugin for Jira 118 tracking time displaying 101, 102 original estimates, specifying 102 work, logging 102 transitions components 178 conditions, adding to 188, 189 post functions, adding to 191-193 triggers, adding to 187, 188 validators, adding to 189-191 triggers 179 adding, to transitions 187, 188 two-factor authentication (2FA) 276 U Universal Plugin Manager (UPM) 353 apps, installing from Atlassian Marketplace 353, 354 apps, installing manually 354, 356 Structured Query Language (SQL) 290 sub-tasks using 107 Suite Utilities for Jira 202 swimlanes 67, 77 setting up 77 Index 381 382 Index apps, searching from Atlassian Marketplace 353, 354 audit log 358 configuring 358 enter safe mode option 360 find apps interface 353 installed apps, managing 356, 357 Jira update check 359 manage apps interface 353 Settings option 360 user adding 245 CAPTCHA, enabling 247 issues, assigning to 90, 91 managing 244, 245 public signup, enabling 246 user browser accessing 244 user directories 255-257 connecting, to LDAP 257-261 parameters 258, 259 user directories, types AD/LDAP 256 Atlassian Crowd 257 Atlassian Jira 257 Jira internal directory 256 LDAP authentication 256 user interface (UI) 178 V validators 180 adding to transitions 189 vote casting, on issue 97, 98 W What You See Is What You Get (WYSIWYG) 219 workflow designer using 181-183 Workflow Enhancer, for Jira reference link 203 workflow post functions updating 240, 241 workflows 174-176 applying 206 authoring 183-185, 187 conditions, adding to transitions 189 extending, with apps 362-364 extending, with workflow add-ons 202 issue status 177 managing 176, 177 post functions, adding to transitions 191-193 setting up 204-206 setting up, for request type 335, 336 transitions 178 triggers, adding to transitions 187, 188 validators, adding to transitions 189-191 workflow schemes 195 applying, to projects 199, 201 association, deleting 199 association, editing 199 configuring 196, 197 creating 196 issue type, assigning to 197, 198 workflow security 275 workflows, transitions conditions 179 post functions 181 Index 383 triggers 179 validators 180 Z zero-downtime upgrade 32, 33 Packt.com Subscribe to our online digital library for full access to over 7,000 books and videos, as well as industry leading tools to help you plan your personal development and advance your career. For more information, please visit our website. Why subscribe? • Spend less time learning and more time coding with practical eBooks and Videos from over 4,000 industry professionals • Improve your learning with Skill Plans built especially for you • Get a free eBook or video every month • Fully searchable for easy access to vital information • Copy and paste, print, and bookmark content Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at packt.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at customercare@packtpub. com for more details. At www.packt.com, you can also read a collection of free technical articles, sign up for a range of free newsletters, and receive exclusive discounts and offers on Packt books and eBooks. Other Books You May Enjoy If you enjoyed this book, you may be interested in these other books by Packt: Jira Work Management for Business Teams John Funk ISBN: 978-1-80323-200-3 • Understand how JWM can help your company to increase productivity • Discover how to use templates to create projects quickly and with ease • Leverage JWM’s newest features, including an in-line editable list, a built-in calendar, a roadmap- style timeline, and an updated board • Explore custom fields and see the impact of your project screen arrangement • Get to grips with simple administration and how schemes can be used to ease maintenance • Find out how Atlassian Marketplace apps can extend your Jira product • Discover how to use automation to complete routine and repetitive tasks Other Books You May Enjoy 387 Automate Everyday Tasks in Jira Gareth Cantrell ISBN: 978-1-80056-286-8 • Understand the basic concepts of automation such as triggers, conditions, and actions • Find out how to use if–then scenarios and conditions to automate your processes with practical examples • Use smart values to achieve complex and more powerful automation • Implement use cases in a practical way, including automation with Slack, Microsoft Teams, GitHub, and Bitbucket • Discover best practices for writing and maintaining automation rules • Explore techniques for debugging rules and solving common issues 388 Other Books You May Enjoy Scaling Agile with Jira Align Dean MacNeil, Aslam Cader ISBN: 978-1-80020-321-1 • Understand Jira Align’s key factors for success • Find out how you can connect people, work, time, and outcomes with Jira Align • Navigate and collaborate in Jira Align • Scale team agility to the portfolio and enterprise • Delve into planning and execution, including roadmaps and predictability metrics • Implement lean portfolio management and OKRs • Get to grips with handling bimodal and hybrid delivery • Enable advanced data security and analytics in Jira Align 389 Packt is searching for authors like you If you’re interested in becoming an author for Packt, please visit authors.packtpub.com and apply today. We have worked with thousands of developers and tech professionals, just like you, to help them share their insight with the global tech community. You can make a general application, apply for a specific hot topic that we are recruiting an author for, or submit your own idea. Share Your Thoughts Now you’ve finished Jira 8 Essentials, we’d love to hear your thoughts! If you purchased the book from Amazon, please click here to go straight to the Amazon review page for this book and share your feedback or leave a review on the site that you purchased it from. Your review is important to us and the tech community and will help us make sure we’re delivering excellent quality content. 390 Download a free PDF copy of this book Thanks for purchasing this book! Do you like to read on the go but are unable to carry your print books everywhere? Is your eBook purchase not compatible with the device of your choice? Don’t worry, now with every Packt book you get a DRM-free PDF version of that book at no cost. Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical books directly into your application. The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free content in your inbox daily Follow these simple steps to get the benefits: 1. Scan the QR code or visit the link below https://packt.link/free-ebook/978-1-80323-265-2 2. Submit your proof of purchase 3. That’s it! We’ll send your free PDF and other benefits to your email directly