Deploy Service

The deploy service allows you to transfer job and configuration definitions to Control-M. Once a job is deployed, it will be scheduled by Control-M according to its scheduling criteria and dependencies. The deploy overwrites any existing definition of the same name.

Jobs, Folders, and Calendars

The following API commands relate to the deployment of jobs, folders, calendars, and site standards:

To deploy Site Standards, you must have Control-M/EM 9.0.21 or later and you must have the Control-M Workload Change Manager add-on installed.

deploy

The deploy command enables you to deploy the provided definitions file to Control-M. As part of the deploy, a build takes place to ensure code validity. deploy can receive definitions files for folders, jobs, calendars, and site standards in .json format or Control-M import/export .xml format, or a package of multiple definition files in .zip or .tar.gz format.

CLI Syntax

Copy 
ctm deploy <definitionsFile> [deployDescriptorFile]

The following table describes the deploy command parameters.

Parameter

Description

<definitionsFile>

Determines the name of the definitions file with Control-M code for various elements.

Valid Formats:

  • .json

  • .zip or .tar.gz (see Package Service).

  • Control-M import/export .xml, as used by either the defjob utility or the deffolder utility.

[deployDescriptorFile]

(Optional) Defines the file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M code properties in either .json format or as a .zip package of JSON files. For detailed information, see Deploy Descriptor.

If annotation is enabled for the Scheduling definitions, Configuration management, or Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json"
-F "deployDescriptorFile=@examples/deployDescriptor.json"
-F "StandardsFile=@examples/StandardsFile.json"  "$endpoint/deploy"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

The response to the deploy command is the same as the response to the build command. The response summarizes the numbers of various elements created (such as folders and jobs), indicates whether a Deploy Descriptor is applied, and provides validation messages if site standards are applied.

If validations are not strictly enforced, site standard warning messages are not included, by default, in the deploy command response. To activate the inclusion of warning messages in the response, add the deployWarningsEnabled property to the automation-api.properties file, and set it to true.

deploy poll

If deployment takes longer than expected to update the Control-M database server, the response returns a poll ID and a deployment status. This occurrence is called an asynchronous deployment, and enables you to continue working while the asynchronous deployment continues in the background. To get an update of the deployment status, run the deploy poll command. Any user that has the required privileges can run the deploy poll command.

This feature requires Control-M/EM 9.0.21 or later.

It is highly unlikely for a deploy response to take so long that that asynchronous deployment is activated. The asynchronous deployment times out after 10 minutes. To change the timeout length, contact support.

CLI Syntax

Copy 
ctm deploy poll <pollId>

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/deploy/poll?pollId"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

  • In the following example, a definitions file that contains 5,000 jobs is deployed—5 folders of 1,000 jobs each. The response shows only 250 jobs have been deployed, so the deployment status is partial and a poll ID is provided:
    Copy
    {
       "deploymentFile": "5000_jobs_async_deploy.json",
       "pollId": "98b565da-eff8-4d78-881e-778b97944229",
       "deploymentStatus": "PARTIAL_RESULT",
       "successfulFoldersCount": 0,
       "successfulSmartFoldersCount": 0,
       "successfulSubFoldersCount": 0,
       "successfulJobsCount": 250,
       "successfulConnectionProfilesCount": 0,
       "successfulDriversCount": 0,
       "isDeployDescriptorValid": false
    }

  • The following example shows the response shortly after deployment. Notice that 2 Smart folders, or 2,000 jobs, have deployed:

    Copy 
    {
       "deploymentFile": "1000_jobs_async_deploy.json",
       "pollId": "98b565da-eff8-4d78-881e-778b97944229",
       "deploymentState": "DEPLOYED_CALENDARS, DEPLOY FOLDERS 2/5",
       "deploymentStatus": "PARTIAL_RESULT",
       "successfulFoldersCount": 0,
       "successfulSmartFoldersCount": 2,
       "successfulSubFoldersCount": 0,
       "successfulJobsCount": 2000,
       "successfulConnectionProfilesCount": 0,
       "successfulDriversCount": 0,
       "successfulCalendarsCount": 1,
       "isDeployDescriptorValid": false,
       "deployedFolders": 
       [
          "BigFolder1",
          "BigFolder2"
       ],
       "deployedCalendars": 
       [
          "PeriodicCalendarForRun"
       ]
    }

  • After running the deploy poll command again a few minutes later, notice that all the jobs have deployed successfully:

    Copy 
    {
       "deploymentFile": "1000_jobs_async_deploy.json",
       "pollId": "98b565da-eff8-4d78-881e-778b97944229",
       "deploymentState": "DEPLOYED_CALENDARS, DEPLOY FOLDERS 5/5",
       "deploymentStatus": "ENDED_OK",
       "successfulFoldersCount": 0,
       "successfulSmartFoldersCount": 5,
       "successfulSubFoldersCount": 0,
       "successfulJobsCount": 5000,
       "successfulConnectionProfilesCount": 0,
       "successfulDriversCount": 0,
       "successfulCalendarsCount": 1,
       "isDeployDescriptorValid": false,
       "deployedFolders":
       [
          "BigFolder1",
          "BigFolder2",
          "BigFolder3",
          "BigFolder4",
          "BigFolder5"
       ],
       "deployedCalendars": 
       [
          "PeriodicCalendarForRun"
       ]
    }

