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:

• deploy

  This command is used for most object types, including connection profiles and site standards.

• deploy poll

• deploy transform

• deploy jobs::get

• deploy job::delete

• deploy folders::get

• deploy folder::delete

• deploy subfolder::delete

• deploy calendars::get

• deploy calendar::delete

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.

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

The following table describes the deploy command parameters.

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

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

deploy poll

If the deployment takes longer than expected to update the Control-M database server, the deployment command 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 at any later time, run the deploy poll command. All users with the required privileges can run the deploy poll command.

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

where <pollId> is a unique deployment identifier returned by the deployment command in an asynchronous deployment.

Response

The following examples show the deploy poll response parameters.

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

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

{
   "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.

The following table describes additional deploy poll response parameters.

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.

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

The following table describes the deploy transform command parameters.

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.

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

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

The following table lists the fields available for a search query.

deploy job::delete

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

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"

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

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.

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

where -s runs a search using the query string format.

The following table lists the fields available for a search query.

deploy folder::delete

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

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

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

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

deploy subfolder::delete

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

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

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

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 criteria, see Calendars.

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

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

-s runs a search in the query string format. The following table lists the fields available for a search query.

deploy calendar::delete

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

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

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

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

Connection Profiles

The following API commands enable you to deploy connection profiles:

• deploy

  This command is used to deploy many different object types and is described separately.

• deploy connectionprofiles:centralized::get

• deploy connectionprofiles:centralized:status::get

• deploy connectionprofile:centralized::deploymentstatus

• deploy connectionprofile:centralized::delete

• deploy connectionprofile:centralized::test

• 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 Control-M SaaS and available for all Agents. Definitions for the Connection Profiles contain the Centralized parameter set to true.

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

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:

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 Control-M SaaS and are available to all your Agents. Definitions for the Connection Profiles contain the Centralized parameter set to true.

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"

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:

deploy connectionprofile:centralized::deploymentstatus

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

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

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

deploy connectionprofile:centralized::delete

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

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:centralized::delete command parameters.

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

deploy connectionprofile:centralized::test

The deploy connectionprofile:centralized::test command enables you to test an existing centralized connection profile on a specific Agent.

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

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

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.

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"

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

Application Integrator Deployment

The following API commands enable you to deploy Application Integrator job types:

• deploy jobtype

• deploy jobtype::get

• deploy ai:jobtype

• deploy ai:jobtypes::get

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.

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"

The following table describes the deploy jobtype command parameters.

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

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.

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

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

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.

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"

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

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.

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

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:

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.

Site Standards

The following API commands enables you to deploy Site Standards:

• deploy

  This command is used to deploy many different object types and is described separately.

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

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

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.

deploy sitestandard::delete

The deploy sitestandard::delete command enables you to delete an existing site standard.

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.

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

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

deploy sitestandards:details::get

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

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

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.

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.

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

The following table describes the deploy sitestandard:fieldRestriction::get command parameters.

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.

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"

The following table describes the deploy sitestandard:fieldRestriction::replaceValues command parameters.

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

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.

>curl -k  -H "x-api-key: $token" "$endpoint/deploy/sitestandardpolicies"

where the <definitionsFile> parameter defines the pathname of a JSON payload 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.

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.

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

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.

deploy sitestandardpolicy::rename

The deploy sitestandardpolicy::rename command enables you to rename an existing site standard policy.

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

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

deploy sitestandardpolicy::delete

The deploy sitestandardpolicy::delete command enables you to delete a site standard policy.

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

where <siteStandardPolicyName> defines the site standard policy to delete.

deploy sitestandardpolicies:details::get

The deploy sitestandardpolicies:details::get command enables you to get the details of all existing site standard policies in your Control-M environment.

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

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.

Response

The following example is a response that contains details of site standard policies:

{
   "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.