Folders and Flows

Folders, subfolders, and flows enable you to group and organize your jobs in a logical manner. They also help simplify the configuration of job settings.

Folder

The default type of folder (as opposed to a Simple Folder) enables you to configure various settings such as scheduling, event management, adding resources, or adding notifications on the folder level. Folder-level definitions are inherited by the jobs or sub-folders within the folder.

If the folder name contains a colon character, escape the colon character with two backslashes.

For example, you can specify scheduling criteria on the folder level instead of defining the criteria per job in the folder. All jobs in the folder will take on the rules of the folder. This reduces job definition in code.

Copy 
{
    "FolderSample": {
        "Type": "Folder",
        "When" : {
            "WeekDays": ["SUN"]
        },         
        "Job1": {
            "Type": "Job:Command",
            "Command": "echo I am a Job",
            "RunAs": "controlm"
        },
        "Job2": {
            "Type": "Job:Command",
            "Command": "echo I am a Job",
            "RunAs": "controlm"
        }
    }
}

In the following example, jobs are defined in an array structure under a Jobs object, instead of under separate job objects that bear the name of each job. This array structure enables you to define more than one job with the same job name.

To enable job definitions in an array format, the allowDuplicateJobNames system setting must be set to true (the default value).

Copy 
{
    "FolderSample": {
        "Type": "Folder",
        "When" : {
            "WeekDays": ["SUN"]
        "Jobs": [
        {
            "Type": "Job:Command",
            "Name":"Job1",
            "Command": "echo I am a Job with name Job1",
            "RunAs": "controlm"
        },
        {
            "Type": "Job:Command",
            "Name":"Job1",
            "Command": "echo I am another Job with the same name",
            "RunAs": "controlm"
        }
        ]
    }
}

Optional parameters:

Copy 
{
    "FolderSampleAll": {
        "Type": "Folder",
        "AdjustEvents": true,
        "ControlmServer": "IN01",
        "SiteStandard": "myStandards",
        "BusinessFields" : [ { "Department" : "HR" }, {"Company":"BMC"} ],
        "OrderMethod": "Manual",
        "Application": "ApplicationName",
        "SubApplication" : "SubApplicationName",
        "RunAs" : "controlm",
        "When" : {
            "WeekDays": ["SUN"]
        },
        "lock1" : {
            "Type": "Resource:Lock",
            "LockType": "Exclusive"
        },
        "Notify1": {
            "Type": "Notify:ExecutionTime",
            "Criteria": "LessThan",
            "Value": "3",
            "Message": "Less than expected"
        }
    }
}

Parameter

Description

AdjustEvents

Whether a job in a folder or sub-folder should run and not wait for events from an unscheduled predecessor job.

A folder contains Jobs A, B, and C. Job B can only run when the events of Job A are met, and Job C can only run when the events of Job B are met. If Job B is not scheduled to run on a certain day, Job C cannot run on that day. AdjustEvents enables Job C to run, and not wait for the events of Job B.

AdjustEvents is applied to the events created within the folder. If a job waits for an event that is not created in the folder, the event is not adjusted.

Valid values:

  • True: The successor job runs and does not wait for events from the unscheduled job.

  • False: The successor job does not run and waits for events from the unscheduled job.

  • Dummy: The unscheduled job runs as a dummy job which enables the successor job to run.

  • Bridge: All the scheduled jobs in the folder run even though there are unscheduled jobs in the same folder. The bridge maintains the order and dependencies between jobs, which enables all the jobs within the folder to run according to their defined criteria.

Default: False

ControlmServer

Specifies a Control-M Scheduling Server. If more than one Control-M Scheduling Server is configured in the system, you must define the server that the folder belongs to.

SiteStandard

Enforces the defined Site Standard to the folder and all jobs contained within the folder.

BusinessFields

Values for the business fields of the specified Site Standard.

Enter this information as an array with the following format:

[ {BusinessField1_Name:value}, {BusinessField2_Name:value} ]

OrderMethod

Options are:

  • Automatic: The folder and its jobs are automatically ordered on days specified in the 'When' property.

  • Manual: The 'When' property is ignored. To order such a folder use the "ctm run order" API or Action Type:Run.

  • Any other value: See the description of the <user daily> method and other methods in Order Method.

Default: Automatic

RunAs

The name of the user responsible for running the jobs in the folder or sub-folder. For more details, see RunAs.

When

Defines scheduling for all jobs in the folder or sub-folder, using various scheduling parameters or rule-based calendars. For more details, see When.

ActiveRetentionPolicy

The retention policy for jobs in the folder or sub-folder, one of the following options:

  • KeepAll: All jobs wait for the folder or sub-folder to complete and are removed at the same time as the folder or sub-folder.

  • CleanEndedOK: Jobs in the folder or sub-folder are removed automatically from the database.

Default: KeepAll

DaysKeepActiveIfNotOk

Defines the number of days to keep all jobs in the folder active after the folder is set to NOT OK.

This parameter is relevant only when ActiveRetentionPolicy=KeepAll.

Valid values: 0-99 (where 99 is forever)

Default: 0

Jobs

Defines jobs in an array structure, which can include multiple jobs with the same name. See Job Properties for detailed information.

<Resource Lock>

See Resource:Lock for detailed information about the resource.

<Notification>

Issues notifications for various scenarios that occur before, during, or after the execution of jobs within the folder or sub-folder. For more details, see Notification.

If

See If and If Actions for detailed information.

<Job >

Defines a job separately from other jobs (not in an array structure). See Job Properties for detailed information.

Events

See Events for detailed information.

Flow

See Flow for detailed information.

Folders support the use of the following additional properties and parameters:

The following example shows a Folder defined in one time zone, with a command job (defined within it) in a different time zone:

Copy 
{
    "Folder8": {
        "Type": "Folder",
        "Description": "folder desc",
        "Application" : "Billing",
        "SubApplication" : "Payable",
        "TimeZone":"HAW",
        "SimpleCommandJob": {
            "Type": "Job:Command",
            "Description": "job desc",
            "Application" : "BillingJobs",
            "SubApplication" : "PayableJobs",
            "TimeZone":"MST",
            "Host":"agent8",
            "RunAs":"owner8",
            "Command":"ls"
        }
    }
}

SubFolder

A sub-folder is a folder contained within another (parent) folder or sub-folder. A sub-folder can contain a group of jobs or a next-level sub-folder, and it can also contain a Flow. sub-folders offer many (but not all) of the capabilities that are offered by folders.

If the subfolder name contains a colon character, escape the colon character with two backslashes.

The following example shows a folder that contains two sub-folders with the most basic definitions:

Copy 
{
    "FolderWithsub-folders":{
        "Type":"Folder",
        "SubFolder1":{
            "Type":"SubFolder",
            "job1": {
                "Type": "Job:Script",
                "FileName": "scriptname.sh",
                "FilePath": "/home/user/scripts",
                "RunAs": "em900cob"
                }
            },
        "SubFolder2":{
            "Type":"SubFolder",
            "job1": {
                "Type": "Job:Script",
                "FileName": "scriptname2.sh",
                "FilePath": "/home/user/scripts",
                "RunAs": "em900cob"
            }
        }
    }
}

In the following example, jobs are defined in an array structure under a Jobs object, instead of under separate job objects that bear the name of each job. This array structure enables you to define more than one job with the same job name.

Copy 
{
    "FolderWithSubFolders": {
        "Type": "Folder",
        "SubFolder1": {
            "Type": "SubFolder",
            "Jobs": [{
                "Type": "Job:Command",
                "Name": "Job1",
                "Command": "echo I am a Job with name Job1",
                "RunAs": "controlm"
            },
            {
                "Type": "Job:Script",
                "Name": "Job2",
                "FileName": "scriptname1.sh",
                "FilePath": "/home/user/scripts",
                "RunAs": "em900cob"
            },
            {
                "Type": "Job:Script",
                "Name": "Job2",
                "FileName": "scriptname2.sh",
                "FilePath": "/home/user/scripts",
                "RunAs": "em900cob"
            }
            ]
        }
    }
}

The following example shows a more complex hierarchy of sub-folders, with scheduling properties:

Copy 
{
 "FolderWithComplexSubFolders" : {
    "Type" : "Folder",
    "ControlmServer" : "LocalControlM",
    "When" : {
        "RuleBasedCalendars" : {
            "Included" : [ "glob1", "cal2","cal1" ],
            "Excluded" : [ "glob2" ],
            "cal1" : {
                "Type" : "Calendar:RuleBased",
                "When" : {
                    "WeekDays" : [ "MON" ],
                    "MonthDays" : [ "NONE" ]
                }
            }
        }
    },
    "subF1" : {
        "Type" : "SubFolder",
        "Application" : "application",
        "When" : {
            "RuleBasedCalendars" : {
                "Included" : [ "USE PARENT" ]
            }
        }
    },
    "subF2" : {
        "Type" : "SubFolder",
        "Application" : "application",
        "When" : {
            "FromTime":"1211",
            "ToTime":"2211",
            "RuleBasedCalendars" : {
                "Included" : [ "cal1" ]
            }
        },
        "subF2a" : {
            "Type" : "SubFolder",
            "Application" : "application",
            "job3" : {
                "Type" : "Job:Script",
                "FileName" : "scriptname.sh",
                "FilePath" : "/home/user/scripts",
                "RunAs" : "em900cob",
                "Application" : "application"
                }
        }
    }
  }
}

You can also add or update a sub-folder as a root object, by specifying details of the hierarchical positioning of the sub-folder under the PathElement property.

Sub-folders support the use of the following properties and parameters:

Simple Folder

Simple Folder is a container of jobs. A Simple Folder does not enable configuration of job definitions at the folder level.

The following example shows how to use a simple folder.

In this example, jobs are defined under separate job objects that bear the name of each job. For an alternative array structure, see the examples provided for a folder and a subfolder.

Copy 
{
    "SimpleFolderName": {
        "Type": "SimpleFolder",
        "ControlmServer": "ec2-54-191-85-182",
        "job1": {
          "Type": "Job:Command",
          "Command": "echo 123",
          "RunAs": "controlm"
        },
        "job2": {
          "Type": "Job:Command",
          "Command": "echo 123",
          "RunAs": "controlm"
        },
        "Flow": {
          "Type": "Flow",
          "Sequence": ["job1", "job2"]
        }
    }
}

The following example shows optional parameters for SimpleFolder:

Copy 
{
    "FolderSampleAll": {
      "Type": "SimpleFolder",
      "ControlmServer": "controlm",
      "SiteStandard": "myStandards",
      "BusinessFields" : [ { "Department" : "HR" }, {"Company":"BMC"} ],
      "OrderMethod": "Manual"
    }
}

Parameter

Description

ControlmServer

Specifies a Control-M Scheduling Server. If more than one Control-M Scheduling Server is configured in the system, you must define the server that the folder belongs to.

SiteStandard

Enforces the defined Site Standard to the folder and all jobs contained within the folder. See Control-M in a nutshell.

BusinessFields

Values for the business fields of the specified Site Standard.

Enter this information as an array with the following format:

[ {BusinessField1_Name:value}, {BusinessField2_Name:value} ]

OrderMethod

Options are:

  • Automatic: The folder and its jobs are automatically ordered on days specified in the 'When' property.

  • Manual: The 'When' property is ignored. To order such a folder use the "ctm run order" API or Action Type:Run.

  • Any other value: See the description of the <user daily> method and other methods in Order Method in the Control-M Online Help.

Default: Automatic

Jobs

Defines the jobs within the simple folder in one of the following structures:

  • Under separate objects that bear the name of each job.

  • As an array under a Jobs object, with the option of including multiple jobs with the same name.

Flow

The Flow object type allows you to define order dependency between jobs in folders and sub-folders. A job must end successfully for the next job in the flow to run.

Copy 
{
    "flowName": {
        "Type":"Flow",
        "Sequence":["job1", "job2", "job3"]
    }
}

The following example shows how one job can be part of multiple flows. Job3 will execute if either Job1 or Job2 end successfully:

Copy 
{
    "FlowSamples" :
    {
        "Type" : "Folder", 
        "Job1": {
            "Type" : "Job:Command",
            "Command" : "echo hello",
            "RunAs" : "user1"
        },
        "Job2": {
            "Type" : "Job:Command",
            "Command" : "echo hello",
            "RunAs" : "user1"
        },
        "Job3": {
            "Type" : "Job:Command",
            "Command" : "echo hello",
            "RunAs" : "user1"
        },
        "flow1": {
            "Type":"Flow",
            "Sequence":["Job1", "Job3"]
        },
        "flow2": {
            "Type":"Flow",
            "Sequence":["Job2", "Job3"]
        }
    }
}

The following example shows how to create flow sequences with jobs contained within different folders and sub-folders:

Copy 
{
    "FolderA" :
    {
        "Type" : "Folder",
        "Job1": {
            "Type" : "Job:Command",
            "Command" : "echo hello",
            "RunAs" : "user1"
        }
    },
    "FolderB" :
    {
        "Type" : "Folder",
        "Job1": {
            "Type" : "Job:Command",
            "Command" : "echo hello",
            "RunAs" : "user1"
    },
        "SubFolderB1" : {
            "Type" : "sub-folder",
            "Job2": {
                "Type" : "Job:Command",
                "Command" : "echo hello again from subjob",
                "RunAs" : "user1"
            }
        }
    },
    "CrossFoldersFlowSample": {
        "Type":"Flow",
            "Sequence":["FolderA:Job1", "FolderB:Job1", "FolderB:sub-folderB1:Job2]
    }
}

The following example shows a flow defined within a sub-folder and referencing jobs within next-level sub-folders:

Copy 
{
    "FolderWithSubFoldersAndFlow":{
        "Type":"Folder",
        "SubFolderA":{
            "Type":"SubFolder",
            "SubFolder1":{
                "Type":"SubFolder",
                "job1": {
                    "Type": "Job:Script",
                    "FileName": "scriptname.sh",
                    "FilePath": "/home/user/scripts",
                    "RunAs": "em900cob"
                }
            },
            "SubFolder2":{
                "Type":"SubFolder",
                "job1": {
                    "Type": "Job:Script",
                    "FileName": "scriptname2.sh",
                    "FilePath": "/home/user/scripts",
                    "RunAs": "em900cob"
                }
            },
            "flowInsub-folderA": {
                "Type": "Flow",
                "Sequence": [
                "SubFolder1:job1",
                "SubFolder2:job1"
                ]
            }
        }
    }
}