Jira 8 Administration Cookbook - Third Edition

5 (2 reviews total)
By Patrick Li
    What do you get with a Packt Subscription?

  • Instant access to this title and 7,500+ eBooks & Videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Free Chapter
    Jira Server Administration
About this book

Jira is a project management tool used widely by organizations to plan, track, and release software. Jira administrators are at the heart of these processes and need to know how to successfully administer and customize Jira offerings. This updated Jira 8 Administration Cookbook demonstrates how to efficiently work with Jira Core and Jira Service Desk.

The book starts with a variety of recipes to help you manage users and workflows. You'll learn how to set up custom forms and capture important data with custom fields and screens. Next, you'll gain insights into the latest email capabilities, which will assist you with everything from managing outgoing email rules to processing incoming emails for automated issue creation. Later, you'll be guided through running scripts to automate tasks, getting easy access to logs, and even working with tools to troubleshoot problems. The book will also ensure you understand how to integrate Jira with Slack, set up SSO with Google, and delegate administrator permissions. Finally, a dedicated section on Jira Service Desk will enable you to set up and customize your own support portal, work with internal teams to solve problems, and achieve optimized services with Service Level Agreement (SLA).

By the end of this book, you'll have the skills you need to extend and customize your Jira implementation effectively.

Publication date:
June 2019


Jira Server Administration

Atlassian Jira is a popular issue tracking system used by many companies across the Globe. One of its strengths, unlike most other enterprise software, is that it does not take days or weeks to install and implement, and is very simple to upgrade and maintain.

We will assume that you already know how to install a brand-new Jira system. So, we will explore common administration tasks, such as upgrading and migrating your Jira, and we'll look at different options, ranging from using the new automated upgrade utility provided by Atlassian to doing everything from scratch. We will also look at some other neat tricks for you as an administrator, such as resetting the admin password to get you out of sticky situations.

Since Jira is now a family of products, including Jira Core (which is the old Jira Classic before Jira 7), Jira Software (which is Jira Core plus agile capabilities), and Jira Service Desk (which is Jira Core plus the old Jira Service Desk add-on), recipes in this book will use the term Jira to refer to the most popular of the three, Jira Software.

In this chapter, we will cover the following topics:

  • Installing Jira for production use
  • Upgrading Jira with an installer
  • Upgrading Jira manually
  • Migrating Jira to another environment
  • Setting up the context path for Jira
  • Setting up SSL
  • Installing SSL certificates from other applications
  • Resetting the Jira administrator password
  • Importing data from CSV
  • Copying configurations between Jira instances

Installing Jira for production use

In this recipe, we will look at how to install and set up Jira in a production environment. This includes setting up a dedicated user to run Jira under and using an external database.

We will use the archive distribution since the steps are consistent across both the Windows and Linux platforms. This will also provide you with an insight into the exact steps required to get a Jira instance deployed and running; these would otherwise be hidden by an automated installer. This will provide you with the information needed for subsequent maintenance and further configurations.

Getting ready

The following things need to be checked before you begin with this recipe:

How to do it...

We first need to create an empty MySQL database for Jira:

  1. Open up a new Command Prompt on the MySQL server.
  1. Run the following command (you can also use another user instead of root as long as the user has permission to create new users and databases):
mysql -u root -p
  1. Enter the password for the user when prompted.
  2. Create a new database for Jira by running the following command:
create database jiradb character set utf8;
  1. Create a new user for Jira in the database and grant the user access to the jiradb database we just created using the following command:
grant all on jiradb.* to 'jirauser'@'localhost'
identified by  'jirapassword';
  1. In the previous five steps, we created a new database named jiradb and a new database user named jirauser. We will use these details later to connect Jira with MySQL. The next step is to install Jira.
  2. Create a dedicated user account to run Jira under. If you're using Linux, run the following command as root or with sudo:
useradd --create-home --comment "Dedicated
Jira account" -- shell /bin/bash jira
It is good practice to reduce security risks by locking down the user account so that it does not have login permissions.
  1. Create a new directory on the filesystem where Jira will be installed. This directory will be referred to as JIRA_INSTALL.
  2. Create another directory on the filesystem. This will be used for Jira to store its attachments, search indexes, application data, and other information. You can create this directory on a different drive with more hard disk capacity, such as a network drive (this could slow down performance). This directory will be referred to as JIRA_HOME.
