Creating Your First Job Flow

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 Setting Up the API.
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/helix-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:
CopyCopied to clipboard
```
> ctm run AutomationAPISampleFlow.json
 
{
  "runId": "7cba67de-9e0d-409d-8d93-1b8229432eee",
  "statusURI": "https://controlmEndPointHost/automation-api/run/status/7cba67de-9e0d-409d-8d93-1b82294e"
}
```
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": "IN01:00007",
      "folderId": "IN01:00000",
      "numberOfRuns": 1,
      "name": "AutomationAPISampleFlow",
      "type": "Folder",
      "status": "Executing",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "Apr 26, 2020 10:43:47 AM",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Folder has no output",
      "logURI": "https://controlmEndPointHost/automation-api/run/job/IN01:00007/log"
    },
    {
      "jobId": "IN01:00008",
      "folderId": "IN01: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://controlmEndPointHost/automation-api/run/job/IN01:00008/log"
    },
    {
      "jobId": "IN01:00009",
      "folderId": "IN01: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://controlmEndPointHost/automation-api/run/job/IN01:00009/log"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25,
  "total": 3

Examine the contents of the AutomationAPISampleFlow.json file to learn about the structure of the job flow, as described in Folder Source Code Structure.
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 on the Agent.
- "Host" : "HOST"
  
  Replace HOST with the hostname of the Agent machine where the jobs will run.
- "FilePath":"SCRIPT_PATH"
  
  Replace SCRIPT_PATH with the path to the script file to run on the Control-M/Agent.
- "FileName":"SCRIPT_NAME"
  
  Replace SCRIPT_NAME with the name of the script file to run on the Control-M/Agent.
The following parameter values are used in a Control-M Workbench environment. The ag_diag_comm script returns a communication report.
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:
CopyCopied to clipboard
```
> ctm run AutomationAPISampleFlow.json
 
{
  "runId": "ed40f73e-fb7a-4f07-a71c-bc2dfbc48494",
  "statusURI": "https://controlmEndPointHost/automation-api/run/status/ed40f73e-fb7a-4f07-a71c-bc2dfbc48494"
}
```

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": "IN01:0000p",
      "folderId": "IN01:00000",
      "numberOfRuns": 1,
      "name": "AutomationAPISampleFlow",
      "type": "Folder",
      "status": "Ended OK",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "May 3, 2020 4:57:25 PM",
      "endTime": "May 3, 2020 4:57:28 PM",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Folder has no output",
      "logURI": "https://controlmEndPointHost/automation-api/run/job/IN01:0000p/log"
    },
    {
      "jobId": "IN01:0000q",
      "folderId": "IN01:0000p",
      "numberOfRuns": 1,
      "name": "CommandJob",
      "folder": "AutomationAPISampleFlow",
      "type": "Command",
      "status": "Ended OK",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "May 3, 2020 4:57:26 PM",
      "endTime": "May 3, 2020 4:57:26 PM",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "https://controlmEndPointHost/automation-api/run/job/IN01:0000q/output",
      "logURI": "https://controlmEndPointHost/automation-api/run/job/IN01:0000q/log"
    },
    {
      "jobId": "IN01:0000r",
      "folderId": "IN01:0000p",
      "numberOfRuns": 1,
      "name": "ScriptJob",
      "folder": "AutomationAPISampleFlow",
      "type": "Job",
      "status": "Ended OK",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "May 3, 2020 4:57:27 PM",
      "endTime": "May 3, 2020 4:57:27 PM",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "https://controlmEndPointHost/automation-api/run/job/IN01:0000r/output",
      "logURI": "https://controlmEndPointHost/automation-api/run/job/IN01:0000r/log"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25,
  "total": 3
}

Retrieve the output of the CommandJob using the run job:output::get command with the jobId that you obtained in the previous step.
CopyCopied to clipboard
```
> ctm run job:output::get "IN01:0000q"
 
+ echo my 1st job
my 1st job
```

Folder Source Code StructureLink copied to clipboard

The AutomationAPISampleFlow.json file contains the following source code:

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": "team@mycomp.com"
            }
         }
      }
   },
   "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.