Atlassian JIRA is a proprietary issue tracking system. It is used to track bugs, resolve issues, and manage project functions. There are many such tools available in the market, but the best thing about JIRA is that it can be easily configured and it offers a wide range of customizations. Out of the box, JIRA offers defect/bug tracking functionalities, but it can also be customized to act like a helpdesk system, a simple test management suite, or a project management system with end-to-end traceability.
This chapter offers a brief introduction to JIRA and the new features of JIRA 7, mainly the three variants JIRA Core, JIRA Software, and JIRA Service Desk. Emphasis is given to planning, installing, and setting up JIRA. After reading this chapter, you should understand how to plan your JIRA installation and ensure the longevity of its installation so that it can accommodate more users and data in the future. We will begin with a questionnaire that needs to be answered before you can deploy a JIRA instance in your company. You will learn about the system and hardware requirements to run JIRA for an enterprise. The installation procedure for Windows and Linux operating systems is discussed briefly and the setup wizard is explained in detail in this chapter.
Topics covered in this chapter include:
What is new in JIRA 7?
Planning your JIRA installation
Setting up the MySQL database
The JIRA setup wizard
JIRA directory structure, startup/shutdown scripts, and log files
Planning your upgrade
Updating JIRA add-ons
Applications, uses, and examples
JIRA core concepts
The much awaited JIRA 7 was released in October 2015 and it is now offered in three different application variants:
JIRA Service Desk
Let us discuss each one of them separately.
This comprises of the base application of JIRA that you might be familiar with, of course with some new features. JIRA Core is a simplified version of JIRA features that we have been using up until the 6.x versions.
This comprises of all the features of JIRA Core and JIRA Agile. From JIRA 7 onwards, JIRA Agile will no longer be offered as an add-on. You will not be able to install JIRA Agile from the marketplace.
This comprises of all the features of JIRA Core and JIRA Service Desk. Just like JIRA Software, JIRA Service Desk will no longer be offered as an add-on and you cannot install it from the marketplace.
This split of applications was done by Atlassian, keeping in mind the usage of JIRA in various organizations across the globe, and it makes it very simple for the companies to choose the right application suitable for their needs. However, it doesn't mean that all three applications (JIRA Core, JIRA Agile, and JIRA Service Desk) can't be used on the same instance. You can certainly buy JIRA Software and later install the JIRA Service Desk application on it.
Apart from this split, JIRA 7 brings new features such as Release Hub, with real-time status of the versions, an improved sidebar where you can add your own shortcuts, better reporting, and visibility of development tools. We will discuss and highlight these improvements in the relevant chapters in this book.
In this book, we will install JIRA Software that comes in-built with JIRA Agile, and later we will install JIRA Service Desk on top of it.
There are certain points to be kept in mind before you install JIRA in the production phase and deploy it. The points that are discussed here should ideally be a part of your JIRA questionnaire, which you will prepare and fill in after discussion with the product owners and project managers. This will not only help you to plan your installation for now, but it will also give you a good idea about the future usage of the tool.
From the very beginning, start preparing the documents to store all the following information:
Number of users: This is the most important thing that the JIRA administrator should worry about. If you are using a limited user license in JIRA, then you should know the number of users who are using JIRA currently and who will be using it a few months down the line. In enterprise systems, there is no limit defined in the license on the number of active users accessing the system, but it's important to worry about various aspects that are discussed here:
Are users part of a single team or several teams? It's also possible to give limited access of your JIRA instance to clients and third-party vendors.
If users are part of several teams working with different groups, then is there a need to limit the visibility of projects within these groups?
Number of projects: The JIRA license will not put any limit on the number of projects. You can create any number of projects irrespective of whether you use 10 users' licenses or 100 users' licenses. The more the number of projects means a lot of issues will be stored in the database and a lot of schemes will have to be managed by administrators. It's good to know the tentative number of projects that will be stored in JIRA.
JIRA server hardware recommendation: The hardware required to run JIRA depends on the number of variables, such as the number of users, number of projects, traffic, and number of schemes used in JIRA:
For approximately 50 projects and 100 users, with less than 5,000 issues—16 GB RAM and a multicore CPU.
For approximately 100 projects and 3,000 users, with less than 100,000 issues—32 GB RAM, 2 Intel (R) Xeon (R), and CPU E5520 @ 2.27 GHz (16 logical cores) processors.
Atlassian has a recommended sizing guide. Refer to the following URL for more information: https://confluence.atlassian.com/enterprise/jira-sizing-guide-461504623.html.
Will you need mail notifications in JIRA?: Do you want e-mail notifications sent to users? JIRA has the capability to send e-mails to users on various events, such as issue creating, updating, and resolving. In order to send e-mails, an SMTP server is required. JIRA can also be configured with Google Apps for Work; just enter your username and password to enable notifications. It's also possible to create issues and post comments using a dedicated e-mail. This functionality can be configured using e-mail handlers in JIRA so that users won't need to launch JIRA to post a comment on the ticket they are assigned to; they can just reply to the e-mail received from JIRA.
Authentication: JIRA has its own internal directory user management system where the information of a user is stored in an internal database. By default, it's enabled when you install JIRA. It's also possible to use directory servers such as LDAP for authentication, user, and group management. In huge organizations where a lot of tools are used, it's important to have such integrated authentication mechanisms so that end users don't have to remember multiple passwords.
Can JIRA be used from multiple locations?: It's important to know the geographical location of the user and from where they will be accessing the JIRA instance. The choice of a JIRA server becomes important here; latency checks should be done from all such locations and the server location should be in such a way that it offers the best performance to everyone accessing it. As a JIRA administrator, your responsibility will be to do performance routine maintenance activities, such as indexing in JIRA. You should know the time window when there are a less number of users connected to the system.
How many concurrent users will access the system?: If you have thousands of users in a geographical location, they may access the system simultaneously. This will result in a degraded performance. Although it's important to know the peak usage during the day beforehand, there are various performance improvement measures that can be worked on.
Tentatively, how many issues per project can be stored?: Discuss with all the product stakeholders about the usage of the tool. You should have plenty of storage to accommodate the huge amount of data. Of course, as an administrator, you will have a fair understanding of the usage. A project can have thousands of issues and these can have file attachments. From time to time, keep a check on the free disk space.
Tentatively, how many total issues can be stored?: JIRA indexing helps in improved search results. However, it can take several minutes to finish and it should ideally be done when there is less usage of the tool. A JIRA instance with less than 100,000 issues may take 10-15 minutes to finish and you should keep this in mind before announcing a downtime. Knowing how many issues will be present in the system will help you to make better decisions.
Will users also upload attachments in their projects?: The out-of-the-box concept of JIRA has a provision to attach files along with issues. Of course, it's a desirable feature and everyone wants this. All the attachments are stored on the disk. Maybe, for some good reason, there is no need to have this feature and it's always good to discuss this first with the product stakeholders.
How many custom fields do you intend to create?: Ideally, all the schemes and configurations should be documented before implementing it, but it's always good to have a clear understanding of the number of custom fields that you need to create in the system.
Choice of platform and database: JIRA (being a pure Java-based application) can be installed either on the Windows or Linux operating system. It needs a JDK or JRE environment to run. If your IT team is more comfortable with Windows and SQL, then use it. Linux has some advantages (such as SSH) and is more suitable for open source tools (such as Postgres or MySQL).
Integration with other tools: JIRA can be integrated into a lot of other tools from Atlassian and other commonly used tools in software development. Will you need integration with Confluence, FishEye/Crucible, Bamboo, Git, or SVN? Keep these possible integrations in mind at the beginning.
Generally, for best performance, most people prefer Linux-RedHat or CentOS as the first choice of distribution. The preferred database is MySQL and Postgres.
For further information on supported platforms, visit the following documentation on Atlassian at https://confluence.atlassian.com/display/JIRA/Supported+Platforms.
JIRA can be easily installed using the automated Windows Installer. If you are using this method, there is no need to set up the JDK; the installer will configure it for you. The following are the steps to install JIRA on Windows:
Download the JIRA Windows Installer (
.exe) file for your platform and architecture from https://www.atlassian.com/software/jira/download.
Run the executable file and in the next step, select Express Install to install JIRA with its default settings; however, a custom installation is recommended, where you can specify the destination directory to install JIRA, the
JIRA HOMEdirectory, and TCP ports. We recommend the Custom Installation.
You will also get an option to install JIRA as a service.
After the JIRA installation, it will launch automatically in the browser to run the setup wizard.
Refer to https://confluence.atlassian.com/display/JIRA/Installing+JIRA+on+Windows for detailed steps to install JIRA on Windows.
Just like Windows Installer, JIRA can also be installed easily on your Linux operating system using the console wizard:
Download the appropriate JIRA Linux 64-bit/32-bit installer (
.bin) file for your platform and architecture from https://www.atlassian.com/software/jira/download.
Open a Linux console and change the (
cd) directory to the
If not already done, make the
.binfile executable using the
chmod a+x atlassian-jira-X.Y.bincommand.
In the next step, select Express Install to install JIRA with its default settings. However, we recommend Custom Install, where you can specify the destination directory to install JIRA, the
JIRA HOMEdirectory, and TCP ports. We recommend Custom Install.
You will also get an option to install JIRA as a service.
After the installation process, JIRA will launch automatically in the browser to run the setup wizard.
Refer to https://confluence.atlassian.com/display/JIRA/Installing+JIRA+on+Linux for detailed steps to install JIRA on Linux.
If you run either the Windows or Linux installer with system administrator rights, then you will get an option to install JIRA as a service. This makes it really easy for JIRA administrators, as the service can be configured to start automatically when the server boots; otherwise, you will need to start JIRA manually every time you start your server.
If you want to install JIRA on Solaris, there is no automatic installation for it and JIRA needs to be installed from an archive file using the following steps:
Download and extract the JIRA archive file.
Set the JIRA home directory.
Create a dedicated user account on the operating system to run JIRA.
Start JIRA using the
Run the setup wizard.
For detailed instructions on how to install JIRA from an archive file, refer to https://confluence.atlassian.com/display/JIRA/Installing+JIRA+from+an+Archive+File+on+Windows%2C+Linux+or+Solaris.
JIRA requires a Java Developers Kit (JDK) or Java Runtime Environment (JRE) platform to be installed on your server's operating system.
If you install JIRA from an archive file then the JDK needs to be installed and set up separately on your system. The Windows Installer and Linux Installer don't need to install the JDK as these installers come with the JDK in-built.
You can download the JDK from http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html.
Select the version relevant to your operating system and architecture. JIRA 7 requires JDK 1.8 to run smoothly.
The steps to install the JDK on Windows are as follows:
Uninstall any earlier version of Java that was installed on your system.
Restart your system.
Using the downloaded installer, you can install the JDK at
C:\java(don't install it in
C:\Program Files\). The JDK specific directory, such as
C:\Java\jdk1.8.0_92, will be created.
JAVA_HOMEwindows environment variable. It should point to the directory where JDK is installed,
C:\Java\jdk1.8.0_92, on the Windows machine.
Restart your system.
JIRA needs to store its data in a database. For this, we will set up a MySQL database. JIRA 7 requires MySQL 5.1 up until 5.6 to run smoothly. You should refer to the preferred MySQL server configurations as described on the following page: https://confluence.atlassian.com/jira/connecting-jira-to-mysql-185729489.html.
It's also possible to use PostgreSQL, Oracle, or Microsoft SQL Server with JIRA, but here we will discuss how to set up the MySQL database:
Log in to your MySQL Server with the following command:
mysql -u root -p
Enter the password.
Create a new database to be used by JIRA using the following command:
Create database jiradb character set utf8 COLLATE utf8_bin;
Create a new user and give it permissions on the database:
GRANT SELECT,INSERT, UPDATE,DELETE,DROP,CREATE,ALTER, INDEX on jiradb.* TO 'jirauser'@'localhost' IDENTIFIED BY 'password';
Flush the privileges using the following command:
We have created a MySQL database name as
jiradb, a database username as
jirauser, and a database password as
password. Keep this information on hand because we will need it when we set up JIRA.
To use MySQL with JIRA, you need to download a
mysql-connector-java-5.1.32-bin.jar database driver and copy it to the
lib folder under JIRA's installation directory. The driver can be downloaded from http://dev.mysql.com/downloads/connector/j.
Let's take a look at the steps involved in the installation of JIRA:
Whether you install JIRA using the custom installer or an archive file, JIRA will first launch itself in the browser with the setup wizard.
The wizard will give you two options—Set it up for me or I'll set it myself. Select I'll set it myself and press the Next button.
In the Database setup screen, select Database Connection as My Own Database.
As we want to use the MySQL database, select MySQL as Database Type. If you want to evaluate JIRA, then you can also use Built In (for evaluation or demonstration) as Database; JIRA uses HyperSQL Database (HSQLDB), which is only used for testing purposes.
Enter your MySQL server Hostname, Port, Database name, database Username, and Password. You may click on the Test Connection button to check whether the credentials are correct or not. Press the Next button to continue.
Now, enter the Application Title for this instance. Select Private as Mode, where only administrators can create accounts. Select Public if you want users to sign up themselves. Enter the Base URL, which users will use to access this instance. You can also change it later on and use the domain name or subdomain such as
jira.company.comas the Base URL. Press the Next button to continue.
In the Specify your license key section, you need to enter your license key that you can generate from my.atlassian.com or simply click on the generate a JIRA trial license link and you will be taken to the Atlassian website where you can generate a New Evaluation License for your instance's Server ID. After that you will be taken back to your instance with the license key filled in. Press the Next button to continue.
Now we need to Set up administrator account. Enter your Full name, Email Address, Username, and Password. Don't forget this credential because this account will have the full admin access of the JIRA instance.
Finally, we have the option to Set up email notifications. If you have the SMTP server in your company, then you can use it. For this example, we have used Service Provider as Google Apps Mail / Gmail. It's quite simple to configure. Just enter your Google Apps Username and Password. There is no need to change any other setting. You can click on the Test Connection button to verify your credentials and communicate with the e-mail server.
Click on the Finish button to complete the setup wizard and JIRA installation.
In the next screen, the wizard will ask you to select your preferred language. Select the language and press the Continue button.
In the next set of screens, you will be presented with A quick tour of JIRA. You can either click on the Next button several times to go through the quick tour or click on the Skip quick tour link in the top-right corner.
Now; you will be logged in automatically and presented with the System Dashboard.
It's important for a JIRA administrator to know the JIRA directory structure really well because you will often need to take backups, make changes in the configuration files, and restore the system. All such activities need to be done on the server and have to be done through its respective directories.
The JIRA installation directory is the directory in which the JIRA application files and libraries are extracted. JIRA does not make changes nor does it save any data here.
If you have installed JIRA using automated Windows or Linux installers, then the JIRA installation directory is stored in the following locations:
The startup and shutdown scripts are available in the
bin directory under the JIRA installation directory:
bin/start-jira.bat or bin/start-jira.sh
bin/stop-jira.bat or bin/stop-jira.sh
The JIRA home directory has important files that JIRA requires to work properly. Do not modify these files.
If you install JIRA using automated Windows or Linux installers, the default location of the JIRA home directory is stored in the following locations:
C:\Program Files\Atlassian\Application Data\JIRA
The following are the list of subdirectories under the JIRA home directory:
data: The application data of the JIRA instance is stored here. Attachments and all its versions are stored under a subdirectory called
attachments import. If you want to restore JIRA, the backfile needs to be placed in this directory.
export: This directory is used to store automated backup files.
log: The log files are stored here.
cache: The cache files are stored here.
tmp: During various runtime operations, such as import, export, and indexing, there are some temporary files that are generated. All such files are stored here.
You should expect issues in the upgrade process, and for this reason, follow these steps:
Set up the staging environment. This could be a clone of your production. Make sure the license of your JIRA instance is valid.
Create a compatibility matrix of the plugins used. Check whether an upgrade of these plugins is available in the new version. Also, check the licenses of your add-ons.
Check the release notes for bug fixes and possible issues.
Perform the upgrade on staging first.
Perform user acceptance testing (UAT) with limited users first, preferably with the managers or the stakeholders of the company.
Collect the feedback and review it.
For any issues, raise a ticket with Atlassian. If you have a valid license, they will help you out.
Always perform a backup of your JIRA installation directory, JIRA home directory, and your database before upgrading.
There are several different ways to upgrade JIRA. The method you choose to use depends on the version of JIRA you use and the type of environment you use it in.
When JIRA is used in companies where it's mission-critical for the business, then it's recommended to use this method because it will let you roll back safely to your previous working version. Prepare the production instance as follows:
Prepare a proxy server.
Install and test the upgraded version.
Refer to https://confluence.atlassian.com/display/JIRA/Upgrading+JIRA+with+a+Fallback+Method for further information on upgrading JIRA using a fallback method.
If you can afford to have a downtime of several minutes and there is no impact on the business due to the downtime, then it's recommended to use this method, which is quite easy. It just needs you to run the installer again on top of the existing installed application:
Keep a note of custom changes.
Take a backup of your database.
Run the JIRA installer and select the upgrade option.
If you have made any changes in some of the files (such as
Refer to https://confluence.atlassian.com/display/JIRA/Upgrading+JIRA+Using+a+Rapid+Upgrade+Method for further information on upgrading JIRA using an RAD method.
With the rapid method, you can easily upgrade JIRA. However, there are certain cases where you cannot use the installation binary. For example, if you want to install JIRA on Solaris, then there are no supported binaries from Atlassian, but you can use the following method with the Web Application Archive (WAR) distribution file to install JIRA on Solaris:
Take a backup of your database and the JIRA installation directory.
Install the new version.
Point your newly installed JIRA instance to a copy of JIRA's existing home directory.
Configure the new version of JIRA to use a new blank database.
Finally, import your JIRA's old data with the restore feature in the newly installed JIRA's instance.
Refer to https://confluence.atlassian.com/display/JIRA/Upgrading+JIRA+Manually for further information on upgrading JIRA manually.
JIRA has a lot of add-ons that can be installed from the marketplace. Add-ons extend the functionalities of JIRA. There are a lot of good add-ons available from Atlassian and other providers. Due to the rapid development in JIRA, this could be a new feature development. To fix bugs, these providers keep on releasing version updates of their add-ons. It's a good idea to update these add-ons from time to time. However, it's recommended to test the upgrades first on your staging environment.
Go to the Manage Add-ons section to check for the updates that are available for your add-ons. The built-in notifications in JIRA will also let you know whenever there is an update available for an add-on. However, these updates should ideally be performed on a test environment first, that is, ideally a staging server identical to your production environment.
Only if the new version of the add-on works on your staging environment will you be able to update it on your production environment. Try using one of the following methods to update the add-ons described:
Updating an add-on to a new version
Updating all add-ons
Updating an add-on by uploading a file
Enabling automatic add-on updates
The detailed steps to update the add-ons can be found at https://confluence.atlassian.com/display/UPM/Updating+add-ons.
We recommend updating the add-ons one by one. There might be an issue in updating all the add-ons simultaneously. Also, you might not know which add-on update caused this problem.
As a good practice, always keep track of all the add-ons currently installed, their current version, their compatibility with currently installed JIRA, and any known issues.
Before you plan to update any add-on, always update the compatibility matrix:
Paid or free
Compatible with JIRA 6.3.6?
Clone Plus Plugin
JIRA Suite Utilities
There are a lot of add-ons available on the Atlassian marketplace, but don't install too many add-ons for no reason. If you are looking for a new feature in JIRA, which is provided as an add-on, always check for how many people are using it by verifying the download count; there is also a user rating that will give you a good idea about this add-on. If you decide to purchase an add-on, then check the provider as well.
The ability to customize JIRA is what makes it popular among various companies who use it. There are various applications of JIRA:
Test case management
Let's take a look at the implementation of test case management:
Test campaign: This will be the standard issue type
Test case: This will be a subtask
Workflow for test campaign:
A test campaign will only pass when all the test cases are passed
Only the reporter can move this test campaign to Closed
When the test campaign is closed, send an e-mail to everyone in a particular group
Workflow for a test case:
Only the assigned user can move the test case to the Passed state
When the test case is moved to the Failed state, change the issue priority to major
Certification with baseline
Let's take a look at the architecture of JIRA; it will help you to understand the core concepts:
Project Categories: When there are too many projects in JIRA, it becomes important to segregate them into various categories. JIRA will let you create several categories that could represent the business units, clients, or teams in your company.
Projects: A JIRA project is a collection of issues. Your team can use a JIRA project to coordinate the development of a product, track a project, manage a help desk, and so on, depending on your requirements.
Components: Components are subsections of a project. They are used to group issues within a project to smaller parts.
Versions: Versions are a point-in-time for a project. They help you schedule and organize your releases.
Issue Types: JIRA will let you create several issue types that are different from each other in terms of what kind of information they store. JIRA comes with default issue types, such as bug, task, and subtask, but you can create more issue types that can follow their own workflow as well as have different sets of fields.
Sub-Tasks: Issue types are of two types—standard and subtasks, which are children of a standard task. For instance, you can have test campaign as a standard issue type and test cases as subtasks.
In this chapter, we discussed things that you plan before implementing JIRA in your company, understood how JIRA is intended to be used in the future, and how it helps JIRA administrators to choose the right hardware. We also discussed the JIRA installation in detail and various ways to upgrade it. Finally, we briefly discussed some possible use cases of JIRA.
In the next chapter, we will understand how to search the issues. JIRA comes with a powerful search mechanism that helps users to easily find the information they are looking for. JIRA has a query language called JIRA Query Language (JQL), which is used for advanced searching. We will also discuss how to save your search queries as filters, which can be referred to again in the future.