Editing Part of an Existing Flow

This tutorial demonstrates how to modify a single job within a flow, without changing any other jobs or folders in the flow. In order to complete this tutorial, you need a valid Control-M endPoint and API token.

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:
Copy
```
git clone https://github.com/controlm/automation-api-quickstart.git
```

Step 1: Access the Tutorial Samples

Go to the directory where the tutorial sample is located:

Copy

cd automation-api-quickstart/helix-control-m/102-Editing-part-of-an-existing-flow

Step 2: Run the Source Code

Run the JSON code to a specific environment. use the -e option to specify a destination environment that differs from the default environment.

Ensure that the version of the destination environment matches the version of the CLI.

The command below shows you how to run a sample JSON file that contains definitions of a folder with two subfolders and one job in each subfolder.

Copy

> ctm run folderWithTwoProjects.json -e testEnvironment

Step 3: Review the Output

Ensure that folder ran successfully and the output contains the run ID and a status URI. Take note of the run ID, to use in the next step in this tutorial.

Copy

Job Output

{
   "runId": "fed27cd0-ef20-47c0-9c0c-9bc37ce239bc",
   "statusURI": "https://sqa/automation-api/run/status/fed27cd0-ef20-47c0-9c0c-9bc37ce239bc"
}

Step 4: Review the Status of All Elements

Retrieve the run status of all elements — the folder, two subfolders, and two jobs. Use the following command:

Copy

> ctm run status fed27cd0-ef20-47c0-9c0c-9bc37ce239bc -e testEnvironment

The command returns the following output. Note that the "status" property of the job_to_modify job is returned as "Ended Not OK".

Copy

Status Result

