WARNING: This utility is still in beta. Please inform us before using this utility. 

Take the backup of your existing RMsis database which can be restored before executing this utility.

Migration utility can be used to backup & restore single project from one JIRA+RMsis instance to another. 

At present, this utility is compatible with RMsis v1.8.9.1.1-r324.

• In case you are using an older version, please update your RMsis to the above mentioned version. 
• If the version being used by you is later than RMsis v1.8.9.1.1-r324, please let us know. We will send the updated version of this utility.

Please note that some changes are expected for different versions of RMsis.

Pre-Requisites:

• Download and install JAVA 1.8 and set the JAVA_HOME Variable.

• Execute the Migration Validator before performing the backup and restoration using this utility. See https://docs.optimizory.com/x/qJ7B for details.

Note: The execution will fail if above two requirements are not met.

Steps to create the dump of existing database:

1. Download the migration utility(migrateutil-1.0.0-RC-05.zip) and store it on the JIRA+RMsis server. (Please send a mail to support@optimizory.com to get the link to download the utility)

   •  

   • Here, migrateutil-1.0.0-RC-05.zip is stored in the "/Users/pritam/path/to/migrationUtility" directory.

2. Extract the contents of the zip file. 

   •  

   • A directory with name "migrateutil-1.0.0-RC-05" will be created.
     

3. Switch to the directory migrateutil-1.0.0-RC-05 and create a directory with name "backup" where the contents of the existing database will be dumped.

   •  
   • Here, a directory named "backup" is created which will be used later to store the database backup.
4. Create a copy of the file migrateutil-1.0.0-RC-05/conf/jdbc.properties.template and save it with the name "jdbc.properties" and then open it in the text editor. The contents of the file is displayed in the image attached below:
   • 
5. The newly created file will be used by the utility to access the RMsis database. You will have to update the database connection details in the file. The following properties needs to be updated:
   1. jdbc.driver: Leave it's value to default (as already present in the jdbc.properties file). This field is used to identify the jdbc driver used to connect to RMsis database.
   2. jdbc.url : Update the IP address and port number of the database server if required. 
   3. db.typeName : Leave it's value to default. This field is used to identify the type of database to be used with RMsis. MySQL is being used here.
   4. db.schemaName : Replace rmsisDatabaseName with the name of the database being used for RMsis.
   5. jdbc.username: Replace it with the username used to connect to RMsis database server.
   6. jdbc.password: Replace it with the password used to connect to RMsis database server.
      
      
   • For example, if  you are using a MySQL database with RMsis having name "rmsisDb". The content of the updated file will look like the image mentioned below:
     

6. Copy the files projectDetails.properties and usersMap.properties created using migration-validator.jar into migrateutil-1.0.0-RC-05/conf directory.

   • Details about migration-validator is available at https://docs.optimizory.com/x/qJ7B
   • 

7. Execute the migration utility using the following command to dump the database content: 

   • -b switch is used to specify the location of the directory where the backup will be stored, here it is the location of the "backup" directory created in step 3.

   • -v switch is used to specify the version of RMsis presently in use. Here, it is v1.8.9.1-r318. Format used: v<RMsisVersionNumber>-r<RMsisBuildNumber>

   • -j  switch is used to specify the location of the jdbc.properties file created and updated in step 4 & 5.

   • -p switch is used to specify the project whose data is to be dumped. PKEY is the project key of the project. Here, it is FIR.

   • dump is the name of the command which directs migration utility to create the backup of RMsis database

     Command to create the backup using migration utility

      ./bin/migrateutil -b /path/to/migrationUtility/backupDirectory/ -v v1.8.9.1.1-r324 -j /path/to/migrationUtility/conf/jdbc.properties dump -p PKEY
      
     Example: 
     ./bin/migrateutil -b /Users/pritam/path/to/migrationUtility/migrateutil-1.0.0-RC-04/backup/ -v v1.8.9.1.1-r324 -j /Users/pritam/path/to/migrationUtility/migrateutil-1.0.0-RC-05/conf/jdbc.properties dump -p FIR
      
     ./bin/migrateutil -b ./backup/ -v v1.8.9.1.1-r324 -j ./conf/jdbc.properties dump -p FIR

   • 

8. Upon successful execution, the database content will be dumped in the directory specified to create the backup using the -b switch. Here, a directory named "318-1.8.9.1-2018-05-11"  is created inside the "/Users/pritam/path/to/migrationUtility/migrateutil-1.0.0-RC-05/backup/" directory.

   • 

9. Copy the migrateutil-1.0.0-RC-05 directory on the destination server. The contents of conf and backup folder will be used to restore the RMsis data on destination database.

Steps to restore the backup to target database:

1. Restore the JIRA project data and run migration-validator.jar to validate if pre-requisites for data restoration is met or not. Make necessary changes if required.
   • Details about migration validator is available at See https://docs.optimizory.com/x/qJ7B
2. Copy the entire  migrateutil-1.0.0-RC-05 directory along-with its content onto the destination server. 
   • It must contain the backup directory which contains the RMsis backup. Here migrateutil-1.0.0-RC-05/backup contains the backup.
   • It should also contain the configuration files created earlier in migrateutil-1.0.0-RC-05/conf directory. Namely jdbc.properties, projectDetails.properties and usersMap.properties.
3. Update the database connection details as per the target RMsis database in the conf/jdbc.properties file as per the steps mentioned in step 5 of "Steps to create the dump of existing database". 
   
   • For example, if  the target database MySQL database having name "rmsisRestoredDb". The content of the updated file will look like the image mentioned below:
     • 
4. Execute the migration utility using the following command to restore the backup in target RMsis database: 

   • -b switch is used to specify the location of the directory where the backup of previous data is stored, here it is the location of the "backup" directory.

   • -v switch is used to specify the version of RMsis presently in use. Here, it is v1.8.9.1-r318. Format used: v<RMsisVersionNumber>-r<RMsisBuildNumber>

   • -j  switch is used to specify the location of the updated jdbc.properties file which contains the details of target RMsis database.

   • restore is the name of the command which directs migration utility to restore the backup of old RMsis database into destination database.

   • -x switch is used to specify that RMsis database already exists. This will restore the additional data related to single project only.
   • Command to restore the backup using migration utility

     ./bin/migrateutil -b /path/to/migrationUtility/backupDirectory/ -v v1.8.9.1.1-r324 -j /path/to/migrationUtility/conf/jdbc.properties restore -x
      
     Example: 
     ./bin/migrateutil -b /Users/pritam/path/to/migrationUtility/migrateutil-1.0.0-RC-05/backup/ -v v1.8.9.1.1-r324 -j /Users/pritam/path/to/migrationUtility/migrateutil-1.0.0-RC-05/conf/jdbc.properties restore -x
      
     ./bin/migrateutil -b ./backup/ -v v1.8.9.1.1-r324 -j ./conf/jdbc.properties restore -x

5. Upon successful execution, the database content will be restored to the destination database.