Job Properties

Below is a list of job properties for Control-M objects.

Type

Defines the type of job. For example:

    "CommandJob1": {
        "Type" : "Job:Command",
        "Command" : "echo hello",
        "RunAs" : "user1"
        }

Many of the other properties that you include in the job's definitions depend on the type of job that you are running. For a list of supported job types and more information about the parameters that you use in each type of job, see Job types.

Application, SubApplication 

Supplies a common descriptive name to a set of related Jobs, Folders, or SubFolders. The jobs do not necessarily have to run at the same time.

    "Job1": {
	    "Type": "Job:Command",
 		"Application": "ApplicationName",
		"SubApplication": "SubApplicationName",
        "Command": "echo I am a Job",
        "RunAs": "controlm"
    }

Back to top

Comment

Allows you to write a comment on an object. Comments are not uploaded to Control-M.

    "JobName": {
        "Type" : "Job:Command",
        "Comment" : "code reviewed by tom",
        "Command" : "echo hello",
        "RunAs" : "user1"
        }

Back to top

When

Enables you to define scheduling parameters for Jobs, Folders and SubFolders, including the option of using calendars. If When is used in a Folder or SubFolder, those parameters apply to all Jobs in the Folder or Subfolder.

When working in a Control-M Workbench environment, jobs will not wait for time constants and will run in an ad-hoc manner. Once deployed to a Control-M instance, all time constraints will be obeyed. 

The following example defines scheduling based on a combination of date and time constraints:

      "When" : {
                "Schedule":"Never",
				"Months": ["JAN", "OCT", "DEC"],
                "MonthDays":["22","1","11"],
                "WeekDays":["MON","TUE"],
                "FromTime":"1500",
                "ToTime":"1800"      
            }

The following example defines scheduling based on specific dates that you specify explicitly:

      "When" : {
                "WeekDays" : [ "NONE" ],
                "Months" : [ "NONE" ],
                "MonthDays" : [ "NONE" ],
                "SpecificDates" : [ "03/01", "03/10" ],
                "FromTime":"1500",
                "ToTime":"1800" 
            }

The following date/time constraints are available for use in the definitions of a Job, Folder, or SubFolder:

OptionDescriptionJobFolderSubFolder
WeekDays

One or more of the following:

"SUN","MON","TUE","WED","THU","FRI","SAT"

For all days of the week, use "ALL" (the default value).

(tick)(tick)(error)
Month

One or more of the following:

"JAN", "FEB", "MAR", "APR","MAY","JUN", "JUL", "AUG",

"SEP", "OCT", "NOV", "DEC"

For all months of the year, use "ALL" (the default value).

(tick)(tick)(error)
MonthDays

One or more days in the range of 1 to 31

For all days of the month, use "ALL" (the default value).

(tick)(tick)(error)
FromTime

FromTime specifies that a job will not start before this time

Format: HHMM

(tick)(tick)(tick)
ToTime

ToTime specifies that a job will not start after this time

Format: HHMM

To allow the job to be submitted even after its original scheduling date (if it was not submitted on the original date), specify a value of ">".

(tick)(tick)(tick)
Schedule

One of the following options:

  • "Everyday" - scheduling is applied every day, provided that the running criteria are met
  • "Never" - no scheduling is defined, and the job must be ordered manually
(tick)(tick)(error)
SpecificDates

Specific dates for running jobs.

For each date, use the format "MM/DD" (enclosed in quotes). Separate multiple dates with commas.

Note: The SpecificDates option cannot be used in combination with options WeekDays, Month, or MonthDays.
However, since the default for these options is "ALL", you must specify these options with a value of "NONE".

(tick)(tick)(error)

MonthDay additional parameters 

You can specify the days of the month the job will run by referencing a predefined calendar set up in Control-M. 

"When": {
	"MonthDaysCalendar": “Summer2017”
}

You can specify the days of the month the job will run by referencing a predefined calendar set up in Control-M, and also using advanced rules specified in the MonthDays parameter:

"When": {
	"MonthDaysCalendar": “Summer2017”,
    “MonthDays":[“1”,”+2”,”-3”,”>4”,”<5”,”D6”,”L7”]
}

Where:

MonthDays syntax

Description

1

Day 1 included only if defined in the calendar
+2Day 2 included regardless of calendar
-3Day 3 excluded regardless of calendar
>4Day 4 or next closest calendar working day
<5Day 5 or previous closest calendar working day
D6The 6th calendar working day
L7The 7th from the last calendar working day
D6PA or D6P*

If MonthDaysCalendar is of type periodical, you can use PA or P* to specify a calendar period name such as A,B,C, or you can use * for any period.

-D6 or -L6P* D and L can also have an exclude specifier

WeekDays additional parameters 

You can specify the days of the week that the job will run by referencing a predefined calendar set up in Control-M, and also using advanced rules specified in the WeekDays parameter:

"When" : {
	"WeekDaysCalendar" : "Summer2017",
	"WeekDays" : ["SUN","+MON","-TUE",">WED","<THU"]
}

Where:

WeekDays syntaxDescription

SUN

Sunday included only if defined in the calendar

+MONMonday included regardless of calendar
-TUETuesday excluded regardless of calendar
>WEDWednesday or next closest calendar working day
<THUThursday or previous closest calendar working day