It is good practice to keep the JIRA_INSTALL and JIRA_HOME directories separate; that is, the JIRA_HOME directory should not be a subdirectory inside JIRA_INSTALL. This will make future upgrading and maintenance easier.
  1. Unzip the Jira archive file in the JIRA_INSTALL directory.
  2. Change both the JIRA_INSTALL and JIRA_HOME directories' owner to the new Jira user.
  3. Open the JIRA_INSTALL/atlassian-jira/WEB-INF/classes/jira-application.properties file in a text editor.
  4. Locate the jira.home= line in this file.
  5. Copy and paste this in the full path to the JIRA_HOME directory and remove the # symbol if present. Make sure you use the forward slash (/). The following line shows how it looks on a Linux system:
Windows uses the backward slash (\) in the file path. You should still use the forward slash (/) while specifying the jira.home directory.
  1. Copy the database driver JAR file (obtained from the Getting ready section) to the JIRA_INSTALL/lib directory.
  2. Start up Jira by running the start-jira.sh (for Linux) or start-jira.bat (for Windows) script from the JIRA_INSTALL/bin directory as the Jira user. You should see the output, Tomcat, started in your console; this means that Jira is up and running.
  1. Jira comes with a setup wizard that will help guide us through the final phase of the installation.
  2. Open up a browser and go to http://localhost:8080 (replace localhost with the actual server name). By default, Jira runs on port 8080. You can change this by changing the connector port value in the JIRA_INSTALL/conf/server.xml file.
  3. The first step in setup is to select how you want Jira to be set up. Select the I'll set it up myself option and click on the Next button:
  1. The second step is to set up database information. Select the My Own Database (recommended for production environments) option.
  2. Select a value for the Database Type option. For this recipe, select the MySQL 5.7+ option.
  1. Enter the details for our new jiradb database:
  1. Click on Test Connection to check whether Jira is able to connect to the database.
  2. Click on the Next button to proceed if the database connection test is successful and move to the next step of the wizard.
  3. Enter the Application Title value for this Jira instance.
  4. Select Public if you would like to let people sign up for accounts, or Private if you want only administrators to create accounts. Most organizations that use Jira to track internal projects will require Private mode.
  5. Set the Base URL option. The base URL is the one that users will use to access Jira. Usually, this should be a fully qualified domain name or the hostname—that is, not localhost or an IP address.
  1. Click on Next to go to the third step of the wizard, as shown in the following screenshot:
  1. Enter your Jira license key if you have one. If you do not have a license key, you can generate a temporary trial license by clicking the Generate a Jira trial license link and following the instructions.
  2. Click on Next to go to the fourth step in the wizard, as shown in the following screenshot:
  1. Enter the details for the initial administrator account. The user account will have access to all the configuration options in Jira, so make sure you do not lose its login credentials.
  2. Click on Next to go to the fifth and final step of the wizard, as shown in the following screenshot:
  1. Choose whether you want to set up an outgoing SMTP server Now or Later. If you do not have an SMTP server ready right now, you can always come back and configure it later.
  2. Click on Finish to complete the setup process.

You will see the following Welcome! screen:

This ends the general configuration part of the setup process. Your Jira system is up and running. Next, Jira will walk you through its onboarding process as a first-time user. You will be asked to select the default language to use, upload a user avatar, and create your very first project.

There's more...

By default, Jira is set to use a maximum of 768 MB of memory. For a production deployment, you might need to increase the amount of memory allocated to Jira. You can increase this by opening up the setenv.sh (on Linux) or setenv.bat (on Windows) files in the JIRA_INSTALL/bin directory and changing the value of the JVM_MAXIMUM_MEMORY parameter.

For example, if we want to set the maximum memory to 2 GB, we will change it to JVM_MAXIMUM_MEMORY="2048m". You will need to restart Jira after performing this change. For production uses, it is recommended that you allocate at least 4 GB (4096 MB) of memory to the Jira JVM. Make sure you have sufficient physical memory available on your server first.