The following table describes the deploy poll command parameters.

Parameter

Description

deploymentFile

The name of the definitions file.

pollId

A unique ID to monitor the status of the deployment.

deploymentStatus

The status of the deployment.

Valid Values:

  • ENDED_OK: All the jobs in the definitions file deployed successfully.

  • ENDED_NOT_OK: None of the jobs in the definitions file deployed successfully.

  • PARTIAL_RESULT: Some of the jobs in the definitions file deployed successfully.

  • TIMED_OUT: The deployment took longer than 10 minutes and is canceled.

  • UNKNOWN: An unknown error occurred in the deployment.

successfulFoldersCount

Number of simple folders deployed.

successfulSmartFoldersCount

Number of SMART folders deployed.

successfulSubFoldersCount

Number of sub-folders deployed.

successfulJobsCount

Number of jobs deployed.

successfulConnectionProfilesCount

Number of connection profiles deployed.

successfulDriversCount

Number of JDBC drivers deployed.

isDeployDescriptorValid

Confirms if the deploy descriptor in the definitions file deployed. For detailed information, see Deploy Descriptor.

Values:

  • true

  • false

The following table describes additional deploy poll command parameters.

Parameter

Description

deploymentState

Describes what has already been deployed.

Valid Values:

  • DEPLOYED_CALENDARS: Confirms that calendars from the definitions file have deployed.

  • DEPLOYED_CONNECTION_PROFILES: Confirms that connection profiles listed in the definitions file have been deployed.

  • DEPLOYED_STANDARDS: Confirms that site standards from the definitions file have deployed.

  • DEPLOY FOLDERS x/x: Confirms that number of folders that have deployed out of the total number of folders included in the definitions file. 

deployedFolders

An array of the folder names that deployed.

deployedCalendars

An array of the calendar names that deployed.

deploy transform

The deploy transform command enables you to apply the rules of the deployDescriptorsFile to the original definitionsFile. The rules define the method to use that change the values of the JSON code properties in the original definitionsFile.

CLI Syntax

Copy 
ctm deploy transform <definitionsFile> <deployDescriptorFile>

The following table describes the deploy transform command parameters.

Parameter

Description

<definitionsFile>

The file or archive that contains code for jobs.

Valid Formats:

  • .json

  • .zip

  • .tar.gz

<deployDescriptorFile>

The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json"
-F "deployDescriptorFile=@examples/deployDescriptor.json"  "$endpoint/deploy/transform"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy jobs::get

The deploy jobs::get command enables you to get the definitions of jobs and folders that match a search criteria in a requested format.

CLI Syntax

Copy 
ctm deploy jobs::get [format] -s <search query>

The following table describes the deploy jobs::get command parameters.

Parameter

Description

format

The format in which to return the output, one of the following:

  • json: JSON format.

  • xml:job: Control-M import/export .xml format, as used by the defjob utility.

  • xml:folder: Control-M import/export .xml format, as used by the deffolder utility.

Default: json

-s is used to run a search using the query string format. The following table lists the fields that can be used in the search query:

Field

Criteria

