Deploy Service
The deploy service allows you to transfer job and configuration definitions to Control-M. After a job is deployed, Control-M schedules it according to the scheduling criteria and dependencies. The deploy service overwrites any existing definition with the same name.
Jobs, Folders, and Calendars
The following API commands enable you to deploy jobs, folders, calendars:
-
This command is used for most object types, including connection profiles and site standards.
deploy
The deploy command enables you to deploy the definitions file provided to Control-M. As part of the deployment, a build occurs to ensure code validity. The deploy command can receive definitions files for folders, jobs, calendars, connection profiles, and site standards in .json format
CLI Syntax
The following shows the CLI syntax for the deploy command:
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:
|
deployDescriptorFile |
(Optional) Defines the file with the rules to apply to the
original definitions file. The rules enable the transformation of Control-M code
properties in |
If annotation is enabled for the Scheduling definitions, Configuration management, or Control-M security category in the
REST API Syntax
The following example shows the REST API syntax for the deploy command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: 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"
To select the AuthHeader value ("Authorization: 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 number 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 in the deploy command response by default. To include warning messages in the response, add the deployWarningsEnabled property to the automation-api.properties file, and set it to true.
deploy poll
If the deployment takes longer than expected to update the Control-M database server, the response returns a poll ID and a deployment status. This is called asynchronous deployment. You can continue to work while asynchronous deployment continues in the background. To get a deployment status update, run the deploy poll command. All users with the required privileges can run the deploy poll command.
This feature requires Control-M/EM 9.0.21 or higher.
It is highly unlikely that a deploy response takes so long that asynchronous deployment is activated. Asynchronous deployment times out after 10 minutes. To change the timeout length, contact support.
CLI Syntax
The following shows the CLI syntax for the deploy poll command:
ctm deploy poll <pollId>
REST API Syntax
The following example shows the REST API syntax for the deploy poll command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/deploy/poll?pollId"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Response
The following examples show the deploy poll response parameters.
The following example shows a response for a definitions file that contains 5,000 jobs and is deployed with 5 folders of 1,000 jobs each. The response shows that only 250 jobs were deployed, so the deployment status is partial and a poll ID is provided:
{
"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, were deployed:
{
"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 you run the deploy poll command again a few minutes later, notice that all the jobs deployed successfully:
{
"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 response parameters.
Parameter |
Description |
---|---|
deploymentFile |
Defines the definitions filename. |
pollId |
Determines a unique ID to monitor the deployment status. |
deploymentStatus |
Determines the deployment status. Valid Values:
|
successfulFoldersCount |
Determines the number of simple folders that are deployed. |
successfulSmartFoldersCount |
Determines the number of SMART folders that are deployed. |
successfulSubFoldersCount |
Determines the number of sub-folders that are deployed. |
successfulJobsCount |
Determines the number of jobs that are deployed. |
successfulConnectionProfilesCount |
Determines the number of connection profiles that are deployed. |
successfulDriversCount |
Determines the number of JDBC drivers that are deployed. |
isDeployDescriptorValid |
Confirms if the deploy descriptor in the definitions file is deployed. For detailed information, see Deploy Descriptor. Valid Values:
|
The following table describes additional deploy poll response parameters.
Parameter |
Description |
---|---|
deploymentState |
Describes what was already deployed. Valid Values:
|
deployedFolders |
Determines an array of the folder names that are deployed. |
deployedCalendars |
Determines an array of the calendar names that are deployed. |
deploy transform
The deploy transform command enables you to apply the rules of the deployDescriptorsFile to the original definitions file. The rules define the method to change the JSON code property values in the original definitions file.
CLI Syntax
The following shows the CLI syntax for the deploy transform command:
ctm deploy transform <definitionsFile> <deployDescriptorFile>
The following table describes the deploy transform command parameters.
Parameter |
Description |
---|---|
definitionsFile |
Defines the file Valid Formats:
|
deployDescriptorFile |
Defines the file with the rules to apply to the original definitions file. The rules enable the transformation of Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
REST API Syntax
The following example shows the REST API syntax for the deploy transform command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST -F "definitionsFile=@examples/AutomationAPISampleFlow.json"
-F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/deploy/transform"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
deploy jobs::get
The deploy jobs::get command enables you to get the job and folder definitions that match a search criteria in a requested format.
CLI Syntax
The following shows the CLI syntax for the deploy jobs::get command:
ctm deploy jobs::get [format] -s <search query>
The following table describes the deploy jobs::get command parameters.
Parameter |
Description |
---|---|
format |
Determines the output format. Valid Values:
Default: json |
The -s is a required option to run a search in the query string format.
The following table lists the fields available for a search query.
Field |
Criteria |
Criteria Example |
---|---|---|
|
|
server=*&folder=* server=*&folder=Auto* server=workbench&folder=AutomationAPISampleFlow server=LocalControlM&folder=folder1:subfolder2 server=LocalControlM&folder=folder1&job=myJob |
Enforces the display of objects in array structures, including jobs and resources. Job arrays enable you to define more than one job with the same job name. Resource arrays enable you to associate a job with a resource pool and lock resource that both have the same name. For examples of these array structures, see the examples in Folders and Flows and in Resources. The useArrayFormat field enforces array structures even when all returned jobs have distinct names, and it enforces the resource array structure even when all resources in a job have distinct names. Valid Values:
Default: false (array structures are used only if multiple jobs with the same name are detected, and a resource array format is utilized only if a job has a resource pool and a lock resource with the same name). |
server=*&folder=*&useArrayFormat=true |
The following command shows how to get a job in JSON format for all the folders that start with Automation:
ctm deploy jobs::get -s "server=*&folder=Automation*"
REST API Syntax
The following example shows the REST API syntax for the deploy jobs::get command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: 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"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
If you retrieve job definitions from a higher version of Control-M Automation API, the job deployment might fail in an environment with an earlier version of Control-M Automation API, due to new and unrecognized job properties. The following error appears:
<Name of new property> is an unknown keyword...
In this situation, add the min.aapi.ste.version property to the automation-api.properties file and set it to the target (lower) version of Control-M Automation API. For example, to deploy a job that was defined in Control-M Automation API 9.0.21.215 to an environment with Control-M 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
The following shows the CLI syntax for the deploy job::delete command:
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. Add colons as separators between a folder, subfolder, and job. Example: SMART_FOLDER_1:SMART_FOLDER_2:job_to_delete |
server |
Defines the name of the Control-M/Server. The parameter is mandatory unless there is only one Control-M/Server in the system. |
library |
Defines the name of the z/OS library. |
REST API Syntax
The following example shows the REST API syntax for the deploy job::delete command in cURL:
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="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/job/$jobpath?server=$server"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy folders::get command:
ctm deploy folders::get -s <search query>
where -s runs a search using the query string format.
The following table lists the fields available for a search query.
Field |
Criteria |
Criteria Example |
---|---|---|
|
|
server=*&folder=* server=*&folder=Auto* server=workbench&folder=AutomationAPISampleFlow |
The following command shows how to get definitions of all folders that start with Automation:
ctm deploy folders::get -s "server=*&folder=Automation*"
REST API Syntax
The following example shows the REST API syntax for the deploy folders::get command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/deploy/folders?server=*&folder=Auto*"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy folder::delete command:
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. This parameter is mandatory unless there is only one Control-M/Server in the system. |
folderName |
Defines the name of the folder to delete. |
library |
Defines the name of the z/OS library. |
If annotation is enabled for the Scheduling definitions category in the
REST API Syntax
The following example shows the REST API syntax for the deploy folder::delete command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
server=
folder=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/folder/$folder?server=$server"
To select the AuthHeader value ("Authorization: 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 in the sub-folder.
CLI Syntax
The following shows the CLI syntax for the deploy subfolder::delete command:
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. You must include a colon to separate the parent folder from the sub-folders. |
server |
Defines the name of the Control-M/Server. This parameter is mandatory unless there is only one Control-M/Server in the system. |
library |
Defines the name of the z/OS library. |
REST API Syntax
The following example shows the REST API syntax for the deploy subfolder::delete command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
server=
subfolderpath=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/subfolder/$subfolderpath?server=$server"
To select the AuthHeader value ("Authorization: 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.
You can define scheduling criteria in calendars and apply them to multiple jobs instead of defining scheduling criteria for each individual job. For information about how to define calendars and calendar scheduling parameters, see Calendars.
CLI Syntax
The following shows the CLI syntax for the deploy calendars::get command:
ctm deploy calendars::get [limit] -s <search query>
The following table describes the deploy calendars::get command parameters.
Parameter |
Description |
---|---|
limit |
Determines the maximum number of calendars to include in the response. Default: 10,000 |
-s runs a search in the query string format. The following table lists the fields available for a search query.
Field |
Criteria |
Criteria Examples |
---|---|---|
|
|
name=* name=*&server=auto* name=S1,S2&server=* |
REST API Syntax
The following example shows the REST API syntax for the deploy calendars::get command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/deploy/calendars?type=Periodic&name=S*"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy calendar::delete command:
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 the
REST API Syntax
The following example shows the REST API syntax for the deploy calendar::delete command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
calendar=
server=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/calendar/$calendar?server=$server"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Connection Profiles
The following API commands enable you to deploy connection profiles:
-
This command is used to deploy many different object types and is described separately.
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
CLI Syntax
The following shows the CLI syntax for the deploy connectionprofiles:centralized::get command:
ctm deploy connectionprofiles:centralized::get -s <search query>
where -s is a required option to run a search in the query string format.
The following table lists the fields available for a search query:
Field |
Description |
Criteria Examples |
---|---|---|
type |
Determines the connection profile type. Valid Values:
For all types, the value is an *. |
type=Hadoop&name=myCP type=*&name=hd* |
name |
Defines the connection profile name. Supported wildcards are * and ?. Multiple values are separated with commas. Default: * (all) |
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofiles:centralized::get command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
name=
type=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofiles/centralized?type=$type&name=$name"
To select the AuthHeader value ("Authorization: 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 centralized connection profile details based on search criteria. The connection profile details include basic properties, metadata, and the current deployment status.
Centralized connection profiles are stored centrally in
CLI Syntax
The following shows the CLI syntax for the deploy connectionprofiles:centralized:status::get command:
ctm deploy connectionprofiles:centralized:status::get <limit> -s <search query>
where <limit> is the maximum number of connection profiles to include in the response.
-s is a required option to run a search in the query string format.
The following table lists the fields available for a search query:
Field |
Description |
Criteria Examples |
---|---|---|
type |
Determines the connection profile type. Valid Values:
For all types, the value is an *. |
type=Hadoop&name=myCP type=*&name=hd* |
name |
Defines the connection profile name. Supported wildcards are * and ?. Multiple values are separated with commas. Default: * (all) |
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofiles:centralized:status::get command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
name=
type=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofiles/centralized/status?type=$type&name=$name&limit=50"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
deploy connectionprofile:centralized::deploymentstatus
The deploy connectionprofile:centralized::deploymentstatus command enables you to get deployment status information for a centralized connection profile.
CLI Syntax
The following shows the CLI syntax for the deploy connectionprofile:centralized::deploymentstatus command:
ctm deploy connectionprofile:centralized::deploymentstatus <type> <name>
The following table describes the deploy connectionprofile:centralized::deploymentstatus command parameters.
Parameter |
Description |
---|---|
type |
Determines the connection profile type. Valid Values:
|
name |
Defines the connection profile name. |
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofile:centralized::deploymentstatus command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofile/centralized/$type/$name/deploymentstatus"
To select the AuthHeader value ("Authorization: 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
CLI Syntax
The following shows the CLI syntax for the deploy connectionprofile:centralized::delete command:
ctm deploy connectionprofile:centralized::delete <type> <name>
The following table describes the deploy connectionprofile:centralized::delete command parameters.
Parameter |
Description |
---|---|
type |
Determines the connection profile type. Valid Values:
|
name |
Defines the connection profile name. |
If annotation is enabled for the Control-M security category in the
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofile:centralized::delete command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/connectionprofile/centralized/$type/$name"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
deploy connectionprofile:centralized::test
The deploy connectionprofile:centralized::test command enables you to test an existing centralized connection profile on a specific Control-M/Agent.
CLI Syntax
The following shows the CLI syntax for the deploy connectionprofile:centralized::test command:
ctm deploy connectionprofile:centralized::test <type> <name> <server> <agent>
The following table describes the deploy connectionprofile:centralized::test command parameters.
Parameter |
Description |
---|---|
type |
Determines the connection profile type. Valid Values:
|
name |
Defines the connection profile name. |
server |
Defines the Control-M/Server name. |
agent |
Defines the Agent hostname or alias. This is the Agent logical name. |
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofile:centralized::test command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
server=
agent=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/deploy/connectionprofile/centralized/test/$type/$name/$server/$agent"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy connectionprofiles:local::get command:
ctm deploy connectionprofiles:local::get -s <search query>
where -s is a required option to run a search in the query string format.
The following table lists the fields available for a search query:
Field |
Criteria |
Criteria Example |
---|---|---|
|
|
server=workbench&agent=agent&type=Database |
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofiles:local::get command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
server=
agent=
type=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/deploy/connectionprofiles/local?server=$server&agent=$agent&type=$type"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy connectionprofile:local::delete command:
ctm deploy connectionprofile:local::delete <server> <agent> <type> <name>
The following table describes the deploy connectionprofile:local::delete command parameters.
Parameter |
Description |
---|---|
server |
Defines the Control-M/Server name. |
agent |
Defines the Agent host name or alias. This is the Agent logical name. |
type |
Determines the connection profile type. Valid Values:
|
name |
Defines the connection profile name. |
If annotation is enabled for the Control-M security category in the CCM, you must also provide an annotation to justify your action. For more information, see Annotation Input.
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofile:local::delete command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
server=
agent=
type=
name=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/deploy/connectionprofile/local/$server/$agent/$type/$name"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
deploy connectionprofile::test
The deploy connectionprofile::test command enables you to test connection profile definitions on a specific Control-M/Server and Agent without deploying it. You provide the definitions of the Connection Profiles in a JSON-format definitions file.
CLI Syntax
The following shows the CLI syntax for the deploy connectionprofile::test command:
ctm deploy connectionprofile::test <definitionsFile> [ctm] [agent]
The following table describes the deploy connectionprofile::test command parameters.
Parameter |
Description |
---|---|
definitionsFile |
Defines the name of the definitions file in JSON-format. |
ctm |
Defines the Control-M/Server name. This parameter is required for a centralized connection profile. It is not required for a local connection profile that is already associated with a specific Control-M/Server. |
agent |
Defines the Agent hostname or alias. This is the Agent logical name. This parameter is required for a centralized connection profile. It is not required for a local connection profile that is already associated with a specific Agent. |
REST API Syntax
The following example shows the REST API syntax for the deploy connectionprofile::test command in cURL:
endpoint=https://<controlm>:8443/automation-api
token=
ctm=
agent=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" \
-X POST "$endpoint/deploy/connectionprofile/test?ctm=$ctm&agent=$agent" \
-F "definitionsFile=@/C:/myConnectionProfile.json"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Application Integrator Deployment
The following API commands enable you to deploy Application Integrator job types:
deploy jobtype
The deploy jobtype command enables you to deploy a new job type provided in the .ctmai format to Control-M.
If you specify the Agent and Control-M/Server in your command, the job type is also published to the Agent.
The response notifies you whether the deployment succeeded or failed.
This API command is supported in Control-M environments with Control-M/EM version 9.0.20.100 or higher.
CLI Syntax
The following shows the CLI syntax for the deploy jobtype command:
ctm deploy jobtype <definitionsFile> [agent] [server] [-f <payload file>]
The following table describes the deploy jobtype command parameters.
Parameter |
Description |
---|---|
definitionsFile |
Defines the name of a .ctmai binary file that contains the job type definitions and is exported from Application Integrator. |
agent |
(Optional) Defines the Agent host name or alias. This is the Agent logical name. |
server |
(Optional) Defines the Control-M/Server name |
payload file |
(Optional) Defines the name of a .json file that contains parameter values. The payload file replaces the need to specify parameters in the API command. The following example shows the contents of a payload file: Copy
|
REST API Syntax
The following example shows the REST API syntax for the deploy jobtype command in cURL:
token=
endpoint=https://<controlm>:8443/automation-api
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST -F "definitionsFile=aif.ctmai"
-F "payloadFile=payload.json" "$endpoint/deploy/jobtype"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
deploy jobtype::get
The deploy jobtype::get command enables you to download a custom job type from the Control-M/Server and store it locally in .ctmai format to be available for deployment with deploy jobtype. You can run this command to copy job types from one environment to another.
CLI Syntax
The following shows the CLI syntax for the deploy jobtype::get command:
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 in Application Integrator. You can obtain this ID in the following ways:
|
filePath |
Defines the full path to the job type .ctmai file to download. |
REST API Syntax
The following example shows the REST API syntax for the deploy jobtype::get command in cURL:
token=
jobType=DevJobType
filePath="C:\JobTypes\ProdJobType.ctmai"
endpoint=https://<controlm>:8443/automation-api
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/deploy/jobtype?jobTypeId=$jobType" -o $filePath
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
deploy ai:jobtype
The deploy ai:jobtype command enables you to publish a deployed Application Integrator job type to the 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/EM version 9.0.19.100 or higher.
CLI Syntax
The following shows the CLI syntax for the deploy ai:jobtype command:
ctm deploy ai:jobtype <server> <agent> <jobTypeId>
The following table describes the deploy ai:jobtype command parameters.
Parameter |
Description |
---|---|
server |
Defines the Control-M/Server name. |
agent |
Defines the Agent host name or alias. This is the Agent logical name. |
JobTypeId |
Determines the ID for the custom job type defined in Application Integrator. The corresponding setting in the Application Integrator is Plug-in ID. For more information, see Application Integrator Jobs. |
REST API Syntax
The following example shows the REST API syntax for the deploy ai:jobtype command in cURL:
token=
endpoint=https://<controlm>:8443/automation-api
server=
agent=
jobType=
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST
"$endpoint/deploy/ai/jobtype?server=$server&agent=$agent&jobTypeId=$jobType"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy ai:jobtypes::get command:
ctm deploy ai:jobtypes::get [-s <search query>]
where the optional -slimits 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 |
---|---|---|
|
Supported wildcard is *. |
"jobTypeName=startName*&jobTypeId=*partOfID*" |
If you include both fields in the query, separate them with &. |
REST API Syntax
The following example shows the REST API syntax for the deploy ai:jobtypes::get command in cURL:
token=
endpoint=https://<controlm>:8443/automation-api
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET
"$endpoint/deploy/ai/jobtypes?jobTypeId=<ID string>&jobTypeName=<name string>"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Response
The following example shows a response that lists three Application Integrator job types, two of which are ready to deploy and one more in draft status:
{
'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 response parameters.
Parameter |
Description |
---|---|
status |
Determines the status of the job type. Valid Values:
|
jobTypeId |
Determines the job type application ID (or Plug-in ID) defined in Application Integrator. For more information, see Application Integrator Jobs. |
description |
Defines a description of the job type, as defined optionally in Application Integrator. |
jobTypeName |
Defines the job type name defined in Application Integrator. |
Site Standards
The following API commands enables you to deploy Site Standards:
-
This command is used to deploy many different object types and is described separately.
To deploy Site Standards, you must have the following installed:
-
Control-M/EM 9.0.21 or higher
-
Control-M Workload Change Manager add-on
-
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.
This API command requires Control-M/EM version 9.0.21 or higher.
CLI Syntax
The following shows the CLI syntax for the deploy sitestandards::get command:
ctm deploy sitestandards::get -s <search query>
where the optional -s limits the list to Site Standards that match specified criteria.
The following table shows the field can be included in the search query.
Field |
Criteria |
Criteria Example |
---|---|---|
name |
|
name=* |
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandards::get command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -k -H "$AuthHeader" "$endpoint/deploy/sitestandards?name=*"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandard::delete command:
ctm deploy sitestandard::delete <siteStandardName>
where <siteStandardName> is the name of the Site Standard to delete.
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandard::delete command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -X DELETE -H "$AuthHeader" "$endpoint/deploy/sitestandard?siteStandardName=Dev_Standard"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandard::rename command:
ctm deploy sitestandard::rename <oldName> <newName>
The following table describes the deploy sitestandard::rename command parameters.
Parameter |
Description |
---|---|
oldName |
Defines the name of the Site Standard to rename. |
newName |
Defines the new Site Standard name. |
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandard::rename command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/deploy/sitestandard/rename?oldName=<Dev_Standard>&newName=<Prod_Standard>"
To select the AuthHeader value ("Authorization: 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.
This API command requires Control-M/EM version 9.0.21 or higher.
CLI Syntax
The following shows the CLI syntax for the deploy sitestandards:details::get command:
ctm deploy sitestandards:details::get -s <search query>
where the optional -s limits the list to Site Standards that match specified criteria.
The following table shows the field can be included in the search query.
Field |
Criteria |
Criteria Example |
---|---|---|
name |
|
name=* |
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandards:details::get command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -k -H "$AuthHeader" "$endpoint/deploy/sitestandards/details?name=*
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandard:fieldRestriction::get command:
ctm deploy sitestandard:fieldRestriction::get <standardName> <fieldName>
The following table describes the deploy sitestandard:fieldRestriction::get command parameters.
Parameter |
Description |
---|---|
standardName |
Defines the name of the Site Standard. |
fieldName |
Defines the name of the field, in lowercase characters. Currently, only the application field is supported. |
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandard:fieldRestriction::get command in cURL:
standardName=standard1
fieldName=application
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET
"$endpoint/deploy/sitestandard/$standardName/fieldRestriction/$fieldName"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandard:fieldRestriction::replaceValues command:
ctm deploy sitestandard:fieldRestriction::replaceValues <standardName> <fieldName> -f <valuesFile>
The following table describes the deploy sitestandard:fieldRestriction::replaceValues command parameters.
Parameter |
Description |
---|---|
standardName |
Defines the name of the Site Standard. |
fieldName |
Defines the name of the field, in lowercase characters. Currently, only the application field is supported. |
valuesFile |
Defines a .json file that contains new values for the field. This replaces all existing values. The following example shows the content of the values file: Copy
|
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandard:fieldRestriction::replaceValues command in cURL:
standardName=standard1
fieldName=application
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: 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"
To select the AuthHeader value ("Authorization: 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/EM version 9.0.21 or higher to run Site Standard Policies commands. To enable the 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
The following shows the CLI syntax for the deploy sitestandardpolicies::add command:
ctm deploy sitestandardpolicies::add <definitionsFile>.json
where <definitionsFile> defines the full path (directory and filename) of the JSON file that contains the definitions of the new Policies, as described in Site Standard Policies.
The response summarizes the number of Site Standard Policies that were added successfully based on the Definitions File and lists their names.
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandardpolicies::add command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
>curl -k -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicies"
To select the AuthHeader value ("Authorization: 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 utilized in subsequent deployments.
CLI Syntax
The following shows the CLI syntax for the deploy sitestandardpolicies::get command:
ctm deploy sitestandardpolicies::get [-s "name=<SiteStandardPolicy>"]
where the optional -s filters the response to specific Site Standard Policies. You can specify multiple values separated by commas. You can include * as wildcards.
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandardpolicies::get command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
>curl -k -X POST -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicies?name=a*,*b"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandardpolicy::rename command:
ctm deploy sitestandardpolicy::rename <siteStandardPolicyName> <siteStandardPolicyNewName>
The following table describes the deploy sitestandardpolicies::rename command parameters.
Parameter |
Description |
---|---|
siteStandardPolicyName |
Defines the Policy to rename. |
siteStandardPolicyNewName |
Defines the new name of the Policy. |
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandardpolicy::rename command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
>curl -X POST -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicy/rename?siteStandardPolicyName=<BIZ_Policy>&siteStandardPolicyNewName=<DEV_Policy>"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandardpolicy::delete command:
ctm deploy sitestandardpolicy::delete <siteStandardPolicyName>
where <siteStandardPolicyName> defines the Site Standard Policy to delete.
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandardpolicy::delete command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -X DELETE -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicy?siteStandardPolicyName=BIZ_Policy"
To select the AuthHeader value ("Authorization: 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
The following shows the CLI syntax for the deploy sitestandardpolicies:details::get command:
ctm deploy sitestandardpolicies:details::get [-s "name=<SiteStandardPolicy>"]
where the optional -s filters the response to specific site standard policies. You can specify multiple values separated by commas. You can include * as wildcards.
REST API Syntax
The following example shows the REST API syntax for the deploy sitestandardpolicies:details::get command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
>curl -k -H "$AuthHeader" "$endpoint/deploy/sitestandardpolicies/details?name=a*,*b"
To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Response
The following example is a response that contains details of Site Standard Polices:
{
"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 response 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 zip file with a set of definitions files that contain job definitions, connection profiles, calendars, site standards, and Application Integrator plug-ins.
For more information, see the Control-M Workbench documentation.
CLI Syntax
The following shows the CLI syntax for the deploy workbench::import command:
ctm deploy workbench::import <resources.zip>
where <resources.zip> is a zip file that contains definitions to import.
REST API Syntax
The following example shows the REST API syntax for the deploy workbench::import command in cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token" #for a session token
curl -X 'POST' -H 'accept: application/json' -H "$AuthHeader" -H 'Content-Type: multipart/form-data'
-F '[email protected];type=application/x-zip-compressed' '$endpoint/deploy/workbench/import'