Control-M SaaS Migration

The Control-M SaaS migration copies the data from a self-hosted An Control-M environment (Control-M Self-Hosted), or specific Control-M component that you install and manage on your own infrastructure. Control-M/EM to a SaaS Control-M/EM and enables you to migrate some or all of your self-hosted Control-M components to Control-M SaaS. This eliminates the need to maintain a self-hosted Control-M/EM, one or more self-hosted Control-M/Servers, and the databases for all migrated components. If you have Control-M for z/OS environments or Control-M/Servers that cannot be migrated, you can instead connect these components to Control-M SaaS Unified View A mode of Control-M SaaS that enables you to connect self-hosted Control-M/Servers and Control-M for z/OS environments to a SaaS Control-M/EM and run jobs that are connected to these self-hosted components from Control-M SaaS..

Before you migrate your data, BMC Services or a BMC certified partner will help you scan your Control-M Self-Hosted components and create a migration plan that best suits your organization.

If you are unable to upgrade your self-hosted Control-M/EM to version 9.0.21.200, as described in Control-M/EM Upgrade, contact a BMC pre-sales representative.
You cannot migrate the following self-hosted components to Control-M SaaS, but you can connect them to Control-M SaaS Unified View.
- Control-M for z/OS environments.
- Self-hosted Control-M/Servers that are connected to Agents that are installed on unsupported platforms or that run unsupported plug-ins, as described in Self-Hosted Agent Compatibility and SaaS Agent Compatibility.
You cannot revert a Control-M SaaS migration.

The following diagram shows the logical architecture of a typical migration:

Migrating to Control-M SaaS

This procedure describes how to migrate the data from a self-hosted Control-M/EM to a SaaS Control-M/EM, and migrate or connect your self-hosted Control-M/Servers to Control-M SaaS, based on your organizational needs and the results of a preliminary qualification scan.

Before You Begin

Verify that you are qualified to migrate to Control-M SaaS, as described in Scanning Control-M Self-Hosted.
Verify that Control-M/EM 9.0.21.200 or higher is installed.
(Control-M/EM 9.0.22 only) Configure automatic time zone management, as described in Configuring Automatic Time Zone Management.

Begin

Register for Control-M SaaS, as described in Registering for Control-M SaaS.

This enables BMC to provide you with a SaaS Control-M/EM and SaaS Control-M/Servers that match the names of your current self-hosted Control-M/Servers.
From your new Control-M SaaS tenant, redefine your IdP settings, as described in Configuring System Settings.
(Optional) For each Control-M/Server in your self-hosted environment, scan all of the self-hosted Agents to determine how you must redefine your Agents for Control-M SaaS, as described in Scanning Control-M Agents.
Migrate your self-hosted Control-M/EM data to Control-M SaaS, as described in Migrating a Self-Hosted Control-M/EM to Control-M SaaS.
For each Control-M/Server or Control-M for z/OS in your current self-hosted environment, do one of the following:
- Migrate a Self-Hosted Control-M/Server to a SaaS Control-M/Server
- Connect one of the following self-hosted components to Control-M SaaS Unified View A mode of Control-M SaaS that enables you to connect self-hosted Control-M/Servers and Control-M for z/OS environments to a SaaS Control-M/EM and run jobs that are connected to these self-hosted components from Control-M SaaS.:
  - Control-M/Server
  - Control-M for z/OS
  A number of Control-M Administrators connect their components to Control-M SaaS Unified View to do one or more of the following:
  - Run self-hosted workflows that rely on mainframe modernization plug-ins or Control-M for z/OS environments.
  - Access both platforms (Control-M Self-Hosted and Control-M SaaS) for the following reasons:
    - Critical workflows must remain on distributed self-hosted components.
    - Some self-hosted features have not yet been integrated into Control-M SaaS.
Resume all connected self-hosted components, as described in Resuming All Connected Self-Hosted Components.
Get started with Control-M SaaS, as described in Getting Started.
(Optional) Migrate your Control-M Workload Archiving to Control-M SaaS, as described in Migrating Self-Hosted Workload Archiving Data to Control-M SaaS.

Scanning Control-M Self-Hosted

This procedure describes how to scan your Control-M Self-Hosted components with BMC Services or a BMC certified partner. The scan produces qualification reports that enable you to determine the following:

The migration plan that best suits your organization.
The steps that you must take before you can migrate to Control-M SaaS.

You can run this tool from your Windows- or Linux-based self-hosted Control-M/EM host.

You cannot migrate the following components to Control-M SaaS, but you can connect them to Control-M SaaS Unified View:

Control-M for z/OS environments.
Control-M/Servers that are connected to the following types of Agents:
- Agents that are installed on operating systems which are not supported in Control-M SaaS.
- Agents that run plug-ins which are not supported in Control-M SaaS.