Specifying a period when a job can or cannot run

In addition to the other date/time elements, you can define a range of dates when a job can or cannot run.

The following example shows a period of time (that is, a range of dates) when the job can run:

 "When": { 
            "StartDate":"20160322", 
            "EndDate":"20160325" 
         }

The following example shows a period of time when the job CANNOT run:

 "When": { 
            "StartDate":"20160322", 
            "EndDate":"20160325", 
            "ActivePeriod" :false
         }

Where:

StartDate

Start date for the period when the job can/cannot run

EndDate

End date for the period when the job can/cannot run

ActivePeriod

Whether the defined period is a period of activity or inactivity, with the following values:

  • true — Period of activity, when the job CAN run. The default.
  • false — Period of inactivity, when the job CANNOT run.

Relationship between MonthDays and WeekDays

"When" : {
    "Months": ["JAN", "OCT", "DEC"], 
	"MonthDays":["22","1","11"],
	“DaysRelation” : “OR”,
    "WeekDays":["MON","TUE"]
}


ParameterDescription
DaysRelation

Default: AND

AND - the job will run only if the WeekDays and MonthDays contraints are met

OR - the job will run if the WeekDays or MonthDays constraints are met

Specifying a Confirmation calendar

You can specify a predefined Confirmation calendar to use for validation of scheduling dates and you can indicate how to handle jobs that are scheduled for a non-working day in this calendar.

The following example shows how to specify a Confirmation calendar:

{
    "Folder1": {
              "Type": "Folder",
              "ControlmServer": "LocalControlM",
              "Application": "Billing",
              "job1": {
                  "Type": "Job:Command",
                  "Application": "BillingJobs",
                  "RunAs": "control ",
                  "Command": "ls",
                  "When": {
                      "ConfirmationCalendars": {
                          "Calendar": "Holidays",
                          "ExceptionPolicy": "OrderOnNextConfirmedDay",
                          "ShiftBy": "1"
                      }
                  }
              }
      }
}

The following parameters appear under the ConfirmationCalendars object:

Calendar

The name of the predefined Confirmation calendar, in which work days are indicated

ExceptionPolicy

A policy to follow when a job is scheduled on a non-working day. Choose from one of the following options:

  • DoNotOrder
  • OrderOnNextConfirmedDay
  • OrderOnPreviousConfirmedDay
  • OrderAnyway

The default is DoNotOrder.

ShiftBy

The number of additional confirmed days to move the job, beyond the action specified by the exception policy. Specify one of the following:

  • A positive number of additional days to move forward when the exception policy is OrderOnNextConfirmedDay
  • A negative number of additional days to move backward when the exception policy is OrderOnPreviousConfirmedDay

The default value is 0.

Using rule-based calendars in job scheduling

You can base scheduling on predefined rule-based calendars (RBC). Under the When parameter for a specific Job, Folder, or SubFolder, you can specify the RBCs to include and the RBCs to exclude from scheduling. For more information, see Rule-based Calendar and Excluded Rule-based Calendar lists in the Control-M Online Help.

"RuleBasedCalJobSimple" : {
  "Type" : "Job:Command",
  "RunAs" : "controlm",
  "Command" : "ls -l",
  "When" : {
	"RuleBasedCalendars":{
		"Included": ["calendar1"],
		"Excluded": ["calendar2"]
	}
  }
}        

You can combine the use of rule-based calendars with standard scheduling parameters. In such a case, the Relationship parameter enables you to define the logical relationship (AND/OR) between the criteria defined by the calendars and all other basic scheduling criteria. In other words, you can decide whether either set of criteria, or both sets of criteria, must be satisfied. The default relationship is OR.

"RuleBasedCalJobComplex" : {
  "Type" : "Job:Command",
  "RunAs" : "controlm",
  "Command" : "ls -l",
  "When" : {
	"RuleBasedCalendars":{
		"Included": ["weekdays"],
		"Excluded": ["endOfQuarter"],
		"Relationship": "AND"
	},
	"Months":["JAN","FEB","MAR"],
	"WeekDays":["TUE","WED"]
  }
 }

Rule-based calendars can also be used with SubFolders. In the following example, two different SubFolders are defined in the parent folder. For one of these SubFolders, RBCs to include and exclude are explicitly specified. These RBCs are either global or from the parent folder. For the other SubFolder, the "USE PARENT" value is specified instead of the name of an actual RBC, so that all scheduling is inherited from the parent folder (as defined in the next example).

{
    "subF1" : {
		"Type" : "SubFolder",
		"When" : {
			"FromTime":"1211",
			"ToTime":"2211",
			"RuleBasedCalendars" : {
				"Included" : [ "calendar1" ],
				"Excluded" : [ "calendar2" ]
			}
		}
	},
	"subF2" : {
		"Type" : "SubFolder",
		"When" : {
			"RuleBasedCalendars" : {
				"Included" : [ "USE PARENT" ]
			}
		}
	}
}

For folders, you can define Folder RBCs in addition to using predefined RBCs or other basic scheduling criteria. Folder RBCs are specific to a single folder and are applied to all jobs within the folder. The following example shows how to define RBCs under the folder's When parameter:

{
 "RuleBasedTestFolder": {
	"Type": "Folder",
	"ControlmServer": "LocalControlM",
	"When": {
		"RuleBasedCalendars": {
			"endOfQ":{
				"Type": "Calendar:RuleBased",
				"When": {
					"Months": ["MAR","JUN","SEP","DEC"],
					"MonthDays": ["29","30","31"]
				}
			},
			"winterWeekendDays": {
				"Type": "Calendar:RuleBased",
				"When": {
					"Months": ["DEC","JAN","FEB"],
					"WeekDays": ["SAT","SUN"]
				}
			},
			"Included": ["winterWeekendDays","calendar1"],
			"Excluded": ["endOfQ"]
		},
		"Months": ["APR"],
		"WeekDays": ["FRI","MON"]
	},
	"TestJobInTestFolder": {
		"Type": "Job:Command",
		"RunAs": "controlm",
		"Command": "ls -l",
		"When": {
			"RuleBasedCalendars": {
				"Included": ["calendar3"],
				"Excluded": ["calendar2"]
			}
		}
	}	
  }
}

Note the following guidelines:

  • Each Folder RBC that you define has its own When parameter, with scheduling parameters under it. The scheduling parameters under this When parameter are similar to the scheduling parameters under a When parameter of a job or folder, with the following exceptions:
    • The When parameter of an RBC does not support the FromTime and ToTime parameters.
    • For the When parameter of an RBC, you can also use the DaysKeepActive parameter.
    • You cannot nest another RuleBasedCalendars parameter under the When parameter of an RBC.
  • To apply the defined Folder RBCs to the jobs within the folder, you must list each of the defined Folder RBCs in either the Included parameter or the Excluded parameter.
  • You can list additional predefined Control-M RBCs in the Included and Excluded parameters. In the example above, a predefined RBC named calendar1 is listed along with the Folder RBC winterWeekendDays.
  • You can combine the use of RBCs with other scheduling parameters. In the example above, the additional Months and WeekDays settings were added after the RuleBasedCalendars definitions. These further scheduling parameters are combined with the RBCs based on a logical AND.
  • The folder's scheduling parameters are inherited by each of the jobs in the folder. In addition, for any specific job in the folder, you can add further scheduling parameters or RBCs. In the example above, further RBCs (calendar3 and calendar2) are associated with a job named TestJobInTestFolder.

Back to top

Events

Events can be generated by Control-M or can trigger jobs. Events are defined by a name and a date.

Here is a list of the various capabilities of event usages:

  1. A job can wait for events before running, add events after running, or delete events after running. See WaitForEvents, AddEvents, and DeleteEvents
  2. Jobs can add or remove events from Control-M. See Event:Add or Event:Delete.
  3. You can add or remove events from the Control-M by an API call. See Event Management.

You can set events for a Job, Folder, or SubFolder.

For "OrderDate", you can use the following values:

Date Type

Description
AnyDateAny scheduled date
OrderDate

Control-M scheduled date.

If you do not specify an OrderDate value, this is the default.

PreviousOrderDatePrevious Control-M scheduled date
NextOrderDateNext Control-M scheduled date
MMDD

Specific date

Example: "0511"

WaitForEvents

The following example shows how to define events that the job must wait for before running:

"Wait1": {
          "Type": "WaitForEvents",
          "Events": [
              {"Event":"e1"}, 
              {"Event":"e2"}, 
              {"Event":"e3", "OrderDate":"AnyDate"}
          ]
}

You can specify the logical relationship between events, using logical operators (AND/OR) and parentheses. The default relationship is AND. Note that nesting of parentheses within parentheses is not supported.

"Wait2": {
           "Type": "WaitForEvents",
           "Events": [
               "(",
               {"Event":"ev1"},
               "OR",
               {"Event":"ev2"},
               ")",
               "OR",
               "(",
               {"Event":"ev3"},
               {"Event":"ev4"},
               ")"
            ]
}

AddEvents

The following example shows how to specify events for the job to add after running:

"add1" :
{
          "Type": "AddEvents",
          "Events": [
              {"Event":"a1"}, 
              {"Event":"a2"}, 
              {"Event":"a3", "OrderDate":"1112"}
          ]
}

DeleteEvents

The following example shows how to specify events for the job to remove after running:

"del1" :
{
          "Type": "DeleteEvents",
          "Events": [
              {"Event":"d1"},
              {"Event":"d2", "OrderDate":"1111"},
              {"Event":"d3"}
          ]
}

Back to top

If

If statements trigger one or more actions when job-related criteria are fulfilled (for example, the job ended with a specific status or the job failed several times).

The following If statements are available for specifying job-related criteria that must occur for action to be taken:

For descriptions of the various actions that can be triggered in response to an If statement that is fulfilled, see If Actions.

If:CompletionStatus

The following example shows an If statement that triggers actions based on job completion status. In this example, if the job runs unsuccessfully, it sends an email and runs another job. You can set this property for a Job, Folder, or SubFolder.

    "JobName": {
        "Type" : "Job:Command",
        "Command" : "echo hello",
        "Host" : "myhost.mycomp.com",
        "RunAs" : "user1",  
        
        "ActionIfFailure" : {
            "Type": "If",        
            "CompletionStatus": "NOTOK",
            
            "mailToTeam": {
              "Type": "Action:Mail",
              "Message": "Job %%JOBNAME failed",
              "To": "team@mycomp.com"
            },
            "CorrectiveJob": {
              "Type": "Action:Run",
              "Folder": "FolderName",
              "Job": "JobName"
            }
        }
    }

