Helix Control-M Custom Migration

The Helix Control-M custom migration migrates your self-hosted Control-M/EM data to Helix Control-M and enables you to determine which self-hosted Control-M/Servers migrate to Helix Control-M and which remain self-hosted, but connected to Helix Control-M via Unified View. You also can determine which Control-M for z/OS environments connect to Helix Control-M via Unified View. This migration eliminates the need to maintain Control-M/EM, migrated Control-M/Servers, and their associated databases.

Migrating to Helix Control-M

This procedure describes how to migrate your self-hosted Control-M/EM data and Control-M/Servers to Helix Control-M, or connect your self-hosted Control-M/Servers and Control-M for z/OS environments to Helix Control-M in Unified View.

Before You Begin

Begin

  1. Register for a Helix Control-M tenant, as described in Registering for Helix Control-M.

    This enables BMC to provide you a Helix tenant that contains Helix Control-M/Servers which match the time zones and Control-M/Server names in your current, self-hosted environment.

  2. Migrate your self-hosted Control-M/EM to Helix Control-M, as described in Migrating Your Self-Hosted Control-M/EM to Helix Control-M.

  3. Do one of the following for each Control-M/Server or Control-M for z/OS in your current self-hosted environment:

  4. Resume Production: Resumes all connected, self-hosted Control-M/Servers and Control-M for z/OS environments, as described in Resuming All Connected Self-Hosted Control-M/Servers and Self-Hosted Control-M for z/OS Environments.

Registering for Helix Control-M

This procedure describes how to register for a Helix Control-M environment that contains the names and time zones of the Control-M/Servers that you intend to migrate. After registration, you will receive an email from BMC Customer Service with a link to the SaaS Subscription Registration form. If you do not receive this email, you must contact your customer service representative.

You must perform this procedure only once.

Before You Begin

Begin

  1. Open the migration metadata file from the following location:

    • UNIX/Linux: <Migration_Path>/output/migration_metadata.xlsx

    • Windows: "<Migration_Path>\output\migration_metadata.xlsx"

  2. From the Time Zone drop-down list next to each Control-M/Server, select your Control-M/Server time zone.

  3. Save the file and upload it in the Helix Control-M Migration - Technical Migration Details section of the SaaS Subscription Registration form.

  4. Complete and submit the SaaS Subscription Registration form.

    A confirmation email with a link to your new Helix Control-M environment arrives after it is ready.

Migrating Your Self-Hosted Control-M/EM to Helix Control-M

This procedure describes how to migrate your self-hosted Control-M/EM to Helix Control-M. This migration exports your Control-M/EM data to an export file, uploads it to an Amazon S3 bucket, transfers the file, uncompresses it, and then integrates it into your new Helix Control-M tenant. If your Control-M/EM is not connected to the internet, you can transfer the export file to any internet-accessible Windows or Linux host and then continue the migration.

Before You Begin

  • Verify that Control-M/EM 9.0.21.300 or higher is installed on your self-hosted Control-M/EM.

Begin

  1. Log in to Helix Control-M with a user that is associated with an Admin role, and generate and record the value of an API token, as described in Creating an API Token.

  2. Download the Helix Control-M/EM Migration Tool to your self-hosted Control-M/EM from Helix Control-M/EM Migration Tool, and unzip it to a temporary folder.

  3. From the command line, navigate to the export directory in the unzipped migration folder, and then and run one of the following commands to export your Control-M/EM data to a compressed archive (*.tar.gz) file:

    • Windows: run_saas_migration_export.bat

    • Linux: run_saas_migration_export.sh

    The export tool runs, produces a compressed archive export file named EMExportForSaaS.tar.gz, which contains your self-hosted Control-M/EM data, and saves it to the temporary folder.

  4. From an internet-accessible host—either your Control-M/EM or a separate Windows or Linux host—do the following:

    1. Verify that Python 3.8 or higher and a pip or pip3 Python package-management system is installed.

    2. If you use a proxy server, define the following environment system variable:

      • Name: https_proxy

      • Value: http://<Proxy_Server_Address>:<Proxy_Server_Port>

    3. Verify that you have outgoing internet access to the following locations:

      • *.controlm.com:443

      • *.amazonaws.com:443

    4. From the internet-accessible host, navigate to the import directory in the unzipped migration folder, and then run the following command to import your Control-M/EM data to Helix Control-M:

      • Windows: run_saas_migration_import.bat

      • Linux: run_saas_migration_import.sh

    5. Navigate to the import directory in the unzipped migration folder, and do one of the following to import your Control-M/EM data to Helix Control-M:

      • From your internet-accessible Control-M/EM, run the following command:

        • Windows: em ./run_saas_migration_import.bat

        • Linux: em ./run_saas_migration_import.sh

      • From your separate internet-accessible host, run the following command:

        • Windows: ./run_saas_migration_import.bat

        • Linux: ./run_saas_migration_import.sh

  5. At the prompts, type the requested information, as described in Import Parameters.

    The import tool runs and a number of status messages appear that describe the steps of the import process.