Criteria Example

  • server

  • folder

  • library

  • job

  • Supported wildcards for server, folder, and z/OS library are * (asterisk) and ? (question mark).

  • To specify multiple servers, folders, or z/OS libraries, use , (commas).

  • The job field specifies a single job and does not support wildcards.

  • To specify a subfolder, include a : (colon) between each parent folder and subfolder in the path. Do not use wildcards in the subfolder.

  • If you use : (colons) in the folder field or if you use the job field to specify a job, specify a single value (without wildcards) in the server field.

  • To use multiple fields, separate by using the & (ampersand) character.

  • The server field was previously named ctm (deprecated name).

  • If you use : (colons) in the folder field to specify a subfolder, the query also returns details of any child subfolders within the specified subfolder.

  • If you use : (colons) in the folder field or if you use the job field, the output contains the PathElement property to define the subfolder or job.

server=*&folder=*

server=*&folder=Auto*

server=workbench&folder=AutomationAPISampleFlow

server=LocalControlM&folder=folder1:subfolder2

server=LocalControlM&folder=folder1&job=myJob

useArrayFormat

Enforces the display of jobs in an array format under a Jobs object, instead of displaying each job separately under an object that bears the name of the individual job.

This array format enables you to define more than one job with the same job name. For examples of the job array structure, see the examples in Folders and Flows.

The useArrayFormat field enforces the job array structure even when all returned jobs have distinct names (and no job name is used by more than one job).

Valid Values:

  • true

  • false

Default: false (a job array format is used only if multiple jobs with the same name are detected).

server=*&folder=*&useArrayFormat=true

The following command shows how to get a job in a JSON format for all the folders that start with Automation:

Copy 
ctm deploy jobs::get -s "server=*&folder=Automation*"

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

>curl -H "$AuthHeader" "$endpoint/deploy/jobs?server=*&folder=Auto*"

>curl -H "$AuthHeader" "$endpoint/deploy/jobs?server=*&folder=Auto*&format=XML"

>curl -H "$AuthHeader" "$endpoint/deploy/jobs?server=*&folder=Auto*&useArrayFormat=true"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

If you retrieve job definitions from a later version of Automation API, deployment of the job might fail in an environment with an earlier version of Automation API, due to unrecognized (new) job properties, and the following error is issued:

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

In such a case, 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

deploy job::delete

The deploy job::delete command enables you to delete a job from an existing folder.

CLI Syntax

Copy 
ctm deploy job::delete <jobPath> [server] [library]

The following table describes the deploy job::delete command parameters.

Parameter

Description

<jobPath>

Defines the full path of the job to delete.

Use colons as separators between folder, subfolder, and job.

Example: SMART_FOLDER_1:SMART_FOLDER_2:job_to_delete

server

Defines the name of the Control-M/Server .

Mandatory unless there is only one Control-M/Server in the system.

library

(z/OS) Defines the name of the z/OS library.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
server=LocalControlM
jobpath=SMART_FOLDER_1:SMART_FOLDER_2:job_to_delete
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/job/$jobpath?server=$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy folders::get

The deploy folders::get command enables you to get details of folders that match a search criteria. Definitions are returned in JSON format.

Scheduling definitions, event details, and folder variables are not included in the command response. For these details use deploy jobs::get.

CLI Syntax

Copy 
ctm deploy folders::get -s <search query>

-s is used to run a search using the query string format. The following table lists the fields that can be used in the search query:

Field

Criteria

Criteria Example

  • server

  • folder

  • folderType

  • application

  • subApplication

  • siteStandard

  • library

  • Supported wildcards for server,folder, and z/OS library are * (asterisk) and ? (question mark).

  • To specify multiple servers,folders, or z/OS libraries, use , (commas).

  • To use multiple fields, separate by using the & (ampersand) character.

  • For the folderType field, valid values are folder and simpleFolder.

server=*&folder=*

server=*&folder=Auto*

server=workbench&folder=AutomationAPISampleFlow

The following command shows how to get definitions of all folders that start with Automation:

Copy 
ctm deploy folders::get -s "server=*&folder=Automation*"

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/deploy/folders?server=*&folder=Auto*"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy folder::delete

The deploy folder::delete command enables you to delete a folder.

CLI Syntax

Copy 
ctm deploy folder::delete <server> <folderName> [library]

The following table describes the deploy folder::delete command parameters.

Parameter

Description

<server>

Defines the name of the Control-M/Server .

Mandatory unless there is only one Control-M/Server in the system.

<folderName>

Defines the name of the folder to delete.

library

(z/OS) Defines the name of the z/OS library.

If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
server=
folder=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/folder/$folder?server=$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy subfolder::delete

The deploy subfolder::delete command enables you to delete a sub-folder and all jobs under the sub-folder.

