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.  

Note: To deploy Site Standards, you must have Control-M/Enterprise Manager version 9.0.21 and you must have the Control-M Workload Change Manager add-on installed.

deploy

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

ctm deploy <definitionsFile> [deployDescriptorFile] [StandardsFile]

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

See REST API reference.

Example using  curl:

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

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.

Note: 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

Note: This feature requires Control-M/Enterprise Manager version 9.0.21.

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.

NOTE: 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

ctm deploy poll <pollId>

REST API Syntax

See REST API reference.

Example using curl:

curl -H "Authorization: Bearer $token"  "$endpoint/deploy/poll?pollId"

Example

In the following example, a definitions file that contains 5000 jobs is deployed—5 folders of 1000 jobs each. The response shows only 250 jobs have been 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 deploy. Notice that 2 Smart folders, or 2000 jobs, have 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 running the ctm deploy poll command again a few minutes later, notice that all the jobs have 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"
  ]
}

deploy transform

The 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

ctm deploy transform <definitionsFile> <deployDescriptorFile>

Where:

REST API Syntax

See REST API reference.

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

deploy jobs::get

Returns the definition of jobs and folders in the requested format that match the search criteria.

CLI Syntax

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

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

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

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

REST API Syntax

See REST API reference.

>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/jobs?server=*&folder=Auto*"
 
>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/jobs?server=*&folder=Auto*&format=XML"

>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/jobs?server=*&folder=Auto*&useArrayFormat=true"

deploy job::delete

Enables you to delete a job from an existing folder.

CLI Syntax

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

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
server=
jobpath=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/job/$server/$jobpath"

deploy folder::delete

Enables you to delete a folder.

CLI Syntax

ctm deploy folder::delete <server> <folderName> [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

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
server=
folder=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/folder/$server/$folder"

deploy subfolder::delete

Enables you to delete a subfolder and all jobs under the subfolder.

CLI Syntax

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

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
server=
subfolderpath=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/subfolder/$server/$subfolderpath"

deploy calendars::get

Returns 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

ctm deploy calendars::get [limit] -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:

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
curl -X GET -H "Authorization: Bearer $token"  "$endpoint/deploy/calendars/?type=Periodic&name=S*"

deploy calendar::delete

Deletes a defined calendar.

CLI Syntax

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

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

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
calendar=
server=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/calendar/$calendar?server=$server"

Connection Profiles

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

deploy connectionprofiles:centralized::get

Returns 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

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:

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
name=
type=
curl -X GET -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofiles/centralized/?type=$type&name=$name"

deploy connectionprofiles:centralized:status::get

Returns 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 Control-M/Agents. Definitions for such connection profiles contain the Centralized parameter set to true.

CLI Syntax

ctm deploy connectionprofiles:centralized:status::get <limit> -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:

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
name=
type=
curl -X GET -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofiles/centralized/status/?type=$type&name=$name&limit=50"

deploy connectionprofile:centralized::deploymentstatus

Returns deployment status information for a centralized connection profile.

CLI Syntax

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

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
curl -X GET -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofile/centralized/$type/$name/deploymentstatus"

deploy connectionprofile:centralized::delete

Deletes a centralized connection profile from the Control-M database.

CLI Syntax

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

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

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
type=
name=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofile/centralized/$type/$name"

deploy connectionprofiles:local::get

Returns the details of local connection profiles associated with your Control-M/Agents, based on specified search criteria.

CLI Syntax

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:

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
server=
agent=
type=
curl -X GET -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofiles/local/?server=$server&agent=$agent&type=$type"

deploy connectionprofile:local::delete

Deletes a local connection profile that was associated with a Control-M/Agent.

CLI Syntax

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

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

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
server=
agent=
type=
name=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofile/local/$server/$agent/$type/$name"

deploy connectionprofile::test

Tests the definitions of a connection profile (without deploying it) on a specific Control-M/Server and Control-M/Agent. You provide the definitions of the connection profile through a JSON-format definitions file.

CLI Syntax

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

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
ctm=
agent=
curl -H "Authorization: Bearer $token" \
  -X POST "$endpoint/deploy/connectionprofile/test?ctm=$ctm&agent=$agent" \
  -F "definitionsFile=@/C:/myConnectionProfile.json"

Application Integrator

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 to the Control-M/Agent based on job definitions that were exported from Application Integrator in .ctmai format.

The response notifies you whether the deployment succeeded or failed.

Note:

• Deployment of a job type that was provided to you in a .ctmai definitions file is supported in Control-M environments with Control-M/Enterprise Manager version 9.0.20.100 or later.
• This command currently supports job types provided through Control-M Integrations. BMC-provided job types in Control-M Integrations include, for example, the AWS Glue job type. Such job types are not editable and you cannot import them into Application Integrator. Instead, you deploy them directly into Control-M.

CLI Syntax

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

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

REST API Syntax

See REST API reference.

token=
endpoint=https://<controlm>:8443/automation-api
curl -X POST -H "Authorization: Bearer $token" -F "definitionsFile=aif.ctmai"
-F "payloadFile=payload.json"  "$endpoint/deploy/jobtype"

deploy ai:jobtype

This command enables you to deploy an Application Integrator job type to the Control-M/Agent to allow it to run.

The response notifies you whether the deployment succeeded or failed.

Note: Deployment of an Application Integrator job type is supported in Control-M environments with Control-M/Enterprise Manager version 9.0.19.100 or later.

CLI Syntax

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

REST API Syntax

See REST API reference.

token=
endpoint=https://<controlm>:8443/automation-api
server=
agent=
jobType=
curl -X POST -H "Authorization: Bearer $token" 
"$endpoint/deploy/ai/jobtype/?server=$server&agent=$agent&jobTypeId=$jobType"

deploy ai:jobtypes::get

This command enables you to get details of deployed Application Integrator job types that match a specified search query.

CLI Syntax

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:

REST API Syntax

See REST API reference.

token=
endpoint=https://<controlm>:8443/automation-api
curl -X GET -H "Authorization: Bearer $token" 
"$endpoint/deploy/ai/jobtypes/?jobTypeId=<ID string>&jobTypeName=<name string>"

Response

The following example response lists 3 Application Integrator job types, 2 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 parameters are provided for each job type:

Site Standards

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

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

deploy sitestandards::get

This command enables you to get the definitions of one or more deployed Site Standards.

CLI Syntax

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:

REST API Syntax

See REST API reference.

Example using curl:

>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/sitestandards/?name=*"

deploy sitestandard::delete

This command enables you to delete an existing Site Standard.

CLI Syntax

ctm deploy sitestandard::delete <siteStandardName>

REST API Syntax

See REST API reference.

Example using curl:

curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/sitestandard?siteStandardName=Dev_Standard"

deploy sitestandard::rename

This command enables you to rename an existing Site Standard.

CLI Syntax

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

REST API Syntax

See REST API reference.

Example using curl:

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

deploy sitestandards:details::get

This command enables you to get specific details for one or more Site Standards.

CLI Syntax

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:

REST API Syntax

See REST API reference.

Example using curl:

>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/sitestandards/details?name=*

Site Standard Policies

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

Note: You must have Control-M/Enterprise Manager version 9.0.21 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

Enables you to deploy new Site Standard Policies based on definitions in a Definitions File (as described in Site Standard Policies).

CLI Syntax

ctm deploy sitestandardpolicies::add <definitionsFile>.json

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

REST API Syntax

See REST API reference.

Example using curl:

>curl -k -X POST -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies" -F "definitionsFile=@examples/SiteStandardPolicies.json"

deploy sitestandardpolicies::get

Retrieves 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

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 use asterisks (*) as wildcards.

REST API Syntax

See REST API reference.

Example using curl:

>curl -k -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies?name=a*,*b"

deploy sitestandardpolicy::rename

Enables you to rename an existing Site Standard Policy.

CLI Syntax

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

REST API Syntax

See REST API reference.

Example using curl:

>curl -X POST -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicy/rename?siteStandardPolicyName=<BIZ_Policy>&siteStandardPolicyNewName=<DEV_Policy>"

deploy sitestandardpolicy::delete

Enables you to delete a Site Standard Policy.

CLI Syntax

ctm deploy sitestandardpolicy::delete <siteStandardPolicyName>

REST API Syntax

See REST API reference.

Example using curl:

curl -X DELETE -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicy?siteStandardPolicyName=BIZ_Policy"

deploy sitestandardpolicies:details::get

This command returns the details of all existing Site Standard Polices in your Control-M environment.

CLI Syntax

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 use asterisks (*) as wildcards.

REST API Syntax

See REST API reference.

Example using curl:

>curl -k  -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies/details?name=a*,*b"

Response Example

{
	"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"
    }
    ]
}

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

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.

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

CLI Syntax

ctm deploy workbench::import <resources.zip>

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

REST API Syntax

See REST API reference.

Example using curl:

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'