Import Parameters

The following table describes the parameters that you must provide at the import tool prompts in Migrating Your Self-Hosted Control-M/EM to Helix Control-M.

Parameter

Description

Helix Control-M Automation API Endpoint

Defines the Helix Control-M Automation API endpoint, in the following format:

<Tenant_Name>-aapi.<Zone>.controlm.com

Control-M Automation API Token

Defines the API token that you created in Migrating Your Self-Hosted Control-M/EM to Helix Control-M.

Compressed Archive Export File Pathname

Defines the pathname of the compressed archive export file that you created in Migrating Your Self-Hosted Control-M/EM to Helix Control-M.

<Temporary_Folder>HelixEmMigrationTool\export\EMExportForSaaS.tar.gz

Python Interpreter Name

Defines the name of the Python interpreter that converts source code into machine language, as follows:

  • Control-M/EM Host: bmcpython

  • Other Host: Press ENTER to define the default Python interpreter—python3.

Migrating a Self-Hosted Control-M/Server to Helix Control-M

This procedure describes how to migrate your current self-hosted Control-M/Server to Helix Control-M. You must perform this procedure for every Control-M/Server in your environment. You can run this tool from any Windows or Linux computer.

  • You cannot migrate Control-M for z/OS environments to Helix Control-M, however you can connect them to Helix Control-M Unified View.

  • You cannot connect Control-M/Servers with Agents on unsupported operating systems or with unsupported plug-ins to Helix Control-M Unified View.

Before You Begin

  • Verify that the most recent version of Control-M Automation API is installed on Control-M/EM Server. For more information, see Automation API Installation.

  • Verify that you have access to the Control-M/EM database.