If can be triggered based on one of the following CompletionStatus values:

ValueAction

NOTOK

When job fails

OK

When job completed successfully

ANY

When the job completed regardless of success or failure

value

When completion status = value

Example: value=10

EvenWhen completion status is an even number
OddWhen completion status is an odd number
">=5", "<=5", "<5", ">5", "!=5"When the completion status comparison operator is true

If:NumberOfReruns

The following example shows how to trigger an action based on number of job reruns. You can set this property for a Job, Folder, or SubFolder.

"ActionByNumberOfReruns" : {
	"Type": "If:NumberOfReruns", 
	"NumberOfReruns": ">=4",
    "RunJob": {
    	 "Type": "Action:Run",
   		 "Folder": "Folder1",
   		 "Job": "job1"
	}
}

Where:

ParameterDescriptionPossible values
NumberOfRerunsPerforms an action if the condition of number of job reruns is met.

"Even"

"Odd"

"!=value"

">=v alue"

"<=v alue"

">v alue"

"<v alue"

"value"

If:NumberOfFailures

The following example shows how to trigger an action based on number of job failures. You can set this property for a Job, Folder, or SubFolder.

"ActionByNumberOfFailures" : {
	"Type": "If:NumberOfFailures", 
	"NumberOfFailures": "1",
    "RunJob": {
          "Type": "Action:Run",
          "Folder": "Folder1",
          "Job": "job1"   
    }
}

Where:

ParameterDescriptionPossible values
NumberOfFailuresPerforms an action if the condition of number of job failures is met

"value"

If:JobNotSubmitted

The following example shows how to trigger an action based on whether the job is not submitted.

"ActionByJobNotSubmitted" : {
	"Type": "If:JobNotSubmitted"
    "RunJob": {
          "Type": "Action:Run",
          "Folder": "Folder1",
          "Job": "job1"   
    }
}

If:JobOutputNotFound

The following example shows how to trigger an action based on whether the job output is not found.

"ActionByOutputNotFound" : {
	"Type": "If:JobOutputNotFound"
    "RunJob": {
          "Type": "Action:Run",
          "Folder": "Folder1",
          "Job": "job1"   
    }
}

If:NumberOfExecutions

The following example shows how to trigger an action based on number of job executions. You can set this property for a Job, Folder, or SubFolder.

"ActionByNumberExecutions" : {
	"Type": "If:NumberOfExecutions", 
	"NumberOfExecutions": ">=5"
    "RunJob": {
          "Type": "Action:Run",
          "Folder": "Folder1",
          "Job": "job1"   
    }
}

Where:

ParameterDescriptionPossible values
NumberOfExecutionsPerforms an action if the condition of number of job executions is met

"Even"

"Odd"

"!=value"

">=value"

"<=value"

">value"

"<value"

"value"

If:Output

The following example shows how to trigger an action based on whether a specified string is found within the job output. You can set this property for a Job, Folder, or SubFolder.

"OutputFound":{
    "Type": "If:Output",
    "Code": "myfile.sh",
    "Statement": "ls -l",
    "RunJob":{
          "Type":"Action:Run",
          "Folder":"Folder1",
          "Job":"job1"
    }
}

Where:

ParameterDescription
Code

The string to search for in the output.

You can include wildcards in the code — * for any number of characters, and $ or ? for any single character.

Statement

(Optional) Limits the search to a specific statement within the output. If no statement is specified, all statements in the output are searched.

You can include wildcards in the statement — * for any number of characters, and $ or ? for any single character.

Back to top

If Actions

The following actions can be triggered in response to an If statement that is fulfilled:

You can set any of these properties for a Job, Folder, or SubFolder.

For descriptions of the various If statements that you can specify to trigger these actions, see If.

Action:Mail 

 The following example shows an action that sends an e-mail.

    "mailToTeam": {
      "Type": "Action:Mail",
      "Message": "%%JOBNAME failed",
      "To": "team@mycomp.com"
    }

The following example shows that you can add optional parameters to the email action.

    "mailToTeam": {
      "Type": "Action:Mail",
      "Urgency": "Urgent", 
      "Subject" : "Completion Email",
      "Message": "%%JOBNAME just completed", 
      "To": "team@mycomp.com",
      "CC": "other@mycomp.com",
      "AttachOutput": true
 }

The following table describes the parameters of the email action:

ParameterDescription
UrgencyLevel of urgency of the message — Regular, Urgent, or VeryUrgent. The default is Regular.
SubjectA subject line for the message.
MessageThe message text.
To

A list of email recipients to whom the message is directed.

Use the semicolon (;) to separate multiple email addresses.

CC

A list of email recipients who receive a copy of the message.

Use the semicolon (;) to separate multiple email addresses.

AttachOutput

Whether to include the job output as an email attachment, either true or false.

If no value is specified, the default follows the configuration of the Control-M/Server.

Action:Rerun

The following example shows an action that reruns the job.

