Constraints

An Instance constraint is one where a previous Plan/Job must have executed to completion before this instance can be allowed to execute. The author of the constraint can further indicate whether the instance must have completed successfully, failed or simply completed (where success or failure is not considered).

To ad an Instance constraint, click the Add button, then select Job Constraint (it is named Job Constraint but Plans can be used as well). The following Job Constraint dialog appears:

The information requested is to identify the Job or Plan that the current Job or Plan will be dependent on - and to populate other associated properties, described below.

Label: This mandatory field names the Job Constraint. This label must be unique within the Plan or Job’s usage. If <AutoAssign> is used, the label will consist of the Job or Plan’s label. For example, /CaseStudy2/JobA would yield a label of JobA (as depicted in the above image).

Job: This mandatory field contains a dropdown box listing all known Jobs/Plans, by name. Select the Job or Plan that the current Job or place will be depending on before it can run.

Type: This mandatory field indicates whether the specified Job must complete successfully (the default), must complete in failure, or just complete. Failure is a less common configuration, but there are scenarios where the current Job should only run when the dependency Job fails.

Instance: This field indicates how current the specified Job instance must be to consider the Job meeting the Type property. Possible choices are defined below.

• Exact Active means either the currently active instance or the last scheduled instance. This is the default and most precise setting. Jobs or Plans that are executed within a single batch run A batch run is when all the instances in a workflow are tied together with the same Batch Run ID (a system-assigned numeric value). The Batch Run ID originates from the first object that was triggered in the workflow. Instances share the same Batch Run ID when 1) A Plan is triggered 2) A completion trigger A completion trigger provides the ability for a Job or Plan to trigger another Job or Plan after it completes. You can determine which jobs or plans to trigger based on how your Job or Plan completes. For example, you can trigger one set of jobs if your Job completes successfully, and another set if your Job fails. is used 3) An alert trigger An Alert Trigger provides the ability to trigger a Job or Plan if the alert condition occurs. For example, if a Job fails, an alert (either embedded or using an Alert object) can be configured to trigger another Job. is used. always adopt the Exact Active scope.

• Exact Active Today Only refines the Exact Active scope further by limiting instance checking to “Today”. Today is defined as the standard 24 hour period beginning with midnight (unless this object is using Business Day Semantics” in which case the period begins based on the StartBusinessDay configuration property). The instance must have been created today, however, it does not have to actually begin execution today. This scope allows for Job/Plan constraints to be considered as part of a today’s business run even though the actual execution of that run could take several days. Note: This scope is only applicable when the target specified is within another Plan or batch run (i.e. outside the current batch run). If the target job is part of a larger batch job, some instances may not execute and register as a failure. If another instance of the batch had executed, where the target job had also run successfully, the constraint was satisfied. If this target job was not triggered as a part of a larger batch, and instead was being directly triggered, then as long as it had run successfully on that same day, it would have also satisfied the constraint.

• Last Completed means the last completed instance as specified by a user provided time period. When this dropdown is selected, the time control labeled “within the last” becomes active and you can set the days and hours/minutes as a time period for ActiveBatch to determine whether a completed instance meets these requirements.

• Not Active means that the selected Job/Plan is not currently running. If the specified Job/Plan is a part of the workflow, the scope will be limited to current batch run. If the specified Job/Plan is not a part of the workflow, the scope is not limited and a simple determination is made to determine if an instance is active. The “Not Active” scope is very similar to “Exact Active” with the single notable exception that a check of the previously completed instance is not performed.

• All Instances includes the preceding settings and expands the scope to include any instance of the Job that completed. This is the most flexible setting.