Begin

  1. Download the Helix Control-M Migration Tool migration tool, based on your operating system, from Helix Control-M Migration Tool, and unzip it to a temporary folder.

  2. (Optional) To migrate %%LIBMEMSYM variable lists, create a %%LIBMEMSYM Control File, as described in Helix Control-M Custom Migration.

  3. From the inputParameters folder, inside the unzipped migrateToHelix folder, open the parameters.txt file in a text editor and define the Scan mode parameters, as described in Helix Control-M Custom Migration.

  4. Do the following:

    1. Run the following command:

      migrateToHelix.bat e

      The extraction scan runs and produces an Excel-based Qualification Report.xlsx file in the report folder, which includes one or more of the following results in the Qualification Summary sheet:

      • Passed

      • An automatic adjustment was made.

      • Manual action is required.

      • An incompatibility was found.

    2. From the report directory in the unzipped folder, open, review, and follow the directions in the Qualification Report.

  5. Verify that no jobs are executing and pause your self-hosted Control-M/Server, as described in Pausing a Control-M/Server or config server::pause.

  6. Unmanage the Control-M/Server, as described in Unmanaging a Control-M/Server or config server::unmanaged.

  7. Set the desired state of the Control-M/EM Gateway to Down from the CCM or via the following ccmcli utility command:

    ccmcli -u <Username> -p <Password> -t Gateway -n <Component_Name> -h <Component_Host> -cmd stop

  8. Do the following:

    1. Run the following command:

      migrateToHelix.bat e

      The extract scan runs a second time and produces an Excel-based Qualification Report.xlsx file in the report folder, which includes one or more of the following results in the Qualification Summary sheet:

      • Passed

      • An automatic adjustment was made.

      • Manual action is required.

      • An incompatibility was found.

    2. From the inputParameters folder, inside the unzipped migrateToHelix folder, open the parameters.txt file in a text editor, define the parameters for the Deploy Only mode, as described in Helix Control-M Custom Migration. If necessary, redefine the parameters that you defined when you ran the extraction scan.

    3. From the command line, navigate to the temporary folder where you unzipped the migration tool folder and run the following command: 

      migrateToHelix.bat deployOnly

      The tool migrates your Control-M/EM and the defined Control-M/Server to Helix Control-M, and produces an Excel-based DeployOnlyReport.xlsx file in the report folder.

  9. (Optional) Migrate Control-M MFT local connection profiles and Application-Integrator-created plug-in connection profiles to Helix-supported centralized connection profiles, as described in Migrating Local to Centralized Connection Profiles.

  10. From the report folder, open, review, and follow the directions in the Deploy Only Report, which might ask you to do the following in Helix Control-M:

    1. Redefine all centralized connection profile passwords.

    2. Redefine jobs to run on supported Agentless Hosts, as described in Agentless Hosts.

    3. Redefine unsupported notification destinations that are listed in the Deploy Only report, as described in Notification Destinations.

    4. Redefine folders that exceed 20,000 job runs at New Day, as described in the Run Method folder attribute in Folder General Attributes.

    5. Redefine only global event prefixes that reference a migrated Control-M/Server, as described in Creating a Global Event Prefix.

      You must view current self-hosted Control-M/EM global events in the Global Events Prefix Workspace in the Tools domain.

    6. Redefine all Control-M Automation API tokens wherever they are used, such as OS job scripts, and change all credentials in Connection Profiles to API tokens, as described in Creating an API Token.

    7. Run test jobs on all connected Helix Agents to validate plug-in job Run as Users and connection profiles to confirm that the new Helix Control-M environment is ready for production.

    8. In all deactivated folders that are listed in the Deploy Only Report, remove the _ (underscore) prefix that was appended to the Run Method name during the Deploy Only migration.

  11. Get started with Helix Control-M, as described in Getting Started.

Migrating Local to Centralized Connection Profiles

This procedure describes how to migrate Control-M MFT local connection profiles and Application-Integrator-created plug-in connection profiles to centralized connection profiles in Helix. You must perform this procedure on every Agent that contains Control-M MFT and Application-Integrator-plug-in-created local connection profiles that you want to migrate.

Before You Begin

  • Verify that Control-M/Agent 9.0.21 or higher is installed.

  • Verify that Helix Agent 9.0.21.200 or higher is installed.

Begin

  1. Download the Helix Control-M LCP-to-CCP Migration Tool, based on your operating system, from Helix Control-M Migration Tool, and unzip it to a temporary folder.

  2. From the self-hosted Agent, navigate to the temporary folder where you unzipped the LCP-to-CCP migration tool, and run the following command to export your local connection profiles:

    lcpToCcp -export [-pluginType <MFT, AI, or ALL>] [-agentDir <Windows_Agent_Directory_Pathname>]

    For more information, see Connection Profile Migration Parameters.

    The directory path and filename of the zipped exported local connection files appears.

  3. Copy the zip file to the Helix Agent.

  4. From the Helix Agent, run the following command to migrate the zipped local connection profiles to centralized connection profiles:

    lcpToCcp -import -path <ZIP_Pathname_and_Filename> -url <Automation_API_URL> -token <API_Token> -ctm <Control-M/Server> -agent <Agent> [-cpnp <OVERWRITE, SKIP, or ASK>] [-d <TRUE or FALSE>] [-agentdir <Agent_Directory_Pathname>]

    For more information, see Connection Profile Migration Parameters.

    The local connection profiles from the self-hosted Agent are migrated to centralized connection profiles in Helix.

Connection Profile Migration Parameters

The following table describes the parameters that you must define when you migrate your Control-M MFT and Application Integrator local connection profiles to centralized connection profiles in Helix Control-M.

Parameter

Description

-pluginType

