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.

Feature

Version

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

9.0.21.220 (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.

9.0.21.215 (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.

9.0.21.205 (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:

9.0.21.200 (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.

9.0.21.200 (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 9.0.21.200 or higher.

9.0.21.200 (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 9.0.21.200 or higher.

9.0.21.200 (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 9.0.20.200 or higher.

9.0.21.200 (September 2023)

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

9.0.21.200 (September 2023)

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

9.0.21.200 (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.

9.0.21.200 (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 9.0.21.200 or higher.

9.0.21.200 (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 9.0.21.200 or higher.

9.0.21.200 (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 9.0.21.200 or later.

9.0.21.200 (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 9.0.21.200 or higher.

9.0.21.200 (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.

9.0.21.130 (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.

9.0.21.130 (August 2023)

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

9.0.21.130 (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.

9.0.21.120 (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.

9.0.21.120 (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.

9.0.21.105 (March 2023)

Changes

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

Feature

Version

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.

9.0.21.125 (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.

9.0.21.125 (July 2023)

Corrected Problems

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

Tracking #

Description

Version

CTM-9675

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.

9.0.21.225 (February 2024)

CTM-9615

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.

9.0.21.225 (February 2024)

CTM-9609

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 9.0.21.200.

9.0.21.225 (February 2024)

CTM-9517

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

9.0.21.225 (February 2024)

CTM-9527

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 9.0.21.215 to an environment with Automation API 9.0.21.130, add the following line:

min.aapi.ste.version=9.0.21.130

9.0.21.220 (January 2024)

CTM-9442

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

9.0.21.220 (January 2024)

CTM-9425

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

9.0.21.220 (January 2024)

CTM-9357

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.

9.0.21.220 (January 2024)

CTM-9228

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

Failed to validate the connection with the selected Agent.

9.0.21.220 (January 2024)

CTM-9417

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

9.0.21.215 (December 2023)

CTM-9404

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.

9.0.21.215 (December 2023)

CTM-9247

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

9.0.21.215 (December 2023)

CTM-9235

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).

9.0.21.215 (December 2023)

CTM-9229

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

9.0.21.215 (December 2023)

CTM-9162

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).

9.0.21.215 (December 2023)

CTM-8693

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.

9.0.21.215 (December 2023)

CTM-5592

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

9.0.21.215 (December 2023)

CTM-9200

Products installations fail due to a failure to stop the Automation API server.

9.0.21.210 (November 2023)

CTM-9194

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

9.0.21.210 (November 2023)

CTM-9119

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.

9.0.21.210 (November 2023)

CTM-9104

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

User not found. Session token is invalid or expired.

9.0.21.210 (November 2023)

CTM-8883

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.

9.0.21.210 (November 2023)

CTM-7709

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.

9.0.21.210 (November 2023)

CTM-8864

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.

9.0.21.205 (October 2023)

CTM-8857

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

9.0.21.205 (October 2023)

CTM-8719

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.

9.0.21.205 (October 2023)

CTM-8823

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.

9.0.21.200 (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.

9.0.21.200 (September 2023)

CTM-8524

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

9.0.21.200 (September 2023)

CTM-8337

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

9.0.21.200 (September 2023)

CTM-7634

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

9.0.21.200 (September 2023)

CTM-6182

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 9.0.21.200 or later.

9.0.21.200 (September 2023)

CTM-8610

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.

9.0.21.130 (August 2023)

CTM-8597

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

9.0.21.130 (August 2023)

CTM-8563

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

9.0.21.130 (August 2023)

CTM-8531

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.

9.0.21.130 (August 2023)

CTM-8471

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

9.0.21.130 (August 2023)

CTM-8467

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.

9.0.21.130 (August 2023)

CTM-8416
CTM-8105

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.

9.0.21.130 (August 2023)

CTM-8323

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.

9.0.21.130 (August 2023)

CTM-7414

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.

9.0.21.130 (August 2023)

CTM-5563

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.

9.0.21.130 (August 2023)

CTM-8514

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

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

9.0.21.125 (July 2023)

CTM-8453

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.

9.0.21.125 (July 2023)

CTM-8444

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

9.0.21.125 (July 2023)

CTM-8442

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

9.0.21.125 (July 2023)

CTM-8441

CTM-8440

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.

9.0.21.125 (July 2023)

CTM-8439

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.

9.0.21.125 (July 2023)

CTM-8107

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

9.0.21.125 (July 2023)

CTM-7916

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.

9.0.21.125 (July 2023)

CTM-8286

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.

9.0.21.120 (June 2023)

CTM-8229

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.

9.0.21.120 (June 2023)

CTM-8179

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"".

9.0.21.120 (June 2023)

CTM-8177

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

9.0.21.120 (June 2023)

CTM-8072

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.

9.0.21.120 (June 2023)

 

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

9.0.21.115 (May 2023)

CTM-8175

The ctm provision image::remove command fails to remove an image of an agent of version 9.0.21.

9.0.21.115 (May 2023)

CTM-8170

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.

9.0.21.115 (May 2023)

CTM-8055

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

9.0.21.115 (May 2023)

CTM-7022

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

9.0.21.115 (May 2023)

CTM-8059

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.

9.0.21.110

(April 2023)

CTM-8058

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.

9.0.21.110 (April 2023)

CTM-7976

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).

9.0.21.110 (April 2023)

CTM-7934

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 9.0.21.100 or later.

9.0.21.110 (April 2023)

CTM-8166

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

9.0.21.105 (March 2023)

CTM-8167

The Region setting of an AWS connection profile is not validated during deployment.

9.0.21.105 (March 2023)

CTM-7927

Deployment of a folder that contains 10 or more jobs in a job array fails.

9.0.21.105 (March 2023)

CTM-7926

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.

9.0.21.105 (March 2023)

CTM-7896

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.

9.0.21.105 (March 2023)

CTM-7811

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).

9.0.21.105 (March 2023)

Deprecated and Discontinued

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

Feature

Announcement Date

Control-M Automation API is no longer supported on Solaris from version 9.0.21.230. 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 9.0.21.100 and will be discontinued in version 9.0.21.300. It is replaced by config systemsettings:server::get.

January 2023