Ignore Constraint if Job/Plan has/is not run or not scheduled to run, today: By default, all constraints when specified must be met. This can be an issue when you need to constrain against an object in another Plan which may have a different Schedule. For example, JobA, which runs daily, needs to be constrained against a Plan named “MonthlyPlan” however, as the name implies, the Plan only runs once a month while JobA runs daily. If a “normal” constraint is specified, JobA will wait even when it shouldn’t. This attribute, when enabled, refines the constraint logic so that a constraining Plan/Job that has not run, is not currently run or is not scheduled to run today; is ignored. Today is defined as the standard 24 hour period beginning with midnight. If specified, using the above example, JobA will only be constrained on the day MonthlyPlan is actually scheduled to execute. On other days, the constraint will be ignored. Please note that this attribute is ignored if the object specified in the constraint is within the same batch runA batch run is when all the instances in a workflow are tied together with the same Batch Run ID (a system-assigned numeric value). The Batch Run ID originates from the first object that was triggered in the workflow. Instances share the same Batch Run ID when 1) A Plan is triggered 2) A completion trigger A completion trigger provides the ability for a Job or Plan to trigger another Job or Plan after it completes. You can determine which jobs or plans to trigger based on how your Job or Plan completes. For example, you can trigger one set of jobs if your Job completes successfully, and another set if your Job fails. is used 3) An alert trigger An Alert Trigger provides the ability to trigger a Job or Plan if the alert condition occurs. For example, if a Job fails, an alert (either embedded or using an Alert object) can be configured to trigger another Job. is used. .