CLI Syntax

Copy 
deploy subfolder::delete <subFolderPath> [server] [library]

The following table describes the deploy subfolder::delete command parameters.

Parameter

Description

<subFolderPath>

Defines the full path of the sub-folder to delete.

Use a colon to separate the parent folder from sub-folders.

server

Defines the name of the Control-M/Server .

Mandatory unless there is only one Control-M/Server in the system.

library

(z/OS) Defines the name of the z/OS library.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
server=
subfolderpath=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/subfolder/$subfolderpath?server=$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy calendars::get

The deploy calendars::get command enables you to get the definitions of calendars based on specified search criteria.

Calendars are used to set scheduling criteria that you can apply to multiple jobs, instead of having to define scheduling criteria in each individual job. For information about defining calendars and calendar scheduling parameters, see Calendars.

CLI Syntax

Copy 
ctm deploy calendars::get [limit] -s <search query>

The following table describes the deploy calendars::get command parameters.

Parameter

Description

limit

Maximum number of calendars to include in the response.

Default: 10,000

Use the required -s option to specify a query string to search for. The following table lists the fields that can be used in the search query:

Field

Criteria

Criteria Examples

  • name

  • type

  • server

  • alias

  • Supported wildcards are * (asterisk) and ? (question mark).

  • To use multiple criteria, separate by using the & (ampersand) character.

  • For type (of calendar), choose from the following options:

    • Regular

    • Periodic

    • RuleBasedCalendar

name=*

name=*&server=auto*

name=S1,S2&server=*

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET  "$endpoint/deploy/calendars?type=Periodic&name=S*"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy calendar::delete

The deploy calendar::delete command enables you to delete a defined calendar.

CLI Syntax

Copy 
ctm deploy calendar::delete <calendarName> [serverName]

The following table describes the deploy calendar::delete command parameters.

Parameter

Description

<calendarName>

Defines the name of the predefined calendar

[serverName]

Defines the name of the Control-M/Server .

If not specified, it is assumed that you want to delete a global calendar.

If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
calendar=
server=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/calendar/$calendar?server=$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Connection Profiles

The following API commands relate to the deployment of connection profiles:

deploy connectionprofiles:centralized::get

The deploy connectionprofiles:centralized::get command enables you to get the full definitions of centralized connection profiles, based on specified search criteria.

Centralized connection profiles are stored centrally in the Control-M database and can be used by all your Control-M/Agents. Definitions for such Connection Profiles contain the Centralized parameter set to true.

CLI Syntax

Copy 
ctm deploy connectionprofiles:centralized::get -s <search query>

Use the required -s option to specify a query string to search for. The following table lists the fields that can be used in the search query:

Field

Description

Criteria Examples

type

Type of connection profile, one of the following options:

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

For all types, use an * (asterisk).

type=Hadoop&name=myCP

type=*&name=hd*

name

Name of connection profile(s).

Supported wildcards are * (asterisk) and ? (question mark).

For multiple values, use , (commas) between values.

The default is * (all).

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
name=
type=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofiles/centralized?type=$type&name=$name"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy connectionprofiles:centralized:status::get

The deploy connectionprofiles:centralized:status::get command enables you to get a summary of details for centralized connection profiles (including basic properties and metadata, and the current deployment status), based on specified search criteria.

Centralized connection profiles are stored centrally in the Control-M database and can be used by all your Agents. Definitions for such Connection Profiles contain the Centralized parameter set to true.

CLI Syntax

Copy 
ctm deploy connectionprofiles:centralized:status::get <limit> -s <search query>

Where <limit> is the maximum number of connection profiles to include in the response.

Use the required -s option to specify a query string to search for. The following table lists the fields that can be used in the search query:

Field

Description

Criteria Examples

type

Type of connection profile, one of the following options:

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

For all types, use an * (asterisk).

type=Hadoop&name=myCP

type=*&name=hd*

name

Name of connection profile(s).

Supported wildcards are * (asterisk) and ? (question mark).

For multiple values, use , commas between values.

The default is * (all).

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
name=
type=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofiles/centralized/status?type=$type&name=$name&limit=50"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy connectionprofile:centralized::deploymentstatus

The deploy connectionprofile:centralized::deploymentstatus command enables you to get the deployment status information for a centralized connection profile.

CLI Syntax

Copy 
ctm deploy connectionprofile:centralized::deploymentstatus <type> <name>

