JIRA 101Ahren Stevens-Taylor
In this article by Ravi Sagar, author of the book, Mastering Jira 7 – Second Edition, you will learn the basics about JIRA. We will look into the components available in the product, their application, and how to use them. We will try our hands on a few JQL queries, after which we will create project reports on JIRA for issue tracking, and then derive information from them using various built-in reports that JIRA comes with. We will also take a look at the gadgets that JIRA provides, which are helpful for reporting purposes. Finally, we will take take a look at the migrating options, which JIRA provides, to fully restore a JIRA instance for a specific project.
(For more resources related to this topic, see here.)
Atlassian JIRA is a proprietary issue tracking system. It is used for tracking bugs, issues, and project management. There are many such tools available, but the best thing about JIRA is that it can be configured very easily and it offers a wide range of customizations. Out of the box, JIRA offers a defect/bug tracking functionality, but it can be customized to act like a helpdesk system, simple test management suite, or a project management system with end-to-end traceability.
The much awaited JIRA 7 was released in October 2015 and it is now offered in the following three different application variants:
- JIRA Core
- JIRA Software
- JIRA Service Desk
Let us discuss each one of them separately.
This comprises the base application of JIRA that you may be familiar with, of course with some new features. JIRA Core is a simplified version of the JIRA features that we have used till 6.x versions.
This comprises of all the features of JIRA Core + 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.
JIRA Service Desk
This comprises of all the features of JIRA Core + JIRA Service Desk. Just like JIRA Software, the JIRA Service Desk will no longer be offered as an add-on and you cannot install it from the marketplace.
Applications, uses, and examples
The ability to customize JIRA is what makes it popular among various companies who use it. The following are the various applications of JIRA:
- Defect/bug tracking
- Change requests
- Helpdesk/support tickets
- Project management
- Test-case management
- Requirements management
- Process management
Let’s take a look at the implementation of test-case management:
- The issue types:
- Test campaign: This will be the standard issue type
- Test case: This will be subtask
- The workflow for test campaign:
- New states:
- Under Execution
- A test campaign will only pass when all the test cases are passed
- Only reporter can move this test campaign to Closed
- Post function:
- When the test campaign is closed, send an email to everyone in a particular group
- Workflow for a test case:
- New states:
- In Review
- Only the assigned user can move the test case to Passed state
- Post function:
- When the test case is moved to Failed state, change the issue priority to major
- Custom fields:
Steps to reproduce
- Backward compatibility
- Certification with baseline
- Partially automatic
JIRA core concepts
Let’s take a look at the architecture of JIRA; it will help you 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 can 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 point-in-time for a project. They help you schedule and organize your releases.
- Issue Types: JIRA will let you create more than one 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 a different set of fields.
- Subtasks: Issue types are of two types, namely standard and subtasks, which are children of a standard task. For instance, you can have test campaigns as standard-issue type and test cases as subtasks.
Introduction to JQL
JIRA Query Language (JQL) is one of the best features in JIRA that lets you search the issues efficiently and offers lots of handy features. The best part about JQL is that it is very easy to learn, thanks to the autocomplete functionality in the Advanced search, which helps the user with suggestions based on keywords typed.
JQL consists of questions, whether single or multiple, that can be combined together to form complex questions.
Basic JQL syntax
JQL has a field followed by an operator. For instance, to retrieve all the issues of the CSTA project, you can use a simple query like this:
project = CSTA
Now, within this project, if you want to find the issues assigned to a specific user, use the following query:
project = CSTA and assignee = ravisagar
There may be several hundred issues assigned to a user and, maybe, we just want to focus on issues whose priority is either Critical or Blocker, you can use the following query:
project = CSTA and assignee = ravisagar and priority in (Blocker, "Critical)
What if, instead of issues assigned to a specific user, we want to find the issues assigned to all other users except one? It can be achieved in the following way:
project = CSTA and assignee != ravisagar and priority in (Blocker, "Critical)
So, you can see that JQL consists of one or more queries.
Once you start using JIRA for issue tracking of any type, it becomes imperative to derive useful information out of it. JIRA comes with built-in reports that show real-time statistics for projects, users, and other fields.
Let’s take a look at each of these reports.
Open any project in JIRA that contains a lot of issues and has around 5 to 10 users, which are either assignee or reporters. When you open any project page, the default view is the Summary view that contains a 30 day summary report and Activity Stream that shows whatever is happening in the project-like creation of new issues, update of status, comments, and basically any change in the project.
On the left-hand side of the project summary page, there are links for Issues and Reports.
Average Age Report
This report displays the average number of days for which issues are in an unresolved state on a given date.
Created vs. Resolved Issues Report
This report displays the number of issues that were created over the period of time versus the number of issues that were resolved in that period:
Pie Chart Report
This chart shows the breakup of data. For instance, in your project, if you are interested in finding out the issue count for all the issue types, then this report can be used to fetch this information.
Recently Created Issues Report
This report displays the statistical information on the number of issues created for the selected period and days. The report also displays status of the issues.
Resolution Time Report
There are cases when you are interested in understanding the speed of your team every month. How soon can your team resolve the issues? This report displays the average resolution time of the issues in a given month.
Single Level Group By Report
It is a simple report that just lists the issues grouped by a particular field, such as Assignee, Issue Type, Resolution, Status, Priority, and so on.
Time Since Issues Report
This report is useful in finding out how many issues were created in a specific quarter over the past one year and, not only that, there are various date-based fields supported by this report.
Time Tracking Report
This comprehensive report displays the estimated effort and remaining effort of all the issues. Not only that, the report will also give you indication on the overall progress of the project.
User Workload Report
This report can tell us about the occupancy of the resources in all the projects. It really helps in distributing the tasks among users.
Version Workload Report
If your project has various versions that are related to the actual releases or fixes, then it becomes important to understand the status of all such issues.
Gadgets for reporting purposes
JIRA comes with a lot of useful gadgets that you can add in the dashboard and use for reporting purposes. Additional gadgets can be added in JIRA by installing add-ons. Let’s take a look at some of these gadgets.
This gadget will display all the latest updates in your JIRA instance. It’s also possible to limit this stream to a particular filter as well. This gadget is quite useful because it displays up-to-date information on the dashboard:
Created vs. Resolved Chart
The project summary page has a chart to display all the issues that were created and resolved in the past 30 days. There is a similar gadget to display this information.
You can also change the duration from 30 days to whatever you like. This gadget can be created for a specific project:
Just like the pie chart, which is there in project reports, there is a similar gadget that you can add in the dashboard. For instance, for a particular project, you can generate a Pie Chart based on Priority:
This gadget is quite useful in generating simple statistics for various fields. Here, we are interested in finding out the breakup of the project in terms of Issue Statistics:
Two Dimensional Filter Statistics
The Issue Statistics gadget can display the breakup of project issues for every Status. What if you want to further segregate this information? For instance, how many issues are open and to which Issue Type they belong to? In such scenarios, Two Dimensional Filter Statistics can be used.
You just need to select two fields that will be used to generate this report, one for x axis and another for y axis:
These are certain common gadgets that can be used in the dashboard; however, there are many more gadgets. Click on the Add Gadget option on the top-right corner to see all such gadgets in your JIRA instance. Some gadgets come out of the box with JIRA and others are a part of add-ons that you can install.
After you select all these gadgets in your dashboard, this is how it looks:
This is the new dashboard that we have just created and configured for a specific project, but it’s also possible to create more than one dashboard. To add another dashboard, just click on the Create Dashboard option under Tools on the top-right corner.
If you have more than one dashboard, then you can switch between them using the links on the top-left corner of the screen, as shown in the following screenshot:
The simple CSV import
Let’s understand how to perform a simple import of the CSV data. The first thing to do is prepare the CSV file that can be imported into JIRA. For this exercise, we will import issues into a particular project; these issues will have data, such as issue Summary, Status, Dates, and a few other fields.
Preparing the CSV file
We’ll use MS Excel to prepare the CSV file with the following data:
If your existing tool has the option to export directly into the CSV file, then you can skip this step, but we recommend reviewing your data before importing it into JIRA. Usually, the CSV import will not work if the format of the CSV file and the data is not correct.
It’s very easy to generate a CSV file from an Excel file. Perform the following steps:
- Go to File | Save As | File name: and select Save as type: as CSV (comma delimited). If you don’t have Microsoft Excel installed, you can use LibreOffice Calc, which is an open source alternative for Microsoft Office Excel:
- You can open the CSV file to verify its format too:
Our CSV file has the following fields:
JIRA’s project key needs to be specified in this field
This field is mandatory and needs to be specified in the CSV file
This is important to specify the issue type
This displays the status of the issue; these are workflow states that need to exist in JIRA and the project workflow should have the states that be imported into the CSV file
The priorities mentioned here should exist in JIRA before import
The resolutions mentioned here should exist in JIRA before import
This specifies the assignee of the issue
This specifies the reporter of the issue
This is the issue creation date
This is the issue resolution date
Performing the CSV import
Once your CSV file is prepared, then you are ready to perform the import in JIRA:
- Navigate to JIRA Administration | System | External System Import | CSV (under IMPORT & EXPORT).
- On the File import screen in the CSV Source File field, click on the Browse… button to select the CSV file that you just prepared on your machine.
- Once you select the CSV file, the Next button will be enabled:
- On the Setup screen, select Import to Project as DOPT, which is the name of our project.
- Verify Date format. It should match the format of the date values in the CSV file.
- Click on the Next button to continue.
- On the Map fields screen, we need to map the fields in the CSV file to JIRA fields. This step is crucial because in your old system, the field name can be different from JIRA fields; so, in this step, map these fields to the respective JIRA fields.
- Click on the Next button to continue.
- On the Map values screen, map the values of Status, in fact, this mapping of field values can be done for any field. In our case, the values in the status field are the same as in JIRA, so click on the Begin Import button.
- You will finally get a confirmation that the issues are imported successfully:
If you encounter any errors during the CSV import, then it’s usually due to some problem with the CSV format. Read the error messages carefully and correct these issues. As mentioned earlier, the CSV import needs to be performed on the test environment first.
Migrate JIRA configurations using Configuration Manager add-on
JIRA has provision to fully restore a JIRA instance from a backup file, restore a specific project, and use the CSV import functionality to important data in it. These utilities are quite important as it really makes the life of JIRA administrators a lot easier. They can perform these activities right from the JIRA user interface. The project-import utility and CSV import is used to migrate one or more projects from one instance of JIRA to another, but the target instance should have the required configuration in place otherwise these utilities will not work. For instance, if there is a project in source instance with custom workflow states along with a few custom fields, then the exact similar configurations of workflow and custom fields should exist already in the target instance. Recreating these configurations and schemes can be a time consuming and error prone process.
Additionally, in various organizations, there is a test environment or a staging server for JIRA where all the new configurations are first tested before they are rolled out to the production instance. Currently, there is no such way to selectively migrate the configurations from one instance to another. It has to be done manually on the target instance.
Configuration Manager is an add-on that does this job. Using this add-on, the project-specific configuration can be migrated from one instance to another.
In this article we looked at the different products offered by JIRA. Then we learned about concepts of JIRA. We then tried our hands on JQL and a few examples of it. We saw the different types of reports provided by JIRA and the various gadgets available for reporting purposes. Finally we saw how to migrate JIRA configurations using the configuration manager add-on.