Folder

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.

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

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

AdjustEvents	Whether a job in a folder or subfolder should run and not wait for events from an unscheduled predecessor job. For example, 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. Adjust Events enables Job C to run, and not wait for the events of Job B. Note: Adjust Event s is applied to the event s created within the folder. If a job waits for an event that is not created in the folder, the event is not adjust ed. Valid values: True: The successor job runs and does not wait for events from the unscheduled job. (Default) 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.
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: (Default) 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.
RunAs	The name of the user responsible for running the jobs in the folder or subfolder. For more details, see RunAs.
When	Defines scheduling for all jobs in the folder or subfolder, using various scheduling parameters or rule-based calendars. For more details, see When.
ActiveRetentionPolicy	The retention policy for jobs in the folder or subfolder, one of the following options: (Default) KeepAll: All jobs wait for the folder or subfolder to complete and are removed at the same time as the folder or subfolder. CleanEndedOK: Jobs in the folder or subfolder are removed automatically from the database.
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 are 0-99 (where 99 is forever). The default is 0.
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 subfolder. For more details, see Notification.
If	See If and If Actions for detailed information
Job	See Job for detailed information
Events	See Events for detailed information
Flow	See Flowfor detailed information

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

The following example shows description and time zone for the object Folder8.

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

_{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 regular 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"
           }
       }
   }
}

The following example shows a more complex hierarchy of subfolders, 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"
}
}
}
}
}

Note

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

Subfolders support the use of the following properties and parameters:

Application, SubApplication
When — only the FromTime and ToTime parameters, as well as rule-based calendars
Events
If statements with If Actions
AdjustEvents(a Folder property)
Confirm
DaysKeepActive
Description
Documentation
Lock resources
Notification
PathElement
Priority
RunAs
Time Zone
Variables

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.

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

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

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: (Default) 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.

_{Back to top}

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}

Folder

Regular Folder

SubFolder

Simple Folder

Flow

On this page