If you are using LDAP for user management in your organization, refer to the Integrating with LDAP for authentication only recipe in Chapter 4, User Management.

Detailed steps for downloading the code bundle are mentioned in the Preface of this book. Please have a look. The code bundle for the book is also hosted on GitHub at https://github.com/PacktPublishing/Jira-8-Administration-Cookbook-Third-Edition. We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

Upgrading Jira with an installer

For both Windows and Linux, Atlassian provides an installer package that can guide you through the upgrade process. The installer will detect your current Jira installation and perform all the necessary tasks to upgrade it to the target version.

In this recipe, we will show you how to upgrade your Jira instance with the standard Jira installer.

Getting ready

As the Jira installer is only available for standalone installations on Windows and Linux, we will run you through the installer on Windows in this recipe:

  • Check the upgrade notes for any special instructions as well as the target Jira version to make sure you can perform a direct upgrade.
  • Make sure you have a valid Jira license.
  • Verify whether your current host environment is compatible with the target Jira version. This includes the Java version, database, and OS.
  • Verify whether your operating environment is compatible with the target's Jira version, specifically, the browser requirements.
  • Make sure that the add-ons you are using are compatible with the new version of Jira.
  • Download the installer binary for your target Jira version.
You can use the Universal Plugin Manager's Jira update check utility to check for add-on compatibility.

How to do it...

Upgrade your Jira system with the installer using the following steps:

  1. Take your current Jira offline, for example, by running the stop-jira.bat script.
  2. Back up the Jira database with its native backup utility.
  3. Launch the installer and select the Upgrade an existing JIRA installation option.
  4. Now, select the directory where the current Jira is installed:
  1. Check the backup JIRA home directory option and click on the Next button.
If your JIRA_HOME directory is big, you might want to manually back it up or remove some of the cache and tmp folders as it would take a long time for the installer to back these up.
  1. Review the Upgrade checklist and click on the Upgrade button:
  1. Wait for the installer to complete the upgrade process. Once the upgrade is complete, the installer will automatically launch Jira.
  2. Update any add-ons once Jira starts successfully.

The installer will detect and provide you with a list of customized files in the JIRA_INSTALL directory, which you will need to copy manually after the upgrade.

See also

If you cannot use the installer to upgrade Jira, refer to the Upgrading Jira manually recipe.


Upgrading Jira manually

If you find yourself in a situation where you cannot use the installer to upgrade Jira—for example, if you are hosting Jira on an OS that does not have an installer binary or on a cloud platform, then you can use the manual upgrade method to upgrade your Jira instance.

Getting ready

The tasks required to upgrade Jira manually will remain the same as those for the installer. Refer to the previous recipe for common tasks involved. As the installer automates many backup tasks while upgrading Jira manually, you will have to do the following:

  1. Back up the Jira database with its native backup utility.
  2. Back up the JIRA_INSTALL directory.
  3. Back up the JIRA_HOME directory.
  4. Get a list of all the customized files in the JIRA_INSTALL directory from the System Info page in Jira.

How to do it...

To manually upgrade your Jira instance, perform the following steps:

  1. Take your current Jira offline.
  2. Install the new version of Jira in a different directory.
  3. Edit the jira-application.properties file in the JIRA_INSTALL/atlassian-jira/WEB-INF/classes directory to point to the existing JIRA_HOME directory.
  4. Copy any modified files from the old Jira instance to the new one.
  5. Start up the new Jira instance.
  6. Update the add-ons once Jira starts successfully.
  7. Remove the previous installation directory to avoid confusion.

How it works...

What we did here essentially involved setting up a new instance of Jira and pointing it at the old Jira instance's data. When we start up the new Jira instance, it will connect to the existing Jira database by reading the dbconfig.xml file from the JIRA_HOME directory, and will perform an in-place upgrade to make all the necessary schema changes.


Migrating Jira to another environment

Now that we have gone through upgrading a Jira instance, we will look at how to move a Jira instance to another server environment. This is a common use case when you need to move an application to a virtualized environment or data center.

Getting ready

