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

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.

CLI Syntax

The following shows the CLI syntax for the deploy command:

ctm deploy <definitionsFile> [deployDescriptorFile]

The following table describes the deploy command parameters.

Parameter

Description

definitionsFile

Determines the name of the .json-format definitions file with Control-M code for various elements.

deployDescriptorFile

(Optional) Defines the file with the rules to apply to the original definitions file. The rules enable the transformation of Control-M code properties in .json format. For detailed information, see Deploy Descriptor.

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.

REST API Syntax

The following example shows the REST API syntax for the deploy command in cURL:

Copy
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 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 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, run the deploy poll command. All users with the required privileges can run the deploy poll command.

Asynchronous deployment times out after 20 seconds.

CLI Syntax

The following shows the CLI syntax for the deploy poll command:

ctm deploy poll <pollId>

REST API Syntax

The following example shows the REST API syntax for the deploy poll command in cURL:

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

Response

The following examples show the deploy poll response parameters.

The following example shows a response for a definitions file that contains 5,000 jobs and is deployed with 5 folders of 1,000 jobs each. The response shows that only 250 jobs were deployed, so the deployment status is partial and a poll ID is provided:

Copy
{
   "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 deployment. Notice that 2 SMART folders, or 2,000 jobs, were deployed:

Copy
{
   "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 you run the deploy poll command again a few minutes later, notice that all the jobs deployed successfully:

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

Parameter

Description

deploymentFile

Defines the definitions filename.

pollId

Determines a unique ID to monitor the deployment status.

deploymentStatus

Determines the deployment status.

Valid Values:

  • ENDED_OK: All jobs in the definitions file deployed successfully.

  • ENDED_NOT_OK: None of the jobs in the definitions file deployed successfully.

  • PARTIAL_RESULT: Some of the jobs in the definitions file deployed successfully.

  • TIMED_OUT: The deployment took longer than 10 minutes and is canceled.

  • UNKNOWN: An unknown error occurred in the deployment.

successfulFoldersCount

Determines the number of simple folders that are deployed.

successfulSmartFoldersCount

Determines the number of SMART folders that are deployed.

successfulSubFoldersCount

Determines the number of sub-folders that are deployed.

successfulJobsCount

Determines the number of jobs that are deployed.

successfulConnectionProfilesCount

Determines the number of connection profiles that are deployed.

successfulDriversCount

Determines the number of JDBC drivers that are deployed.

isDeployDescriptorValid

Confirms if the deploy descriptor in the definitions file is deployed. For detailed information, see Deploy Descriptor.

Valid Values:

  • true

  • false

The following table describes additional deploy poll response parameters.

Parameter

Description

deploymentState

Describes what was already deployed.

Valid Values:

  • DEPLOYED_CALENDARS: Confirms the deployment of calendars from the definitions file.

  • DEPLOYED_CONNECTION_PROFILES: Confirms the deployment of connection profiles listed in the definitions file.

  • DEPLOYED_STANDARDS: Confirms the deployment of site standards from the definitions file.

  • DEPLOY FOLDERS x/x: Confirms that the number of folders that were deployed out of the total number of folders included in the definitions file. 

deployedFolders

Determines an array of the folder names that are deployed.

deployedCalendars

Determines an array of the calendar names that are deployed.

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.

CLI Syntax

The following shows the CLI syntax for the deploy transform command:

ctm deploy transform <definitionsFile> <deployDescriptorFile>

The following table describes the deploy transform command parameters.

Parameter

Description

definitionsFile

Defines the .json file that contains code for jobs.

deployDescriptorFile

Defines the file with the rules to apply to the original definitions file. The rules enable the transformation of Control-M JSON code properties. For detailed information, see Deploy Descriptor.

REST API Syntax

The following example shows the REST API syntax for the deploy transform command in cURL:

Copy
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 job and folder definitions that match a search criteria in a requested format.

CLI Syntax

The following shows the CLI syntax for the deploy jobs::get command:

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

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

Parameter

Description

format

Determines the output format: json

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

Field

Criteria

Criteria Example

  • server

  • folder

  • job

  • Supported wildcards for server, folder, and z/OS library are * and ?.

  • Multiple servers, folders, or z/OS libraries are separated with commas.

  • The job field specifies a single job and does not support wildcards.

  • A subfolder must include a colon between each parent folder and subfolder in the path. Do not use wildcards in the subfolder.

  • If you include : in the folder field or if you utilize the job field to define a job, specify a single value without wildcards in the server field.

  • Multiple fields are separated with &.

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

  • If you include a colon in the folder field to specify a subfolder, the query also returns details of any child subfolders within the specified subfolder.

  • If you include a colon in the folder field or if you utilize the job field, the output contains the PathElement property to define the subfolder or job.

server=*&folder=*

server=*&folder=Auto*

server=IN01&folder=AutomationAPISampleFlow

server=IN01&folder=folder1:subfolder2

server=IN01&folder=folder1&job=myJob

useArrayFormat

Enforces the display of objects in array structures, including jobs and resources.

Job arrays enable you to define more than one job with the same job name. Resource arrays enable you to associate a job with a resource pool and lock resource that both have the same name. For examples of these array structures, see the examples in Folders and Flows and in Resources.

The useArrayFormat field enforces array structures even when all returned jobs have distinct names, and it enforces the resource array structure even when all resources in a job have distinct names.

Valid Values:

  • true

  • false

Default: false (array structures are used only if multiple jobs with the same name are detected, and a resource array format is utilized only if a job has a resource pool and a lock resource with the same name).

server=*&folder=*&useArrayFormat=true

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

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

REST API Syntax

The following example shows the REST API syntax for the deploy jobs::get command in cURL:

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

If you retrieve job definitions from a higher version of Control-M Automation API, the job deployment might fail in an environment with an earlier version of Control-M Automation API, due to new and unrecognized job properties. The following error appears:

<Name of new property> is an unknown keyword...

In this situation, add the min.aapi.ste.version property to the automation-api.properties file and set it to the target (lower) version of Control-M Automation API. For example, to deploy a job that was defined in Control-M Automation API 9.0.21.215 to an environment with Control-M Automation API 9.0.21.130, add the following line:

min.aapi.ste.version=9.0.21.130

deploy job::delete

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

CLI Syntax

The following shows the CLI syntax for the deploy job::delete command:

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

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

Parameter

Description

jobPath

Defines the full path of the job to delete.

Add colons as separators between a folder, subfolder, and job.

Example: SMART_FOLDER_1:SMART_FOLDER_2:job_to_delete

server

Defines the name of the Server.

library

Defines the name of the z/OS library.

REST API Syntax

The following example shows the REST API syntax for the deploy job::delete command in cURL:

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

Scheduling definitions, event details, and folder variables are not included in the command response. For these details use deploy jobs::get.

CLI Syntax

The following shows the CLI syntax for the deploy folders::get command:

ctm deploy folders::get -s <search query>

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

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

Field

Criteria

Criteria Example

  • server

  • folder

  • folderType

  • application

  • subApplication

  • siteStandard

  • The search query must contain at least the mandatory server and folder fields.

  • Supported wildcards for server,folder, and z/OS library are * and ?.

  • Multiple servers,folders, or z/OS libraries are separated with commas.

  • Multiple fields are separated with &.

  • The folderType field has the following valid values:

    • folder

    • simpleFolder

server=*&folder=*

server=*&folder=Auto*

server=IN01&folder=AutomationAPISampleFlow

The following command shows how to get definitions of all folders that start with Automation:

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

REST API Syntax

The following example shows the REST API syntax for the deploy folders::get command in cURL:

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

deploy folder::delete

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

CLI Syntax

The following shows the CLI syntax for the deploy folder::delete command:

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

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

Parameter

Description

server

Defines the name of the Server.

folderName

Defines the name of the folder to delete.

library

Defines the name of the z/OS library.

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.

REST API Syntax

The following example shows the REST API syntax for the deploy folder::delete command in cURL:

Copy
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 in the sub-folder.

CLI Syntax

The following shows the CLI syntax for the deploy subfolder::delete command:

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

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

Parameter

Description

subFolderPath

Defines the full path of the sub-folder to delete.

You must include a colon to separate the parent folder from the sub-folders.

server

Defines the name of the Server.

library

Defines the name of the z/OS library.

REST API Syntax

The following example shows the REST API syntax for the deploy subfolder::delete command in cURL:

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

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

CLI Syntax

The following shows the CLI syntax for the deploy calendars::get command:

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

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

Parameter

Description

limit

Determines the maximum number of calendars to include in the response.

Default: 10,000

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

Field

Criteria

Criteria Examples

  • name

  • type

  • server

  • alias

  • Supported wildcards are * and ?.

  • Multiple criteria are separated by &.

  • The following calendar types are supported:

    • Regular

    • Periodic

    • RuleBasedCalendar

name=*

name=*&server=auto*

name=S1,S2&server=*

REST API Syntax

The following example shows the REST API syntax for the deploy calendars::get command in cURL:

Copy
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

The following shows the CLI syntax for the deploy calendar::delete command:

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

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

Parameter

Description

calendarName

Defines the name of the predefined calendar

serverName

Defines the name of the 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 the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the deploy calendar::delete command in cURL:

Copy
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 enable you to deploy connection profiles:

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

CLI Syntax

The following shows the CLI syntax for the deploy connectionprofiles:centralized::get command:

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

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:

Field

Description

Criteria Examples

type

Determines the connection profile type.

Valid Values:

  • Hadoop

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

  • SAP

For all types, the value is an *.

type=Hadoop&name=myCP

type=*&name=hd*

name

Defines the connection profile name.

Supported wildcards are * and ?.

Multiple values are separated with commas.

Default: * (all)

REST API Syntax

The following example shows the REST API syntax for the deploy connectionprofiles:centralized::get command in cURL:

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

CLI Syntax

The following shows the CLI syntax for the deploy connectionprofiles:centralized:status::get command:

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

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:

Field

Description

Criteria Examples

type

Determines the connection profile type.

Valid Values:

  • Hadoop

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

  • SAP

For all types, the value is an *.

type=Hadoop&name=myCP

type=*&name=hd*

name

Defines the connection profile name.

Supported wildcards are * and ?.

Multiple values are separated with commas.

Default: * (all)

REST API Syntax

The following example shows the REST API syntax for the deploy connectionprofiles:centralized:status::get command in cURL:

Copy
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 deployment status information for a centralized connection profile.

CLI Syntax

The following shows the CLI syntax for the deploy connectionprofile:centralized::deploymentstatus command:

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

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

Parameter

Description

type

Determines the connection profile type.

Valid Values:

  • Hadoop

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

  • SAP

name

Defines the connection profile name.

REST API Syntax

The following example shows the REST API syntax for the deploy connectionprofile:centralized::deploymentstatus command in cURL:

Copy
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

The following shows the CLI syntax for the deploy connectionprofile:centralized::delete command:

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

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

Parameter

Description

type

Determines the connection profile type.

Valid Values:

  • Hadoop

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

  • SAP

name

Defines the connection profile name.

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.

REST API Syntax

The following example shows the REST API syntax for the deploy connectionprofile:centralized::delete command in cURL:

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

deploy connectionprofile:centralized::test

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

CLI Syntax

The following shows the CLI syntax for the deploy connectionprofile:centralized::test command:

ctm deploy connectionprofile:centralized::test <type> <name> <server> <agent>

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

Parameter

Description

type

Determines the connection profile type.

Valid Values:

  • Hadoop

  • Database

  • FileTransfer

  • ApplicationIntegrator:<customType>

  • Informatica

  • AWS

  • Azure

  • SAP

name

Defines the connection profile name.

server

Defines the Server name.

agent

Defines the Agent hostname or alias. This is the Agent logical name.

REST API Syntax

The following example shows the REST API syntax for the deploy connectionprofile:centralized::test command in cURL:

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

deploy connectionprofile::test

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

CLI Syntax

The following shows the CLI syntax for the deploy connectionprofile::test command:

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

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

Parameter

Description

definitionsFile

Defines the name of the definitions file in JSON-format.

ctm

Defines the Server name.

agent

Defines the Agent hostname or alias. This is the Agent logical name.

REST API Syntax

The following example shows the REST API syntax for the deploy connectionprofile::test command in cURL:

Copy
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 enable you to deploy Application Integrator job types:

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.

This API command is supported in Control-M environments with Control-M/EM version 9.0.20.100 or higher.

CLI Syntax

The following shows the CLI syntax for the deploy jobtype command:

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

The following table describes the deploy jobtype command parameters.

Parameter

Description

definitionsFile

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

agent

(Optional) Defines the Agent host name or alias. This is the Agent logical name.

server

(Optional) Defines the Server name.

payload file

(Optional) Defines the name of a .json file that contains parameter values. The payload file replaces the need to specify parameters in the API command.

The following example shows the contents of a payload file:

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

REST API Syntax

The following example shows the REST API syntax for the deploy jobtype command in cURL:

Copy
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

The deploy jobtype::get command enables you to download a custom job type from the 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.

CLI Syntax

The following shows the CLI syntax for the deploy jobtype::get command:

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

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

Parameter

Description

JobTypeId

Defines the ID for the custom job type defined in Application Integrator.

You can obtain this ID in the following ways:

  • The name of a .ctmai file that you deployed previously.

  • The Plug-in ID setting of a plug-in in Application Integrator.

filePath

Defines the full path to the job type .ctmai file to download.

REST API Syntax

The following example shows the REST API syntax for the deploy jobtype::get command in cURL:

Copy
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

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.

CLI Syntax

The following shows the CLI syntax for the deploy ai:jobtype command:

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

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

Parameter

Description

server

Defines the Server name.

agent

Defines the Agent host name or alias. This is the Agent logical name.

JobTypeId

Determines the ID for the custom job type defined in Application Integrator.

The corresponding setting in the Application Integrator is Plug-in ID. For more information, see Application Integrator Jobs.

REST API Syntax

The following example shows the REST API syntax for the deploy ai:jobtype command in cURL:

Copy
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

The following shows the CLI syntax for the deploy ai:jobtypes::get command:

ctm deploy ai:jobtypes::get [-s <search query>]

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:

Fields

Criteria

Example

  • jobTypeName

  • jobTypeId

Supported wildcard is *.

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

If you include both fields in the query, separate them with &.

REST API Syntax

The following example shows the REST API syntax for the deploy ai:jobtypes::get command in cURL:

Copy
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 shows a response that lists three Application Integrator job types, two of which are ready to deploy and one more in draft status:

Copy
{
   '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.

Parameter

Description

status

Determines the status of the job type.

Valid Values:

  • ready to deploy

  • draft

jobTypeId

Determines the job type application ID (or Plug-in ID) defined in Application Integrator.

For more information, see Application Integrator Jobs.

description

Defines a description of the job type, as defined optionally in Application Integrator.

jobTypeName

Defines the job type name defined in Application Integrator.

Site Standards

The following API commands enables you to deploy Site Standards:

To enable Site Standards configuration, you must first install the Control-M Workload Change Manager add-on.

deploy sitestandards::get

The deploy sitestandards::get command enables you to get the definitions of one or more deployed Site Standards.

CLI Syntax

The following shows the CLI syntax for the deploy sitestandards::get command:

ctm deploy sitestandards::get -s <search query>

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.

Field

Criteria

Criteria Example

name

  • Supported wildcard is *.

  • Escape character is \.

name=*

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandards::get command in cURL:

Copy
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

The following shows the CLI syntax for the deploy sitestandard::delete command:

ctm deploy sitestandard::delete <siteStandardName>

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

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandard::delete command in cURL:

Copy
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

The following shows the CLI syntax for the deploy sitestandard::rename command:

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

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

Parameter

Description

oldName

Defines the name of the Site Standard to rename.

newName

Defines the new Site Standard name.

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandard::rename command in cURL:

Copy
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

The following shows the CLI syntax for the deploy sitestandards:details::get command:

ctm deploy sitestandards:details::get -s <search query>

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.

Field

Criteria

Criteria Example

name

  • Supported wildcards are * and ?.

  • Escape character is \.

name=*

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandards:details::get command in cURL:

Copy
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

The following shows the CLI syntax for the deploy sitestandard:fieldRestriction::get command:

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

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

Parameter

Description

standardName

Defines the name of the Site Standard.

fieldName

Defines the name of the field, in lowercase characters.

Currently, only the application field is supported.

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandard:fieldRestriction::get command in cURL:

Copy
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

The following shows the CLI syntax for the deploy sitestandard:fieldRestriction::replaceValues command:

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

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

Parameter

Description

standardName

Defines the name of the Site Standard.

fieldName

Defines the name of the field, in lowercase characters.

Currently, only the application field is supported.

valuesFile

Defines a .json file that contains new values for the field. This replaces all existing values.

The following example shows the content of the values file:

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

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandard:fieldRestriction::replaceValues command in cURL:

Copy
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

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

The following shows the CLI syntax for the deploy sitestandardpolicies::add command:

ctm deploy sitestandardpolicies::add <definitionsFile>.json

where <definitionsFile> defines the full path (directory and filename) of the JSON 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.

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandardpolicies::add command in cURL:

Copy
>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 utilized in subsequent deployments.

CLI Syntax

The following shows the CLI syntax for the deploy sitestandardpolicies::get command:

ctm deploy sitestandardpolicies::get [-s "name=<SiteStandardPolicy>"]

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.

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandardpolicies::get command in cURL:

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

The following shows the CLI syntax for the deploy sitestandardpolicy::rename command:

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

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

Parameter

Description

siteStandardPolicyName

Defines the Policy to rename.

siteStandardPolicyNewName

Defines the new name of the Policy.

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandardpolicy::rename command in cURL:

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

The following shows the CLI syntax for the deploy sitestandardpolicy::delete command:

ctm deploy sitestandardpolicy::delete <siteStandardPolicyName>

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

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandardpolicy::delete command in cURL:

Copy
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

The following shows the CLI syntax for the deploy sitestandardpolicies:details::get command:

ctm deploy sitestandardpolicies:details::get [-s "name=<SiteStandardPolicy>"]

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.

REST API Syntax

The following example shows the REST API syntax for the deploy sitestandardpolicies:details::get command in cURL:

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

Response

The following example is a response that contains details of Site Standard Polices:

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

Parameter

Description

name

Defines the name of the Policy.

description

Describes the Policy.

createdTime

Determines the time that the Policy was created.

username

Defines the name of the user who created the Policy.

siteStandard

Defines the Site Standard associated with the Policy.

status

Indicates whether the Policy is Active or Not Active.