This example shows how to write command and script jobs that run in sequence.
Before You Begin
Ensure that you have set up your environment, as described in Setting Up the Prerequisites.
Step 1: Access the Tutorial Samples
Go to the directory where the tutorial sample is located:
cd automation-api-quickstart/control-m/101-create-first-job-flowStep 2: Verify the Code for Control-M
Let's take the AutomationAPISampleFlow.json file, which contains job definitions, and verify that the code within it is valid. To do so, use the build command. The following example shows the command and a typical successful response.
> ctm build AutomationAPISampleFlow.json
[
{
"deploymentFile": "AutomationAPISampleFlow.json",
"successfulFoldersCount": 0,
"successfulSmartFoldersCount": 1,
"successfulSubFoldersCount": 0,
"successfulJobsCount": 2,
"successfulConnectionProfilesCount": 0,
"isDeployDescriptorValid": false
}
]If the code is not valid, an error is returned.
Step 3: Run the Source Code
Use the run command to run the jobs on the Control-M environment. The returned runId is used to check the job status. The following shows the command and a typical successful response.
> 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"
}This code ran successfully and returned the runId of "7cba67de-9e0d-409d-8d93-1b8229432eee".
Step 4: Check Job Status Using the runId
The following command shows how to check job status using the runId. Note that when there is more than one job in the flow, the status of each job is checked and returned.
> 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"Step 5: Examine the Source Code
Let's look at the source code in the AutomationAPISampleFlow.json file. By examining the contents of this file, you'll learn about the structure of the job flow and what it should contain.
{
"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"]
}
}
}The first object is called "Defaults". It allows you to define a parameter 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 is taken if a job ends unsuccessfully.
This example contains two jobs: CommandJob and ScriptJob. These jobs are contained within a folder named AutomationAPISampleFlow. To define the sequence of job execution, the Flow object is used.
Step 6: Modify the Code to Run in Your Environment
In the code above, the following parameters need to be set to run the jobs in your environment. Change the values to match your Control-M environment.
"RunAs" : "USERNAME"
"Host" : "HOST"
"FilePath":"SCRIPT_PATH"
"FileName":"SCRIPT_NAME"-
RunAs identifies the operating system user that will execute the jobs.
-
Host defines the machine where the jobs will run.
-
FilePath and FileName define the location and name of a file that contains a script to run on the Control-M/Agent.
Change the values to suit your Control-M environment. In a Control-M Workbench environment, change the values of the following parameters as shown in the example below. The ag_diag_comm script returns a communication report.
"RunAs" : "workbench"
"Host" : "workbench"
"FilePath":"/home/workbench/ctm/scripts"
"FileName":"ag_diag_comm"Step 7: Rerun the Code Sample
Now that we've modified the source code in the AutomationAPISampleFlow.json file, let's rerun the sample:
> 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"
}Each time you run the code, a new runId is generated. Let's take the new runId, and check the jobs statuses again:
> 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"
}You can now see that both jobs Ended OK.
Let's view the output of CommandJob. Use the jobId to get this information, as in the following example:
> ctm run job:output::get "workbench:0000q"
+ echo my 1st job
my 1st jobStep 8: View Job Details through an Interactive Interface
Control-M Workbench offers an interactive user interface for debugging purposes. Through this interface, you can view various job run details (including, for example, an activity log and statistics for each job). To launch this interface when you run jobs, enter "--interactive" or "-i" at the end of the run command.
> 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
}A browser window opens, where you can view and manage your jobs.
Where to Go from Here
To learn more about what you can do with the Control-M Automation API, read through Code Reference and Services.
YouTube
Twitter
Facebook
LinkedIn