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.03 to 7.8.x. 

In the instructions on this page

  • AO_Home represents the directories in which you installed your BMC Atrium Orchestrator components, such as the CDP or repository.
  • In the migration tool file name, migration-tool-version.zip, replace version with the BMC Atrium Orchestrator version to which you are migrating data. For example, if you are migrating data to BMC Atrium Orchestrator version 7.8 the file name will be migration-tool-7.8.00.zip.

Note

Definitions for users already defined in BMC Atrium Single Sign-On or known to BMC Atrium Single Sign-On through an external definition are not altered.  User passwords cannot be exported from Access Manager, so a generated password is used during import. The password for a user imported into BMC Atrium Single Sign-On is set to the userid and padded with as many numbers (12345678) as needed to create a password of the required minimum length (default: 8 characters). The minimum password length is defined by BMC Atrium Single Sign-On.

For example, the userid "sam" will be assigned a password of "sam12345."  

Locating the migration tool utility

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

  • Download the migration-tool-version.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 the BMC Atrium Orchestrator platform, the migration-tool-version.zip file is located in the AO_Home\tools directory. 
    • (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.03 version to 7.8.x

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.8.x installation files. 
  • Your current environment is 7.6.03.
  • Stop all services for all platform server components (including Access Manager) on your 7.6.03 environment.
  • Back up the existing AMREPO and CDP servers or AM, Repository, and CDP servers.

To run the migration tool utility

Run the migration tool utility in your current 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.8.x environment. 

  1. In your current 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-version.zip file in the directory.
  2. Extract the contents of the zipped file.
    The migration-tool-version directory is created when you unzip the migration tool. This directory is referenced later in these instructions.
  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-version\runAuthTool.bat --export AuthorizationExport.xml

    • UNIX: ./runAuthTool.sh --export AuthorizationExport.xml

      Note

      When you run this command, the AuthorizationExport.xml export file is generated in the migration-tool-version directory.

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

  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.8.x.

    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_ADMINREPOSITORY_ADMINDESIGNER, 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. In your platform 7.8.x 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. 

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

    In this command, the options are specified as described in the following table.

    OptionsDescription

    migration-tool-version\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.8.x.

    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-version\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.8.x environment by using an independent repository database

You can install a new parallel 7.8.x environment along with your existing 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.03 environment to 7.8.x. 

Before you begin

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

  • You have downloaded the migration-tool-version.zip file from the BMC Electronic Product Download site (Support credentials required). 
  • You have downloaded the BMC Atrium Orchestrator Platform 7.8.x installation files. 
  • Your current environment is 7.6.03.
  • Access Manager and the repository are 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.8.x repository and perform the necessary configuration steps before starting the new repository.
  3. From the 7.6.03 repository UI, transfer the content to the 7.8.x 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.8.x repository.
  5. Shut down the 7.6.03 repository.
  6. Shut down 7.6.03 Access Manager (used by the old repository).
  7. From the 7.8.x repository AO_HOME\Repo\tools location, copy the migration-tool‑version.zip file and place it where your 7.6.03 Access Manager is installed.
  8. In the AO_HOME\AMRepo directory, extract the migration-tool‑version.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-version\runAuthTool.bat --export AuthorizationExport.xml

    • UNIX: ./runAuthTool.sh --export AuthorizationExport.xml

  10. In your platform 7.8.x 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. 

    migration-tool-version\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.8.x 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.8.x environment by using the same repository database

You can install a new parallel 7.8.x environment along with your existing 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-version.zip file from the BMC Electronic Product Download site (Support credentials required).
  • You have downloaded the BMC Atrium Orchestrator Platform 7.8.x installation files. 
  • Your current environment is 7.6.03.
  • Stop all services for all platform server components on your 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.8.x 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.8.xrepository AO_HOME\Repo\tools location, copy the migration-tool‑version.zip file and place it where your 7.6.03 Access Manager is installed.
  4. In the AO_HOME\AMRepo directory, extract the migration-tool‑version.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-version\runAuthTool.bat --export AuthorizationExport.xml

    • UNIX: ./runAuthTool.sh --export AuthorizationExport.xml

  6. On your platform 7.8.x 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. 

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

  7. Go to the 7.8.x AO_Home\Repo directory 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.

Using the migration tool video

This BMC Communities video (3:32) demonstrates how to use the BMC Atrium Orchestrator migration tool to migrate all authorization and authentication data from Access Manager in BAO 7.6.03 to BMC Atrium Single Sign-On in BAO 7.8.

 https://youtu.be/F0k1Z_5SLm0

Related topics

Transferring content between repositories
Migration tool options
Downloading the installation files
 

Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Vinnie Lima

    Before running the migration tool, you must stop the AMREPO service.  

    Nov 01, 2016 01:44
    1. Dorothy Poole

       Thank you for your comment. Where do you feel that think this instruction is missing? In the section on upgrading to 7.8.x (before running the migration utility), we instruct have the instruction, "Stop all services for all platform server components on your 7.6.03 environment." This includes Access Manager, which is a platform server component.

      Is there another place that you feel we should add the instruction to stop AMREPO? I'd like to add it if you feel that it is missing?

      Nov 02, 2016 08:12