Tutorial - 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.

You can use this tutorial also for modifying subfolders within a flow 

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/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.

Note

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.

> 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. 

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:

> 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".

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 folder that contains "job_to_modify" job and modify its properties.

> ctm deploy jobs::get -s "ctm=LocalControlM&folder=Folder_1" -e testEnvironment

The command returns the following output:

{
  "Folder_1": {
     "Type":  "Folder",
     "ControlmServer": "LocalControlM",
     "Project_Folder1": {
        "Type": "SubFolder",
        "CreatedBy": "emuser1",
        "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"
        }
     },
     "Project_Folder2": {
        "Type": "SubFolder",
        "AdjustEvents": false,
        "good_Job": {
           "Type": "Job:Command",
           "Description": "this job was created to editing part of an existing flow - ended ok",
           "RunAs": "controlm",
           "Application": "FOLDER_HOLDER",
           "Command": "echo good job"
        }
     }
  }      
}

Let's save the part that we need to change that contains job_to_modify in a JSON file named modify_single_job.json.

job_to_modify
{
  "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"
  }  
}

Step 6 - Modify the job

In modify_single_job.json, make the following changes:

  • Correct the erroneous "Command" property, by adding "echo" at the beginning of the command.
  • Add a PathElement object. this object defines the path to the job or subfolder that needs to be modified.
  • Specify the target server and the full path to the folder where you want to modify this job.
{
  "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: 

> ctm deploy modify_single_job.json

The command returns the following output:

[
   {
      "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.

> ctm run order LocalControlM Folder_1

The command returns the following output:

{
 "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:

> 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".

{
   "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

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*