Before You Begin

Verify that Control-M/EM 9.0.20 or higher is installed.
Verify that you have access to the Control-M/EM host.
Verify that Control-M Automation API 9.0.20.245 or higher is installed on the Control-M/EM server.

BMC recommends that you use the latest version of Control-M Automation API. For more information, see Setting Up the API.

Begin

Log in to the host where Control-M/EM is installed with a username that is associated with an Admin role.
Download the Control-M SaaS Qualification Tool from Control-M SaaS/EM Scanning and Migration Tools, and unzip it to a temporary directory.
From a command line, navigate to the temporary directory where you unzipped the Control-M SaaS Qualification Tool, and run the following command:
- Linux: SaasQualificationTool.sh -u <Control-M/Automation_API_Username> -p <Control-M/Automation_API_Password>
- Windows: SaasQualificationTool.bat -u <Control-M/Automation_API_Username> -p <Control-M/Automation_API_Password>
The qualification tool scans your Control-M/EM and all connected Control-M/Servers, creates one Control-M/EM qualification report, and creates two Control-M/Server reports for every connected Control-M/Server. All of these reports are saved to the <Temporary_Installation_Directory>/report directory, as follows:
- EM_SaaS_Qualification.xlsx: Contains the Control-M/EM qualification scan results, which describes the actions that you must take before you can migrate to Control-M SaaS.
- Server_Qualification_<Control-M/Server_Name>.xlsx: Contains the Self-Hosted-to-SaaS Control-M/Server qualification scan results, which describes the actions that you must take before you can migrate this Control-M/Server to a SaaS Control-M/Server.
- Server_Qualification_Self_Hosted_<Control-M/Server_Name.xlsx>: Contains the self-hosted Control-M/Server qualification scan results, which describes the actions that you must take before you can connect this self-hosted Control-M/Server to Control-M SaaS Unified View.
Send the compressed ControlMSaasQualificationResults_<Timestamp> file, which contains the results of the qualification scan, to BMC Services or a BMC certified partner.
Navigate to the report directory, review the qualification reports, and do the following:
1. Based on the qualification report results, determine which self-hosted Control-M/Servers will fully migrate and which will connect to Control-M SaaS Unified View.
2. Follow the directions in the relevant qualification reports.
3. Migrate to Control-M SaaS, as described in Migrating to Control-M SaaS.

Scanning Control-M Agents

This procedure describes how to scan all of the self-hosted Agents that are connected to a Control-M/Server in your current self-hosted environment. This scan produces a qualification report that enables you to determine the migration plan that best suits each self-hosted Agent.

You must run this scan for every Control-M/Server that is connected to your self-hosted Control-M/EM.

Before You Begin

Verify that Control-M/EM 9.0.20 or higher is installed.
Verify that you have downloaded the Control-M SaaS Qualification Tool from Control-M SaaS/EM Scanning and Migration Tools, and unziped it to a temporary directory, as described in Scanning Control-M Self-Hosted.
Verify that Control-M Automation API 9.0.20.245 or higher is installed on the Control-M/EM server.

BMC recommends that you use the latest version of Control-M Automation API. For more information, see Setting Up the API.

Begin

Log in to the host where Control-M/EM is installed with a username that is associated with an Admin role.
From a command line, navigate to the temporary directory where you unzipped the Control-M SaaS Qualification Tool, and run the following command:
- Linux: <Control-M_SaaS_Qualification Tool_Directory>/scripts/SaasAgentQualificationTool.bat -u <EM_Username> -p <EM_Password>
- Windows: <Control-M_SaaS_Qualification Tool_Directory>/scripts/SaasAgentQualificationTool.bat -u <EM_Username> -p <EM_Password>
Follow the on-screen instructions until the scan is complete.

The qualification tool scans all of the Agents that are connected to the Control-M/Server that you define, creates an Agents_Qualification_Report_<Control-M/Server_Name>.xlsx, and saves it to the report folder in the temporary directory.
Navigate to the report directory, review the qualification report, and do one or more of the following to redefine each of your self-hosted Agents for Control-M SaaS:
- Install a new SaaS Agent, as described in Agent Installation.
- Connect a self-hosted Agent to a SaaS Control-M/Server, as described in Agent Connection to Multiple Control-M/Servers.
- Define an Agentless Host, as described Agentless Hosts.

Registering for Control-M SaaS

This procedure describes how to register for Control-M SaaS, which enables BMC to provide you a with a SaaS Control-M/EM and SaaS Control-M/Servers that match the names of your current self-hosted Control-M/Servers. You only need to perform this procedure once.

Before You Begin