"RerunActionName": {
      "Type": "Action:Rerun"  
}

Action:Set

The following example shows an action that sets a variable.

"SetVariable": {
   "Type": "Action:Set",
    "Variable": "var1",
    "Value": "1"
}

Action:SetToOK

The following example shows an action that sets the job status to OK.

"SetToOKActionName": {
      "Type": "Action:SetToOK"
}

Action:SetToNotOK

The following example shows an action that sets the job status to not OK.

"SetToNotOKActionName": {
      "Type": "Action:SetToNotOK"
}

Action:StopCyclicRun

The following example shows an action that disables the cyclic attribute of the job.

"CyclicRunActionName": {
      "Type": "Action:StopCyclicRun"
}

Action:Run

The following example shows an action that runs another job.

"CorrectiveJob": {
        "Type": "Action:Run",
        "Folder": "FolderName",
        "Job": "JobName",
        "ControlmServer":"RemoteControlM",
        "Date":"010218",
        "Variables":[{"Cvar1":"val1"}, {"Cvar2":"val2"}]
}

The run action has the following optional properties:

PropertyDescription
ControlmServer

The Control-M Scheduling Server for the run action.

By default, the Control-M Scheduling Server for the run action is the same as defined for the folder.

You can use this property to specify a different, remote server.

Date

Value to be used as the original scheduling date for the job.

The default is OrderDate (that is, the Control-M scheduled date).

For any other date, specify the date in the relevant 4-character or 6-character format mmdd, ddmm, yymmdd, or yyddmm, depending on the site standard.

VariablesIf the run action is defined for a remote Control-M Scheduling server, you can define variables for the run action.

Action:Notify

The following example shows an action that sends a notification.

"Notifying": {
   "Type": "Action:Notify",
   "Message": "job1 just ran",
   "Destination": "JobLog",
   "Urgency": "VeryUrgent"
}

Event:Add

The following example shows an action that adds an event for the current date.

"setEvent1": {
    "Type": "Event:Add",
    "Event": "e1"
}

Optional parameters:

"setEvent1": {
    "Type": "Event:Add",
    "Event": "e1",
    "OrderDate": "1010"
}
Date TypeDescription
AnyDateAny scheduled date
NoDateNot date-specific
OrderDateControl-M scheduled date.
PreviousOrderDatePrevious Control-M scheduled date
NextOrderDateNext Control-M scheduled date
MMDD

Specific date

Example: "0511"

Event:Delete

The following example shows an action that deletes an event.

OrderDate possible values:

  • "AnyDate"
  • "OrderDate"
  • "PreviousOrderDate"
  • "NextOrderDate"
  • "0511" - (MMDD) 
"unsetEvent2": {
    "Type": "Event:Delete",
    "Event": "e2",
    "OrderDate": "PreviousOrderDate"
}

Action:Output

The Output action supports the following operations:

  • Copy
  • Move
  • Delete
  • Print

The following example shows an action that copies the output to the specified destination.

"CopyOutput": {
         "Type": "Action:Output",
         "Operation": "Copy",
         "Destination": "/home/copyHere"
}

Action:CaptureOutput

The CaptureOutput action enables you to search job output and capture text from the job output into a variable.

The following example shows an action that captures text when the string "failure" is discovered in the output. In this example, the capture operation starts only 5 lines and 1 word later.

"CaptureOutput" : {
    "Type" : "Action:CaptureOutput",
    "Capture" : "10",
    "Search" : "failure",
    "VariableName" : "myVar",
    "ForwardBy" : {
        "Columns" : "1",  
        "Delimiter" : "Tab",   
        "Lines" : "5",   
        "ColumnsOption" : "Words"
    }
} 

The CaptureOutput action has the following properties:

PropertyDescription
Capture

The scope of what to capture from job output and store in a variable:

  • Number of words or characters
  • UpToEndOfLine — All the words or characters up to the end of the line

The default is 1 (word or character, depending on the value of ColumnsOption).

SearchThe string to search for in the job output sysout after job processing
VariableNameName of a variable in which to store captured text
ForwardByInstructions for skipping ahead (from the point in the output where the search string was detected) before beginning the capture operation
   Columns

The number of words or characters to skip in job output for the capture operation.

If Lines=0, the count of columns to skip starts from the end of the search string. Otherwise, the count of columns to skip starts at the beginning of the line.

The default is 0.

   Delimiter

The delimiter character to use as a split separator between words in job output for the capture operation, one of the following:

  • WhiteSpace (default) — either space or tab
  • Space
  • Tab
  • Any other single character that you specify

A delimiter is relevant only if ColumnsOption is set to words.

   Lines

The number of lines to skip from the search string in the job output for the capture operation

The default is 0.

   ColumnsOptionThe unit to use for column skipping, either words (the default) or characters

Back to top

Confirm

Allows you to define a job, folder, or subfolder that requires user confirmation. This can be done by running the run confirm command.

 "JobName": {
        "Type" : "Job:Command",
        "Comment" : "this job needs user confirmation to start execution",
        "Command" : "echo hello",
        "RunAs" : "user1",
		"Confirm" : true
        }

Back to top

CreatedBy

