Using the migration tool utility

This topic describes the scenarios in which you can run the migration tool utility to migrate all authentication and authorization data from BMC Atrium Orchestrator Platform version 7.6.02.06 or 7.6.03 to 7.7.02. 

• • Locating the migration tool utility
  • Upgrading from BMC Atrium Orchestrator Platform 7.6.02.06 or 7.6.03 version to 7.7.02
  • Installing a new, parallel 7.7.02 environment by using an independent repository database
  • Installing a new, parallel 7.7.02 environment by using the same repository database
  • Related topics

Locating the migration tool utility

You can locate the migration tool by using any of the following options:

• Download the migration-tool-7.7.02.zip file from the BMC Electronic Product Download site (Support credentials required).
  For more information about downloading the files from EPD, see Downloading-the-installation-files. 
• When you install platform 7.7.02, the migration-tool-7.7.02 zip file is located in the <AO_Home>\toolsdirectory. 
  • (Windows) In the <AO_Home>\tools, use the runAuthTool.bat file to run the tool. 
  • (Linux) In the <AO_Home>/tools, the runAuthTool.sh file is available. 

Upgrading from BMC Atrium Orchestrator Platform 7.6.02.06 or 7.6.03 version to 7.7.02

You can run the migration tool if you are currently on BMC Atrium Orchestrator Platform version 7.6.02.06 or 7.6.03 and you want to upgrade to version 7.7.02. Use this process if you want to upgrade your environment by using the same internal or external repository database. 

Before you begin

Before you run the migration tool, ensure that the following conditions are met:

• You have downloaded the BMC Atrium Orchestrator Platform 7.7 Service Pack 2 installation files. 
• Your current environment is 7.6.03, or 7.6.02.06.
• Stop all services for all platform server components on your 7.6.02.06 or 7.6.03 environment.
• Back up the existing AMREPO and CDP servers or AM, Repository, and CDP servers.

To run the migration tool utility

You run the migration tool utility in your current 7.6.02.06 or 7.6.03 environment to export the users, rules, roles, and permissions from the current environment and then import it in BMC Atrium Single Sign-On and BMC Atrium Orchestrator 7.7.02 environment. 

1. In your current 7.6.02.06 or 7.6.03 environment, go to the <AO_HOME>\AmRepo (if you have installed only Access Manager, go to the Access Manager directory) location and place the migration-tool-7.7.02 zipped file in the directory.
2. Extract the contents of the zipped file.

3. From the command prompt, go to the location where your Access Manager and the repository are installed and enter the following command to export the authorization data in an XML file. 

   Windows

   migration-tool-7.7.02\runAuthTool.bat --export AuthorizationExport.xml
   

   Linux

   ./runAuthTool.sh --export AuthorizationExport.xml
   

   The AuthorizationExport.xml export file is generated in the migration-tool-7.7.02 directory.

   Note

   Ensure that you copy the AuthorizationExport.xml export file and place it in another location before you upgrade to platform 7.7.02.

   The migration-tool-7.7.02 folder is created when you unzip the migration tool.

    

4. Install BMC Atrium Single Sign-On and ensure that it is up and running. 
   For information about installing BMC Atrium Single Sign-On, see Installing-BMC-Atrium-Single-Sign-On.  

5. Upgrade your repository to 7.7.02.

   Warning

   While upgrading the repository, do not start the server automatically after the upgrade.

6. Go to <AO_HOME>\Repo\tools and verify whether the migration tool files are still in the folder.

7. Create a properties file.
   This properties file is required only if you want to export the default roles available in Access Manager and import to BMC Atrium Single Sign-On as groups.

   Notes

   To import the default roles except ADMIN (GRID_ADMIN, REPOSITORY_ADMIN, DESIGNER, and USER) in BMC Atrium Single Sign-On, the repository and CDP, you need to create a properties file to map the roles to the new groups in BMC Atrium Single Sign-On. 

   This is an optional activity, which you can perform only if you want to import the default Access Manager roles. 

   However, after you migrate all your data in BMC Atrium Single Sign-On, you cannot run this tool again for importing the default roles.

   When you install the repository, by default an AoAdmin role is created in BMC Atrium Single Sign-On, which is equivalent to the ADMIN role in Access Manager. You need not import the default ADMIN role from Access Manager to BMC Atrium Single Sign-On. If you choose to import, then the ADMIN role will be assigned all permissions as per the USER role in Access Manager. For more information about role mapping properties file, see Using-a-role-mapping-file-to-import-default-roles.

   The following figure displays a sample properties file.

   ADMIN=adminnew
   GRID_ADMIN=gridadminnew
   REPOSITORY_ADMIN=repoadminnew
   DESIGNER=designernew
   USER=usernew

