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
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.
{
"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, you must set the allowDuplicateJobNames system setting to true.
{
"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:
{
"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 |
|---|---|
|
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:
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:
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 a Folder defined in one time zone, with a command job (defined within it) in a different time zone:
{
"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:
{
"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.
{
"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:
{
"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:
-
When — only the FromTime and ToTime parameters, as well as Using Rule-based Calendars in Job Scheduling
-
If statements with If Actions
-
AdjustEvents (a Folder property).
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.
{
"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:
{
"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:
{
"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:
{
"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"
]
}
}
}
}
YouTube
Twitter
Facebook
LinkedIn