This example shows how to write command and script jobs that run in sequence.
Before You Begin
Ensure that you meet the following prerequisites:
-
You have successfully completed API setup, as described in
-
You have Git installed. If not, obtain it from the Git Downloads page.
-
You have local copies of the tutorial samples from GitHub and a local copy of the source code using the git clone command:
git clone https://github.com/controlm/automation-api-quickstart.git
Begin
-
Access the tutorial sample with the following command:
cd automation-api-quickstart/control-m/101-create-first-job-flow
-
Verify that the code within the AutomationAPISampleFlow.json file is valid by running the build command.
The following example shows the build command and a typical successful response:
Copy> ctm build AutomationAPISampleFlow.json
[
{
"deploymentFile": "AutomationAPISampleFlow.json",
"successfulFoldersCount": 0,
"successfulSmartFoldersCount": 1,
"successfulSubFoldersCount": 0,
"successfulJobsCount": 2,
"successfulConnectionProfilesCount": 0,
"isDeployDescriptorValid": false
}
] -
Run the jobs on the Control-M environment using the run command.
The returned runId is used to check the job status.
The following example shows the run command and a typical successful response:
Copy> ctm run AutomationAPISampleFlow.json
{
"runId": "7cba67de-9e0d-409d-8d93-1b8229432eee",
"statusURI": "https://localhost:8443/automation-api/run/status/7cba67de-9e0d-409d-8d93-1b82294e",
"monitorPageURI": "https://localhost:8443/SelfService#Workbench:runid=7cba67de-9e0d-409d-8d93-29432eee&title=AutomationAPISampleFlow.json"
}In this example, the code ran successfully and returned a runId of "7cba67de-9e0d-409d-8d93-1b8229432eee".
-
Check job status for the runId that you obtained in the previous step using the run status command.
The following example shows the run status command and a typical successful response, with job status information for each of the jobs in the flow:
Copy> ctm run status "7cba67de-9e0d-409d-8d93-1b8229432eee"
{
"statuses": [
{
"jobId": "workbench:00007",
"folderId": "workbench:00000",
"numberOfRuns": 1,
"name": "AutomationAPISampleFlow",
"type": "Folder",
"status": "Executing",
"held": "false",
"deleted": "false",
"cyclic": "false",
"startTime": "Apr 26, 2017 10:43:47 AM",
"endTime": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "Folder has no output",
"logURI": "https://localhost:8443/automation-api/run/job/workbench:00007/log"
},
{
"jobId": "workbench:00008",
"folderId": "workbench:00007",
"numberOfRuns": 0,
"name": "CommandJob",
"folder": "AutomationAPISampleFlow",
"type": "Command",
"status": "Wait Host",
"held": "false",
"deleted": "false",
"cyclic": "false",
"startTime": "",
"endTime": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "Job did not run, it has no output",
"logURI": "https://localhost:8443/automation-api/run/job/workbench:00008/log"
},
{
"jobId": "workbench:00009",
"folderId": "workbench:00007",
"numberOfRuns": 0,
"name": "ScriptJob",
"folder": "AutomationAPISampleFlow",
"type": "Job",
"status": "Wait Condition",
"held": "false",
"deleted": "false",
"cyclic": "false",
"startTime": "",
"endTime": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "Job did not run, it has no output",
"logURI": "https://localhost:8443/automation-api/run/job/workbench:00009/log"
}
],
"startIndex": 0,
"itemsPerPage": 25,
"total": 3,
"monitorPageURI": "https://localhost:8443/SelfService#Workbench:runid=7cba67de-9e0d-409d-8d93-1b8229432eee&title=Status_7cba67de-9e0d-409d-8d93-1b8229432eee" -
Examine the contents of the AutomationAPISampleFlow.json file to learn about the structure of the job flow, as shown below:
Copy{
"Defaults" : {
"Application" : "SampleApp",
"SubApplication" : "SampleSubApp",
"RunAs" : "USERNAME",
"Host" : "HOST",
"Job": {
"When" : {
"Months": ["JAN", "OCT", "DEC"],
"MonthDays":["22","1","11"],
"WeekDays":["MON","TUE", "WED", "THU", "FRI"],
"FromTime":"0300",
"ToTime":"2100"
},
"ActionIfFailure" : {
"Type": "If",
"CompletionStatus": "NOTOK",
"mailToTeam": {
"Type": "Mail",
"Message": "%%JOBNAME failed",
"To": "[email protected]"
}
}
}
},
"AutomationAPISampleFlow": {
"Type": "Folder",
"Comment" : "Code reviewed by John",
"CommandJob": {
"Type": "Job:Command",
"Command": "echo my 1st job"
},
"ScriptJob": {
"Type": "Job:Script",
"FilePath":"SCRIPT_PATH",
"FileName":"SCRIPT_NAME"
},
"Flow": {
"Type": "Flow",
"Sequence": ["CommandJob", "ScriptJob"]
}
}
}This source code contains the following main objects:
-
The "Defaults" object at the top of this example allows you to define parameters once for all objects.
For example, it includes scheduling using the When parameter, which configures all jobs to run according to the same scheduling criteria.
-
The "ActionIfFailure" object determines what action to take when a job ends unsuccessfully.
-
The folder in this example is named AutomationAPISampleFlow, and it contains two jobs, CommandJob and ScriptJob.
-
The Flow object defines the sequence of job execution.
-
-
Set parameter values that match your Control-M environment in the following lines in the AutomationAPISampleFlow.json file:
-
"RunAs" : "USERNAME"
Replace USERNAME with the name of an operating system user that will execute jobs.
-
"Host" : "HOST"
Replace HOST with the hostname of the host where the jobs will run.
-
"FilePath":"SCRIPT_PATH"
Replace SCRIPT_PATH with the path to the script file to run on the Agent.
-
"FileName":"SCRIPT_NAME"
Replace SCRIPT_NAME with the name of the script file to run on the Agent.
The following parameter values are used in a Control-M Workbench environment. The ag_diag_comm script returns a communication report.
Copy"RunAs" : "workbench"
"Host" : "workbench"
"FilePath":"/home/workbench/ctm/scripts"
"FileName":"ag_diag_comm" -
-
After modifying the AutomationAPISampleFlow.json file, rerun the sample code using the run command.
The following example shows the run command and a typical successful response after setting parameter values that match your Control-M environment:
Copy> ctm run AutomationAPISampleFlow.json
{
"runId": "ed40f73e-fb7a-4f07-a71c-bc2dfbc48494",
"statusURI": "https://localhost:8443/automation-api/run/status/ed40f73e-fb7a-4f07-a71c-bc2dfbc48494",
"monitorPageURI": "https://localhost:8443/SelfService#Workbench:runid=ed40f73e-fb7a-4f07-a71c-bc2dfbc48494&title=AutomationAPISampleFlow.json"
} -
Check job status for the new runId that you obtained in the previous step using the run status command.
The following example shows the run status command and a typical successful response. This time, both jobs have the Ended OK status.
Copy> ctm run status "ed40f73e-fb7a-4f07-a71c-bc2dfbc48494"
{
"statuses": [
{
"jobId": "workbench:0000p",
"folderId": "workbench:00000",
"numberOfRuns": 1,
"name": "AutomationAPISampleFlow",
"type": "Folder",
"status": "Ended OK",
"held": "false",
"deleted": "false",
"cyclic": "false",
"startTime": "May 3, 2017 4:57:25 PM",
"endTime": "May 3, 2017 4:57:28 PM",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "Folder has no output",
"logURI": "https://localhost:8443/automation-api/run/job/workbench:0000p/log"
},
{
"jobId": "workbench:0000q",
"folderId": "workbench:0000p",
"numberOfRuns": 1,
"name": "CommandJob",
"folder": "AutomationAPISampleFlow",
"type": "Command",
"status": "Ended OK",
"held": "false",
"deleted": "false",
"cyclic": "false",
"startTime": "May 3, 2017 4:57:26 PM",
"endTime": "May 3, 2017 4:57:26 PM",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "https://localhost:8443/automation-api/run/job/workbench:0000q/output",
"logURI": "https://localhost:8443/automation-api/run/job/workbench:0000q/log"
},
{
"jobId": "workbench:0000r",
"folderId": "workbench:0000p",
"numberOfRuns": 1,
"name": "ScriptJob",
"folder": "AutomationAPISampleFlow",
"type": "Job",
"status": "Ended OK",
"held": "false",
"deleted": "false",
"cyclic": "false",
"startTime": "May 3, 2017 4:57:27 PM",
"endTime": "May 3, 2017 4:57:27 PM",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "https://localhost:8443/automation-api/run/job/workbench:0000r/output",
"logURI": "https://localhost:8443/automation-api/run/job/workbench:0000r/log"
}
],
"startIndex": 0,
"itemsPerPage": 25,
"total": 3,
"monitorPageURI": "https://localhost:8443/SelfService#Workbench:runid=ed40f73e-fb7a-4f07-a71c-bc2dfbc48494&title=Status_ed40f73e-fb7a-4f07-a71c-bc2dfbc48494"
} -
Retrieve the output of the CommandJob using the run job:output::get command with the jobId that you obtained in the previous step.
Copy> ctm run job:output::get "workbench:0000q"
+ echo my 1st job
my 1st job -
Run the jobs again using the run command with the "--interactive" or "-i" option, to launch the Control-M Workbench interactive interface and view additional job details.
The Workbench interactive interface is especially useful for debugging puroposes. It enables you to view various job run details, such as an activity log and statistics for each job.
The following example shows the run command with the --interactive option. This command opens a browser window, where you can view and manage your jobs.
Copy> ctm run AutomationAPISampleFlow.json --interactive
{
"runId": "40586805-60b5-4acb-9f21-a0cf048f1051",
"statusURI": "https://ec2-54-187-1-168.us-west-2.compute.amazonaws.com:8443/run/status/40586805-60b5-4acb-9f21-a0cf048f1051",
"monitorPageURI": "https://localhost:8443/SelfService#Workbench:runid=40586805-60b5-4acb-9f21-a0cf048f1051&title=AutomationAPISampleFlow.json
}
YouTube
Facebook
LinkedIn