Note: If the constraint logic fails and the Wait, Check every... option is enabled, the recheck logic kicks in. The system reevaluates the constraint logic based on the frequency and duration configured. The system also forces a reevaluation of the constraint logic as the Job(s)/Plans(s) the constraint Job is waiting on complete. This is true because the system knows about its own Jobs (it's not checking an external resource, like it does with a file, variable or dynamic (active variable) Resource Constraint). Therefore, as soon as the constraint Jobs(s)/Plans(s) complete, a constraint logic recheck occurs. The Job will not have to wait for the next recheck logic interval. This means that your recheck logic interval does not need to be overly frequent due to the forced recheck.

A file constraint allows you to specify what file(s) must be present or absent in order for the constraint to be met. To add a File Constraint, click the Add button, then select File Constraint. Alternatively, you can select an existing file constraint, then click the Edit button. Below you see the dialog associated with editing an existing file constraint.

The information requested in this dialog box is primarily details about the file.

File Specification: This mandatory field indicates the file that the Job or Plan is dependent on, before it can run. The file specification must be complete and can represent a local or UNC file specification. You can specify wildcard characters. The characters must be added as per the execution machine’s operating system’s requirements. Please note that local represents the execution machine since all file dependency checks are performed in the Job’s security context on the execution machine. This means that you must have security access to the file. (Variable Substitution supported).

Check for File Present/Absent: This radio button indicates whether the file must be present or absent. The default is present.

The following checkboxes allow further refinement of the file constraint check.

If enabled File must be available for exclusive access means that no other process can be accessing the file. If a process is accessing the file, the dependency will fail. An example of when to use this might be expecting a customer to FTP a file into your production system. You don’t want to start the Job until the file has completed populating.

If enabled File must be at least n bytes means that the present file must be at least n bytes in size in order to successfully pass the file constraint check. This is particularly useful when a zero (0) byte file should be considered as a file constraint check failure.

If enabled File should have been allows you to perform a date validation on the specified file. You can choose Created, Last Accessed, Last Written dates as well as Before or Within and a relative day/time range. The relative time range can be expressed in days, hours and minutes from the initial file dependency check start time. This option allows you to discriminate between “old” files that just happen to still be present from newer files that should have been created.

If enabled the If Wildcard spec… option allows you to further refine wildcard processing by indicating whether ALL files must meet the above checking criteria or simply the first file should result in a dependency check failure. By default, the first file to meet the above criteria will cause the dependency check to succeed.

Queue and User properties may be specified when you want to check a File Constraint that is actually present on another machine (in particular, if that machine is another OS platform). The Queue property, if specified, indicates the Execution Queue (and machine) in whose context the file constraint is checked. Similarly, the User property represents a User Account object whose credentials are appropriate for the Execution Queue specified and will pass the authentication necessary for accessing the file and directory specified.

A Variable Constraint lets you to create an Active Variable from a built-in data source, then use the return variable value for comparison purposes, to determine if the constraint is met. To add a Variable Constraint, click the Add button, then select Variable. The following dialog appears:

Using the above dialog, configure the desired Active Variable. Variable usage within the constraint should not be confused with variable substitution. In other words, when you configure variable(s) as a constraint, the system does not add the standard curly brace variable syntax in the Constraint Logic property (it just adds the variable constraint's label).  Reminder: The label for any type of new constraint is automatically added to the Constraint logic when the constraint is saved.

In the above image, an active variable constraint is defined. MainFolderExists checks whether the directory C:\MainFolder is present. If it is, a Boolean value of True (1) is returned. Otherwise, a Boolean value of False (0) is returned. In this example, the Constraint Logic property would simply be: MainFolderExists.

Let's say another variable constraint is added (in addition to the above-described variable constraint) using the SQL query active variable. The query retrieves a database table record count that is then used to determine if there are enough records to satisfy the constraint. If the variable label is “RecordCount” then AND RecordCount is what would be added to the existing Constraint Logic by the system after saving the new variable constraint. It is up to you to enter the comparison portion of the constraint logic (since RecordCount doesn't return a simple True of False value). For example, the Constraint Logic property would look something like this:      MainFolderExists AND (RecordCount > 5).  Both conditions must evaluate to true to satisfy the constraint.

Note: By default, the AND operator is automatically added to the Constraint Logic property when you add multiple constraints. You can manually change this to another supported operator, such as OR.

Note: All Active Variable constraints require security credentials to access the data source. If the Execution User’s credentials (the default credentials used) are not appropriate for Windows, you must specify alternative credentials in the Variable constraint.

User Input Variable Constraint

A special constraint is an “Interactive” constraint. An Interactive constraint is used when you need to request information and/or pause a Job/Plan mid-stream.

To create an Interactive constraint, create a variable constraint as an active variable using the “UserInput” action.

The above variable named “input” uses the UserInput action (an active variable type) which is used during a Respond operation to format and request data for the variable. The “waiting-for-the-information” portion is performed as part of the constraint. In the above example, the variable “input” requests “text” from the user - displaying a question (“Enter Database to attach…”).

The variable “input” is checked, as part of the constraint logic” for the value of “DB”. Unless the user enters that value, the constraint will not be satisfied.

A Resource represents a finite value that is to be shared among other Jobs and Plans. When the object triggers, the Plan/Job attempts to access the resource it needs, based on how the Resource Constraint is configured. If it cannot access the resource, the instance will fail or wait, depending the constraint's failure logic (applicable to all general constraints).

ActiveBatch resources are numeric by definition. For example, the Resource may be a static number that represents the maximum number of Jobs of a particular type that can run at the same time. More dynamic resources might be the amount of free disk space a particular system has and the fixed amount needed by this Job. If the required amount of disk space isn’t available, the Job shouldn’t run. In order to configure a Resource Constraint, you would first need to create a Resource Object object, since you must specify one in the Resource Constraint, as depicted in the image below (see the Resource Object property).

To add a Resource Constraint, click the Add button, then select Resource Constraint. The following dialog appears:

In the image above, the Resource Constraint labeled “FreeSpaceCDrive” references the dynamic Resource Object (named DiskSpace) which corresponds to the amount of free space on drive C: (in Megabyte units). This particular Job needs one hundred million bytes of free space (as per the Units needed property) before being allowed to run (assuming any other constraints are met). For Constraint Logic purposes, the system will add the label - FreeSpaceCDrive (after you click OK), and that is all that is needed (no comparison operation is required, since the "Units needed" is specified in the Resource Constraint itself). If the Resource constraint is met, the label FreeSpaceCDrive is equated to true, if not, false; when true, 100 (megabytes) is then subtracted from the Resource.

Note: If the constraint logic fails and the Wait, Check every... option is enabled, the recheck logic kicks in. The system reevaluates the constraint logic based on the frequency and duration configured. When you are using a static Resource Constraint, the system also forces a reevaluation of the constraint logic when a Job that was allocated unit(s) has completed and returned the unit(s). This is true because the system keeps track of its static units (it's not checking an external resource, like it does with a file, variable or dynamic (active variable) Resource Constraint). Therefore, as soon as a Job returns its static resource unit(s), a constraint logic reevaluation takes place. The Job will not have to wait for the next recheck logic interval. This means that your recheck logic interval does not need to be overly frequent due to the forced recheck.

The Date/Time constraint lets you specify when triggerable objects should not run, even if a trigger occurs. Two types of date/time constraints are provided: Exclusion (List) and Calendar, as depicted in the image below.

The Date/Time Exclusion List constraint allows you to indicate a day, specific date (or date range), and time(s) that indicate when a Plan or Job is not allowed to execute. This means that should a Plan or Job trigger on a date/time specified in the exclusion list, the Plan or Job will not execute. These exclusions are set on a per Job or Plan basis. The Calendar constraint uses the shared Calendar object to filter triggers. A common use to is add holiday dates to a Calendar object, then associate the Calendar to multiple Jobs and/or Plans. The holiday dates indicate when the Plan or Job should not run, even if a trigger occurs.

Exclusion List Constraint

The exclusion list has two (2) properties: Date and Time. These are the date(s) and time(s) the Job/Plan should not run if triggered. The date can be a specific date or date range, or any day(s) Monday through Sunday. The time can be all day, or a time range (e.g. 1:00 PM to 2:45PM). Using the exclusion list, you could specify that a Job scheduled to run every 5 minutes should not run at 3:05 am. Or, not run on Mondays. The figure below is the dialog box that appears when you add or edit a Date/Time exclusionary period. You can have more than one exclusionary period for any given Job or Plan.

 

Calendar Constraint

 

The Date/Time Calendar constraint is used when a Plan/Job is only allowed to execute on business days. The Calendar Object acts as a filter constraining triggers to only operate on business days. Holidays and non-working days (typically weekends) would not be considered business days. Therefore, what you add to a Calendar object are non-business days and/or holidays. You can associate one or more Calendar objects as constraints to the Plan/Job.

 

As an example, assume a Job is configured to trigger Monday through Friday, using a Schedule object. A holiday is set to fall on a Monday. Add the Monday holiday to the Calendar object and associate the Calendar to the Job. When the holiday date arrives, the Job will not run.

 

Alternatively, you can also associate a Calendar object with a Schedule object. Please see a discussion about this in the Schedule Object section. This topic only discusses how the Calendar object works when it is associated to a Plan/Job on the Constraints property sheet.

 

To add an existing Calendar object to the Calendars list, click the Associate button. An "Associate" window will pop up, allowing you to navigate to your desired Calendar object. Click the checkbox to the left of the Calendar name, then click OK. The Calendar will be added to the list of Calendars. You can also select an existing Calendar to edit it, or disassociate it. Additionally, you can click the New button, which will pop up a window allowing you to select the container to place the new Calendar in. After selecting the container, the property sheets for the new Calendar will be tabbed in the Main view.  Configure the Calendar, then save it. The Calendar will be added to the Calendars list, and it will be visible in the container you previously selected.

 

On Business Day - This property is located under the Calendars list. If a holiday date occurs on a day that the object normally is triggered, you can opt to run the Job on a different day - which includes the next day or the previous day. You can also skip the run (the default selection). If you choose UseNext or UsePrevious from the dropdown list of options, the triggerable object will be scheduled to run on the previous or next business day.  If it is already scheduled to run on the previous or next business day, it will run as usual and the next/previous selection will be ignored (it won't run twice).