The following things need to be checked before you start with this recipe:

  • Make sure you have a valid Jira license.
  • Check whether your new environment is compatible with Jira system requirements.
  • Ensure that both the old and new Jira instances are of the same major or minor version. If you intend to run a newer version of Jira in the new environment, it is recommended that you upgrade once the migration is successful.
Migrating a system can be very disruptive for users. Make sure you communicate this to your users and allocate sufficient time for rollbacks.

How to do it...

To migrate an existing Jira instance to another server, perform the following steps:

  1. Download and install a brand-new Jira instance in your new environment with an empty database.
  1. Note down the files listed under Modified Files and Removed Files in the System Info page for your current Jira. The following screenshot shows an example:
  1. Shut down your current Jira instance.
  2. Back up your current Jira database with the database's native backup utility.
  3. Back up your current JIRA_HOME directory.
  4. Take your new Jira offline.
  5. Copy over your JIRA_HOME backup and replace the new JIRA_HOME directory with it.
  6. Update the dbconfig.xml file with the new Jira database details.
  7. Copy your database backup and restore the new Jira database.
  8. Start up the new Jira instance.
  9. Apply the same changes to the new Jira instance from step 2.

Setting up the context path for Jira

If you have multiple web applications running on the same domain, you might want to set up a context path for Jira—for example, http://example.com/jira, where /jira is the context path.

How to do it...

Perform the following steps to set up a context path for Jira:

  1. Shut down Jira if it is running.
  2. Open up JIRA_INSTALL/conf/server.xml in a text editor.
  1. Locate the following line and enter the context path for the path attribute—for example, path="/jira":
<Context path="/jira"docBase="${catalina.home}
/atlassian-jira" reloadable="false"

  1. Save the file and restart Jira. If you are doing this after Jira has been installed, you will have to update Jira's base URL option so that its links will reflect the change.
  2. Log into Jira as an administrator.
  3. Navigate to Administration > Systems > General Configuration.
  4. Click on the Edit Settings button.
  5. Enter the fully qualified URL in Jira, including the context path, in the Base URL field.
  6. Click on Update to apply the change.

After you have all this set up, you will be able to access Jira with the new context path, and all the links, including those from Jira's notification emails, will be the context path in the URL.


Setting up SSL

By default, Jira runs with a standard non-encrypted HTTP protocol. This is acceptable if you are running Jira in a secure environment, such as an internal network. However, if you plan to open up access to Jira over the internet, you need to tighten up security by encrypting sensitive data, such as the usernames and passwords that are sent, by enabling HTTP over SSL (HTTPS).

This recipe describes how to install SSL on the Jira Tomcat application server. If you have an HTTP web server such as Apache in front of Jira, you can install the SSL certificate on the web server instead.

Getting ready

You need to have the following set up before you can step through this recipe:

  1. Obtain a valid SSL certificate: You can either use a self-signed certificate or obtain one from a certificate authority (CA) such as Verisign. Using a self-signed certificate will display a warning message when users first visit the site, as shown in the following screenshot:
  1. Ensure that the JAVA_HOME environment variable is set properly.
  2. Make sure you know which JDK/JRE Jira is using. You can find this information from the System Info page in Jira, where you need to look for the java.home property.
  3. Make sure your JRE/JDK's bin directory is added to your PATH environment variable, and the keytool command will output its usage, as shown in the following screenshot:

Now let's get started with the steps for this recipe.

How to do it...

Perform the following steps to import an SSL certificate:

  1. Open up a command window and go to the directory where the certificate file resides.
  2. Generate a Java KeyStore (JKS) for Jira by running the keytool -genkey -alias jira -keyalg RSA -keystore $JIRA_HOME/jira.jks command.
  3. Import the certificate into the KeyStore repository by running the keytool -import -alias jira -keystore $JIRA_HOME/jira.jks -file file.crt command, where file.crt is the certificate file.
  4. Open the server.xml file located in the JIRA_INSTALL/conf directory in a text editor.
  1. Locate and uncomment the following XML configuration snippet:
<Connector port="8443" 
maxHttpHeaderSize="8192" SSLEnabled="true" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" useBodyEncodingForURI="true"/>
  1. Add a few new attributes to the Connector tag and save the file, as follows:
  1. Restart Jira to apply the changes.