{
  "completion": "Completed",
  "statuses": [
    {
      "jobId": "IN01:000ci",
      "folderId": "IN01:",
      "numberOfRuns": 1,
      "name": "Folder_1",
      "folder": "Folder_1",
      "type": "Folder",
      "status": "Ended Not OK",
      "held": false,
      "deleted": false,
      "cyclic": false,
      "startTime": "Sep 4, 2022, 5:22:49 PM",
      "endTime": "Sep 4, 2022, 5:22:52 PM",
      "estimatedStartTime": [
        "20220904172630"
      ],
      "estimatedEndTime": [
        "20220904173130"
      ],
      "orderDate": "220904",
      "ctm": "IN01",
      "description": "",
      "host": "sqa",
      "application": "",
      "subApplication": "",
      "outputURI": "Folder has no output",
      "logURI": "https://sqa/automation-api/run/job/IN01:000ci/log"
    },
    {
      "jobId": "IN01:000cj",
      "folderId": "IN01:000ci",
      "numberOfRuns": 0,
      "name": "Project_Folder1",
      "folder": "Folder_1",
      "type": "Sub-Table",
      "status": "Ended Not OK",
      "held": false,
      "deleted": false,
      "cyclic": false,
      "startTime": "Sep 4, 2022, 5:22:49 PM",
      "endTime": "Sep 4, 2022, 5:22:51 PM",
      "estimatedStartTime": [
        "20220904172630"
      ],
      "estimatedEndTime": [
        "20220904173130"
      ],
      "orderDate": "220904",
      "ctm": "IN01",
      "description": "",
      "host": "sqa",
      "application": "",
      "subApplication": "",
      "outputURI": "https://sqa/automation-api/run/job/IN01:000cj/output",
      "logURI": "https://sqa/automation-api/run/job/IN01:000cj/log"
    },
    {
      "jobId": "IN01:000ck",
      "folderId": "IN01:000cj",
      "numberOfRuns": 1,
      "name": "job_to_modify",
      "folder": "Folder_1/Project_Folder1",
      "type": "Command",
      "status": "Ended Not OK",
      "held": false,
      "deleted": false,
      "cyclic": false,
      "startTime": "Sep 4, 2022, 5:22:49 PM",
      "endTime": "Sep 4, 2022, 5:22:50 PM",
      "estimatedStartTime": [
        "20220904172630"
      ],
      "estimatedEndTime": [
        "20220904173130"
      ],
      "orderDate": "220904",
      "ctm": "IN01",
      "description": "This job was created for editing part of an existing flow - Ended Not OK",
      "host": "sqa",
      "application": "FOLDER_HOLDER",
      "subApplication": "",
      "outputURI": "https://sqa/automation-api/run/job/IN01:000ck/output",
      "logURI": "https://sqa/automation-api/run/job/IN01:000ck/log"
    },
    {
      "jobId": "IN01:000cl",
      "folderId": "IN01:000ci",
      "numberOfRuns": 0,
      "name": "Project_Folder2",
      "folder": "Folder_1",
      "type": "Sub-Table",
      "status": "Ended OK",
      "held": false,
      "deleted": false,
      "cyclic": false,
      "startTime": "Sep 4, 2022, 5:22:49 PM",
      "endTime": "Sep 4, 2022, 5:22:51 PM",
      "orderDate": "220904",
      "ctm": "IN01",
      "description": "",
      "host": "sqa",
      "application": "",
      "subApplication": "",
      "outputURI": "https://sqa/automation-api/run/job/IN01:000cl/output",
      "logURI": "https://sqa/automation-api/run/job/IN01:000cl/log"
    },
    {
      "jobId": "IN01:000cm",
      "folderId": "IN01:000cl",
      "numberOfRuns": 1,
      "name": "job_not_to_touch",
      "folder": "Folder_1/Project_Folder2",
      "type": "Command",
      "status": "Ended OK",
      "held": false,
      "deleted": false,
      "cyclic": false,
      "startTime": "Sep 4, 2022, 5:22:49 PM",
      "endTime": "Sep 4, 2022, 5:22:50 PM",
      "orderDate": "220904",
      "ctm": "IN01",
      "description": "This job was created for editing part of an existing flow - ended ok",
      "host": "sqa",
      "application": "FOLDER_HOLDER",
      "subApplication": "",
      "outputURI": "https://sqa/automation-api/run/job/IN01:000cm/output",
      "logURI": "https://sqa/automation-api/run/job/IN01:000cm/log"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25,
  "total": 5

Step 5: Retrieve Job Definitions

Let's now retrieve the definitions of the "job_to_modify" job and modify its properties.

Copy

> ctm deploy jobs::get -s "ctm=IN01&folder=Folder_1&job=job_to_modify" -e testEnvironment

The command returns the following output:

Copy

{
   "job_to_modify": {
      "Type": "Job:Command",
      "Description": "this job was created to editing part of an existing flow - Ended Not OK",
      "RunAs": "controlm",
      "Application": "FOLDER_HOLDER",
      "Command": "job that need to be modify",
      "PathElement": {
         "Folder": "Folder_1:Project_Folder1",
         "Server": "IN01"
      }
   } 
}

The PathElement object defines the path to the job or subfolder within the folder on the target server.

Step 6: Modify the Job

In modify_single_job.json, correct the erroneous "Command" property, by adding "echo" at the beginning of the command.

Copy

{
   "job_to_modify": {
      "Type": "Job:Command",
      "Description": "this job was created to editing part of an existing flow - Ended Not OK",
      "RunAs": "controlm",
      "Application": "FOLDER_HOLDER",
      "Command": "echo job that need to be modify",
      "PathElement": {
         "Folder": "Folder_1:Project_Folder1",
         "Server": "IN01"
      }
   } 
}

Step 7: Deploy the Modified Job

After modifying the modify_single_job.json job definitions, we can now use the following command to deploy the job:

Copy

> ctm deploy modify_single_job.json

The command returns the following output:

Copy

[
    {
       "deploymentFile": "modify_single_job.json ",
       "deploymentStatus": "ENDED_OK",
       "successfulFoldersCount": 0,
       "successfulSmartFoldersCount": 0,
       "successfulSubFoldersCount": 0,
       "successfulJobsCount": 1,
       "successfulConnectionProfilesCount": 0,
       "successfulDriversCount": 0,
       "isDeployDescriptorValid": false
    }  
]

Step 8: Test the Flow

We will now run the flow again, this time with the modified job, using the run order command.

Copy

> ctm run order IN01 Folder_1

The command returns the following output:

Copy

{
   "runId": "cedeb0cc-82c6-47a4-88b2-0407781089c3",
   "statusURI": "https://sqa/automation-api/run/status/cedeb0cc-82c6-47a4-88b2-0407781089c3"
}

Step 9: Review the Status of All Elements After Job Modification

Retrieve the run status of all elements after modifying the job. Use the following command:

Copy

> ctm run status cedeb0cc-82c6-47a4-88b2-0407781089c3

The command returns the following output. Note that the "status" property of the job_to_modify job is returned as "Ended OK".

Copy

{
    "completion": "Completed",
    "statuses": [
       {
          "jobId": "IN01:000ci",
          "folderId": "IN01:",
          "numberOfRuns": 2,
          "name": "Folder_1",
          "folder": "Folder_1",
          "type": "Folder",
          "status": "Ended Not OK",
          "held": false,
          "deleted": false,
          "cyclic": false,
          "startTime": "Sep 4, 2022, 5:49:40 PM",
          "endTime": "Sep 4, 2022, 5:49:42 PM",
          "estimatedStartTime": [
             "20220904174940"
          ],
          "estimatedEndTime": [
             "20220904175450"
          ],
          "orderDate": "220904",
          "ctm": "IN01",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "Folder has no output",
          "logURI": "https://sqa/automation-api/run/job/IN01:000ci/log"
      },
      {
          "jobId": "IN01:000cr",
          "folderId": "IN01:000ci",
          "numberOfRuns": 0,
          "name": "Project_Folder1",
          "folder": "Folder_1",
          "type": "Sub-Table",
          "status": "Ended OK",
          "held": false,
          "deleted": false,
          "cyclic": false,
          "startTime": "Sep 4, 2022, 5:49:40 PM",
          "endTime": "Sep 4, 2022, 5:49:41 PM",
          "estimatedStartTime": [
             "20220904174940"
          ],
          "estimatedEndTime": [
             "20220904175000"
          ],
          "orderDate": "220904",
          "ctm": "IN01",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "https://sqa/automation-api/run/job/IN01:000cr/output",
          "logURI": "https://sqa/automation-api/run/job/IN01:000cr/log"
      },
      {
          "jobId": "IN01:000cs",
          "folderId": "IN01:000cr",
          "numberOfRuns": 1,
          "name": "job_to_modify",
          "folder": "Folder_1/Project_Folder1",
          "type": "Command",
          "status": "Ended OK",
          "held": false,
          "deleted": false,
          "cyclic": false,
          "startTime": "Sep 4, 2022, 5:49:40 PM",
          "endTime": "Sep 4, 2022, 5:49:41 PM",
          "orderDate": "220904",
          "ctm": "IN01",
          "description": "This job was created for editing part of an existing flow - ended ok",
          "host": "sqa",
          "application": "FOLDER_HOLDER",
          "subApplication": "",
          "outputURI": "https://sqa/automation-api/run/job/IN01:000cs/output",
          "logURI": "https://sqa/automation-api/run/job/IN01:000cs/log"
      },
      {
          "jobId": "IN01:000ct",
          "folderId": "IN01:000ci",
          "numberOfRuns": 0,
          "name": "Project_Folder2",
          "folder": "Folder_1",
          "type": "Sub-Table",
          "status": "Ended OK",
          "held": false,
          "deleted": false,
          "cyclic": false,
          "startTime": "Sep 4, 2022, 5:49:40 PM",
          "endTime": "Sep 4, 2022, 5:49:41 PM",
          "estimatedStartTime": [
             "20220904174940"
          ],
          "estimatedEndTime": [
             "20220904175000"
          ],
          "orderDate": "220904",
          "ctm": "IN01",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "https://sqa/automation-api/run/job/IN01:000ct/output",
          "logURI": "https://sqa/automation-api/run/job/IN01:000ct/log"
      },
      {
          "jobId": "IN01:000cu",
          "folderId": "IN01:000ct",
          "numberOfRuns": 1,
          "name": "job_not_to_touch",
          "folder": "Folder_1/Project_Folder2",
          "type": "Command",
          "status": "Ended OK",
          "held": false,
          "deleted": false,
          "cyclic": false,
          "startTime": "Sep 4, 2022, 5:49:40 PM",
          "endTime": "Sep 4, 2022, 5:49:41 PM",
          "orderDate": "220904",
          "ctm": "IN01",
          "description": "This job was created for editing part of an existing flow - ended ok",
          "host": "sqa",
          "application": "FOLDER_HOLDER",
          "subApplication": "",
          "outputURI": "https://sqa/automation-api/run/job/IN01:000cu/output",
          "logURI": "https://sqa/automation-api/run/job/IN01:000cu/log"
      } 
   ],
   "startIndex": 0,
   "itemsPerPage": 25,
   "total": 4
}

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.