(Optional) Determines which plug-in connection profiles are exported, as follows:

  • ALL: Exports the Control-M MFT and Application Integrator local connection profiles.

  • FileTransfer: Exports the Control-M MFT local connection profiles.

  • AI: Exports the Application Integrator local connection profiles.

Default: ALL

-agentDir

(Windows only) Defines the Agent directory pathname where the connection profiles are stored.

You must use this parameter if you have multiple Agents on the same host.

Default: Defaults to the local Agent directory.

"C:\Program Files\BMC Software\Helix Control-M Agent\ABC-TLV-WEG30I_1"

-path

Defines the *.zip file pathname on the Helix Agent that contains the exported local connection profiles.

/home/myuser/pluginExportedData_dba-tlv-w5r6p9_20230716_121315.zip

-url

Defines the Control-M Automation API URL.

https://myemserver-aapi.us1.ci.ctmsaas.com/automation-api/

-token

Defines the Control-M Automation API token, as described in Creating an API Token.

-ctm

Defines the Control-M/Server name, such as AA01.

-agent

Defines the Agent name or alias, such as Agent1.

-cpnp

(Optional) Determines one of the following actions to take when a centralized connection profile with the same name is found:

  • SKIP: Leaves the current centralized connection profile as is.

  • OVERWRITE: Overwrites the current centralized connection profile with the migrated local connection profile definitions.

-d

(Optional)

Determines whether to save or delete the *.zip file that contains the Control-M MFT local connection profiles and Application-Integrator-created plug-in connection profiles after they are migrated to centralized connection profiles in Helix.

  • TRUE: Deletes the *.zip file.

  • FALSE: Saves the *.zip file.

Default: FALSE

Generating a Server Token

This procedure describes how generate a Server token, which enables you to add a self-hosted Control-M/Server or self-hosted Control-M for z/OS to Helix Control-M.

Begin

  1. Log in to Helix Control-M with a user ID that is associated with an Admin role.

  2. From the icon, select Configuration.

    The Configuration domain appears.

  3. From the drop-down list, select Control-M/Servers.

    The Control-M/Servers pane appears.

  4. Toggle on Self-Hosted and verify that your self-hosted Control-M/Servers or self-hosted Control-M for z/OS environments appear in the Self-Hosted area of the Control-M/Servers pane.

    In the Status column, a Ready to Connect button appears next to the added self-hosted Control-M/Servers or self-hosted Control-M for z/OS.

  5. Select the required self-hosted Control-M/Server or self-hosted Control-M for z/OS, and then click Ready to Connect.

    A Control-M/Server Token dialog box appears with the token value and enables you to copy it to your clipboard.

    Record this token, which you must provide when you are prompted by the registration utility, as described in Connecting a Self-Hosted Control-M/Server to Helix Control-M Unified View and Connecting a Self-Hosted Control-M for z/OS to Helix Control-M Unified View.

Connecting a Self-Hosted Control-M/Server to Helix Control-M Unified View

This procedure describes how to disconnect a self-hosted Control-M/Server from your self-hosted Control-M/EM and connect it to Helix Control-M Unified View via the ctm_menu utility.

  • You cannot connect a self-hosted Control-M/Server that is installed on Windows to Helix Control-M Unified View.

  • If your Control-M/Servers execute more than 100,000 jobs daily, you must distribute these jobs on two or more Control-M/Servers.

Before You Begin

Begin

  1. Pause the self-hosted Control-M/Server, as described in Pausing a Control-M/Server or config server::pause.

  2. Disable the self-hosted Control-M/Server, as described in Disabling a Control-M/Server, and verify that the Actual State is Disabled.

  3. Unmanage the self-hosted Control-M/Server, as described in Unmanaging a Control-M/Server or config server::unmanaged.

  4. Set the desired state of the Control-M/EM Gateway to Down from the CCM or via the ccmcli utility.

  5. From the self-hosted Control-M/Server host, do the following:

    1. Run the following command:

      ctm_menu

      The Control-M Main Menu appears.

    2. Press 1.

    3. Type 11 and follow the prompts.

      The registration utility runs and connects the self-hosted Control-M/Server to Helix Control-M.

  6. From the Control-M/Servers pane in Helix Control-M, verify that the self-hosted Control-M/Server status changes from Ready to Connect to OK.

    The self-hosted Control-M/Server is now disconnected from the self-hosted Control-M/EM and is connected to Helix Control-M.