Rescan your Control-M Self-Hosted components, as described in Scanning Control-M Self-Hosted.

Begin

From the temporary folder where you unzipped the Control-M SaaS Qualification Tool, open the following file:
- Linux: <Temporary_Folder>/output/migration_metadata.xlsx
- Windows: <Temporary_Folder>\output\migration_metadata.xlsx
Open the migration_metadata.xlsx file and, from the Control-M/Server column, delete all Control-M/Servers that must remain self-hosted and will not migrate to SaaS Control-M/Servers.

Do not change the self-hosted Control-M/Server names that remain in the Control-M/Server column. If you do, they will fail to migrate. After migration, these new SaaS Control-M/Servers retain their original self-hosted names.
Save the migration_metadata.xlsx file and upload it in the online Control-M SaaS Production: Migration Metadata file (Migration Only!) section of the SaaS Subscription Registration form.
Complete and submit the SaaS Subscription Registration form.

A confirmation email with a link to your new Control-M SaaS tenant will arrive when it is ready. If you do not receive this email, you must contact your customer service representative.

Migrating a Self-Hosted Control-M/EM to Control-M SaaS

This procedure describes how to migrate a self-hosted Control-M/EM to Control-M SaaS. This migration exports your self-hosted Control-M/EM data to an export file, uploads it to an Amazon S3 bucket, transfers and extracts it, and then imports the Control-M/EM data into your new Control-M SaaS tenant.

If your Control-M/EM host 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.200 or higher is installed.

Begin