Allows you to specify the Control‑M user responsible for job definitions. You can define this property for a Job object or Folder object.

    "SimpleJob": {
        "Type": "Job:Command",
        "Command": "echo I am a Job.",
        "RunAs": "controlm",
        "CreatedBy":"username"
    }

The behavior of this property depends on the security policy defined in the Control-M environment, as controlled by the AuthorSecurity parameter in Control-M/Enterprise Manager:

Security levelAllowed valuesDefault value
PermissiveAny user namectmdk (an internal user)
RestrictiveUser currently logged inUser currently logged in


Back to top

Critical

Allows you to set a critical job. A critical job is a job that has a higher priority to reserve resources in order to run.

Default: false

"Critical": true

Back to top

DaysKeepActive

Allows you to define the number of days to keep a job if the job did not run at its scheduled date. You can set this property for a Job, Folder, or SubFolder.

Jobs in a folder are kept until the maximum DaysKeepActive value for any of the jobs in the folder has passed. This enables you to retrieve job status of all the jobs in the folder. 

{
  "DaysKeepActiveFolder": {
       "Type" : "Folder",
       "Defaults": {
         "RunAs":"owner8" 
       },
       "keepForeverIfDidNotRun": { 
         "Type": "Job:Command", 
         "Command":"ls",
         "DaysKeepActive": "Forever" 
       },
       "keepForThreeDaysIfDidNotRun": { 
         "Type": "Job:Command", 
         "Command":"ls",
         "DaysKeepActive": "3" 
       }
  }
}

Where:

DaysKeepActive

Valid values:

  • 0-98
  • Forever

Default: 0

Back to top

Description

Enables you to add a description to a Job, Folder, or SubFolder.

{
 "DescriptionFolder":
   {
       "Type" : "Folder",
       "Description":"folder description",
       "SimpleCommandJob": { 
         "Type": "Job:Command", 
         "Description":"job description",
         "RunAs":"owner8", 
         "Command":"ls"
       }   
    }
}

Back to top

Documentation

Allows you to add the location and name of a file that contains the documentation for the Job, Folder, or SubFolder.

{
 "DocumentationFile":{
	"Path": "C://temp",
	"FileName": "job.txt"
  }
}

Allows you to add the URL location of a file that contains the documentation for the Job, Folder, or SubFolder.

{
 "DocumentationUrl":{
	"Url": "http://bmc.com"
  }
}

Back to top

EndFolder

Enables you to specify which job is the end point in a folder. After this job completes, no additional jobs in the folder will run, unless they have already started running. The folder is complete once all jobs that are still running complete. Remaining jobs that have not yet started running change to status WAIT SCHEDULE.

Values: true | false
Default: false

{
  "EndFolder": {
        "Type": "Folder",
        "EndFolderJob": {
            "Type": "Job:Command",
            "Command": "echo When this job ends, the folder is complete",
            "RunAs": "controlm",
            "EndFolder": true
        }
    }
}

Back to top

Notification

Allows you to create a notification for certain scenarios before, during and after job execution. You can set notifications for a Job, Folder, or SubFolder.

This example shows a notification sent to JobLog of critical job failure.

"NotifyCriticalJobFailure": {
   "Type":"Notify:NotOK",
   "Message": "Critical job failed, details in job output",
   "Urgency": "Urgent",
   "Destination": "JobLog"
}

The following parameters are relevant to all notification types.

Parameters

Description
MessageThe message to display

Destination

(description for each of the options)

The message is sent to one of the following:

  • (Default) Alerts - Control-M Alerts window
  • JobLog - writes to Control-M job log , to get the job log use the run job:log::get
  • Console - operating system console

Or

Predefined destination values (for example, FinanceGroup)

Urgency

The message urgency is logged as one of the following:

  • (Default) Regular
  • Urgent
  • VeryUrgent

Notify:OK

When setting the notification type to OK, if job executed with no errors, the notification "Job run OK" is sent to the JobLog. 

{
  "Folder1": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "user1", 
	  "Notify1": {
        "Type": "Notify:OK",
        "Message": "Job run OK",
        "Destination": "JobLog"
 	  }
	}
  }
}	

Notify:NotOK

When setting the notification type to NotOK, if job executed with errors, the notification "Job run not OK" is sent to the JobLog. 

{
 "Folder1": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "user1", 
	  "Notify1": {
        "Type": "Notify:NotOK",
        "Message": "Job run not OK",
        "Destination": "JobLog"
 	  }
	}
  }
}	

Notify:DoesNotStart

If the job has not started by 15:10, a notification is immediately sent to the email defined in the job with the message that the job has not started.

{
"Folder1": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "user1",
	  "Notify3": {
        "Type": "Notify:DoesNotStart",
        "By": "1510",
        "Message": "Job has not started",
        "Destination": "mail",
        "Urgency": "VeryUrgent"
	    }
	}
  }
}	

Parameters

Description
By

Format: HHMM  

Notification sent when job does not start by specified time

Notify:ExecutionTime

When setting the notification type ExecutionTime to LessThan, if the job completes in less than 3 minutes, the notification "Less than expected" is sent to the Alert destination. 

{
  "Folder1": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "user1",
      "Notify1": {
        "Type": "Notify:ExecutionTime",
        "Criteria": "LessThan",
        "Value": "3",
        "Message": "Less than expected"
      }
	}
  }
}

