Running the migration tool

This topic describes how to use the migration tool to migrate your data from TrueSight Capacity Optimization to BMC Helix Continuous Optimization. 


Related topics

Migrating-to-BMC-Helix-Continuous-Optimization

Migration-process-overview

Before you begin

Before you migrate data, make sure that the following requirements are met:

  • You have administrator privileges for accessing TrueSight Capacity Optimization.
  • TrueSight Capacity Optimization is upgraded to version 20.02. To migrate data from a version earlier than 20.02, you must first upgrade to 20.02 and then migrate data to BMC Helix Continuous Optimization.
  • You have reviewed key considerations.
  • You have prepared your target environment by completing the premigration tasks.

To migrate data

Perform the following tasks:

  1. As an OS user, log in to the host computer on which the TrueSight Capacity Optimization Application Server is installed and the migration toolkit is copied as described in the premigration tasks. The OS user is the user that you specified during the Application Server installation (for example: cpit).

    No. You need not stop any TrueSight Capacity Optimization services and ETL data collection. Migration activity can be performed parallelly without needing to stop any services in the source environment.

  2. Extract the contents of the toolkit file. Make sure that the OS user has the read and write permissions to the extracted migration toolkit folder. 
    The extracted folder contains the following directory structure and files:

    Folder or file

    File

    Description

    bin

    NA

    Contains the jar file of the migration toolkit.

    conf


    Contains customizable properties and configuration files.

    application.properties

    Contains the parameters of the target environment to which you want to migrate data. You need to specify the values of the following parameters.

    • helix.host: Base URL of BMC Helix Portal
    • helix.tenant: ID of BMC Helix tenant
    • helix.accessKey: Access key to authenticate the user who is performing the migration to connect to BMC Helix tenant
    • helix.accessSecretKey: Secret key to authenticate the user to connect to BMC Helix tenant

    • (Optional parameter) dry-run: Parameter that indicates the test run of the migration. Set this parameter to true if you want to perform a dry run of the migration and avoid migrating any real data to the target environment.

      Best practice
      We recommend that you perform the dry run of the migration utility using the dry-run=true parameter before you run the actual migration.

    • (Optional parameter) migrate-datamarts-and-views: Set this parameter to false if you do not want to migrate datamarts and views. By default, this parameter is set to true.

    cpit.properties

    Contains internal configurations for the migration toolkit.

    ds.properties

    Contains configurations to connect to the source database.

    log4j.conf

    Contains log configurations.


    Note: You need to configure the application.properties file only. Other files are used by advanced users or developers.

    run.sh


    Script used to launch the migration toolkit.

  3. At the shell prompt, change to the directory where you extracted the toolkit files.

    Tip

    You can run the ./run.sh command to view the help for the available options.

  4. Run the following command to provide the execute permission for the run.sh script to the OS user.

    chmod +x run.sh
  5. Configure the application.properties file.
    1. Navigate to the /conf folder and edit the application.properties file.
    2. Specify the host URL, tenant ID, and API key values that you obtained during the prerequisites procedure, and save the file.

  6. Run the following command to set CUSTOM_JAVA_HOME to the folder with JDK17 installed in the preparation steps:

    export CUSTOM_JAVA_HOME=[directory path of the JDK17]

    For example:

    export CUSTOM_JAVA_HOME=/data/jdk17/jdk-17

  7. Run the following command to start the migration:

    ./run.sh -b [environment variable/base directory of Capacity Optimization]  

    For example: 

    ./run.sh -b /data/bmc/BCO/

    The migration toolkit creates a dump of configurations in the migration-toolkit.zip file and sends this file to BMC Helix Continuous Optimization.

  8. Monitor the progress and status of the migration and logs by using the Migrator system task in BMC Helix Continuous Optimization. Check if the Migration task is completed successfully with no errors.  
    For details about running or scheduling a system task, see Managing-ETL-and-System-tasks. 
    The data is migrated in two phases:
    • In phase 1, the migration tool extracts all configurations, such as definition of entities, relationships, tags, analysis, models, external DB connections, and entity catalogs, and migrates this data to BMC Helix Continuous Optimization. This Migrator system task might take up to few minutes to be completed.
      After this task is complete, review the ORACLE_HOME path in BMC Helix Continuous Optimization > Administration > ETL & SYSTEM TASKS > External DB connections. Specify the ORACLE_HOME path for the Oracle client of the Helix Remote ETL Engine if this path is not same as the path for the Oracle client of the TrueSight Remote ETL Engine. 
      For more information, see Adding-external-database-connections.
    • In phase 2, the Remote ETL Engine of  BMC Helix Continuous Optimization schedules a set of ETLs to migrate the historical data from the source environment. After this data migrator ETL task completes at least one run, you can see data for last 7 days, as these ETLs migrate historical data of 7 days at a time. Depending on the size of the historical data, it might take from few hours to a couple of days to completely migrate the historical data. 
  9. Validate data in BMC Helix Continuous Optimization. 
    Validate whether all ETLs, historical data, and Workspace data are migrated in BMC Helix Continuous Optimization and perform a sanity check of the environment.


Post migration tasks

Perform the following post migration tasks:

  • Some default user groups and roles are available out of the box when you subscribe to BMC Helix Continuous Optimization. You can start using the product with these users. Additionally, you can configure more users and roles in BMC Helix Portal.
  • (Optional) If you missed to configure the service account key file for GCP API Extractor to be read from the upload compressed folder option as suggested in Preparing-for-migration, you need to reconfigure the service account key file setting after migration. For details, see Google-Cloud-Platform-GCP-API-Extractor.


Troubleshooting

  • Although all the data marts are migrated, some of the SQL data marts might be in the Error or Warning status in BMC Helix Continuous Optimization after migration. You need to resolve issues in such data marts. For more information, see Resolving-SQL-data-mart-issues-after-migration.
  • If you have performed the migration by using the migration toolkit provided in versions earlier than 23.3.02, the minimum and maximum values for metrics of migrated entities might be missing. To resolve this issue, provide a list of these entities in a custom property of the data migrator ETL and rerun the ETL. For details, see Troubleshooting-issues-with-the-migration-of-min-and-max-values-of-entities. 


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*