Migrating to JIRA: Retrospective

It’s been over a month since we deployed JIRA as our issue tracking tool, replacing IBM Rational ClearQuest.

It took me a few months to prepare for this move. At first I thought it would be a good opportunity to make some very needed changes in our issue tracking processes, but later on I realized it would be too much for the users, to handle both a new tool as well as major process changes.

Hence, the guiding concept for this migration was: let’s make it as close to our ClearQuest schema as possible (fields, workflows, screens, etc.). Then, as time goes by and we get to know JIRA better, we can make any changes we want to improve the process.

One exception to this was later added – try to adhere to JIRA’s ‘vanilla’ objects (fields, states, etc.) as much as possible. This is because many charts, reports, add-ons (e.g. GreenHopper) and other items expect certain fields or statuses to be present in order to utilize them properly.

Here’s how I prepared the migration:

  1. Learn the tool – both usage and administration. Of course, this required setting up a test server. having unlimited 10-user license for just 10$ is great for this purpose. Also, the ‘JIRA 101‘ help page was really useful for this. The scheme mapping page is also very useful to understand JIRA’s somewhat complicated scheme system.
  2. Create the issue types you want to migrate with all their fields – use built-in fields when possible, use custom fields for the rest. Try to keep the same field name & type as much as possible.
    – Since JIRA’s built-in (system) fields cannot be renamed, I found it useful to prepare a ‘map’ table between the ClearQuest field names and JIRA ones. This table was used later in training the users.
    – Checkboxes in JIRA are awkward. After a lot of stumbling I decided to repalce them with ‘Yes/No’ select lists, and figure out in the future what to do with them.
  3. Create the workflow for each issue type. Again using built-in states and transitions when possible. This is done by making a copy of the JIRA system workflow and modifying it accordingly.
  4. Create the appropriate screens and assign them to workflow transitions (where applicable).
    – In JIRA the screen are simply a vertical list of fields (can be separated into tabs). You don’t have much control on the layout except for the order of fields and tabs.
  5. Now it is the time for testing import from ClearQuest. Since there is no CQ-JIRA importer (either built-in or as a plugin), I used the CSV importer. I aimed for importing 10% of our ClearQuest issues, trying to cover everything (all issue types, all states, all fields). The process was as followed:
    – Export a set of records from ClearQuest as CSV
    – Manipulate the CSV to be compatible with JIRA (mostly regarding handling of attachments and multi-value fields)
    – Use the JIRA CSV Importer to import the issues. Handle all warnings/errors and re-import, until satisfied with the results.
    It sounds simple enough, but in reality it was quite painful. There were several changes needed for the CSV so I ended up scripting them. Also defining the mapping when importing into JIRA was time consuming and quite error-prone, and took several attempts until I got it right. But eventually I had well-tested scripts and import configurations to use when it’s time to go live.
  6. Now comes another painful task – trying to obtain the same behavior as we have in ClearQuest (and we had a heavily-scripted schema). Here JIRA has some limitations (as I mentioned in past posts:
    – The most obvious one is the lack of pre-functions for transitions.
    – JIRA comes with a useful, but very basic set of validators and post-functions.
    – JIRA has no built-in functionality for field-based behavior (i.e. making change in one field can affect other fields).
    There are many useful JIRA plug-ins that fill-in these gaps (except pre-functions, which is a JIRA inherent limitation). It takes time and patience to find the ones you need and try them out. Even with that, eventually some compromises were made. And it certainly made me feel our current process if far too complex than it should be.
  7. Show the system to a handful of R&D leaders and get their feedback. Force it out of them if you have too. I can’t stress that enough. Anything I didn’t handle at this stage was much more complicated to fix in production.
  8. Finally, everything was ready on time for the ‘go live’ milestone. I spent about 6 hours exporting and importing around 30,000 issues, but everything went smooth due to my intense preparations and pre-tests. I was very proud of my tedious preparations, I must say.
  9. Training sessions –  it was decided that most people can settle for a written ‘quick start’ guide (after all, JIRA is quite user friendly, especially that I’ve made it familiar by mimicking our ClearQuest schema). Only major users (Testers and R&D leaders) were given a 1-hour training session which was more than enough.
  10. Reception was good. I was a bit concerned that people won’t like the fact that it’s a web-based tool (as opposed to ClearQuest ‘rich’ clients), but no one seems to mind. Most people like the new tool better than ClearQuest. Many have pointed out that having a dashboard is a great benefit; as well as responsiveness and performance. And managers like all the colorful graphs and useful reports. And I was happy for getting this into production so smoothly (sure, there were some minor issues, but nothing I couldn’t immediately handle).

Bottom line – it was a major undertaking, perhaps the biggest challenge I’ve had in years, and being able to accomplish it with such good results is something I am very proud of.

Now I’m starting to wonder what it is like to migrate a version control tool. We’ve been using ClearCase for over 15 years, maybe it’s time for migration as well… time will tell.

9 thoughts on “Migrating to JIRA: Retrospective

  1. Thanks for the detailed post. I am in the same process of migrating ClearQuest to JIRA. I have used CQ earlier in my project. Could you elaborate by providing a sample of the script you had used and the process followed. Once we export from the clearquest what needs to be done for 1-2-1 mapping.

    • Hi Kiran,
      There are several things to consider, both when exporting CQ issues to csv, and when updating the csv to fit JIRA.
      It’s a bit lengthy for a comment, so I will add a separate post about it.

      • Thanks for your reply. I will be eagerly waiting for your post. In fact did a lot of research and only options were from 3rd party paid solutions. Your’s was the only one which talked about doing it all by yourself with custom scripting.

  2. Pingback: Migrating to JIRA – Technical | Adventures in SCM

  3. Good post. Migrations are indeed often a painful process to get right. I’ve done dozens of them into JIRA from many different systems over the past ten years.

    One thing I don’t usually recommend is copying the default JIRA workflow because it has unexpected restrictions on when JIRA statuses can be changed or the issue edited. It’s better to create JIRA workflows from scratch I find.

    • It’s true that the default workflow is quite restrictive, but I feel that it’s useful, at least for novice JIRA administrators – for example, allowing only developers to work on and resolve bugs. Even if it’s not always what the team needs, it provides a guideline, or at least something to think about, when creating or modifying transitions.

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