The Behave Pro migrate cli tool is a Java based command line interface tool for migrating Behave Pro projects from Jira Server or Data Center to Jira Cloud.
Important notes before you begin
With all Behave Pro Cloud migration options, it is important that the numeric IDs for Jira issues and projects must be the same between Jira server and Jira Cloud so the migration tool can correctly map issues and scenarios between the two systems.
If you are migrating projects that use Behave Pro's git integration please do not use this tool. For Git-based projects, a migration can be as simple as connecting the Jira Cloud project to the Git repository.
How does the tool work
The cli tool communicates with both Jira Server/Data Center and Jira Cloud over the network. The tool can be used on any machine that has network access to both your Jira server and Jira Cloud. The initial release of the tool requires bash and JVM 8+ to work.
The tool works by exporting data from the Jira server and storing it on a local disk in a directory. Then the local copy of the data can be imported into Jira Cloud. Both export and import can be run for all projects or specified projects. Projects can be specified using their numerical id rather than project key.
The tool has been designed in this way so projects can be moved at selected times (reducing the load on your Jira server) and the ability to replay imports to help with test environments or recover from failed imports.
Installing the Behave Pro migrate tool
Download latest bp-migrate bp-migrate-0.8.0.zip
Extract the file and make it executable: $ chmod +x bp-migrate
You should then be able to run ./bp-migrate <subcommand> <args/flags> to run the program.
Tool commands
There are 3 essential commands for the migrate cli tool: clean, export, import
Clean
This command is used when you want to remove data exported from a Jira server. This could be done because you've completed the migration (always important to do this for security reasons) or the export of your Jira data is now old and you would like to export a new copy of the data.
./bp-migrate clean
This command deletes an entire directory and everything inside it. The default directory is export/ in your current directory. If you have used a directory other than the default you can specify that directory with the d flag.
Another directory can be specified with -d="another_dir/"
./bp-migrate clean -d="deleteThisPlease/"
Export
Export command with all possible options
./bp-migrate export [-ahVv] [-o=OUTPUT-DIRECTORY] -p=<password> -u=<username> -U=<url> [-t=<timeout>] [<projectIDs>...]
The username and password should be Jira username and password of a project administrator. If you use have SSO enabled for Jira please use the credentials you use for programmatic access.
Example usage
Export data from all projects to the export/ directory.
./bp-migrate export -u=admin -p=admin -U="https://ira.serverurl.com" --allProjects
Example usage
Export data from projects 100, 200 and 300 to the directory exportedData/ with debug level logging and a download timeout of 20 minutes.
./bp-migrate export -u=admin -p=admin -U="https://jira.serverurl.com" -o=exportedData/ -t=20 100 200 300 -vv
Import
./bp-migrate import [-FhkVv] -A=<apiKey> [-i=INPUT-DIRECTORY] [-P=<url>]
The import command tracks its progress. If an import times out or hits a rate limit you can simply re-run the same command and the import will continue it's progress from where it failed. If you need to override this functionality please use the -F flag to force a full import.
To use this command instead of your Jira Cloud username and password you will need a special import API key. A Jira Cloud administrator can Go to Settings > Apps in Jira Cloud and in the left sidebar navigate to BEHAVE PRO > Configure.
The URL used with -U flag is the address of your Jira cloud server.
Usage example
Import all data found in export/.
./bp-migrate import --apiKey="your_api_key" -U="https://your.atlassian.net"
Usage example with a customer directory
Import data from importedData/ directory.
./bp-migrate import --apiKey="your_api_key" --inputDir=exportedData/ -U="https://your.atlassian.net"
Usage example with a network proxy
Import data via a proxy server.
./bp-migrate import --apiKey="your_api_key" -U="https://your.atlassian.net" --proxy="http://localhost:8080"
If you encounter a PKIX or security certificate error, you should append -k flag.
WARNING: using this option makes the transfer insecure.