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 is a container of jobs that enables you to configure various settings such as scheduling, event management, adding resources, or adding notifications for a group of jobs, all at once. Folder-level definitions are inherited by the jobs or subfolders within the folder.

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

         "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. The job array format is available only if you set the allowDuplicateJobNames system setting to true, as described in System Settings reference.

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

{
    "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"]
        },
        "ActiveRetentionPolicy": "KeepAll",
        "DaysKeepActiveIfNotOk" : "41",
        "lock1" : {
            "Type": "Resource:Lock",
            "LockType": "Exclusive"
        },
        "Notify1": {
            "Type": "Notify:ExecutionTime",
            "Criteria": "LessThan",
            "Value": "3",
            "Message": "Less than expected"
        }
    }
}

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

• Application, SubApplication
• Confirm
• CreatedBy
• DaysKeepActive
• Description
• Documentation
• EndFolder
• Priority
• Rerun
• RerunLimit
• Variables

The following example shows the description and details for a Folder object named Folder8. 

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

_{Back to top}

SubFolder

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

The following example shows a folder that contains two subfolders with the most basic definitions:

{
    "FolderWithSubFolders":{
        "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. The job array format is available only if you set the allowDuplicateJobNames system setting to true, as described in System Settings reference.

{
    "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 subfolders, with scheduling properties:

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

Subfolders support the use of the following properties and parameters:

• Application, SubApplication
• When — only the FromTime and ToTime parameters, as well as rule-based calenders
• Events
• If statements with If Actions
• AdjustEvents (a Folder property)
• Confirm
• DaysKeepActive
• Description
• Documentation
• Jobs — either under separate objects that bear the name of each job, or as an array under a Jobs object
• Lock resources
• Notification
• PathElement
• Priority
• RunAs
• Variables

Flow

The Flow object type allows you to define order dependency between jobs in folders and subfolders. 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 subfolders.

{
    "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" : "SubFolder",
			"Job2": {
				"Type" : "Job:Command",
				"Command" : "echo hello again from subjob",
            	"RunAs" : "user1"  
        	}
		}
 	},    
    "CrossFoldersFlowSample": {
        "Type":"Flow",
          "Sequence":["FolderA:Job1", "FolderB:Job1", "FolderB:SubFolderB1:Job2]
    }
} 

The following example shows a flow defined within a subfolder and referencing jobs within next-level subfolders.

{  
  "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"
                  }
            },
            "flowInSubFolderA": {
                  "Type": "Flow",
                  "Sequence": [
                  "SubFolder1:job1",
                  "SubFolder2:job1"
                  ]
            }
        }
    }
}

_{Back to top}