Criteria

ValueDescription
LessThan

Value in minutes

Example: 3

If the job runs less than the defined value, a notification is sent to the defined destination

GreaterThan

Value in minutes

Example: 5

If the job runs longer than the defined value, a notification is sent to the defined destination

LessThanAverage

Value in minutes or percentage

Example: 10%

If the job runs less than the defined value of the average execution time of the job, a notification is sent to the defined destination
GreaterThanAverage

Value in minutes or percentage

Example: 10%

If the job runs longer than the defined value of the average execution time of the job, a notification is sent to the defined destination

Notify:DoesNotEnd

When setting the notification type DoesNotEnd, if job does not end by the specified time, message is sent to JobLog.

{
  "Folder1": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "user1",
      "Notify1": {
        "Type": "Notify:DoesNotEnd",
        "By": "1212",
		"Message": "Job does not end",	
		"Destination": "JobLog"
      }
	}
  }
}

Parameters

Description
By

Format: HHMM  

Notification sent when job does not end by specified time

Notify:ReRun 

When setting the notification type ReRun, when job reruns, message is sent to console.

{
  "Folder1": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "user1",
      "Notify1": {
        "Type": "Notify:ReRun",
		"Message": "Job5 ReRun",	
		"Destination": "Console"
      }
	}
  }
}

Back to top

OverridePath

Enables you to specify an alternative location for a script file without changing the original script file that you specified for a job of type Job:Script using the FileName and FilePath properties. The alternative script file in the alternative location must have the same name as the original job script file, in order for it to run instead of the original job script file. This is especially useful for troubleshooting purposes or during development of a new release.

The following example demonstrates the use of the OverridePath property:

"JobName": {
    "Type": "Job:Script",
    "FileName": "task1123.sh",
    "FilePath": "/home/user1/scripts",
    "Host": "myhost.mycomp.com",
    "RunAs": "user1",
    "Priority": "XB",
    "OverridePath":"/usr/lib/overridepath" ,
    "RunAsDummy": true
}


Back to top

Priority

Allows you to define the priority that a job has over other jobs. You can set this property for a Job, Folder, or SubFolder.

The following options are supported:

  • Very High

  • High

  • Medium

  • Low

  • Very Low (default)

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

Back to top

Rerun

Allows to define cyclic jobs or folders.

The example shows how to define a cyclic job or folder that runs every 2 minutes indefinitely.

    "Rerun" : {
        "Every": "2"
    }

The following example shows how to run a job or folder four times where each run starts three days after the previous run ended.

    "Rerun" : {
        "Every": "3",
        "Units":  "Days",                     
        "From": "End",                               
        "Times": "4"
    }

Units

One of the following: "Minutes" "Hours" or "Days". The default is "Minutes"

From

One of the following values:

  • Start - next run time is calculated an N Units from the start time of the current run
  • End - next run time is calculated as N Units from the end time of current run
  • Target - run starts every N units

The default is "Start".

Times

Number of cycles to run. To run forever, define 0

The default is run forever.

Back to top

RerunIntervals

Allows to define a set of time intervals for rerun of:

  • Jobs
  • 9.0.19.110 Folders

The example shows how to define Rerunintervals for the job to run every 12 months, 12 days, 11 hours and 1 minute from the end of the last job run.

"RerunIntervals": {
           "Intervals" : ["12m","11h","12d","1m"],
           "From": "End"
       }

Intervals

The time intervals for job or folder to run again in months, hours, days and minutes

From

One of the following values:

  • Start - next run time is calculated an N Units from the start time of the current run
  • End - next run time is calculated as N Units from the end time of current run
  • Target - run start every N units

The default is "Start".

Back to top

RerunSpecificTimes

Allows to define specific times at which to rerun:

  • Jobs
  • 9.0.19.110 Folders

The following example shows how to define RerunSpecificTimes to run at those specific times. 

"RerunSpecificTimes": {
        "At" : ["0900","1100","1230","1710"],
        "Tolerance": "20"
   }

At

One or more time of day in the format HHMM

Tolerance

Maximum delay in minutes permitted for a late submission of a specific time

Back to top

RerunLimit

Allows you to set a limit to the number of times a non-cyclic job or folder can rerun.

The following example shows the use of this property for a job:

"jobWithRerunLimit": {
        "Type":"Job:Command",
		"Command":"ls",
		"RunAs":"user1",
		"RerunLimit": {
			"Times":"5"
		}
     }

The following example shows the use of this property for a folder:

{
 "FolderWithRerunLimit": {
    "Type": "Folder",
    "RerunLimit": {
      "Times": "5"
    }
  }
}


Times

Maximum number of times a non-cyclic job or folder can rerun

Default 0, no limit to the number of reruns.

Back to top

Resources 

Resource:Semaphore

Allows you to set the Semaphore (also known as quantitative resourcesquantity to the job, used to control access to a resource that is concurrently shared by other jobs. For API command information on resources, see Resource Management.

The following example shows how to add a semaphore parameter to a job. 

{
  "FolderRes": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls",
      "RunAs": "pok",
      "Critical": true,
      "sem1": {
        "Type": "Resource:Semaphore",
        "Quantity": "3"
      }      
    }
  }
}

Resource:Mutex