How it works...

We first created a new Java KeyStore repository for Jira to store its own SSL certificate with Java's keytool utility. During this step, you are prompted to provide information about the store as well as a password to access the KeyStore repository.

Do not lose the password to the KeyStore repository.

After we created the KeyStore repository, we imported the certificate (and then enabled an additional connector to listen for HTTPS connections) by uncommenting the connector XML tag. We also added new attributes to the tag so that Tomcat knows where our new KeyStore repository is and how to access it to get to the certificate.

You can also change the port number for the connector if you want to run HTTPS on a more common port, 443, instead of the default port, 8443, and your final XML snippet will look something similar to the following:

<Connector port="443"
maxHttpHeaderSize="8192" SSLEnabled="true" maxThreads="150" minSpareThreads="25"
maxSpareThreads="75" enableLookups="false"
disableUploadTimeout="true" acceptCount="100"
scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" useBodyEncodingForURI="true"
keyAlias="jira" keystoreType="JKS"/>

There's more...

At this point, users can access Jira with both HTTP and HTTPS, and you need to configure Jira so that it will automatically redirect all HTTP traffic to HTTPS. Jira comes with a handy configuration utility that can help you set up this configuration.

You should first make sure your HTTPS configuration is working correctly before attempting this recipe.

Perform the following steps:

  1. Open the Command Prompt and go to the JIRA_INSTALL/bin directory.
  2. Depending on your OS, run the config.bat (Windows) or config.sh (Linux / OS X) file.
  3. Select the Web Server tab from the JIRA Configuration Tool window.
  4. Select the HTTP and HTTPs (redirect HTTP to HTTPs) option for Profile.
  5. Click on the Save button at the bottom of the window, as shown in the following screenshot.
  1. Restart Jira to apply the change:

If you cannot use the JIRA Configuration Tool, you can perform the following steps to set up the configuration manually:

  1. Open the web.xml file located in the JIRA_INSTALL/atlassian-jira/WEB-INF directory.
  2. Add the following XML snippet at the end of the file just before the closing </webapp> tag:
 <display-name>HTTP to HTTPs Redirection</display-name> 
  1. Restart Jira to apply the change.

See also

For information on connecting Jira to other applications that run on SSL, refer to the next recipe.


Installing SSL certificates from other applications

You might need to connect Jira to other services, such as LDAP, mail servers, and other websites. Often, these services make use of SSL. In such cases, the connection will fail, and you will see the following errors in your Jira log file:

sun.security.validator.ValidatorException: PKIX path building failed:  
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification
path to requested target

Getting ready

For this recipe, we will use the Java keytool utility, so make sure you have the following configuration set up:

  • Obtain the required SSL certificate from the target system.
  • Ensure that the JAVA_HOME environment variable is set properly.
  • Make sure you know which JDK/JRE Jira is using. You can find this information on the System Info page, where you need to look for the java.home property.
  • Make sure your JRE/JDK's bin directory is added to your PATH environment variable, and the keytool command will output its usage.
  • Obtain the password for the Java trust store used by Jira.

How to do it...

In this recipe, let's assume we want to connect Jira to an LDAP server that is running on SSL. Perform the following steps to make it a trusted site inside Jira:

  1. Open up a Command Prompt and go to the directory where the certificate file resides.
  1. Import the certificate into the trust store by running keytool -import -alias tomcat -file file.cer $JAVA_HOME/jre/lib/security/cacertscommand, where file.cer is the certificate file.
  2. Restart Jira to apply the changes.

How it works...

When Jira attempts to connect to an SSL-protected service, it will first check whether the target service's certificate can be trusted. This is done by checking to see whether the certificate is present in what is called the Java trust store. If the certificate is not present, the connection will fail.

The trust store is a special KeyStore repository, usually called cacerts, and is located in the $JAVA_HOME/lib/security directory on the server.

We used the keytool utility to import the certificate to our local trust store, so the target service will be registered as a trusted service and will allow Jira to connect to it successfully.


Resetting the Jira administrator password

