What's New

New developments in Control-M Automation API are divided into the following categories:

New Features

The following new features were introduced in the specified versions.



Control-M Workbench is now available as a Docker image from containers.bmc.com, as described in Using Control-M Workbench. (January 2024)

You can now use the historyRunDate field in query strings of the run jobs:status::get command to filter for jobs that ran on a specific date. (December 2023)

You can now use the deploy folders::get command to get details of folders that match a search criteria. Definitions are returned in JSON format. (October 2023)

You can now use the following Agent (Host) Restrictions API commands to restrict the resources used and the number of concurrent jobs that you can execute on one or more Agents, which helps prevent resource overload: (September 2023)

You can now use the deploy jobtype::get command to download a custom job type from theControl-M/Server and store it locally in *.ctmai format, so that it is available for deployment (using What's New). You can use this command when you want to copy job types from one environment to another. (September 2023)

You can now use the following API commands to check for jobs that were not ordered because a specific Order Method (a specific User Daily job) was interrupted, such as when an operating system crashes, and reorder those jobs.

These API commands replace the ctmudchk utility.

These commands require Control-M/EM or higher. (September 2023)

You can now use run ondemand API command to immediately execute jobs, without deploying them to the Control-M/EM database and without requiring the User Daily job in Control-M to trigger them This approach can be useful for event-driven job executions.

This API command replaces the use of the ctmcreate utility.

This command requires Control-M/EM or higher. (September 2023)

You can now use the following API commands to configure a High Availability environment for the Control-M/EM:

These commands require Control-M/EM or higher. (September 2023)

File Transfer job definitions now support the inclusion of various new parameters, as described in Job Types. (September 2023)

You can now use the config item::recycle API command to recycle a Control-M service, in addition to an Agent. (September 2023)

You can now use the config server:notification:list::setactive API command to activate a notification destination list.

This API command replaces the use of the ctmshtb utility. (September 2023)

You can now configure and manage Agentless Hosts with Control-M Automation API, as described in Agentless Host Configuration.

These commands require Control-M/EM or higher. (September 2023)

You can now configure and manage SSH keys with Control-M Automation API, as described in SSH Key Configuration.

This command requires Control-M/EM or higher. (September 2023)

You can now use the config server:agent::test command to test the connectivity of an Agent to a Control-M/Server.

As part of the connectivity test, you can submit a configuration file that contains Agent parameter settings, to simulate new values for Agent parameters during the Agent connectivity test.

This command requires Control-M/Enterprise Manager version or later. (September 2023)

You can now manage processing rules in Control-M Managed File Transfer Enterprise (MFTE) B2B with the following API commands:

These commands require Control-M/EM or higher. (September 2023)

The deploy service now supports transforming a *.zip package of JSON files using a Deploy Descriptor, in addition to a single JSON file. (August 2023)

You can now use the config server:agent::update command to update parameters from the configuration of an Agent that is already registered to the Control-M/Server. (August 2023)

Control-M Automation API has been upgraded with a new design to enhance ease of use. (August 2023)

When you register an Agent image with the provision agent::setup command, the new secondaryServerHostName parameter is now available for High Availability (HA) configurations. You include this parameter in the optional configuration file if the user performing agent provisioning uses Role Based Administration Authorizations. (June 2023)

Control-M Python client is now available in Pypi. The latest version of the python client is available for installation by running pip install ctm-python-client, as described in https://github.com/controlm/ctm-python-client. (June 2023)

You can now use the new search query field in the deploy jobs::get command to limit the returned results from z/OS jobs to specific z/OS libraries. (March 2023)


The following changes were made in existing features in the specified versions:



The hostgroupAgentParticipation object returned by the config server:hostgroups:agents::get API has been deprecated, and it is replaced by the participationRules object.

The participationRules object lists multiple defined participation rules of two types:

  • dateTime: Limits the inclusion of an Agent host in a host group to scheduled dates and times.

  • event: Limits the inclusion of an Agent host in a host group based on an event.

If you use the hostgroupAgentParticipation object in your code, you must replace it with the new participationRules object. (July 2023)

Return code 503, Service Unavailable, is now returned when the following API requests are used soon after server restart.

After receiving this return code, we recommend that you wait up to a minute before resubmitting the requests, to allow these services to become fully available. (July 2023)

Corrected Problems

The following table lists issues that have been corrected in the most recent releases:

Tracking #




The run ondemand API command ignores the specified Host property of a job in a sub-folder, and this might cause the job run to fail. (February 2024)


The run workloadpolicy::delete deletes multiple Workload Policies with similar names, instead of just the one specified. This occurs when the specified name appears as a string within the names of other Workload Policies. (February 2024)


Control-M Automation API uses the Java home path defined in external_java_path_9.0.21.100.dat instead of the one defined in external_java_path_9.0.21.200.dat after an upgrade of Control-M/EM to (February 2024)


The deploy jobs::get fails to return the specified parameters in a Stored Procedure Database job. (February 2024)


Deployment of a job that was obtained from a later version of Automation API (using the deploy jobs::get command) fails in an Automation API environment of an earlier version, due to unrecognized (new) job properties. The following error is issued:

<Name of new property> is an unknown keyword...

To enable the resolution of this issue, you must add the min.aapi.ste.version property to the automation-api.properties file and set it to the target (earlier) version of Automation API.

For example, to deploy a job that was defined in Automation API to an environment with Automation API, add the following line:

min.aapi.ste.version= (January 2024)


Password-type fields are corrupted in Application Integrator connection profiles when you make changes to non-password fields. (January 2024)


The run ondemand API command ignores the specified Host property, and this might cause the job run to fail. (January 2024)


The deploy jobs::get command does not return an array of jobs from a sub-folder specified through the folder field in the search query, even though useArrayFormat=true was included in the search query. (January 2024)


The deploy connectionprofile::test API command fails with the following error:

Failed to validate the connection with the selected Agent. (January 2024)


The provision agent::setup API command fails to set the tag parameter on the Agent if this parameter is defined in the configuration file. (December 2023)


Job deployment fails for a job of type Job:Database:StoredProcedure, if the job runs on a PostgreSQL database and the stored procedure has no return value. (December 2023)


After an upgrade on AIX 7.2, Control-M Automation API fails to start. (December 2023)


The config server:agent::update API command fails to update the sslState parameter on the Agent. In addition, the range of values for the maximumRetries parameter is too narrow (up to 10, where some users might need values up to 100). (December 2023)


Agent provisioning fails if the Control-M Automation CLI version differs from the Automation API version on the Control-M/Server. (December 2023)


The default value for the Delimiter parameter under a Capture Output action (Action:CaptureOutput) is an empty value (appropriate for z/OS jobs). It should be WhiteSpace (appropriate for other job types). (December 2023)


Non-default scheduling definitions are set to default values during deployment of a job that was defined as a root object with a PathElement property. (December 2023)


The run variables::set API command fails when a named pool variable contains an underscore character. (December 2023)


Products installations fail due to a failure to stop the Automation API server. (November 2023)


The error message for a failed export to JSON of a folder that contains an unidentified Site Standard does not contain clear details. (November 2023)


The run job:output::get command fails to get the output of a z/OS job, and the following error is issued:

Request rejected by Data Center\n ECS3000 SERVER INTERNAL ERROR - TYPE 24. (November 2023)


AAPI calls that use an API token fail with the following error:

User not found. Session token is invalid or expired. (November 2023)


A return code of 500 (server internal error), instead of 404 (defined item not found), is issued when you attempt to GET details regarding objects in a folder that does not exist in Control-M/EM. (November 2023)


The deploy sitestandards::get API command returns a corrupt JSON when the list of Site Standard rules contains conditions. The Conditions array is not created, and condition details appear directly under the Rules object. Deployment of this JSON fails with a null pointer exception error. (November 2023)


Deletion of a Site Standard or renaming of a Site Standard fails after an upgrade to version 9.0.21 if Control-M is in Compatibility mode. (October 2023)


The provision agent::setup API command fails when a payload configuration file is used and annotation is enabled. (October 2023)


Deployment of an array of jobs fails with a java.lang.NullPointerException error when a validation error is detected in one of the job properties. (October 2023)


Deployment fails with a "Table in use" error. This occurs if Control-M/Server attempts to synchronize folders at the same time as the deployment. (September 2023)

CTM 8622

Deployment of z/OS jobs fails with the following error:

Folder .... cannot contain both an array of jobs and a single, named job

This occurs even though the folder does not contain both an array of jobs and individual jobs. (September 2023)


Control-M Automation API does not preserve memory settings during an upgrade, and instead resets them to default. (September 2023)


Job deployment fails when the job contains an Action:Run and the job was defined as a root object with a PathElement property. (September 2023)


Deployment fails for a job of type Job:DetachedScript with the RunAsDummy property set to true. (September 2023)


A build of File Transfer jobs (performed by the build service or the deploy service) issues the following warning message:

Cannot find field 'IsGroupAccount' in context 'AftAccount'.

The fix for this issue requires Control-M/Enterprise Manager version or later. (September 2023)


The deploy jobs::get may fail to return job details when a folder contains multiple jobs with the same name and a defined job has both a filename and job name in its definitions. (August 2023)


The deploy API command returns a validation error when job definitions contain an active period with a start date that equals the end date. (August 2023)


The deploy jobs::get fails to return job details for z/OS jobs when a library filter is used in the API command. (August 2023)


The JSON file returned by the deploy transform API command fails compilation by the build command. This occurs when you run the deploy transform command through the CLI and the job name contains only numeric characters. (August 2023)


The run order API command fails when the placeInFolder parameter (previously named orderIntoFolder) is set to a specific folder order ID. (August 2023)


The provision image API command fails to provision an Agent or a plug-in on a Windows machine that already has a plug-in installed. The following error is issued:

Cannot invoke "java.lang.Boolean.booleanValue()" because ''x" is null. (August 2023)


The deploy jobs::get API command returns invalid JSON code, rather than an error message, when you attempt to retrieve the definitions of a job that is not supported by Control-M Automation API. (August 2023)


Deployment of an Embedded Query Database Job fails when the variable contains special characters, but the error message does not properly describe the reason for the failure. (August 2023)


The reporting download API command fails to download a report if port 18080 is blocked.

To resolve this issue, reports are now downloaded through the port specified in the API command request URL. (August 2023)


Control-M Web fails to create a connection profile when annotation is enabled for certain categories but not for the Security category, due to issues in the communication with Control-M Automation API. (August 2023)


Folder creation fails after an upgrade to Control-M Automation API version, and the following error is issued:

Internal validation problem: cannot find field 'retentionPolicyUnits' in context 'FolderPropertiesData' set by rule #2447. (July 2023)


Vulnerability sonatype-2022-6438 was reported in jackson-core version 2.14.2 packaged with Control-M Automation API.

To resolve this issue, the jackson-core package in Control-M Automation API was updated to version 2.15.2. (July 2023)


Details of an Action:Output object in a z/OS job returned by the deploy jobs::get command are incomplete. (July 2023)


The deploy jobs::get command issues an Invalid JSON error when a folder and a job within the folder have the same name. (July 2023)



Security protocols used for communication between the Automation CLI and Automation API to Control-M components were outdated.

To resolve this issue, communication protocols were updated to TLSv1.2. (July 2023)


Deployment of a job within a sub-folder fails when the sub-folder contains a ReferencePath property that references a folder rather than a job. (July 2023)


The YAML file generated by the REST API server returns errors when validating the Swagger specifications (OpenAPI2.0) of the REST APIs. (July 2023)


Host Group Management API commands get or process only one participation rule defined for the host group under the hostgroupAgentParticipation object.

For more information about the resolution of this issue and the introduced changes, see Changes. (July 2023)


The deploy jobs::get command retrieves a wrong name for a job property of type Load text file in an Application Integrator job. Deployment of the retrieved job fails. (June 2023)


The run job::rerun command support the restart of a z/OS job only if the job is in Ended OK or Ended Not OK status. Wait User status (which corresponds to Wait Confirmation status in Control-M for z/OS) is not supported.

To resolve this issue, support for the Wait User status was added to the run job::rerun command. (June 2023)


The deploy jobs::get command fails to retrieve a job that contains an If statement, with the following error:

Retrieving as JSON is not fully supported ... has an invalid property ""code"" = ""COMPSTAT > 0"". (June 2023)


The deploy jobs::get returns does not retrieve the "RunAsDummy": true property in an Embedded Script job. (June 2023)


The deploy job::delete command fails with an erroneous error that indicates that the folder name is longer than the allowed 64 characters. This occurs when the job resides within a nested sub-folder in a folder path that exceeds the allowed length, even though the individual sub-folder name does not exceed the allowed length. (June 2023)


Site Standards are not applied to jobs or sub-folders that were defined as root objects under a PathElement property. (May 2023)


The ctm provision image::remove command fails to remove an image of an agent of version 9.0.21. (May 2023)


Connection Profiles with password-type fields that require very long strings fail to establish a connection with the target platform. This occurs in centralized connection profiles for job types developed in Application Integrator. For example, connection profiles that connect to the Google Cloud, which require a Service Account Key. (May 2023)


The deploy jobs::get command fails to retrieve the details of a job type developed in Application Integrator if the job type was renamed. (May 2023)


The deploy connectionprofile::test command exposes sensitive details of a modified connection profile to external tools. (May 2023)


The CVE-2021-43138 vulnerability was reported in the async 0.9.2 library used by winston. These libraries are packaged with Control-M Automation CLI.

To resolve this issue, a newer version of the library is now packaged with Control-M Automation CLI.

(April 2023)


The provision command fails to provision an agent when the location of the installed java package is detected by Control-M Automation CLI and not through the BMC_INST_JAVA_HOME environment variable. (April 2023)


An event defined within a sub-folder is not created during deployment of the sub-folder. This occurs if the sub-folder is defined as a root object (using the PathElement property). (April 2023)


The deploy folder::delete command does not work properly. The original folder is deleted, but a new, empty folder with the same name is created. This occurs in product version or later. (April 2023)


The proxy port number setting of an AWS connection profile is not validated during deployment. (March 2023)


The Region setting of an AWS connection profile is not validated during deployment. (March 2023)


Deployment of a folder that contains 10 or more jobs in a job array fails. (March 2023)


The deploy jobs::get command returns an empty parameters array ("Parameters": [],) from a Database Job for a Stored Procedure (Job:Database:StoredProcedure) when no parameters were defined. Deployment of the returned JSON fails. (March 2023)


The run order command requires a value for the placeInFolder parameter (previously named orderIntoFolder) in the submitted configuration file, and does not apply the default value ("New") for this parameter. This occurs in versions 9.0.21.xxx, but not in earlier versions, of Automation API. (March 2023)


The ctm deploy connectionprofile::test command returns an unclear error message for a connection profile of a plug-in developed through Control-M Application Integrator (including Control-M Integration plug-ins). (March 2023)

Deprecated and Discontinued

The following table lists features that are deprecated and/or discontinued in Control-M Automation API:


Announcement Date

Control-M Automation API is no longer supported on Solaris from version Installation packages for Solaris will no longer be provided in any future release.

February 2024

API command config server:params::get is deprecated from version and will be discontinued in version It is replaced by config systemsettings:server::get.

January 2023