×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

New Documentation

   

Control-M Automation API Documentation has moved to a new location, with a new design to enhance ease of use.
Control-M SaaS Automation API Tutorials

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

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

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

Step 1 - Access the tutorial samples

Go to the directory where the tutorial sample is located:

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.

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

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

The command returns the following output:

{
   "Folder_1": {
      "Type":  "Folder",
      "ControlmServer": "IN01",
      "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": "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: 

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

The command returns the following output:

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

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

Was this page helpful? Yes No Submitting... Thank you
Last modified by Yechezkel Schatz on Jan 24, 2023

Comments

Log in or register to comment.

Automating code deployment
Running applications and programs in your environment
© Copyright 2022 BMC Software, Inc.
Legal notices
© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.