Allows you to set a Mutex (also known as control resource) as shared or exclusive. If the resource is shared, other jobs can use the resource concurrently. If set to exclusive, the job has to wait until the resource is available before it can run. You can set a Mutex for a Job, Folder, or SubFolder.

The following example shows how to add a Mutex parameter to a job.

{
  "FolderRes": {
    "Type": "Folder",
    "job1": {
      "Type": "Job:Command",
      "Command": "ls", 
      "RunAs": "pok",
      "Critical": true,
      "mut1": {
        "Type": "Resource:Mutex",
        "MutexType": "Exclusive"
      }
    }
  }
}

Back to top

RetroactiveJob

Enables you to order a job retroactively to make up for days on which the job did not run. For example, Control-M was down for two days due to a hardware issue; as soon as jobs can run again, this job is scheduled retroactively to run an additional two times, to make up for the days that Control-M was inactive.

Values: true | false
Default: false

"RetroactiveJob": {
            "Type": "Job:Command",
            "Command": "echo I am a retroactive order Job, I will be ordered even after my date",
            "RunAs": "controlm",
            "RetroactiveOrder": true
        }

Back to top

RunAs

Enables you to define the OS user responsible for running a job (or all jobs in a folder or subfolder).

By default, jobs are run by the user account where the Control-M/Agent is installed. To specify a diferent user, the agent must be running as root.

	"Job1": {
		"Type": "Job:Command",
		"Command": "echo I am a Job",
		"RunAs": "controlm",
	}

Back to top

RunAsDummy

Enables you to run a job of any type (other than Dummy) as a dummy job.

This is useful, for example, when a job is temporarily not in use but is still included in a flow. You can temporarily set this job to run as a dummy job, so that there is no impact to the flow.

Values: true | false
Default: false

	"Job1": {
		"Type": "Job:Command",
		"Command": "echo I am a Job",
		"RunAs": "controlm",
		"RunAsDummy": true
    }

Back to top

RunOnAllAgentsInGroup

Allows you to set jobs to run on all agents in the group. 

The example shows how to define RunOnAllAgentsInGroup 

"jobOnAllAagents": {
         "Type": "Job:Dummy",
         "RunOnAllAgentsInGroup" : true,
         "Host" : "dummyHost"
       } 

RunOnAllAgentsInGroup

true | false

Default: false

Back to top

Time Zone

Allows you to add the time zone to jobs, folder, or subfolder. Time zones should be defined at least 48 hours before the intended execution date. We recommend to define the same time zone for all jobs in a folder. 

"TimeZone":"MST"

Time zone possible values:

HNL (GMT-10:00)
HAW (GMT-10:00)
ANC (GMT-09:00)
PST (GMT-08:00)
MST (GMT-07:00)
CST (GMT-06:00)
EST (GMT-05:00)
ATL (GMT-04:00)
RIO (GMT-03:00)
GMT (GMT+00:00)
WET (GMT+01:00)
CET (GMT+02:00)
EET (GMT+03:00)
DXB (GMT+04:00)
KHI (GMT+05:00)
DAC (GMT+06:00)
BKK (GMT+07:00)
HKG (GMT+08:00)
TYO (GMT+09:00)
TOK (GMT+09:00)
SYD (GMT+10:00)
MEL (GMT+10:00)
NOU (GMT+11:00)
AKL (GMT+12:00)

Back to top

Variables

Allows you to use job level variables with %% notation in job fields. You can set this property for a Job, Folder, or SubFolder.

"job1": {
     "Type": "Job:Script",

     "FileName": "scriptname.sh",
     "FilePath":"%%ScriptsPath",
     "RunAs": "em900cob",

     "Arguments":["--date", "%%TodayDate" ],

     "Variables": [
       {"TodayDate": "%%$DATE"},
       {"ScriptsPath": "/home/em900cob"}
     ]
 }

For specifications of system defined variables such as %%$DATE see Control-M system variables in the Control-M Online Help.

Named pools of variables can share data between jobs using the syntax "\\poolname\variable". NOTE that due to JSON character escaping, each backslash in the pool name must be doubled. For example, "\\\\pool1\\date".

        "job1": {
           "Type": "Job:Dummy",
	       "Variables": [

	         {"\\\\pool1\\date": "%%$DATE"}
	       ]
	    },
 
        "job2": {
           "Type": "Job:Script",

           "FileName": "scriptname.sh",
	       "FilePath":"/home/user/scripts",
	       "RunAs": "em900cob",

	       "Arguments":["--date", "%%\\\\pool1\\date" ]
	    }

Jobs in a folder can share variables at the folder level using the syntax "\\variable name" to set and %%variable to use

{
  "Folder1"   : {
     "Type" : "Folder", 
 
     "Variables": [
	    {"TodayDate": "%%$DATE"}
	 ],
 
     "job1": {
           "Type": "Job:Dummy",

           "Variables": [
              {"\\\\CompanyName": "compName"}
           ]
	  },
	  
      "job2": {
           "Type": "Job:Script",

           "FileName": "scriptname.sh",
	       "FilePath":"/home/user/scripts",
	       "RunAs": "em900cob",

	       "Arguments":["--date", "%%TodayDate", "--comp", "%%CompanyName" ]
	    }
    }
}

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments