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

A 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",
         
        "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 this array format, you must set the allowDuplicateJobNames system setting to true.

Copy 
{
    "FolderSample": {
        "Type": "Folder",
        "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": "controlm",
        "SiteStandard": "myStandards",
        "BusinessFields" : [ { "Department" : "HR" }, {"Company":"BMC"} ],
        "OrderMethod": "Manual",
        "Application": "ApplicationName",
        "SubApplication" : "SubApplicationName",
        "RunAs" : "controlm",
        "When" : {
            "WeekDays": ["SUN"]
        },
        "ActiveRetentionPolicy": "KeepAll",
        "DaysKeepActiveIfNotOk" : "41",
        "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.

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

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.

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 the description and details for a Folder object named Folder8:

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.

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:

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"
                ]
            }
        }
    }
}