8. On your platform 7.7.02 environment, from the command prompt, go to the location where the repository is installed and enter the following command to import the authorization data in the repository. 

   Sample command for importing the data in BMC Atrium Single Sign-On and the respository

   migration-tool-7.7.02\runAuthTool.bat --roleMap RMNEW.properties --atssoPassword pass:bmc***** --import AuthorizationExport.xml

   Here, the options are specified as described in the following table.

   Options	Description
   migration-tool-7.7.02\runAuthTool.bat	Specifies the path to the .bat file required to import the data.
   --roleMap RMNEW.properties	Specifies the name of the role map properties file required to import the default roles. In the sample, the properties file is placed in the <AO_Home>\Repo folder. You can specify the path where your role map properties file is located.
   --atssoPassword pass:bmc*****	Specifies the BMC Atrium Single Sign-On password for the administrative connection to BMC Atrium Single Sign-On used to add users and groups or update group membership. This option is required to import users and groups in BMC Atrium Single Sign-On.
   --import AuthorizationExport.xml	Specifies the export file that you want to import. In the sample, the export file is placed in the <AO_Home>\Repo folder. You can specify the path where your export file is located.

9. Start the BAO-REPO service.
10. Log on to BMC Atrium Single Sign-On and the repository to verify whether the roles and permissions available in Access Manager are imported successfully. 

11. Upgrade your CDP to 7.7.02.

    Warning

    While upgrading CDP, do not start the server automatically after the upgrade.

12. From the command prompt, go to the location where CDP is installed and enter the following command to import the authorization data in CDP.

    migration-tool-7.7.02\runAuthTool.bat --roleMap RMNEW.properties --atssoPassword pass:bmc***** --import AuthorizationExport.xml

    The default and custom roles and permissions are imported successfully in CDP. 

13. Start the BAO-CDP service.
14. Log on to the CDP to verify whether the roles and permissions are imported successfully. 

Installing a new, parallel 7.7.02 environment by using an independent repository database

You can install a new parallel 7.7.02 environment along with your existing 7.6.02 or 7.6.03 environment and use an independent repository database. In such a scenario, the migration tool allows you to migrate the current users, groups, and permissions from the 7.6.02 environment to 7.7.02. 

Before you begin

Before you run the migration tool, ensure that the following conditions are met:

• You have downloaded the migration-tool-7.7.02.zip file from the BMC Electronic Product Download site (Support credentials required). 
• You have downloaded the BMC Atrium Orchestrator Platform 7.7 Service Pack 2 installation files. 
• Your current environment is 7.6.03, or 7.6.02.06.
• Access Manager and the repository is up and running.

To run the migration tool utility

1. Install BMC Atrium Single Sign-On and ensure that it is up and running. 
   For information about installing BMC Atrium Single Sign-On, see Installing-BMC-Atrium-Single-Sign-On.  
2. Install the platform 7.7.02 repository and perform the necessary configuration steps before starting the new repository.

3. From the 7.6.02.06 or 7.6.03 repository UI, transfer the content to the 7.7.02 repository. 
   For more information about transferring content between repositories, see Transferring content between repositories.

   Note

   If transfer permissions are required, add only the necessary permissions as these will be replaced at a later stage.

4. After all content is transferred successfully, shut down the 7.7.02 repository.
5. Shut down the 7.6.02.06 or 7.6.03 repository.
6. Shut down 7.6.02.06 or 7.6.03 Access Manager (used by the old repository).
7. From the 7.7.02 repository <AO_HOME>\Repo\tools location, copy the migration-tool‑7.7.02.zip file and place it where your 7.6.02.06 or 7.6.03 Access Manager is installed.
8. In the <AO_HOME>\AMRepo directory, extract the migration-tool‑7.7.02.zip file.

