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",
       "mut1" : {
           "Type": "Resource:Mutex",
           "MutexType": "Exclusive"
       },
       "Notify1": {
           "Type": "Notify:ExecutionTime",
           "Criteria": "LessThan",
           "Value": "3",
           "Message": "Less than expected"
       }
   }
}

AdjustEvents

Whether a job in a folder or subfolder should start running and not wait for an event from a predecessor job that was not scheduled.

Values: true | false
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. 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:Mutex

See Resource:Mutex 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"
}
}
}
 }
}

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

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

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*