Sometimes, you might forget or lose the password to the account with the Jira administrator or Jira System Administrator permission, and you cannot retrieve it using the password reset option. For example, suppose Jira does not have an SMTP server configured, or you restored Jira from a data dump and do not know the account and/or password. In these cases, you need to reset the administrator password directly in the database.

This recipe only applies to Jira instances that use the default internal user directory option. External user management, such as LDAP, will not work with this recipe.

Getting ready

As we will reset the password stored in Jira's database, make sure you do the following:

  • Connect to the Jira database via either the command line or a GUI.
  • Update the Jira database records.

How to do it...

Let's assume we use the default mysql command-line tool and MySQL as the backend database for Jira. If you are using a different database, you may need to change the following SQL statements accordingly:

  1. Connect to the Jira database with a client tool by running the mysql -u jirauser -p command, where jirauser is the username used by Jira to access the Jira database.
  2. You can find Jira's database details from the dbconfig.xml file located in JIRA_HOME.
  3. Change to the Jira database by running the use jiradb command, where jiradb is the name of Jira's database.
  4. Determine the groups that have the Jira System Administrator global permission with the following SQL statement:
select perm_parameter from 
schemepermissions where PERMISSION=44;
  1. Find users that belong to the groups returned in the previous step by running the following SQL statement, where jira-administrators is a group returned from the previous step:
select child_name, directory_id
from cwd_membership where
The jira-administrators group is the default group that administrators belong to. You might get a different group if you customize the permission configurations. The table column for the username is child-name.
  1. Reset the user's password in the database with the following SQL statement, where admin is a user returned in the previous step:
update cwd_user set
CZvms6yMMvA8I7FViHVEqr6Mj4pCLKAFQ==' where
  1. Restart Jira to apply the change.

How it works...

With Jira's internal user directory, all user and group data is stored in the Jira database. The value 44 is the ID of the Jira System Administrator global permission.

If you do not know which groups or users are granted the Jira System Administrator global permission, you will first have to find this information using steps 4 and 5. Otherwise, you can skip to step 6 in order to reset the password.

Jira's user password is stored in the cwd_user table. As Jira only stores the hash value of the password, we changed the user's admin password hash to uQieO/1CGMUIXXftw3ynrsaYLShI+GTcPS4LdUGWbIusFvHPfUzD7CZvms6yMMvA8I7FViHVEqr6Mj4pCLKAFQ==, which is the UTF-8-encoded hash value of sphere.


Importing data from CSV

Often, you will need to import data from other systems into Jira. For example, you might want to migrate data from an older bug-tracking system, or if you have data coming out of other systems, you may want to use this output to populate your project.

As systems often have their own data structure, it is often not this straightforward to perform data migration. However, the good news is that most systems can export data in CSV (or Excel, which can be easily transformed into CSV format); we will look at using CSV as a way to import data into Jira in this recipe.

Getting ready

When importing data into Jira, the most important thing is to prepare your input data file and make sure it is formatted correctly and contains all the necessary information. To help the importer, keep the following in mind:

  • Remove any non-data-related content, especially if you created your CSV file from a spreadsheet, which will help to keep the file size down.
  • If your file contains users who need to be imported into fields such as Assignee, make sure you use either their usernames or email addresses that can be matched against corresponding accounts in Jira.
  • If your file contains dates that need to be imported into fields, such as Due date, make sure they are all formatted using the same date format. This is so that Jira can process date values consistently.

How to do it...

To import data from other systems, perform the following steps:

  1. Log in to Jira as an administrator.
  2. Select the Projects menu from the top and select the Import External Project option.
  3. Select the CSV option. If, however, you see your system in the list, you can choose that instead. The process of using a system-specific importer will be mostly the same as the CSV importer, with some minor differences.
  1. Select the CSV file for the CSV Source File field. If you are performing an import for the first time, do not select the Use an existing configuration option. We will generate the configuration at the end of the import, and you will be able to use this to fast-track future imports.
  1. Expand the Advanced option if your file uses a different file encoding or uses a character other than a comma (,) as its separators. Click on the Next button to proceed to step 2 of the wizard:
  1. Select the project to import your data into. If you do not have a project, you can select the Select New option and create a project on-the-fly.