Connecting a Self-Hosted Control-M for z/OS to Helix Control-M Unified View

This procedure describes how to disconnect a self-hosted Control-M for z/OS from your self-hosted Control-M/EM and connect it to Helix Control-M Unified View via the ICE utility.

If your Control-M for z/OS environments execute more than 100,000 jobs daily, you must distribute these jobs on two or more Control-M for z/OS environments.

Before You Begin

Begin

  1. Pause the self-hosted Control-M for z/OS, as described in Pausing a Control-M/Server or config server::pause.

  2. Disable the self-hosted Control-M for z/OS, as described in Disabling a Control-M/Server, and verify that the Actual State is Disabled.

  3. Unmanage the self-hosted Control-M for z/OS, as described in Unmanaging a Control-M/Server or config server::unmanaged.

  4. Set the desired state of the Control-M/EM Gateway to Down from the CCM or via the ccmcli utility.

  5. From your Control-M for z/OS, load ICE, as described in Installing INCONTROL Products with ICE.

  6. Select Installation.

    The IOA Installation menu appears.

  7. Select Customized Installation.

    The IOA Customized Installation menu appears.

  8. From the IOA Customized Installation menu, at the Option ===> prompt, type 2, at the Product ID ===> prompt, type CTM, and then press ENTER.

    The Major Steps Selection menu appears.

  9. Select 13 - Register Control-M for z/OS to Helix CTM.

    The Minor Steps Selection menu appears for major step 13 - Register Control-M for z/OS to Helix CTM.

  10. Follow steps 1–8 in the Minor Steps Selection menu, as described in Step 13 - Register Control-M for z/OS to Helix CTM.

    The self-hosted Control-M for z/OS is now connected to Helix Control-M.

Resuming All Connected Self-Hosted Control-M/Servers and Self-Hosted Control-M for z/OS Environments

This procedure describes how to resume all connected, self-hosted Control-M/Servers and self-hosted Control-M for z/OS environments, which enables you to run jobs from Helix Control-M.

Before You Begin

  • Verify that you have connected all required self-hosted Control-M/Servers and self-hosted Control-M for z/OS environments.

Begin

  1. From the icon in Helix Control-M, select Configuration.

    The Configuration domain appears.

  2. From the drop-down list, select Control-M/Servers.

    The Control-M/Servers pane appears.

  3. Do one of the following:

    • From the Control-M/Servers Pane: Toggle on Self-Hosted and select the required self-hosted Control-M/Server or self-hosted for Control-M for z/OS, and then click Resume.

    • From a Command Prompt: Run config server::resume.

  4. Verify that the self-hosted Control-M/Server or self-hosted Control-M for z/OS Actual State changes from Paused & Up to Up.

  5. Resume the remaining connected, self-hosted Control-M/Servers and self-hosted Control-M for z/OS environments.

    You can now access your resumed, self-hosted Control-M/Servers and self-hosted Control-M for z/OS environments from Helix Control-M Unified View.

Removing a Self-Hosted Control-M/Server from Helix Control-M

This procedure describes how to remove a self-hosted Control-M/Server from Helix Control-M, which disconnects the self-hosted Control-M/Server and deletes its data from Helix Control-M.

Begin

  1. From the icon in Helix Control-M, select Configuration.

    The Configuration domain appears.

  2. From the drop-down list, select Control-M/Servers.

    The Control-M/Servers pane appears.

  3. Toggle on Self-Hosted and from the Self-Hosted area of the Control-M/Servers pane, select the required self-hosted Control-M/Server, and click Delete.

    The Control-M/Server and all of its data is deleted from Helix Control-M.

  4. Log in to Control-M/Server and run the following command:

    ctm_menu

    The CONTROL-M Main Menu appears.

  5. Press 1 to select CONTROL-M Manager.

    The CONTROL-M Manager Menu appears.

  6. Type 12 to select Unregister Control-M/Server from Helix Control-M/EM, and follow the prompts.

    Your Self-Hosted Control-M/Server is now removed from Helix Control-M.

You can now reconnect your self-hosted Control-M/Server to a self-hosted Control-M/EM.