Log in to Control-M SaaS with a username that is associated with an Admin role, and then generate and record the value of an API token, as described in Creating an API Token.
Download the Control-M SaaS EM Data Migration Tool to your Control-M/EM host from Control-M SaaS Scanning and Migration Tools, and unzip it to a temporary folder.
From the command line, navigate to the export/EM directory in the unzipped migration tool folder, and then run the following command to export your self-hosted Control-M/EM data to a compressed archive export (*.tar.gz) file:
- Linux: run_saas_migration_export.sh
- Windows: run_saas_migration_export.bat
The export tool runs, produces a compressed archive export file (EMExportForSaaS.tar.gz) that contains your self-hosted Control-M/EM data, and saves it to the temporary folder.
From an internet-accessible host (either your self-hosted 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. From the import/EM directory in the unzipped migration tool folder, run one of the following commands:
  - Pip: pip install -r requirements.txt
  - Pip3: pip3 install -r requirements.txt
3. If you use a proxy server, define the following environment system variable:
  - Name: https_proxy
  - Value: http://<Proxy_Server_Address>:<Proxy_Server_Port>
4. Verify that you have outgoing internet access to the following locations:
  - *.controlm.com:443
  - *.amazonaws.com:443
5. Navigate to the import/EM directory in the temporary folder.
  
  From the import/EM directory in the unzipped migration tool folder, do one of the following to import your self-hosted Control-M/EM data to Control-M SaaS:
  - Control-M/EM Host: From your internet-accessible Control-M/EM host, run the following command:
    - Linux: em ./run_saas_migration_import.sh
    - Windows: em ./run_saas_migration_import.bat
  - Separate Host: From your separate internet-accessible host, run the following command:
    - Linux: ./run_saas_migration_import.sh
    - Windows: ./run_saas_migration_import.bat
At the prompts, type the requested information, as described in Control-M/EM and Workload Archiving Import Parameters.

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

Control-M/EM and Workload Archiving Import Parameters

The following table describes the parameters that you must provide at the import tool prompts in Migrating a Self-Hosted Control-M/EM to Control-M SaaS and Migrating Self-Hosted Workload Archiving Data to Control-M SaaS.

Parameter	Description
SaaS Control-M Automation API Endpoint	Defines the SaaS Control-M Automation API endpoint, in the following format: <Tenant_Name>-aapi.<Zone>.controlm.com https://jdoe-12345-aapi.us1.devci.ctmsaas.com
Control-M Automation API Token	Defines the API token that you created in Migrating a Self-Hosted Control-M/EM to Control-M SaaS.
Control-M/EM to Control-M/SaaS Compressed Archive Export File Pathname	Defines the pathname The fully specified name of a computer file, including the position of the file in the file system directory structure. of the compressed archive export file that you created in Migrating a Self-Hosted Control-M/EM to Control-M SaaS. Linux: <Temp_Folder>ControlMSaaSEmDataMigrationTool\export\EMExportForSaaS.tar.gz Windows: <Temp_Folder>ControlMSaaSEmDataMigrationTool/export/EMExportForSaaS.tar.gz
Python Interpreter Name or Pathname	Defines the name or pathname of the Python interpreter that converts source code into machine language, as follows: Control-M/EM Host: bmcpython Separate Host Name: <Python_Interpreter_Name> Press ENTER to utilize the default Python interpreter (python3). Pathname: <Python_Interpreter_Pathname> Linux: /user/bin/python Windows: C:\Users\dbauser\AppData\Local\Programs\Python312\python.exe
Workload Archiving Compressed Archive Export Files Directory	Defines the full path to a local or network directory where the compressed Workload Archiving data files are exported.

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

This procedure describes how to migrate a self-hosted Control-M/Server to a SaaS Control-M/Server. You must perform this procedure for every self-hosted Control-M/Server that must be migrated. You can run this tool from any Windows or Linux host.

You cannot migrate Control-M for z/OS environments to Control-M SaaS. However, you can connect them to Control-M SaaS Unified View, as described in Connecting a Self-Hosted Control-M for z/OS to Control-M SaaS Unified View.
If your Control-M/Servers execute more than 150,000 jobs daily, you must distribute these jobs on two or more Control-M/Servers.

Before You Begin

Verify that the most recent version of Control-M Automation API is installed on Control-M/EM server, as described in Setting Up the API.
Verify that you have access to the Control-M/EM database.
If you made changes to the self-hosted Control-M/Server after the qualification scan, then you must run the scan again, as described in Scanning Control-M Self-Hosted.

Begin

Download the Control-M SaaS Server Data Migration tool from Control-M SaaS Scanning and Migration Tools, and unzip it to a temporary folder.
From the inputParameters folder inside the temporary folder, open the parameters.txt file and define the relevant parameters, as described in Control-M/Server Migration Tool Parameters.
(Optional) Migrate your variable lists to pool variables, as described in Creating a LIBMEMSYM Control File.
From the command line, navigate to the temporary folder and run the following commands:
- Linux:
  - migrateToSaaS.sh extract
  - migrateToSaaS.sh deployCtmServer
- Windows:
  - migrateToSaaS.bat extract
  - migrateToSaaS.bat deployCtmServer
The tool migrates your self-hosted Control-M/Server to a SaaS Control-M/Server and produces a Deploy_Server_Report-<Server_Name>.xslx Excel file in the report folder.
(Optional) Do one of the following to migrate Control-M MFT, Control-M for Databases, Application Integrator, and Control-M Integration local connection profiles (LCPs) to SaaS-supported connection profiles:
- Migrate LCPs to centralized connection profiles (CCPs), as described in Migrating Local Connection Profiles.
- Copy LCPs from self-hosted Agents to SaaS Agents or Agents that can connect to self-hosted and SaaS Control-M/Servers, as described in Migrating Local Connection Profiles.
Log in to Control-M SaaS, open the Shared Variables tool, and verify that all self-hosted Control-M/Server variables now appear in Control-M SaaS.
From the report folder, open, review, and follow the directions in the Deploy_Server_Report-<Server_Name>.xslx file. You might be asked to do one or more of the following in Control-M SaaS:
- Ask the BMC Pre-sales team to help you migrate your Control-M for MFT Enterprise sites to Control-M SaaS.
- Redefine the unsupported notification destinations that are listed in the Deploy_Server_Report-<Server_Name>.xslx file, as described in Notification Destinations.
- Redefine folders that exceed 20,000 job runs at New Day, as described in the Run Method folder attribute in Folder General Attributes.
- Redefine all Control-M Automation API tokens wherever they are used, such as OS job scripts, and change all connection profile credentials to API tokens, as described in Creating an API Token.
- Redefine passwords in all Run as Users.
- Run test jobs on all connected SaaS Agents to validate plug-in job Run as Users and connection profiles to confirm that the new Control-M SaaS environment is ready for production.
- Verify that the Run Method name on all folders is correct.
  
  The _ (underscore) prefix was appended to the Run Method name on all folders to prevent Control-M SaaS from automatically ordering these folders.

Control-M/Server Migration Tool Parameters

The following table describes the parameters that you must define in the parameters.txt file in the inputParameters folder when Migrating a Self-Hosted Control-M/Server to a SaaS Control-M/Server.

Parameter	Definition
Control-M Automation API Endpoint	--control-m-automation-api-endpoint "https://<Automation-API-endpoint>:8443/automation-api"
Control-M/Server Name	--control-m-server-name "<Control-M/Server-Name>" Defines the name of the Control-M/Server, as it appears in the CCM and in the Configuration domain in Control-M/EM 9.0.21.300 and higher.
Control-M Automation API Username	--control-m-enterprise-manager-username "<EM_Username>"
Control-M Automation API Password	--control-m-enterprise-manager-password "<EM_Password>" To enter the password when prompted by the migration tool, delete "<EM_Password>".
Control-M/EM Database Username	--control-m-enterprise-manager-database-username "<Database_Username>"
Control-M/EM Database Password	--control-m-enterprise-manager-database-password "<Database_Password>" To enter the password when prompted by the migration tool, delete "<Database_Password>".
Control-M/EM Database Type	--control-m-enterprise-manager-database-type "<Database_Type>" Type MSSQL, PostgreSQL, or Oracle.
Control-M/EM Database Host Name	--control-m-enterprise-manager-database-hostname "<Database_Host_Name>"
Control-M/EM Database Port Number	--control-m-enterprise-manager-database-port "<Port_Number>"
Control-M/EM Database Name	--control-m-enterprise-manager-database-name "<EM_Database_Name>" Type your database (PostgreSQL, MSSQL) or service (Oracle) name.
Control File with LIBMEMSYM Details	--libmemsym-control-file "<LIBMEMSYM_Control_File.csv_Pathname>" (Optional) Defines the filename that you create in Control-M SaaS Migration, which enables you to create pool variables with names and values that correspond to each variable in the %%LIBMEMSYM list variable. Control-M SaaS does not recognize %%LIBMEMSYM variable lists. To migrate your variable lists, you must find all your %%LIBIMEMSYM variable lists, copy them to your local host, and create a control file to migrate your %%LIBIMEMSYM variable lists to pool variables, as described in Creating a LIBMEMSYM Control File.
Time Zone Mapping File Pathname	--time-zone-mapping-file "<Time_Zone_Mapping_File_Pathname>" (Optional) Defines the pathname of the time zone mapping file that you must modify after you scan your Control-M Self-Hosted environment, as described in the Server_Qualification_<Control-M/Server_Name>.xlsx report. --time-zone-mapping-file "inputParameters/TimeZoneMapping.txt"
Output Folder Path	--output-folder-path "output" (Optional) To change the default output folder, replace output with a new directory path.
Control-M SaaS Automation API Endpoint	--control-m-saas-automation-api-endpoint "<Endpoint>/automation-api"
Control-M SaaS Automation API Token	--control-m-saas-api-token "<Token_ID>" To enter the API token when prompted by the migration tool, delete "<Token_ID>". For more information, see Creating an API Token.
Default Agent Hostname	--default-host-name "<Hostname>" (Optional) Defines the Agent hostname in the Host/Host group job attribute for all current jobs saved on the Control-M/Server that do not have this attribute defined. These types of jobs execute on the local Agent that is installed on the relevant self-hosted Control-M/Server. After the migration, these jobs execute on the default hostname that you define.
Skip Missing Agents	--skip-if-missing-agents (Optional) Does not migrate job and folder definitions when the required SaaS Agents are not installed.
Control-M SaaS Proxy Hostname	--control-m-saas-https-proxy-hostname "proxy.bmc.com" (Optional) Enables you to pass all HTTPS requests to Control-M/SaaS via the HTTP proxy hostname that you define.
Control-M SaaS Proxy Port	--control-m-saas-https-proxy-port "8080" (Optional) Enables you to pass all HTTPS requests to Control-M/SaaS via the HTTP proxy port that you define.

Creating a LIBMEMSYM Control File

This procedure describes how to create a LIBMEMSYM control file, which the Control-M SaaS Server Data Migration tool uses to migrate the self-hosted %%LIBMEMSYM variable lists into corresponding SaaS pool variables. For more information, see List Variables.

Begin

Find all unique LIBMEMSYM files that each %%LIBMEMSYM variable points to, and copy these files from the self-hosted Control-M/Server to a location that is accessible to the Control-M SaaS Server Data Migration tool.
From the inputParameters folder, open the libmemsymControlFile.txt in a text editor and for each unique %%LIBMEMSYM list variable, type the following entries, separated by commas, on a new line:
- Pathname of the copied LIBMEMSYM file that you copied from the self-hosted Control-M/Server, on your host.
- Pathname of the LIBMEMSYM file on the self-hosted Control-M/Server.
c:\temp\libMem1.txt,C:\Program Files\BMC Software\Control-M Server\ctm_server\libMem1

c:\temp\libMem2.txt,C:\Program Files\BMC Software\Control-M Server\ctm_server\libMem2

c:\temp\libMem3.txt,C:\Program Files\BMC Software\Control-M Server\ctm_server\libMem3
Save the libmemsymControlFile.txt file.
From the inputParameters folder, open the parameters.txt file, locate --libmemsym-control-file, and then type a space and the LIBMEMSYM control file pathname, enclosed in " (quotation marks), as described in Control-M/Server Migration Tool Parameters.

Linux: --libmemsym-control-file "/home/ABC_User/Temp/libmemsymControlFile.txt"
Windows: --libmemsym-control-file "c:\temp\libmemsymControlFile.txt"

Connecting a Self-Hosted Control-M/Server to Control-M SaaS 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 Control-M SaaS Unified View via the ctm_menu utility.

You cannot connect Control-M/Servers with Agents that are installed on unsupported platforms or that run unsupported plug-ins. For more information, see Self-Hosted Agent Compatibility and SaaS Agent Compatibility.
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

Verify that Control-M/EM 9.0.21.200 or higher is installed.
Verify that Control-M/Server 9.0.21.300 or higher is installed.
Generate a server token in Control-M SaaS, as described in Generating a Server Token.

Begin

Pause the self-hosted Control-M/Server, as described in Pausing a Self-Hosted Control-M/Server or config server::pause.
Do the following:
1. Disable the Control-M/Server from the CCM or from Control-M/EM 9.0.21.300 or higher, as described in Disabling a Self-Hosted Control-M/Server.
2. Verify that the Actual State of the Control-M/Server is Disabled.
Unmanage the Control-M/Server from the CCM, via the config server::unmanaged Control-M Automation API command, or from Control-M/EM 9.0.21.300 or higher, as described in Unmanaging a Control-M/Server.
Set the desired state of the Control-M/EM Gateway to Down from the CCM, via the ccmcli utility, or from the Configuration domain in Control-M/EM 9.0.21.300 and higher.
From the 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 9 or 12, depending on your database type, to select Register Control-M/Server in Control-M/EM SaaS, and then follow the prompts.
  
  The registration utility runs and connects the Control-M/Server to Control-M SaaS.
From the Control-M/Servers pane in Control-M SaaS, 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 Control-M/EM and is connected to Control-M SaaS.

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

This procedure describes how to disconnect a self-hosted Control-M for z/OS from your Control-M/EM and connect it to Control-M SaaS 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

Verify that Control-M/EM 9.0.21.200 or higher is installed.
Verify that Control-M for z/OS 9.0.21.300 or higher is installed.
Verify that the Control-M API Gateway is installed, as described in Step 12 – Install Control-M API Gateway in the INCONTROL documentation.
Generate a server token in Control-M SaaS, as described in Generating a Server Token.

Begin

Pause the Control-M for z/OS, as described in Pausing a Self-Hosted Control-M/Server or config server::pause.
Disable the Control-M for z/OS, as described in Disabling a Self-Hosted Control-M/Server, and verify that the Actual State is Disabled.
Unmanage the Control-M for z/OS from the CCM, via the config server::unmanaged Control-M Automation API command, or from Control-M/EM 9.0.21.300 or higher, as described in Unmanaging a Control-M/Server.
Set the desired state of the Control-M/EM Gateway to Down from the CCM, via the ccmcli utility, or from Control-M/EM 9.0.21.300 or higher, as described in Shutting Down a Control-M/EM Component.
From your Control-M for z/OS, load ICE, as described in Installing INCONTROL Products with ICE.
Select Installation.

The IOA Installation menu appears.
Select Customized Installation.

The IOA Customized Installation menu appears.
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.
Select 13 - Register Control-M for z/OS to CTM SaaS.

The Minor Steps Selection menu appears for major step 13 - Register Control-M for z/OS to CTM SaaS.
Follow steps 1–8 in the Minor Steps Selection menu, as described in Step 13 - Register Control-M for z/OS to CTM SaaS.

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

Generating a Server Token

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

Begin

Log in to Control-M SaaS with a user ID that is associated with an Admin role.
From the icon, select Configuration.

The Configuration domain opens.
From the drop-down list, select Control-M/Servers.

The Control-M/Servers page appears.
Toggle on Self-Hosted and verify that your self-hosted Control-M/Servers or 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 recently added Control-M/Server or Control-M for z/OS.
Select the required self-hosted Control-M/Server or self-hosted Control-M for z/OS, and then do the following:
1. Click Ready to Connect.
  
  A Control-M/Server Token dialog box appears.
2. Click Get Control-M/Server Token.
  
  A dialog box appears with the token value and enables you to copy it to your clipboard.
3. Record the token, which you must provide when you are prompted by the registration utility, as described in Connecting a Self-Hosted Control-M/Server to Control-M SaaS Unified View and Connecting a Self-Hosted Control-M for z/OS to Control-M SaaS Unified View.

Resuming All Connected Self-Hosted Components

This procedure describes how to resume all self-hosted Control-M/Servers and Control-M for z/OS environments that are now connected to Control-M SaaS Unified View. This enables you to run jobs on Agents that are connected to these self-hosed components from Control-M SaaS.

Before You Begin

Verify that you have connected all required self-hosted Control-M/Servers, as described in the following procedures:
- Connecting a Self-Hosted Control-M/Server to Control-M SaaS Unified View
- Connecting a Self-Hosted Control-M for z/OS to Control-M SaaS Unified View

Begin

From the icon, select Configuration.

The Configuration domain opens.
From the drop-down list, select Control-M/Servers.

The Control-M/Servers page appears.
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 Control-M for z/OS, and then click Resume.
- From a Command Prompt: Run config server::resume.
Verify that the Control-M/Server or Control-M for z/OS Actual State changes from Paused & Up to Up.
Repeat this procedure to resume the remaining connected, self-hosted Control-M/Servers or Control-M for z/OS environments.

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

Migrating Self-Hosted Workload Archiving Data to Control-M SaaS

This procedure describes how to migrate your self-hosted Control-M Workload Archiving data to Control-M SaaS. This migration exports your self-hosted Workload Archiving data to one or more compressed export files, uploads them to an Amazon S3 bucket, transfers and extracts the files, and then imports the Workload Archiving data into your new Control-M SaaS tenant.

If your Control-M/EM host 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 your self-hosted Control-M/EM and Control-M/Servers are migrated or connected to Control-M SaaS, as described in Migrating to Control-M SaaS.
Verify that Workload Archiving is activated on your Control-M SaaS tenant.
Verify the self-hosted Workload Archiving database is up and that one of the following versions is installed:
- BMC-dedicated PostgreSQL 11 or higher
- External PostgreSQL 14 or higher
- Oracle, all versions
Verify that all the Workload Archiving policies that are defined in Control-M Self-Hosted are defined in Control-M SaaS, as described in Defining a Workload Archiving Policy.
Create a local or network directory with sufficient free space for the compressed, exported Control-M Workload Archiving data.
Verify that all self-hosted Control-M/EM components are down.
Verify you have your Workload Archiving database password available.
Verify that you have outgoing internet access to the following locations:
- *.controlm.com:443
- *.amazonaws.com:443

Begin

Download the Control-M SaaS EM Data Migration Tool to your self-hosted Control-M/EM host where Workload Archiving is installed from Control-M SaaS Scanning and Migration Tools, and unzip it to a temporary folder.
Do the following to export the Workload Archiving data:
1. From the command line, navigate to the Control-M_Archive/export directory in the unzipped migration tool folder, and then run the following command to export your data to one or more compressed (*.tar) export files:
  - Linux: run_archive_migration_export.sh --output-dir <Data_Export_Directory>
  - Windows: run_archive_migration_export.bat --output-dir <Data_Export_Directory>
  where the <Data_Export_Directory> defines the full path to the local or network directory where the Workload Archiving data is exported.
  
  You can move the export script to a background process, which enables the export to continue if you need to log out of the session during the export process or the shell unexpectedly shuts down.
2. At the prompt, type the Workload Archiving database password.
  
  The export tool runs, produces one or more compressed data export files that contain your data, and saves them to the <Data_Export_Directory>.
  - On average, the export takes around 24 hours to complete.
  - If the export stops, rerun the run_archive_migration_export command and the export will continue from where it stopped.
Do the following to import the Workload Archiving data:
1. Navigate to the Control-M_Archive/import directory in the unzipped migration tool folder, and then run the following command to import your exported data into Control-M SaaS:
  - Linux: run_archive_migration_import.sh
  - Windows: run_archive_migration_import.bat
2. At the prompts, type the requested information, as described in Control-M/EM and Workload Archiving Import Parameters.
  
  The import script uploads, extracts, and imports the exported data into Control-M SaaS.
  
  On average, the import takes around 24 hours to complete.
Do the following to verify that all the exported data has been imported into Control-M SaaS:
1. Run the following command:
  - Linux: run_archive_migration_report.sh
  - Windows: run_archive_migration_report.bat
2. At the prompts, type the requested information, as described in Control-M/EM and Workload Archiving Import Parameters.
  
  The integration status of each exported data archive file appears, as shown in the following example:
  
  "2025_12_07_15_45_57 Sales.tar": "In Progress",
  
  "2025_12_07_11_22_10 Records.tar": "Completed",
  
  "2025_12_07_10_58_41 Planning.tar": "In Progress"
  
  You can rerun the run_archive_migration_report command to refresh the migration progress.
  
  On average, the verification process takes around 24 hours to complete.
  
  The self-hosted Control-M Workload Archiving data is migrated to Control-M SaaS when all of the files in the report appear Completed.

You can troubleshoot common Workload Archiving migration problems, as described in Workload Archiving Migration Troubleshooting.

Workload Archiving Migration Troubleshooting

The following table describes how to troubleshoot common problems that you might encounter when you try to migrate your self-hosted Workload Archiving data to Control-M SaaS, as described in Migrating Self-Hosted Workload Archiving Data to Control-M SaaS.

Problem	Corrective Action
The export script fails because the local or network output directory lacks sufficient disk space to store the exported Control-M Workload Archiving data. The following error appears: Your export file sizes exceed the maximum amount of allowed disk space (<Disk_Space_Utilization_Limit>%).	Create more disk space in the output directory, as described in Creating More Disk Space. Increase maximum percentage of disk space that export files can utilize, as described in Increasing the Disk Space Utilization Limit.
The export script fails for some other reason.	Rerun the export command with the same parameters, as follows: Linux: run_archive_migration_export.sh --output-dir <Data_Export_Directory> Windows: run_archive_migration_export.bat --output-dir <Data_Export_Directory> The export script continues from where it stopped to export the Workload Archiving data.
The import script fails with one of the following errors: An import exception has occurred. Failed to retrieve the Control-M SaaS Workload Archiving policies.	Verify that the following Workload Archiving import parameters are correct: SaaS Control-M Automation API Endpoint Control-M Automation API Token Full Path of the Compressed Archive Export Files For more information, see Control-M/EM and Workload Archiving Import Parameters. Verify that you have outgoing internet access to the following locations: .controlm.com:443 .amazonaws.com:443
The import script fails with one of the following errors: No Control-M SaaS Workload Archiving policies are defined. The following Control-M Self-Hosted and SaaS Workload Archiving policies do not match: <Self-Hosted_WA_Policy_Name_01, Self-Hosted_WA_Policy_Name_02, …>.	Verify that the same Workload Archiving policies that are defined in Control-M Self-Hosted are defined in Control-M SaaS, as described in Defining a Workload Archiving Policy.
The import script fails for some other reason.	Rerun the import command, as follows: Linux: run_archive_migration_import.sh Windows: run_archive_migration_import.bat At the prompts, type the requested information, as described in Control-M/EM and Workload Archiving Import Parameters. The import script continues from where it stopped to upload, extract, and import the exported data into Control-M SaaS.
The report script fails with the following error: The Athena service is busy. Please try again later.	Wait 30 seconds and then rerun the report command, as follows: Linux: run_archive_migration_report.sh Windows: run_archive_migration_report.bat
The integration status of one or more exported data archive files appears with an error, as shown in the following example: "2025_12_07_15_45_57 Sales.tar": "In Progress", "2025_12_07_11_22_10 Records.tar": "Completed", "2025_12_07_10_58_41 Planning.tar": "Error"	Navigate to the Control-M_Archive/import directory and open the progress-import.json file. Locate the TAR file that failed to import, such as "2025_12_07_10_58_41 Planning.tar": "Error", delete that entry, and then save and close the file. Do the following: Rerun the import command, as follows: Linux: run_archive_migration_import.sh Windows: run_archive_migration_import.bat At the prompts, type the requested information, as described in Control-M/EM and Workload Archiving Import Parameters. The import script reattempts to import the TAR file that failed to import. If the same error occurs again, contact BMC Technical Support.

Creating More Disk Space

This procedure describes how to create more disk space in the Workload Archiving migration output directory, as described in Workload Archiving Migration Troubleshooting.

Begin

Move the exported TAR files to a different drive or network location to create more free disk space.
Rerun the following export command to decrease the number of simultaneous TAR file exports:
- Linux: run_archive_migration_export.sh --output-dir <Data_Export_Directory> --max-workers=<Simultaneous_Exports>
- Windows: run_archive_migration_export.bat --output-dir <Data_Export_Directory> --max-workers=<Simultaneous_Exports>
where the <Simultaneous_Exports> parameter defines a number lower than the default of 5.

run_archive_migration_export.sh --output-dir <Data_Export_Directory> --max-workers=2

Increasing the Disk Space Utilization Limit

This procedure describes how to increase the maximum percentage of disk space that the Workload Archiving migration export files can utilize, as described in Workload Archiving Migration Troubleshooting. By default, the export utility can utilize up to 90 percent of disk space.

Begin

Rerun the following export command to increase the maximum percentage of disk space that the export files can utilize:
- Linux: run_archive_migration_export.sh --output-dir <Data_Export_Directory> --max-disk-usage=<Disk_Space_Utilization_Limit>
- Windows: run_archive_migration_export.bat --output-dir <Data_Export_Directory> --max-disk-usage=<Disk_Space_Utilization_Limit>
where the <Disk_Space_Utilization_Limit> parameter defines a number higher than the default of 90 percent.

run_archive_migration_export.sh --output-dir <Data_Export_Directory> --max-disk-usage=95