Generally, it is best to have the project created beforehand to ensure that it is set up with the correct configuration schemes, such as the workflow and fields.
  1. Verify the E-mail Suffix for New Users and Date format values used in your CSV file. This will ensure that data such as dates will be correctly parsed while being imported and saved in Jira's date fields, such as Due dates:
  1. Select and map the CSV columns to Jira fields. Certain fields, such as the Summary field, must have a corresponding column in the file; otherwise, Jira will not allow you to proceed. If you do not want to map a column, you can select the Don't map this field option.
  1. Select the Map field value option for any columns mapping to a selected list style field. This will allow you to map individual values from the CSV file column to options available in Jira. Unless you are sure that your file contents can be mapped to the Jira field options exactly, it is best to manually verify this; otherwise, you will end up with duplicated values due to, for example, case sensitivity:
  1. If you opt to map field values, review all of the listed values and map them to their corresponding field options in Jira. If a value does not have an option, you can type in the desired option and Jira will create it.
  2. Click on the Begin Import button to start importing your data into Jira:
  1. After the import process is completed, review the result. You can click on the Download a detailed log link to get a full log of the process if the import fails. You can also click on the Save the configuration link to get a copy of the mapping files so that, next time, you do not have to remap everything from scratch.

There's more...

Using CSV files to import custom data into Jira is the most versatile approach since many systems can export their data into CSV. However, as you will have noted already, Jira comes with a number of specialized importers for various systems. These importers often have additional features to help with data import. The Atlassian Marketplace website (https://marketplace.atlassian.com) also has a number of importers created by third parties. If you do not see your system listed in the out-of-the-box importers, make sure you do a search in the marketplace and check whether someone has already created an importer for it.


Copying configuration settings between Jira instances

If you have a controlled IT environment where changes need to go through development, testing/staging, and production processes, then, without a doubt, you will know how painful it is to promote Jira configuration changes across different environments. Since Jira does not provide a way to export configurations out of the box, all changes will need to be manually applied to each environment, which is both time-consuming and error-prone.

In this recipe, we will look at using a specialized tool that can help to make this process easier.

Getting ready

How to do it...

The Configuration Manager for Jira add-on requires you to first create a snapshot. A snapshot contains all the configuration settings you want to copy over to a different Jira instance.

You can create two types of snapshot:

  • System: This includes all configurations in Jira.
  • Project: This includes only configurations required for the selected project.

Proceed with the following steps to create a configuration snapshot:

  1. Navigate to Administration > Configuration Management > Snapshots.
  2. Click on the Add Snapshot button.
  3. Opt to create either a System Configuration or Project Configuration snapshot.
  4. Enter a name for the snapshot.
  5. Click on the Create button. The following screenshot shows the details of the snapshot we created:

Having created the snapshot, there are several ways in which we can promote and deploy changes to another Jira instance. We can either download the snapshot ZIP file and upload it or link the two Jira instances together with Application Link and load the snapshot remotely. We will use the snapshot file option in this recipe. Proceed with the following steps to deploy a snapshot:

  1. Log in to the other Jira instance as an administrator.
  2. Navigate to Administration > Configuration Management > Deploy.
  3. Select the From Snapshot File option.
  4. Choose the snapshot ZIP file.
  5. Click on the Deploy link to start the deployment.

The add-on will walk you through a deployment wizard, where it will analyze the contents of the snapshot and determine whether your current Jira system meets all the necessary requirements. For example, in the following screenshot, it has informed us that there is an add-on version mismatch:

After the add-on has determined that all the requirements are met, it will provide a quick summary of all the changes that will be applied (seen in the following screenshot). This is a good time to review the list of items to make sure we are not introducing unwanted changes accidentally, as shown in the following screenshot:

If everything looks good, we can finish migrating the configuration changes and deploy them to the target instance.

About the Author
  • Patrick Li

    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.

    Browse publications by this author
Latest Reviews (2 reviews total)
That's a nice book to read!
awesome! I recommend this book!
Jira 8 Administration Cookbook - Third Edition
Unlock this book and the full library FREE for 7 days
Start now