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, or an endpoint with a username and password.

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:

Copy

cd automation-api-quickstart/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:8443/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": "LocalControlM:000ci",
          "folderId": "LocalControlM:",
          "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": "LocalControlM",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "Folder has no output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000ci/log"
      },
      {
          "jobId": "LocalControlM:000cj",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cj/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cj/log"
      },
      {   
          "jobId": "LocalControlM:000ck",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "This job was created for editing part of an existing flow - Ended Not OK",
          "host": "sqa",
          "application": "FOLDER_HOLDER",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000ck/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000ck/log"
      },
      {   
          "jobId": "LocalControlM:000cl",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cl/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cl/log"
      },
      {   
          "jobId": "LocalControlM:000cm",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "This job was created for editing part of an existing flow - ended ok",
          "host": "sqa",
          "application": "FOLDER_HOLDER",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cm/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM: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=LocalControlM&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": "LocalControlM"
      } 
   }  
}

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": "LocalControlM"
      } 
   }  
}

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 LocalControlM Folder_1

The command returns the following output:

Copy

{
   "runId": "cedeb0cc-82c6-47a4-88b2-0407781089c3",
   "statusURI": "https://sqa:8443/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": "LocalControlM:000ci",
           "folderId": "LocalControlM:",
           "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": "LocalControlM",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "Folder has no output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000ci/log"
      },
      {
          "jobId": "LocalControlM:000cr",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cr/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cr/log"
      },
      {
          "jobId": "LocalControlM:000cs",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "This job was created for editing part of an existing flow - ended ok",
          "host": "sqa",
          "application": "FOLDER_HOLDER",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cs/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cs/log"
      },
      {
          "jobId": "LocalControlM:000ct",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "",
          "host": "sqa",
          "application": "",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000ct/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000ct/log"
      },
      {
          "jobId": "LocalControlM:000cu",
          "folderId": "LocalControlM: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": "LocalControlM",
          "description": "This job was created for editing part of an existing flow - ended ok",
          "host": "sqa",
          "application": "FOLDER_HOLDER",
          "subApplication": "",
          "outputURI": "https://sqa:8443/automation-api/run/job/LocalControlM:000cu/output",
          "logURI": "https://sqa:8443/automation-api/run/job/LocalControlM: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.