9. From the command prompt, go to the location where your Access Manager and the repository are installed and enter the following command to export the authorization data in an XML file. 

   Windows

   migration-tool-7.7.02\runAuthTool.bat --export AuthorizationExport.xml
   

   
   

   Linux

   ./runAuthTool.sh --export AuthorizationExport.xml
   

10. On your platform 7.7.02 environment, from the command prompt, go to the location where the repository is installed and enter the following command to import the authorization data in the repository. 

    Sample command for importing the data in BMC Atrium Single Sign-On and the respository

    migration-tool-7.7.02\runAuthTool.bat --roleMap RMNEW.properties --replaceRules --atssoPassword pass:bmc***** --import AuthorizationExport.xml

    This imports users and groups into BMC Atrium Single Sign-On and replaces the rules in the repository server. For more information about the options, see Migration-tool-options.

11. Start the 7.7.02 repository and confirm content access permissions.  
    Permissions assigned to "Default" must be manually adjusted according to local needs/policy as the migration tool does not alter these assignments.
12. Perform the same procedure for CDP.
13. Start the new CDP and confirm operation and process execution permissions.  
    Permissions assigned to "Default" must be manually adjusted according to local needs/policy — the migration tool does not alter these assignments.

Installing a new, parallel 7.7.02 environment by using the same repository database

You can install a new parallel 7.7.02 environment along with your existing 7.6.02 or 7.6.03 environment and use the same external database, which is configured with the existing platform.

Before you begin

Before you run the migration tool, ensure that the following conditions are met:

• You have downloaded the migration-tool-7.7.02.zip file from the BMC Electronic Product Download site (Support credentials required).
• You have downloaded the BMC Atrium Orchestrator Platform 7.7 Service Pack 2 installation files. 
• Your current environment is 7.6.03, or 7.6.02.06.
• Stop all services for all platform server components on your 7.6.02.06 or 7.6.03 environment.

To run the migration tool utility

1. Install BMC Atrium Single Sign-On and ensure that it is up and running. 

2. Install the 7.7.02 repository and perform the necessary steps to configure the external database.
   For more information, see Configuring-the-repository-to-use-an-external-database. 

   Warning

   While installing the repository, do not start the server automatically after the installation.

3. From the 7.7.02 repository <AO_HOME>\Repo\tools location, copy the migration-tool‑7.7.02.zip file and place it where your 7.6.02.06 or 7.6.03 Access Manager is installed.
4. In the <AO_HOME>\AMRepo directory, extract the migration-tool‑7.7.02.zip file.

5. From the command prompt, go to the location where your Access Manager and the repository are installed and enter the following command to export the authorization data in an XML file. 

   Windows

   migration-tool-7.7.02\runAuthTool.bat --export AuthorizationExport.xml
   

   Linux

   ./runAuthTool.sh --export AuthorizationExport.xml
   

6. On your platform 7.7.02 environment, from the command prompt, go to the location where the repository is installed and enter the following command to import the authorization data in the repository. 

   Sample command for importing the data in BMC Atrium Single Sign-On and the respository

   migration-tool-7.7.02\runAuthTool.bat --roleMap RMNEW.properties --atssoPassword pass:bmc***** --import AuthorizationExport.xml
7. Go to the 7.7.02 <AO_Home>\Repodirectory and delete the following indices:
   • ./repository/workspaces/security/index
   • ./repository/workspaces/default/index
   • ./repository/repository/index
8. Start the new repository and confirm content access permissions.  
   Permissions assigned to "Default" must be manually adjusted according to local needs/policy — the migration tool does not alter these assignments.
9. Install, but do not start, the new CDP.
10. Copy the Access Manager export file to the new CDP <AO_HOME>.
11. Run the migration tool in the new CDP for import; this imports rules into the CDP server.  
    The ‑‑atssoPassword option may be specified but is unnecessary if provided during Repository import.
12. Start the new CDP and confirm operation and process execution permissions.  
    Permissions assigned to "Default" must be manually adjusted according to local needs/policy — the migration tool does not alter these assignments.  Permissions originally assigned to USER may need additional work.

Related topics

Transferring-content-between-repositories
Migration-tool-options
Downloading-the-installation-files