In this article by Patrick Li, author of the book JIRA Essentials - Third Edition, we will start with a high-level view of the overall hierarchy on how data is structured in JIRA. We will then take a 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 for the first time in the context of projects and will expand on this.

In this article, you will learn the following:

• How JIRA structures content
• Different user interfaces for project management in JIRA
• How to create new projects in JIRA
• How to import data from other systems into JIRA
• How to manage and configure a project
• How to manage components and versions

(For more resources related to this topic, see here.)

The JIRA hierarchy

Like most other information systems, JIRA organizes its data in a hierarchical structure. At the lowest level, we have field, which are used to hold raw information. Then the next level up, we have issue, which are like a unit of work to be performed.

An issue will belong to a project, which defines the context of the issue. Finally, we have project category, which logically group similar projects together. The figure in the following illustrates the hierarchy we just talked about:

Project category

Project category is a logical grouping for projects, usually of similar nature. Project category is optional. Projects do not have to belong to any category in JIRA. When a project does not belong to any category, it is considered uncategorized. The categories themselves do not contain any information; they serve as a way to organize all your projects in JIRA, especially when you have many of them.

Project

In JIRA, a project is a collection of issues. Projects provide the background context for issues by letting users know where issues should be created. Users will be members of a project, working on issues in the project. Most configurations in JIRA, such as permissions and screen layouts, are all applied on the project level.

It is important to remember that projects are not limited to software development projects that need to deliver a product. They can be anything logical, such as the following:

• Company department or team
• Software development projects
• Products or systems
• A risk register

Issue

Issues represent work to be performed. From a functional perspective, an issue is the base unit for JIRA. Users create issues and assign them to other people to be worked on. Project leaders can generate reports on issues to see how everything is tracking. In a sense, you can say JIRA is issue-centric.

Here, you just need to remember three things:

• An issue can belong to only one project
• There can be many different types of issues
• An issue contains many fields that hold values for the issue

Field

Fields are the most basic unit of data in JIRA. They hold data for issues and give meaning to them. Fields in JIRA can be broadly categorized into two distinctive categories, namely, system fields and custom fields. They come in many different forms, such as text fields, drop-down lists, and user pickers. Here, you just need to remember three things:

• Fields hold values for issues
• Fields can have behaviors (hidden or mandatory)
• Fields can have a view and structure (text field or drop-down list)

Project permissions

Before we start working with projects in JIRA, we need to first understand a little bit about permissions. We will briefly talk about the permissions related to creating and deleting, administering, and browsing projects.

In JIRA, users with the JIRA administrator permission will be able to create and delete projects. By default, users in the jira-administrators group have this permission, so the administrator user we created during the installation process will be able to create new projects. We will be referring to this user and any other users with this permission as JIRA Administrator.

For any given project, users with the Administer Project permission for that project will be able to administer the project's configuration settings. This allows them to update the project's details, manage versions and components, and decide who will be able to access this project. We will be referring to users with this permission as the Project Administrator. By default, the JIRA Administrator will have this permission.

If a user needs to browse the contents of a given project, then he must have the Browse Project 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.

As you have probably realized already, one of the key differences in the three permissions is that the JIRA Administrator's permission is global, which means it is global across all projects in JIRA. The Administer Project and Browse Project permissions are project-specific. A user may have the Administer Project permission for project A, but only Browse Project permission for project B. As we will see the separation of permissions allows you to set up your JIRA instance in such a way that you can effectively delegate permission controls, so you can still centralize control on who can create and delete projects, but not get over-burdened with having to manually manage each project on its own settings. Now with this in mind, let's first take a quick look at JIRA from the JIRA Administrator user's view.

Creating projects

To create a new project, the easiest way 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 we explained, 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 the permission.

When creating a new project in JIRA, we need to first select the type of project we want to create, from a list of project templates. Project template, as the name suggests, acts as a blueprint template for the project. Each project template has a predefined set of configurations such as issue type and workflows. For example, if we select the Simple Issue Tracking project template, and click on the Next button.

JIRA will show us the issue types and workflow for the Simple Issue Tracking template. If we select a different template, then a different set of configurations will be applied. For those who have been using JIRA since JIRA 5 or earlier, JIRA Classic is the template that has the classic issue types and classic JIRA workflow. Clicking on the Select button will accept and select the project template.