The following table describes the deploy connectionprofile:centralized::deploymentstatus command parameters.

Parameter

Description

<type>

Type of connection profile, one of the following:

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

<name>

Name of the connection profile.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofile/centralized/$type/$name/deploymentstatus"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy connectionprofile:centralized::delete

The deploy connectionprofile:centralized::delete command enables you to delete a centralized connection profile from the Control-M database.

CLI Syntax

Copy 
ctm deploy connectionprofile:centralized::delete <type> <name>

The following table describes the deploy connectionprofile:centralized::delete command parameters.

Parameter

Description

<type>

Type of connection profile, one of the following:

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

<name>

Name of the connection profile.

If annotation is enabled for the Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/connectionprofile/centralized/$type/$name"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy connectionprofiles:local::get

The deploy connectionprofiles:local::get command enables you to get the details of local connection profiles associated with your Control-M/Agents, based on specified search criteria.

CLI Syntax

Copy 
ctm deploy connectionprofiles:local::get -s <search query>

Use the required -s option to specify a query string to search for. The following table includes the fields that can be used in the search query:

Field

Criteria

Criteria Example

  • server

  • agent

  • type

  • No wildcards supported.

  • To use multiple criteria, separate by using an & (ampersand).

  • For type (of connection profile) choose from the following options:

    • Hadoop

    • Database

    • FileTransfer

    • ApplicationIntegrator:<customType>

    • Informatica

    • SAP

    • AWS

    • Azure

The server field was previously named ctm (deprecated name).

server=workbench&agent=agent&type=Database

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
server=
agent=
type=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofiles/local?server=$server&agent=$agent&type=$type"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy connectionprofile:local::delete

The deploy connectionprofile:local::delete command enables you to delete a local connection profile that was associated with a Control-M/Agent.

CLI Syntax

Copy 
ctm deploy connectionprofile:local::delete <server> <agent> <type> <name>

The following table describes the deploy connectionprofile:local::delete command parameters.

Parameter

Description

<server>

Name of Control-M/Server.

<agent>

Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent.

<type>

Type of connection profile, one of the following:

  • Hadoop

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • SAP

  • AWS

  • Azure

<name>

Name of the connection profile.

If annotation is enabled for the Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
server=
agent=
type=
name=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/connectionprofile/local/$server/$agent/$type/$name"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy connectionprofile::test

The deploy connectionprofile::test command enables you to test the definitions of a connection profile (without deploying it) on a specific Control-M/Server and Agent. You provide the definitions of the Connection Profiles through a JSON-format definitions file.

CLI Syntax

Copy 
ctm deploy connectionprofile::test <definitionsFile> [ctm] [agent]

The following table describes the deploy connectionprofile::test command parameters.

Parameter

Description

definitionsFile

Name of the JSON-format definitions file.

ctm

Name of the Control-M/Server .

This parameter is required for a centralized connection profile. It is not required for a local connection profile (which is already associated with a specific Control-M/Server).

agent

Host name or alias of the Agent. This is the logical name of the Agent.

This parameter is required for a centralized connection profile. It is not required for a local connection profile (which is already associated with a specific Control-M/Agent).

REST API Syntax

cURL:

Copy 
endpoint=https://<controlm>:8443/automation-api
token=
ctm=
agent=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" \
-X POST "$endpoint/deploy/connectionprofile/test?ctm=$ctm&agent=$agent" \
-F "definitionsFile=@/C:/myConnectionProfile.json"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Application Integrator Deployment

The following API commands relate to the deployment of Application Integrator job types:

deploy jobtype

This command enables you to deploy a new job type provided in the .ctmai format to Control-M.

If you specify the agent and server in your command, the job type is also published to the Control-M/Agent.

The response notifies you whether the deployment succeeded or failed.

This API command is supported in Control-M environments with Control-M/Enterprise Manager version 9.0.20.100 or later.

CLI Syntax

Copy 
ctm deploy jobtype <definitionsFile> [agent] [server] [-f <payload file>]

The following table describes the deploy jobtype command parameters.

Parameter

Description

definitionsFile

The name of a .ctmai binary file that contains the definitions of the job type and was exported from Application Integrator.

agent

(Optional) Host name or alias of the Agent. This is the logical name of the Agent.

server

(Optional) Name of the Control-M/Server , required only in an environment with multiple servers.

payload file

