Migrating to JIRA – Technical

When migrating from ClearQuest to JIRA, there are some several technical pitfalls which one may encounter. In this post I will detail the main issues which I tackled during the migration process.

The general strategy is to use as much of the built-in JIRA fields as possible, since many abilities and plug-ins uses them by default (such as JIRA Agile). It required effort, but it certainly paid off.

Let’s discuss the details, then:

Exporting to CSV

You will need to create queries, and export their results. Here are some guidelines below:

(a) Export each issue type (defect, feature, etc.) separately, as they will require different import configuration.

(b) Export resolved and unresolved issues separately. This is due to two reasons:

1. JIRA uses the built-in ‘Resolution’ field to determine whether an issue is resolved or not (for reports, boards, etc.).  So this field must remain empty when importing unresolved issues, and it must be filled when importing resolved ones

2. JIRA uses a single version field, ‘Fix Version/s’ to define the issue’s target version(s). For unresolved issues, it means what version(s) should the issue be handled in. For resolved issues, it means what version(s) was the issue handled in. If, like us, you have separate ClearQuest fields for these two cases (‘target version’ and ‘fixed in version’), you will have to map the correct field to the ‘fix Version’ field when importing.

(c) if you need the ClearQuest issue history, select it during the export process. It will be imported to JIRA as attachment (see below). Use the same export folder as the csv one.

(d) make sure to export attachments. Use the same export folder as the csv one.

(e) if you have a large number of issues (thousands), don’t export all at once. it will take more time, but will be safer and easier to export and import smaller ‘chunks’ of issues – preferably no more than 500 – each time (especially if you need to fix some specific problems and re-import).

Preparing History Files

We will import issue history as text file attachment. This is the Perl script I used to convert the exported history file (which contains all issues which were exported) into separate history file, one per issue. It will create a ‘dbid’ folder for each issue, if missing (each issue with attachments should already have this folder if you exported attachments).

# Convert the single CQ-exported defect history file to mutiple files, one per issue
use strict;
my $file = $ARGV[0];
($file) || die "Missing argument: history.txt file";
open(HIST,"<$file") || die "Can't open $file: $!";
my $header_line = <HIST>;
foreach my $line (<HIST>)
 $line =~ s/\"//g;
 my ($dbid,$display_name,$action_timestamp,$user_name,$action_name,$old_state,$new_state,$comments) = split(/\,/,$line);
 my $hist_file = "${dbid}\\history.txt";
 print IDHIST "\"$dbid\",\"$display_name\",\"$action_timestamp\",\"$user_name\",\"$action_name\",\"$old_state\",\"$new_state\",\"$comments\"\n";

Preparing Attachments for Import

JIRA CSV import requires the attachment to be available from a URL. I couldn’t make it work using file:// so I ended up setting an Apahce web server on some old machine which was lying around. Then I copied the entire attachment export folder to the web root of the server. This way i could access attachments using a URL like http://mywebserver/33564151/screenshot.jpg

Preparing the CSV for Import

This required developing quite a complicated script, but it largely depends on how much customization your ClearQuest installation has. There are some common issues that needs to be handled though. 

(a) multi-value fields  – including attachments –  you need to add a separate column for each value (you will have several columns with the same title). This means that you need to check which issue has the most values in each such field, add the appropriate number of columns to the CSV, and then fill the values.

(b) non-ASCII characters: you might need to convert them to base characters, that depends on the JIRA version and encoding supported by the database you use.

(c) I recommend you keep the existing ClearQuest issue IDs – but you will need to change the format to JIRA’s one (e.g. SAMPL-251 instead of SAMPL00000251). If possible, keep the same project name as well – your users will like that.

(d) You will want to add a ‘resolution’ field (empty for unresolved issues, ‘Fixed’ for resolved ones) if you don’t have an equivalent one in ClearQuest.

You might want to consider adding other built-in JIRA fields if you don’t have the equivalent ones, for readability and completeness. Things like ‘resolved’ (the date/time when the issue was resolved).

(e) You may need to generate new fields based on existing ones, for example our version fields were split to ‘major vesion’ and ‘minor version’, but in JIRA we decided to use the built-in fields, so the script needed to ‘combine’ the values of the major and minor version field to a single value

(f) you may need to change the format of fields, such as work time, if you want to map them to the built-in JIRA fields (in our case we used hours, but the CSV import required seconds)

(g) you may want to convert checkboxes to ‘yes/no’ fields (see my JIRA migration retrospective post))

The Import Process

The initial import test should be done in stages, so that you gradually build a working import configuration file while controlling changes to both the CSV update script and the jira instance. Here is my recommendation; the most important thing though is to document any change you make in the JIRA instance. You will need to reproduce these changes in the production JIRA server.

(1) Start by importing the csv files, mapping only built-in JIRA fields (I recommend using a clean JIRA instance without any plug-ins). Make sure to map values for the status field and priority (“severity” in default ClearQuest). Save the import configuration file, and test the results. you will probably need to tweak the issue types, priorities and statuses, as well as project-specific items (versions, components)

(2) Re-run the import (using the configuration file you saved), this time add all text-based and single-select fields. save the configuration again and test the results.

(3) Re-run the import, adding multi-selection fields, attachments, and any other fields. Save the configuration and test the results.

(4) delete and re-create the project. run the import again with the latest configuration file and test the results. Once satisfied, involve other users in the testing, they may see things you don’t!

Final Words

As I mentioned, there are a lot of technical challenges to handle until the import process  runs smoothly. This will require time, patience, and thoroughness. I can only say that it’s extremely rewarding when you finally get it right.

Good luck!



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s