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:

• deploy

• deploy poll

• deploy transform

• deploy jobs::get

• deploy job::delete

• deploy folder::delete

• deploy subfolder::delete

• deploy calendars::get

• deploy calendar::delete

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.

CLI Syntax

ctm deploy <definitionsFile> [deployDescriptorFile]

The following table describes the deploy command parameters.

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 -H "x-api-key: $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json"
-F "deployDescriptorFile=@examples/deployDescriptor.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 error messages if site standards are applied and validations are strictly enforced.

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.

CLI Syntax

ctm deploy poll <pollId>

REST API Syntax

curl -H "x-api-key: $token"  "$endpoint/deploy/poll?pollId"

Response

The following table describes the deploy poll command parameters.

The following table describes additional deploy poll command parameters.

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

ctm deploy transform <definitionsFile> <deployDescriptorFile>

The following table describes the deploy transform command parameters.

REST API Syntax

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

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

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

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

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

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

REST API Syntax

curl -k  -H "x-api-key: $token"  "$endpoint/deploy/jobs?server=*&folder=Auto*&useArrayFormat=true"

deploy job::delete

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

CLI Syntax

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

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

REST API Syntax

endpoint=https://<controlm>/automation-api
token=
server=IN01
jobpath=SMART_FOLDER_1:SMART_FOLDER_2:job_to_delete
curl -H "x-api-key: $token" -X DELETE "$endpoint/deploy/job/$jobpath?server=$server"

deploy folder::delete

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

CLI Syntax

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

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

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

endpoint=https://<controlm>/automation-api
token=
server=
folder=
curl -H "x-api-key: $token" -X DELETE "$endpoint/deploy/folder/$folder?server=$server"

deploy subfolder::delete

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

CLI Syntax

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

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

REST API Syntax

endpoint=https://<controlm>/automation-api
token=
server=
subfolderpath=
curl -H "x-api-key: $token" -X DELETE "$endpoint/deploy/subfolder/$subfolderpath?server=$server"

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

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

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

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

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

deploy calendar::delete

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

CLI Syntax

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

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

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

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

Connection Profiles

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

• deploy connectionprofiles:centralized::get

• deploy connectionprofiles:centralized:status::get

• deploy connectionprofile:centralized::deploymentstatus

• deploy connectionprofile:centralized::delete

• deploy connectionprofile::test

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 Helix Control-M 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

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

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

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:

REST API Syntax

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

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

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

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

REST API Syntax

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

deploy connectionprofile:centralized::delete

The deploy connectionprofile:centralized::delete command enables you to delete a centralized connection profile.

CLI Syntax

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

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

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

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

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

deploy connectionprofile::test

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

CLI Syntax

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

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

REST API Syntax

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"

Application Integrator Deployment

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

• deploy jobtype

• deploy jobtype::get

• deploy ai:jobtype

• deploy ai:jobtypes::get

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>]

The following table describes the deploy jobtype command parameters.

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

REST API Syntax

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

deploy jobtype::get

This command enables you to download a custom job type from theServer 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

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

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

REST API Syntax

token=
jobType=DevJobType
filePath="C:\JobTypes\ProdJobType.ctmai"
endpoint=https://<controlm>:8443/automation-api
curl -H "x-api-key: $token" -X GET "$endpoint/deploy/jobtype?jobTypeId=$jobType" -o $filePath

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.

CLI Syntax

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

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

REST API Syntax

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

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

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

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

Response

The following example response 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 command parameters.

Site Standards

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

• deploy sitestandards::get

• deploy sitestandard::delete

• deploy sitestandard::rename

• deploy sitestandards:details::get

• deploy sitestandard:fieldRestriction::get

• deploy sitestandard:fieldRestriction::replaceValues

deploy sitestandards::get

The deploy sitestandards::get 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

curl -H "x-api-key: $token" "$endpoint/deploy/sitestandards?name=*"

deploy sitestandard::delete

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

CLI Syntax

ctm deploy sitestandard::delete <siteStandardName>

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

REST API Syntax

curl -X DELETE -H "x-api-key: $token" "$endpoint/deploy/sitestandard?siteStandardName=Dev_Standard"

deploy sitestandard::rename

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

CLI Syntax

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

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

REST API Syntax

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

deploy sitestandards:details::get

The deploy sitestandards:details::get 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

curl -H "x-api-key: $token" "$endpoint/deploy/sitestandards/details?name=*

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

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

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

REST API Syntax

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

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

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

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

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

REST API Syntax

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"

Site Standard Policies

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

• deploy sitestandardpolicies::add

• deploy sitestandardpolicies::get

• deploy sitestandardpolicy::rename

• deploy sitestandardpolicy::delete

• deploy sitestandardpolicies:details::get

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

ctm deploy sitestandardpolicies::add <definitionsFile>.json

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

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 -k  -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies"

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

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 -k -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies?name=a*,*b"

deploy sitestandardpolicy::rename

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

CLI Syntax

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

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

REST API Syntax

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

deploy sitestandardpolicy::delete

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

CLI Syntax

ctm deploy sitestandardpolicy::delete <siteStandardPolicyName>

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

REST API Syntax

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

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

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 -k  -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies/details?name=a*,*b"

Response

The following example response 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 command parameters.