Migrating an R4J Tree from Data Center to the Cloud example

This repository exemplifies how to migrate the tree structure from a Jira Server/Data Center to a Jira Cloud instance using Python and the R4J APIs. It assumes that the Jira issues were already migrated to the Cloud using the Jira Cloud Migration Assistant or Jira Site import. The script will just copy the Tree structure. It won't create any issues in the Jira Cloud besides the R4J folders.

Table of Contents

• Pre-requisites
• Setup the development machine
• Preparing to run the migration script
• How to run the migration script
  • Optional: Clean up the tree
  • Migrate a Server or Data Center R4J tree to the Cloud
• Known Issues and Possible Improvements
• Disclaimer

Pre-requisites

• A Jira Server or Data Center instance with R4J 4.9* or greater installed and a project containing an R4J Tree Structure
• A Jira Cloud instance with R4J installed
• A project migrated to the Cloud using Jira Cloud Migration Assistant or Jira Site import and activated in R4J for both instances.
• The R4J Folder issue type is correctly configured in the Cloud instance. (See R4J Folder configurations )
• The R4J Folder issue type is associated with the project(s) to be migrated

*The script was tested and develop for R4J version 4.9 or greater. Nevertheless it might also work with older versions, but for these no tests were performed. We have reports of customers using versions 4.5 and 4.2.2 that successfully migrated their instances with this script.

Setup the development machine

1. Install Python 3.8.9 or greater Python official documentation
2. Clone the repository. How to clone a repository
3. Install the Python dependencies

    pip install -r requirements.txt

Preparing to run the migration script

The script relies on a set of parameters to run. Before running the script you need to set these up in the config.yaml file. This file is not committed to this repository.

Your config.yaml file should look something like this:

settings:
  cloud_env:
    # Cloud
    application_url: https://your-domain.atlassian.net
    username: cloud-your-username
    jira_api_token:  JIRAAPITOKEN
    r4j_api_token: R4JCAPITOKEN
    
  data_center_env:
    # Data Center
    application_url: https://www.mywebsite.com/jira/
    username: data-center-username
    password: data-center-password
    # pat: data-center-personal-access-token

Cloud instance configurations

1. application_url: URL of your Cloud instance.
2. username: Jira Cloud user with WRITE rights to the project being migrated.
3. jira_api_token: Jira API Token to access the Jira Cloud instance generated for the above user. https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
4. r4j_api_token: R4JC API token to access the R4J Cloud endpoints generated for the above user. https://easesolutions.atlassian.net/wiki/spaces/R4JC/pages/2250473484/API+Tokens

Server/Data Center configurations

1. application_url: URL to the Jira Server or Data Center instance.
2. username: User with READ access to the projects you want to migrate.
3. password: Password for the user.
4. pat: Alternatively to providing the username and password, you can provide a Personal Access Token (PAT)

How to run the migration script

Optional: Clean up the tree

The script assumes that the R4JC project tree is empty in the Cloud instance. If this is not the case, you can run the below command to empty it. It won't delete any Jira issues, but simply empty the tree. WARNING: If you run the below command, the project tree will be empty. This cannot be reversed.

python cloud_clean_tree.py {project_key}

Where project_key is the key to the Jira project you want to clean up.

Migrate a Server or Data Center R4J tree to the Cloud

To finally migrate a tree to the Cloud just run the following script:

python migrate.py {project_key} {dry_run: optional} {ignore_missing_issues: optional}

Setting dry_run to True allows you to verify if the migration is possible without actually creating any items in the Jira or R4J Cloud instance. After running it on dry run mode, an HTML file will open in your default browser showing the expected tree. Example:

python migrate.py {project_key} True

If you don't specify the dry_run command-line parameter, it assumes to be false.

DANGER: Setting ignore_missing_issues to True will migrate the tree even if not all issues are found in the Cloud instance. This must be done only on test instances for test purposes. Migrating a tree with missing issues makes no sense for a productive instance. It may lead to an unpredictable state which can only be recovered by completing erasing the Jira Cloud instance and restarting the full migration from scratch.

Known Issues and Possible Improvements

• The script doesn't migrate folder attachments
• The script doesn't check for user rights before running. If the users associated with the tokens cannot perform the needed operations, the script will fail leaving a potentially uncomplete R4J Tree in the Cloud instance.
• If the below error is encountered in the logs, check if there is an issue security configuration in the project. If yes, add the user performing the migration to the issue security level.

'error': 'Issue does not exist or you do not have permission to see it.'  

Disclaimer

THIS REPOSITORY IS PROVIDED BY THE CONTRIBUTORS “AS IS”. IT IS NOT AN OFFICIAL MIGRATION PROCEDURE SUPPORTED BY EASE SOLUTIONS OR ITS AFFILIATES. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.