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, or calendars 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

CLI
ctm deploy <definitionsFile> [deployDescriptorFile]

Parameter

Description

<definitionsFile>

The definitions file name

Valid file formats are:

[deployDescriptorFile]

(Optional) The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy-Descriptor.

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"  "$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 jobs::get

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

CLI Syntax

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

Parameter

Description

format

The format in which to return the output, one of the following:

  • json — JSON format (the default)
  • xml:job — Control-M import/export .xml format, as used by the defjob utility
  • xml:folder — Control-M import/export .xml format, as used by the deffolder utility

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

Field

Criteria

Criteria example

  • server
  • folder
  • Supported wildcards are *, ?
  • To specify multiple values for a field, use commas.
  • To use multiple criteria, separate by using &

Note: The server field was previously named ctm (deprecated name).

server=*&folder=*

server=*&folder=Auto*

server=workbench&folder=AutomationAPISampleFlow

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"

deploy calendars::get

9.0.20.025 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

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

Parameter

Description

limit

Maximum number of calendars to include in the response. The default is 10000.

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:

Field

Criteria

Criteria examples

  • name
  • type
  • server
  • alias
  • Supported wildcards are *, ?
  • To use multiple criteria separate by using &
  • For type (of calendar) choose from the following options:
    • Regular
    • Periodic
    • RuleBasedCalendar

name=*

name=*&server=auto*

name=S1,S2&server=*

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

9.0.20.025 Deletes a defined calendar.

CLI Syntax

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

Parameter

Description

<calendarName>

Name of the defined calendar

[serverName]

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

deploy connectionprofiles:centralized::get

9.0.20.000 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

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

Field

Description

Criteria examples

type

Type of connection profile, one of the following options:

  • Database
  • FileTransfer
  • ApplicationIntegrator:<customType>
  • Informatica
  • AWS
  • Azure

For all types, use an asterisk *.

type=Hadoop&name=myCP

type=*&name=hd*

name

Name of connection profile(s).
Supported wildcards are * (asterisk) and ? (question mark). For multiple values, use commas between values.

The default is * (all).

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

9.0.20.000 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

CLI
ctm deploy connectionprofiles:centralized:status::get <limit> -s <search query>

Parameter

Description

limit

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:

Field

Description

Criteria examples

type

Type of connection profile, one of the following options:

  • Database
  • FileTransfer
  • ApplicationIntegrator:<customType>
  • Informatica
  • AWS
  • Azure

For all types, use an asterisk *.

type=Hadoop&name=myCP

type=*&name=hd*

name

Name of connection profile(s).
Supported wildcards are * (asterisk) and ? (question mark). For multiple values, use commas between values.

The default is * (all).

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

9.0.20.000 Returns deployment status information for a centralized connection profile.

CLI Syntax

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

Parameter

Description

<type>

Type of connection profile, one of the following:

  • Database
  • FileTransfer
  • ApplicationIntegrator:<customType>
  • Informatica
  • AWS
  • Azure

<name>

Name of the connection profile

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

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

CLI Syntax

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

Parameter

Description

<type>

Type of connection profile, one of the following:

  • Database
  • FileTransfer
  • ApplicationIntegrator:<customType>
  • Informatica
  • AWS
  • Azure

<name>

Name of the connection profile

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

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

Field

Criteria

Criteria example

  • server
  • agent
  • type
  • No wildcards supported
  • To use multiple criteria separate by using &
  • For type (of connection profile) choose from the following options:
    • Hadoop
    • Database
    • FileTransfer
    • ApplicationIntegrator:<customType>
    • Informatica
    • SAP
    • AWS
    • Azure

Note: The server field was previously named ctm (deprecated name).

server=workbench&agent=agent&type=Database

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

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

Parameter

Description

<server>

Name of Control-M/Server

<agent>

Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent

<type>

Type of connection profile, one of the following:

  • Hadoop
  • Database
  • FileTransfer
  • ApplicationIntegrator:<customType>
  • Informatica
  • SAP
  • AWS
  • Azure

<name>

Name of the connection profile

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

9.0.20.000 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

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

Parameter

Description

definitionsFile

Name of the JSON-format definitions file

ctm

Name of Control-M/Server

This parameter is required for a centralized connection profile. It is not required for a local connection profile (which is already associated with a specific Control-M/Server).

agent

Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent

This parameter is required for a centralized connection profile. It is not required for a local connection profile (which is already associated with a specific Control-M/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"

deploy folder::delete

The delete folder command enables you to delete a folder.

CLI Syntax

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

Parameter

Description

<server>

Name of the Control-M/Server

<folderName>

Name of the folder to delete

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

CLI
ctm deploy transform <definitionsFile> <deployDescriptorFile>

Where:

Parameter

Description

<definitionsFile>

The file or archive that contains code for jobs.

Valid formats are:

  • .json format
  • .zip or .tar.gz

<deployDescriptorFile>

The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy-Descriptor.

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

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

Parameter

Description

<server>

Name of the Control-M/Server

<agent>

Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent

<JobTypeId>

ID for the custom job type defined through Control-M Application Integrator

The corresponding setting in the Control-M Application Integrator is Plug-in ID. For more information, see Job:ApplicationIntegrator.

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

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

Fields

Criteria

Example

  • jobTypeName
  • jobTypeId

As wildcards, use asterisks (*).

"jobTypeName=startName*&jobTypeId=*partOfID*"

If you include both fields in the query, separate them with an ampersand (&).

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:

Parameter

Description

status

The status of the job type, either ready to deploy or draft

jobTypeId

The job type application ID (or Plug-in ID) defined in Control-M Application Integrator

For more information, see Job:ApplicationIntegrator.

description

A description of the job type, as defined (optionally) in Control-M Application Integrator

jobTypeName

The job type name defined in Control-M Application Integrator

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

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

Parameter

Description

definitionsFile

The name of a .ctmai binary file that contains the definitions of the job type and was exported from Application Integrator

agent

Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent

server

Name of the Control-M/Server, required only in an environment with multiple servers

payload file

Name of a .json file that contains parameter values, for use instead of specifying parameters in the API command

Here is an example of the content of such a 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 sitestandard:fieldRestriction::get

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

Note: API commands related to Site standards are supported in Control-M environments with Control-M/Enterprise Manager version 9.0.19.000 or later.

CLI Syntax

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

Where:

Parameter

Description

<standardName>

The name of the Site standard

<fieldName>

The name of the field, in lowercase characters

Currently, only the application field is supported.

REST API Syntax

See REST API reference.

standardName=standard1
fieldName=application
curl -X GET -H "Authorization: Bearer $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.

Note: API commands related to Site standards are supported in Control-M environments with Control-M/Enterprise Manager version 9.0.19.000 or later.

CLI Syntax

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

Where:

Parameter

Description

<standardName>

The name of the Site standard

<fieldName>

The name of the field, in lowercase characters

Currently, only the application field is supported.

<valuesFile>

A .json file that contains new values for the field, to replace all existing values

Here is an example of the content of such a file:

{
 "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 "Authorization: Bearer $token"
-d "@examples/SiteStandardApplicationFieldValues.json"
"$endpoint/deploy/sitestandard/$standardName/fieldRestriction/$fieldName"

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*