search

agapoff / Lumper

YouTrack-to-Jira migration tool
9 stars 7 forks source link

readme

Lumper

The tool for migration from YouTrack to Jira: easy and for free

Table of Contents

  1. Capabilities
  2. Environment Setup
  3. Prepare YouTrack
  4. Prepare Jira
  5. Do all the job
  6. Things To Remember
  7. Needed Perl modules

Capabilities

Supported Versions (tested with):

Lumper can:

Lumper can not:

Note that creation time for the YouTrack issues can be applied to the real creation time in Jira by modifying the database directly. Follow these instructions to transfer values from custom field Original Creation Date to the Creation Time in Jira. You can safely delete the custom field after that.

Environment Setup

Perl

You'll need Perl installed on your machine. Most Linux distros already have it preinstalled, however, if you're using Windows, you should install in manually. Check these installation instructions for Perl.

J2M Tool

YouTrack is using regular markdown language to create rich text formatting (bold text, italic, headers etc). Jira is different - it supports some specific rich text formatting language. So if you want to save the text formatting you need to install special tool for Markdown -> Jira parser written in JavaScript (thanks to J2M Team). To do that follow these steps:

  1. Install npm for Windows/Linux
  2. Run this command in cmd/bash: 
    npm install j2m --save

Prepare YouTrack

  1. Allow to export more than 500 issues if needed: Global Settings -> Max Issues to Export
  2. Generate permanent token in your profile by clicking on profile image -> Profile -> Account Security -> Tokens -> New Token. Then copy generated token and paste to the config file described in the next article

Prepare Jira

  1. Remove from project screens all the mandatory fields that are absent in YouTrack
  2. Add Reporter field to the screens and add the permission for modifying reporter to your user
  3. Disable notifications for project and enable them after the migration to avoid overdisturbing the users
  4. If you are going to match some YT states to some Jira resolutions then you need to add Resolution field to the screens
  5. If you want to save the original creation date you must add Original Creation Date custom field in Jira (this field name is a subject to change). This must be the Date and Time type of a field.
  6. Please make sure that your project workflow allows all needed transitions right from the initial state. Maybe you will need to prepare a simplified workflow to proceed with the migration and get back to your cool workflow afterwards.
  7. Make sure that Issue Linking feature is enabled in you Jira instance if you're planning to export issue links

Here's the list of minimum required issue fields:

Do all the job

First you will need to rename config.pl_example to config.pl and edit it for your needs. The file is well-commented and you will have no problems with it if you have some familiarity with Perl syntax (even if not).

Then you just run the script:

./migrate.pl [--no-test|-t] [--verbose|-v] [--skip|-s N] [--max-issues|-m N]

--no-test or -t - Skip testing the passwords from JiraPasswords in config. You can save some time but if there is an invalid password then the script will fail while adding the comment from user with this invalid password. By default all the passwords will be checked and invalid ones will be excluded. Their comments will be recreated from the default user with mentioning the original users in the comment body.

--skip <number> ot -s <number> - skips the YT issues up to PROJECTKEY-N. This is useful for proceeding the migration from some breakpoint. For example if you have migrated the issues from KEY-1 to KEY-438 then you can proceed with KEY-439 by setting --skip=438.

--max-issues <number> or -m <number> - set the maximum number of issues to migrate. Useful for some testing purposes if you need to test the migration only for one (ony other amount) issue.

--verbose or -v - overwhelms you with its standard output.

--cookie-file or -c - explicit Jira cookie file location.

Lean back in you chair and prepare for a very long process.

After the job

Issue links are the last things copied over. If anything failed during the process and you had to start back again using --skip, then the links for the skipped issues may have been missed.

The ./syncLinks.pl script can be used to sync the issue links which may have been skipped. This should only be run if all of the issues migrated came over with the same number.

Things To Remember

Restrictions For Some Fields

Summary - the title of your ticket will be cropped according to Jira restriction (max 255 symbols)

Description - the body of the ticket cannot contain more than 32 767 symbols and it will be trimmed as well. However, long descriptions will be saved as description.md attachment.

Note On Some Specific Issue Types

Epic - this type of an issue requires special field Epic Name, this field is mandatory, so Lumper will fill it with Summary text.

Attachments

Attachments will be renamed to attachment<number> to avoid problems with exotic filenames. However, attachment links will be exported correctly.

Attachments will be saved on your hard disk during export process (in the temporary folder), please make sure you have enough free space for the whole process.

Needed Perl modules

Make sure all of them present in your perl environment.
To install these components you'll need cpan utility.

In cmd/bash type 

cpan

or you can run (which is the same)

perl -MCPAN -e shell

then, inside the cpan utility run

install <name_of_component>

Here's the list of used components: