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.

deploy

Deploy the provided definitions file to Control-M. Build will take place as part of the deploy to ensure code validity. deploy can receive definitions files for folders, jobs, calendars, or site standards in .json format, or a package of multiple definition files in .zip or .tar.gz format.

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 error messages if site standards are applied and validations are strictly enforced.

CLI Syntax

ctm deploy <definitionsFile> [deployDescriptorFile]

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 "x-api-key: $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json" 
-F "deployDescriptorFile=@examples/deployDescriptor.json"  "$endpoint/deploy" 

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.

NOTE: The asynchronous deployment times out after 20 seconds.

CLI Syntax

ctm deploy poll <pollId>

REST API Syntax

See REST API reference.

Example using curl:

curl -H "x-api-key: $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 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 "x-api-key: $token"  "$endpoint/deploy/jobs?server=*&folder=Auto*&useArrayFormat=true"

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>/automation-api
token=
curl -X GET -H "x-api-key: $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>/automation-api
token=
calendar=
server=
curl -X DELETE -H "x-api-key: $token"  "$endpoint/deploy/calendar/$calendar?server=$server"

deploy connectionprofiles:centralized::get

Returns the full definitions of centralized connection profiles, based on specified search criteria.

Centralized connection profiles are stored centrally in Helix Control-M and can be used by all your 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>/automation-api
token=
name=
type=
curl -X GET -H "x-api-key: $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 Helix Control-M and can be used by all your 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>/automation-api
token=
name=
type=
curl -X GET -H "x-api-key: $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>/automation-api
token=
type=
name=
curl -X GET -H "x-api-key: $token" "$endpoint/deploy/connectionprofile/centralized/$type/$name/deploymentstatus"

deploy connectionprofile:centralized::delete

Deletes a centralized connection profile.

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>/automation-api
token=
type=
name=
curl -X DELETE -H "x-api-key: $token" "$endpoint/deploy/connectionprofile/centralized/$type/$name"

deploy connectionprofile::test

Tests the definitions of a connection profile (without deploying it) on a specific server and 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>/automation-api
token=
ctm=
agent=
curl -H "x-api-key: $token" \
  -X POST "$endpoint/deploy/connectionprofile/test?ctm=$ctm&agent=$agent" \
  -F "definitionsFile=@/C:/myConnectionProfile.json"

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>/automation-api
token=
server=IN01
jobpath=SMART_FOLDER_1:SMART_FOLDER_2:job_to_delete
curl -X DELETE -H "x-api-key: $token" "$endpoint/deploy/job/$server/$jobpath"

deploy folder::delete

The delete folder command enables you to delete a folder.

CLI Syntax

ctm deploy folder::delete <server> <folderName>

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>/automation-api
token=
server=
folder=
curl -X DELETE -H "x-api-key: $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>/automation-api
token=
server=
subfolderpath=
curl -X DELETE -H "x-api-key: $token" "$endpoint/deploy/subfolder/$server/$subfolderpath"

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 "x-api-key: $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json" 
-F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/deploy/transform"

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.

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>/automation-api
curl -X POST -H "x-api-key: $token" -F "definitionsFile=aif.ctmai"
-F "payloadFile=payload.json"  "$endpoint/deploy/jobtype"

deploy ai:jobtype

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

CLI Syntax

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

REST API Syntax

See REST API reference.

token=
endpoint=https://<controlm>/automation-api
server=
agent=
jobType=
curl -X POST -H "x-api-key: $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>/automation-api
curl -X GET -H "x-api-key: $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:

deploy sitestandard:fieldRestriction::get

This command obtains the list of allowed values defined for a restricted-text field in a Site standard.

CLI Syntax

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

Where:

REST API Syntax

See REST API reference.

standardName=standard1
fieldName=application
curl -X GET -H "x-api-key: $token" 
"$endpoint/deploy/sitestandard/$standardName/fieldRestriction/$fieldName"

deploy sitestandard:fieldRestriction::replaceValues

This command replaces the allowed values defined for a restricted-text field in a Site standard with a new set of allowed values.

CLI Syntax

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

Where:

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

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.

standardName=standard1
fieldName=application
curl -X POST -H "Content-Type: application/json" -H "x-api-key: $token"
-d "@examples/SiteStandardApplicationFieldValues.json"
"$endpoint/deploy/sitestandard/$standardName/fieldRestriction/$fieldName"

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": "PRODUCTION_Policy",
        "description": "Policy for production teams",
        "createdTime": "2021-12-20T07:18:36Z",
        "username": "emuser",
        "siteStandard": "PROD_Standard",
        "status": "Not Active"
    }
    ]
}