(Optional) Name of a .json file that contains parameter values, for use instead of specifying parameters in the API command.

Here is an example of the content of such a file:

Copy 
{  
   "server": "server1",  
   "agent": "agent1"
}

REST API Syntax

cURL:

Copy 
token=
endpoint=https://<controlm>:8443/automation-api
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -F "definitionsFile=aif.ctmai"
-F "payloadFile=payload.json"  "$endpoint/deploy/jobtype"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy jobtype::get

This command enables you 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 deploy jobtype). You can use this command when you want to copy job types from one environment to another.

CLI Syntax

Copy 
ctm deploy jobtype::get <jobTypeId> -o <filePath>

The following table describes the deploy jobtype::get command parameters.

Parameter

Description

<JobTypeId>

Defines the ID for the custom job type defined through Control-M Application Integrator.

You can obtain this ID in any of the following ways:

  • The name of a .ctmai file that you deployed previously.

  • The Plug-in ID setting of a plug-in in Control-M Application Integrator.

<filePath>

Defines the full path to the Job Type (.ctmai) file that you want to download.

REST API Syntax

cURL:

Copy 
token=
jobType=DevJobType
filePath="C:\JobTypes\ProdJobType.ctmai"
endpoint=https://<controlm>:8443/automation-api
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/deploy/jobtype?jobTypeId=$jobType" -o $filePath

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy ai:jobtype

This command enables you to publish a deployed Application Integrator job type to the Control-M/Agent to allow it to run.

The response notifies you whether the deployment succeeded or failed.

This API command is supported in Control-M environments with Control-M/Enterprise Manager version 9.0.19.100 or later.

CLI Syntax

Copy 
ctm deploy ai:jobtype <server> <agent> <jobTypeId>

The following table describes the deploy ai:jobtype command parameters.

Parameter

Description

<server>

Name of the Control-M/Server .

<agent>

Host name or alias of the Agent. This is the logical name of the Agent.

<JobTypeId>

ID for the custom job type defined through Control-M Application Integrator.

The corresponding setting in the Control-M Application Integrator is Plug-in ID. For more information, see Application Integrator Jobs.

REST API Syntax

cURL:

Copy 
token=
endpoint=https://<controlm>:8443/automation-api
server=
agent=
jobType=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST 
"$endpoint/deploy/ai/jobtype?server=$server&agent=$agent&jobTypeId=$jobType"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy ai:jobtypes::get

The deploy ai:jobtypes::get command enables you to get details of deployed Application Integrator job types that match a specified search query.

CLI Syntax

Copy 
ctm deploy ai:jobtypes::get [-s <search query>]

The optional -s option enables you to limit the list to job types that match specified criteria. The format for the query string is "field1=criteria1&field2=criteria2", according to the following guidelines:

Fields

Criteria

Example

  • jobTypeName

  • jobTypeId

Use * (asterisks) for wildcards.

"jobTypeName=startName*&jobTypeId=*partOfID*"

If you include both fields in the query, separate them with an & (ampersand).

REST API Syntax

cURL:

Copy 
token=
endpoint=https://<controlm>:8443/automation-api
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET 
"$endpoint/deploy/ai/jobtypes?jobTypeId=<ID string>&jobTypeName=<name string>"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

The following example response lists three Application Integrator job types, two of which are ready to deploy and one more in draft status:

Copy 
{
   'jobtypes': 
   [
      {'status': 'ready to deploy', 'jobTypeId': 'CTMREMOTE', 'description': 'Track job running on remote Control-M Stack', 'jobTypeName': 'Monitor Remote Job'},
      {'status': 'ready to deploy', 'jobTypeId': 'AZUREBLOB', 'description': 'Azure blob storage', 'jobTypeName': 'Azure blob storage'},
      {'status': 'draft', 'jobTypeId': 'DRAFT4GET', 'description': 'Draft Job Type', 'jobTypeName': 'Draft Job'}
   ]
}

The following table describes the deploy ai:jobtypes::get command parameters.

Parameter

Description

status

The status of the job type, either ready to deploy or draft.

jobTypeId

The job type application ID (or Plug-in ID) defined in Control-M Application Integrator.

For more information, see Application Integrator Jobs.

description

A description of the job type, as defined (optionally) in Control-M Application Integrator.

jobTypeName

The job type name defined in Control-M Application Integrator.

Site Standards

The following API commands relate to the deployment of Site Standards:

To enable Site Standards configuration, you must first install the Control-M Workload Change Manager add-on.

deploy sitestandards::get

The deploy sitestandards::get command enables you to get the definitions of one or more deployed Site Standards.

To use this API command, you must have Control-M/Enterprise Manager version 9.0.21 or later.

CLI Syntax

Copy 
ctm deploy sitestandards::get -s <search query>

The optional -s enables you to limit the list to Site Standards that match specified criteria. The following field can be used in the search query:

Field

Criteria

Criteria Example

name

  • Supported Wildcard: * (asterisk).

  • Escape character: \ (backslash).

name=*

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -k  -H "$AuthHeader" "$endpoint/deploy/sitestandards?name=*"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandard::delete

The deploy sitestandard::delete command enables you to delete an existing Site Standard.

CLI Syntax

Copy 
ctm deploy sitestandard::delete <siteStandardName>

Where <siteStandardName> is the name of the Site Standard to delete.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X DELETE -H "$AuthHeader" "$endpoint/deploy/sitestandard?siteStandardName=Dev_Standard"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandard::rename

The deploy sitestandard::rename command enables you to rename an existing Site Standard.

CLI Syntax

Copy 
ctm deploy sitestandard::rename <oldName> <newName>

The following table describes the deploy sitestandard::rename command parameters.

Parameter

Description

<oldName>

Name of the Site Standard to rename.

<newName>

The new Site Standard name.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/deploy/sitestandard/rename?oldName=<Dev_Standard>&newName=<Prod_Standard>"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandards:details::get

The deploy sitestandards:details::get command enables you to get specific details for one or more Site Standards.

To use this API command, you must have Control-M/Enterprise Manager version 9.0.21 or later.

CLI Syntax

Copy 
ctm deploy sitestandards:details::get -s <search query>

The optional -s enables you to limit the list to Site Standards that match specified criteria. The following field can be used in the search query:

Field

Criteria

Criteria Example

name

  • Supported Wildcards: * (asterisk) and ? (question mark).

  • Escape Character: \ (backslash).

name=*

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -k -H "$AuthHeader" "$endpoint/deploy/sitestandards/details?name=*

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandard:fieldRestriction::get

The deploy sitestandard:fieldRestriction::get command enables you to get the list of allowed values defined for a restricted-text field in a Site Standard.

CLI Syntax

Copy 
ctm deploy sitestandard:fieldRestriction::get <standardName> <fieldName>

The following table describes thedeploy sitestandard:fieldRestriction::get command parameters.

Parameter

Description

<standardName>

The name of the Site Standard.

<fieldName>

The name of the field, in lowercase characters.

Currently, only the application field is supported.

REST API Syntax

cURL:

Copy 
standardName=standard1
fieldName=application
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET 
"$endpoint/deploy/sitestandard/$standardName/fieldRestriction/$fieldName"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandard:fieldRestriction::replaceValues

The deploy sitestandard:fieldRestriction::replaceValues command enables you to replace the allowed values defined for a restricted-text field in a Site Standard with a new set of allowed values.

CLI Syntax

Copy 
ctm deploy sitestandard:fieldRestriction::replaceValues <standardName> <fieldName> -f <valuesFile>

The following table describes thedeploy sitestandard:fieldRestriction::replaceValues command parameters.

Parameter

Description

<standardName>

The name of the Site Standard.

<fieldName>

The name of the field, in lowercase characters.

Currently, only the application field is supported.

<valuesFile>

A .json file that contains new values for the field, to replace all existing values.

Here is an example of the content of such a file:

Copy 
{
   "values": [
   {
      "value": "App1"
   },
   {
      "value": "App2",
      "description": "description of application2"
   }]
}

REST API Syntax

cURL:

Copy 
standardName=standard1
fieldName=application
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X POST -H "Content-Type: application/json" -H "$AuthHeader"
-d "@examples/SiteStandardApplicationFieldValues.json"
"$endpoint/deploy/sitestandard/$standardName/fieldRestriction/$fieldName"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Site Standard Policies

The following API commands relate to the deployment of Site Standard Policies

You must have Control-M/Enterprise Manager version 9.0.21 or later to run Site Standard Policies commands. To enable Site Standards Policies configuration, you must first install the Control-M Workload Change Manager add-on.

deploy sitestandardpolicies::add

The deploy sitestandardpolicies::add command enables you to deploy new Site Standard Policies based on definitions in a Definitions File (as described in Site Standard Policies).