For the last step, we need to provide the new project's details. JIRA will help you validate the details, such as making sure the project key conforms to the configured format. After filling in the project details, click on the Submit button to create the new project.

The following table lists the information you need to provide when creating a new project:

Changing the project key format

When creating new projects, you may find that the project key needs to be in a specific format and length. By default, the project key needs to adhere to the following criteria:

• Contain at least two characters
• Cannot be more than 10 characters in length
• Contain only characters, that is, no numbers

You can change the default format to have less restrictive rules.

These changes are for advanced users only.

First, to change the project key length perform the following steps:

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. Change the value for the Maximum project key size option to a value between 2 and 255 (inclusive), and click on the Update button to apply the change.

Changing the project key format is a bit more complicated. JIRA uses a regular expression to define what the format should be. To change the project key format use the following steps:

1. Browse to the JIRA Administration console.
2. Select the System tab and then the General Configuration option.
3. Click on the Advanced Settings button.
4. Hover over and click on the value (([A-Z][A-Z]+)) for the jira.projectkey.pattern option.
5. Enter the new regular expression for the project key format, and click on Update.

There are a few rules when it comes to setting the project key format:

• The key must start with a letter
• All letters must be uppercase, that is (A-Z)
• Only letters, numbers, and the underscore character can be used

Importing data into JIRA

JIRA supports importing data directly from many popular issue-tracking systems, such as Bugzilla, GitHub, and Trac. All the importers have a wizard-driven interface, guiding you through a series of steps. These steps are mostly identical with few differences. Generally speaking, there are four steps when importing data into JIRA that are as follows:

1. Select your source data. For example, if you are importing from CSV, it will select the CSV file. If you are importing from Bugzilla, it will provide Bugzilla database details.
2. Select a destination project where imported issues will go into. This can be an existing project or a new project created on the fly.
3. Map old system fields to JIRA fields.
4. Map old system field values to JIRA field values. This is usually required for select-based fields, such as the priority field, or select list custom fields.

Importing data through CSV

JIRA comes with a CSV importer, which lets you import data in the comma-separated value format. This is a useful tool if you want to import data from a system that is not directly supported by JIRA, since most systems are able to export their data in CSV.

It is recommended to do a trial import on a test instance first.

Use the following steps to import data through a CSV file:

1. Select the Import External Project option from the Projects drop-down menu.
2. Click on the Import from Comma-separated Values (CSV) importer option. This will start the import wizard.
3. First 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 selected the source file, you can also expand the Advanced section to select the file encoding and delimiter used in the CSV file. There is also a Use an existing configuration option, we will talk about this later in this section.
5. Click on the Next button to proceed.

   

6. For the second step, you need to select the project you want to import our 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, make sure you enter the format used in the Date format field.
8. Click on the Next button to proceed.

   

9. For the third step, you need to map the CSV fields to the fields in JIRA. Not all fields need to be mapped. If you do not want to import a particular field, simply leave it as Don't map this field for the corresponding JIRA field selection.
10. For fields that contain data that needs to be mapped manually, such as for select list fields, you need to check the Map field value option. This will let you map the CSV field value to the JIRA field value, so they can be imported correctly. If you do not manually map these values, they will be copied over as is.
11. Click on the Next button to proceed.

    

12. For the last step, you need to map the CSV field value to the JIRA field value. This step is only required if you have checked the Map field value option for a field in step 10.
13. Enter the JIRA field value for each CSV field value.
14. Once you are done with mapping field values, click on the Begin Import button to start the actual import process. Depending on the size of your data, this may take some time to complete.

    

15. Once the import process completes, you will get a confirmation message that tells you the number of issues that have been imported. This number should match the number of records you have in the CSV file.

    

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. Even if you need to run a similar import in the future, you can use this import file so that you will not need to manually re-map everything again. To use this configuration file, check the Use an existing configuration file option in step one.

As we can see, JIRA's project importer makes importing data from other systems simple and straightforward. However, you must not underestimate its complexity. For any data migration, especially if you are moving off one platform and onto a new one, such as JIRA, there are a number of factors you need to consider and prepare for. The following list summarizes some of the common tasks for most data migrations:

• Evaluate the size and impact. This includes how many records you will be importing and also the number of users that will be impacted by this.
• Perform a full gap analysis between the old system and JIRA, such as how the fields will map from one to the other.
• Set up test environments for you to run test imports on to make sure you have your mappings done correctly.
• Involve your end users as early as possible, and have them review your test results.
• Prepare and communicate any outages and support procedure post-migration.

Project user interfaces

There are two distinctive interfaces for projects in JIRA. The first interface is designed for everyday users, providing useful information on how the project is going with graphs and statistics, called Project Browser.

The second interface is designed for project administrators to control project configuration settings, such as permissions and workflows, called Project Administration.

The Help Desk project

In this exercise, we will be setting up a project for our support teams:

• A new project category for all support teams
• A new project for our help desk support team
• Components for the systems supported by the team
• Versions to better manage issues created by users

Creating a new project category

Let's start by creating a project category. We will create a category for all of our internal support teams and their respective support JIRA projects.

Please note that this step is optional as JIRA does not require any project to belong to a project category:

1. Log in to JIRA with a user who has JIRA Administrator's permission.
2. Browse to the JIRA administration console.
3. Select the Projects tab and Project Categories.
4. Fill in the fields as shown in the following screenshot.
5. Click on Add to create the new project category.

Creating a new project

Now that we have a project category created, let's create a project for our help desk support team. To create a new project, perform the following steps:

1. Bring up the create project dialog by selecting the Create Project option from the Projects drop-down menu.
2. Select the Simple Issue Tracking project template.
3. Name our new project as Global Help Desk and accept the other default values for Key and Project Lead.
4. Click on the Submit button to create the new project.

You should now be taken to the Project Browser interface of your new project.

Assigning a project to a category

Having created the new project, you need to assign the new project to your project category, and you can do this from the Project Administration interface:

1. Select the Administration tab.
2. Click on the None link next to Category, on the top left of the page, right underneath the project's name.
3. Select the new Support project category we just created.
4. Click on Select to assign the project.

Creating new components

As discussed in the earlier sections, components are subsections of a project. This makes logical sense for a software development project, where each component will represent a software deliverable module. For other types of project, components may first appear useless or inappropriate.

It is true that components are not for every type of project out there, and this is the reason why you are not required to have them by default. Just like everything else in JIRA, all the features come from how you can best map them to your business needs.

The power of a component is more than just a flag field for an issue. For example, let's imagine that the company you are working for has a range of systems that need to be supported. These may range from phone systems and desktop computers to other business applications. Let's also assume that our support team needs to support all of the systems. Now, that is a lot of systems to support. To help manage and delegate support for these systems, we will create a component for each of the systems that the help desk team supports. We will also assign a lead for each of the components. This setup allows us to establish a structure where the Help Desk project is led by the support team lead, and each component is led by their respective system expert (who may or may not be the same as the team lead). This allows for a very flexible management process when we start wiring in other JIRA features, such as notification schemes:

1. From the Project Administration interface, select the Components tab.
2. Type Internal Phone System for the new component's name.
3. Provide a short description for the new component.
4. Select a user to be the lead of the component.
5. Click on Add to create the new component.
6. Add a few more components.

Putting it together

Now that you have fully prepared your project, let's see how everything comes together by creating an issue. If everything is done correctly, you should see a dialog box similar to the next screenshot, where you can choose your new project to create the issue in and also the new components that are available for selection:

1. Click on the Create button from the top navigation bar. This will bring up the Create Issue dialog box.
2. Select Global Help Desk for Project.
3. Select Task for Issue Type, and click on the Next button.
4. Fill in the fields with some dummy data. Note that the Component/s field should display the components we just created.
5. Click on the Create button to create the issue.

You can test out the default assignee feature by leaving the Assignee field as Automatic, select a component, and JIRA will automatically assign the issue to the default assignee defined for the component.

If everything goes well, the issue will be created in the new project.

Summary

In this article, we looked at one of the most important concepts in JIRA, projects, and how to create and manage them. Permissions were introduced for the first time, and we looked at three permissions that are related to creating and deleting, administering, and browsing projects.

We were introduced to the two interfaces JIRA provides for project administrators and everyday users, the Project Administration interface and Project Browser interface, respectively.

Resources for Article:

Further resources on this subject:

• Securing your JIRA 4 [article]
• Advanced JIRA 5.2 Features [article]
• Validating user input in workflow transitions [article]