CLI Syntax

Copy 
ctm deploy sitestandardpolicies::add <definitionsFile>.json

The following table describes thedeploy sitestandardpolicies::add command parameters.

Parameter

Description

definitionsFile

Defines the full path (directory and filename) of the JSON file that contains the definitions of new Policies, as described in Site Standard Policies.

The response summarizes the number of Standard Policies that were added successfully (based on the Definitions File) and lists their names.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

>curl -k  -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicies"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandardpolicies::get

The deploy sitestandardpolicies::get command enables you to get the definitions of deployed Site Standard Policies.

The response is formatted as described in Site Standard Policies, and can be used in subsequent deployments.

CLI Syntax

Copy 
ctm deploy sitestandardpolicies::get [-s "name=<SiteStandardPolicy>"]

The optional -s enables you to filter the response to specific site standard policies. You can specify multiple values separated by , (commas), and you can use * (asterisks) as wildcards.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
>curl -k -X POST -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicies?name=a*,*b"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandardpolicy::rename

The deploy sitestandardpolicy::rename command enables you to rename an existing Site Standard Policy.

CLI Syntax

Copy 
ctm deploy sitestandardpolicy::rename <siteStandardPolicyName> <siteStandardPolicyNewName>

The following table describes thedeploy sitestandardpolicies::rename command parameters.

Parameter

Description

siteStandardPolicyName

Defines the Policy to rename.

siteStandardPolicyNewName

Defines the new name of the Policy.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
>curl -X POST -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicy/rename?siteStandardPolicyName=<BIZ_Policy>&siteStandardPolicyNewName=<DEV_Policy>"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandardpolicy::delete

The deploy sitestandardpolicy::delete command enables you to delete a Site Standard Policy.

CLI Syntax

Copy 
ctm deploy sitestandardpolicy::delete <siteStandardPolicyName>

Where <siteStandardPolicyName> defines the Site Standard Policy to delete.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -X DELETE -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicy?siteStandardPolicyName=BIZ_Policy"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

deploy sitestandardpolicies:details::get

The deploy sitestandardpolicies:details::get command enables you to get the details of all existing Site Standard Polices in your Control-M environment.

CLI Syntax

Copy 
ctm deploy sitestandardpolicies:details::get [-s "name=<SiteStandardPolicy>"]

The optional -s enables you to filter the response to specific site standard policies. You can specify multiple values separated by , (commas), and you can use * (asterisks) as wildcards.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

>curl -k  -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicies/details?name=a*,*b"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

The following example response contains details of Site Standard Polices:

Copy 
{
   "siteStandardPolicies": [
   {
      "name": "ACC_Policy",
      "description": "Policy for accounting team",
      "createdTime": "2021-06-16T03:09:45Z",
      "username": "emuser",
      "siteStandard": "ACC_Standard",
      "status": "Active"
   },
   {
      "name": "PROD_Policy",
      "description": "Policy for production teams",
      "createdTime": "2021-12-20T07:18:36Z",
      "username": "emuser",
      "siteStandard": "PROD_Standard",
      "status": "Not Active"
   }
   ]
}

The following table describes the deploy sitestandardpolicies:details::get command parameters.

Parameter

Description

name

Defines the name of the Policy.

description

Describes the Policy.

createdTime

Determines the time that the Policy was created.

username

Defines the name of the user who created the Policy.

siteStandard

Defines the Site Standard associated with the Policy.

status

Indicates whether the Policy is Active or Not Active.

Workbench

The following API command is available when you use a Control-M Workbench environment.

Docker images of the Control-M Workbench are available in https://hub.docker.com/r/controlm/workbench.

deploy workbench::import

The deploy workbench::import command enables you to import to the Workbench a set of definitions files (with definitions of jobs, connection profiles, calendars, site standards, and Application Integrator plug-ins) packed in a zip file.

For more information, see the Control-M Workbench documentation.

CLI Syntax

Copy 
ctm deploy workbench::import <resources.zip>

Where <resources.zip> is a zip file that contains definitions to import.

REST API Syntax

cURL:

Copy 
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
curl -X 'POST' -H 'accept: application/json' -H "$AuthHeader" -H 'Content-Type: multipart/form-data'
-F 'definitionsFile=@resources.zip;type=application/x-zip-compressed' '$endpoint/deploy/workbench/import'