Cron Trigger

Overview

The Cron trigger, similar to the Time trigger, allows you to specify dates and times at which a task will be triggered.

With both Cron and Time triggers, you can define:

  • Simple date and times, such as "every weekday at 12:00 a.m."
  • Specific dates and times, such as "March 15 at 12:00 a.m."
  • A series of dates and times, such as "every Friday at every hour."
  • A mixture of specific dates/times and a series, such as "every Monday at 9 a.m."
  • Complex dates and times, such as "every 3 hours between 8 a.m. and 5 p.m. on the last business day of the year."

(Read Daylight Saving Time for details about how Universal Controller handles Daylight Saving Time.)

It is recommended that you use a Cron trigger, rather than a Time trigger, if you want to schedule non-standard time intervals for a triggering a task (see Scheduling a Time Interval, below).

Cron Syntax

The Cron trigger uses standard Cron syntax. Once the Cron trigger is entered into the system, the Controller interprets it and processes it as it would any other trigger. The trigger is satisfied when the current date and time match all the values specified in the Minutes, Hours, Day of Month, Month, and Day of Week fields.

Cron Fields

The following table identifies the allowed values for the time and date fields that are used to specify the Cron Criteria in the Cron Trigger Details.

Field Name

Required

Allowed Values

Allowed Special Characters

Minutes

Yes

0-59

* / , -

Hours

Yes

0-23

* / , -

Day of Month

Yes

1-31

* / , -

Month

Yes

1-12 or JAN-DEC

* / , -

Day of Week

Yes

0-7 or SUN (0 or 7)-SAT

* / , -

Note

The day when a Cron trigger launches can be specified by two fields: Day of Month and Day of Week. If both fields are restricted (that is, they both are not *), the trigger launches based on the Day Logic field value. If Day Logic is set to Or, when either Day field matches, the trigger can launch. For example: 30 4 1,20 * 5 would cause the trigger to launch at 4:30 a.m. on the 1st and 20th of each month, as well as on every Friday. If, however, Day Logic is set to And, the trigger would launch at 4:30 a.m. only on days that are the 1st or 20th which are also a Friday.

Cron Special Characters

Asterisk ( * )

An asterisk indicates that the expression matches for all values of the field. For example, using * in the Month field indicates every month.

Slash ( / )

A slash describes an increment of ranges. For example, 5-50/15 in the Minutes field indicate the fifth minute of the hour and every 15 minutes thereafter until the 50th minute (5,20,35,50).

Hyphen ( - )

Defines a range of numbers, which are two numbers separated by a hyphen. The specified range is inclusive. For example, 9-17 in the Hours field means from 9 a.m. to 5 p.m., inclusive.

Comma ( , )

Separates items in a list. A list is a set of numbers or ranges separated by commas. For example, 1,5-9,18-20 in the Hours field indicate the following hours 1,5,6,7,8,9,18,19,20.

Cron Criteria Examples

Cron Criteria

Description

0 3 30 4,6,9,11 5

At 3 a.m. on the 30th of the month, for months with exactly 30 days, if the 30th is a Friday.

0 3 31 * 0

At 3 a.m. on the 31st of the month if the 31st is a Sunday.

0 3 22-28 * 0

At 3 a.m. on the 4th Sunday of every month.

0 5-19/7 * * *

Every 7 hours between 5 a.m. and 7 p.m., daily.

0 5,12,19 * * 1,3

Every 7 hours between 5 a.m. to 7 p.m. on Monday and Wednesday.

0 9-17 * * Mon-Fri

Every hour between 9 a.m. and 5 p.m. from Monday to Friday.

0 2-11/3 * * *

Every 3 hours between 2 a.m. and 11 a.m., daily.

0 3 29 2 *

At 3 a.m. on February 29th.

30 1-3,17 * * 1,3,5

At 30 minutes past the hours of 1 a.m., 2 a.m., 3 a.m., and 5 p.m. on Monday, Wednesday, and Friday.

Creating a Cron Trigger

Step 1

From the Automation Center navigation pane, select Triggers > Cron Triggers. The Cron Triggers list displays.
 
To the right of the list, Cron Trigger Details for a new Cron trigger displays.
 

Step 2

Enter/select Details for a new Cron trigger, using the field descriptions below as a guide.

  • Required fields display an asterisk ( * ) after the field name.
  • Default values for fields, if available, display automatically.

To display more of the Details fields on the screen, you can either:

  • Use the scroll bar.
  • Temporarily hide the list above the Details.
  • Click the  button above the list to display a pop-up version of the Details.

Step 3

Click a  button. The trigger is added to the database, and all buttons and tabs in the Trigger Details are enabled.

Step 4

Enable the trigger(s) as desired.

Note

To open an existing record on the list, either:

  • Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
  • Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
  • Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).

Cron Trigger Details

The following Cron Trigger Details is for an existing Cron trigger. See the field descriptions, below, for a description of the fields that display in the Cron Trigger Details.
 

Cron Trigger Details Field Descriptions

The following table describes the fields, buttons, and tabs that display in the Cron Trigger Details.
 

Field Name

Description

General

This section contains general information about the trigger.

Name


Name used within the Controller to identify this trigger. It can contain a maximum of 255 alphanumerics. It is the responsibility of the user to develop a workable naming scheme for triggers.

Version

System-supplied; version number of the current record, which is incremented by the system every time a user updates a record. Click the Versions tab to view previous versions. For details, see Record Versioning.

Description

Description of this record. Maximum length is 255 characters.

Member of Business Services

User-defined; Allows you to select one or more Business Services that this record belongs to.  (You also can Check All or Uncheck All Business Services for this record.)

You can select up to 62 Business Services for any record type, and enter a maximum of 2048 characters for each Business Service.

If the Business Service Visibility Restricted Universal Controller system property is set to true, depending on your assigned (or inherited) Permissions or Roles, Business Services available for selection may be restricted.

Calendar


Calendar that defines the business days, holidays, and other special days that determine the run dates for the task(s) specified in the trigger.

Select a Calendar from the drop-down list of all existing Calendars. To display detailed information about a selected calendar, click the Details icon next to the Calendar field.


Time Zone

User-defined; allows you to specify the time zone that will be applied to the time(s) specified in the trigger. For example, if you specify 23:00 and a time zone of Canada/Central, the task will run at 11:00 p.m. Central Canada time.

Task(s)

Name of the task(s) being triggered when this trigger is satisfied. When selecting tasks from the Details, click on the lock icon to unlock the field and select tasks.

Purge By Retention Duration


Specification for whether triggered task instances can be purged by retention duration.

Exclude Backup

If Purge By Retention Duration is selected; Specification for whether qualifying task instances can be excluded from the backup when being purged by retention duration.

Retention Duration

If Purge By Retention Duration is selected; Minimum retention duration for the selected Retention Duration Unit before triggered task instances can qualify for purge.

If Retention Duration Unit = Days, valid values are 1 to 366.

If Retention Duration Unit = Hours, valid values are 1 to 24.

Retention Duration Unit

If Purge By Retention Duration is selected; Retention duration unit.
 
Options:

  • Hours
  • Days

Execution User


Read-only; Execution user that has been selected (via the Assign Execution User action) to override the execution user of task instances being launched by the trigger.

Forecast


If checked, the Controller calculates the date and time when this trigger will be satisfied for the next number of days, as specified in the Forecast Period In Days Universal Controller system property.

The Controller writes the forecasting entries to the Forecasts List.
 

Note

If this field is checked on a trigger and the trigger is promoted, it will not be checked for that trigger on the target system.


Simulate Forecast

Enables the override of the System Default Trigger Simulate Forecast Universal Controller system property specification for whether or not to simulate forecasting of a trigger.
By enabling trigger forecast simulation, it allows you to enable a trigger to generate forecast records without the trigger launching the specified task(s) at the next scheduled time.
 
Options:
  • -- System Default --
    • Use the system default for enabling / disabling trigger forecast simulation as specified by System Default Trigger Simulate Forecast.
  • True
    • Enable trigger forecast simulation.
  • False
    • Disable trigger forecast simulation.
At the next scheduled time the controller will only log a message similar to the following.
Trigger simulation: Trigger [Time] "trigger-name" with id trigger-uuidlaunching task "task-name" with id task-uuid using trigger variables {...}. Next scheduled trigger time "Sat Apr 01 11:02:00 EDT 2023".

Status

This section contains information about the current status of the trigger.

Status

System-defined; Specification for whether the trigger is Enabled or Disabled. The user enables and disables the trigger by clicking the Enable / Disable buttons. Only enabled triggers are processed by the Controller.

Next Scheduled Time

System-supplied; for time-based triggers. If Status = Enabled, the next date and time this trigger will be satisfied. See Displaying Trigger Forecast Information.

Enabled By

System-supplied. If Status = Enabled, ID of the user who most recently enabled this trigger.

Disabled By

System-supplied; If Status = Disabled, ID of the user who most recently disabled this trigger. (By default, all new triggers are disabled.)

Enabled Time

System-supplied. If Status = Enabled, Date and time that the trigger was enabled.

Disabled Time

System-supplied. If Status = Disabled, Date and time that the trigger was disabled.

Skip Details This section contains detailed information about skipping the trigger.

Task Launch Skip Condition

User-defined; Controls when launching a task for the trigger will be skipped.

Default is the value of the Trigger Task Launch Skip Condition Default Universal Controller system property.

Options:

  • -- None --
    Do not skip the task launch.
  • Active
    Skip the task launch if a previous instance is still active.
  • Active By Trigger
    Skip the task launch if a previous instance launched by the trigger is still active.

Task Launch Skip Condition is not applicable when using the Trigger Now... command and will be ignored.

Skip Restriction

User-defined; Specification for when this trigger should skip and not launch the task(s).

Options:

  • - - None - -
    No skip restrictions
  • Before
    Trigger will skip if the current date and time is before the specified Skip Before Date and Skip Before Time values.
  • After
    Trigger will skip if the current date and time is after the specified Skip After Date and Skip After Time values.
  • Span
    Trigger will skip if the date and time qualifies based upon the specified Skip After DateSkip After Time, Skip Before Date, and Skip After Date values.

    Note

    If Skip After Date and Skip After Time are prior to the Skip Before Date and Skip Before Time, the Span is a "between" period. In this case, if the triggered time is after the Skip After Date and Skip After Time as well as before the Skip Before Date and Skip Before Time, the Trigger will skip and not launch the configured Task(s).

    If the Skip Before Date and Skip Before Time are prior to the Skip After Date and Skip After Time, the Span is a "not between" period. In this case, if the triggered time is either after the Skip After Date and Skip After Time or before the Skip Before Date and Skip Before Time, then the trigger will skip and not launch the configured Task(s).

  • On
    Trigger will skip on any of the dates specified in the Skip Date LIst.

Default is - - None - -.

Skip Count

User-defined; Allows you to specify that the Controller should skip the next N times this task is triggered.
 
Skip Count is not applicable when using the Trigger Now... command and will be ignored.

Skip Before Date

If Skip Restriction is Before or Span; Date before which the Trigger will skip.

Skip Before Time

If Skip Restriction is Before or Span; Time before which the Trigger will skip on the specified Skip Before Date.

Skip After Date

If Skip Restriction is After or Span; Date after which the Trigger will Skip.

Skip After Time

If Skip Restriction is After or Span; Time after which the Trigger will skip on the specified Skip After Date.

Skip Date List

If Skip Restriction is On;  List of dates on which the trigger will skip.

Cron Details

This section contains assorted detailed information about the trigger.

Minutes

Time in minutes, using standard Cron syntax.

Hours

Time in hours, using standard Cron syntax. (See also Daylight Saving Time.)

Day of Month

Day of the month, using standard Cron syntax.

Month

Required. Month, using standard Cron syntax.

Day of Week

Day of the week, using standard Cron syntax.

Cron Criteria

System-supplied; summary of the Cron specifications. Also displays in the Cron Criteria column on the Cron Triggers list.

Day Logic

Specification for whether to And the Day of Month with the Day of Week criteria or to Or the Day of Month with the Day of Week criteria.

Restrictions

This section specifies any restrictions that apply to the trigger.

Special Restriction

Enable this field in order to specify additional parameters that tell the Controller how to handle exceptions, such as when the trigger is satisfied on a holiday or non-business day. You can specify simple and/or complex restrictions.

For example, you can specify a Simple Restriction that disables the trigger if it is satisfied on a holiday identified in the calendar and/or a Complex Restriction that disables the trigger on the last business day of every month.

Action

If Special Restriction is enabled, allows you to select an action to take on a non-business day or holiday (see Situation field).

Options:

  • Do Not Trigger
  • Next Day (run on the next day)
  • Next Business Day (run on the next business day, as defined in the calendar)
  • Previous Day (run on the previous day)
  • Previous Business Day (run on the previous business day, as defined in the calendar)

Simple Restriction

If enabled, allows you to specify an action (see Action field) such as Do Not Trigger on a non-business day or holiday (see Situation field). For example, do not trigger on a non-business day.

Situation

If Simple Restriction is enabled, allows you to select the situation that causes the system to initiate the action specified in the Action field.

Options:

  • On Non Business Day
  • On Holiday

Complex Restriction

If enabled, allows you to specify a set of parameters that determine one or more situations when this trigger should not be satisfied. Used in conjunction with the following fields: Restriction Mode, Restriction Adjective, Restriction Noun, Restriction Qualifier. For example, you may specify that you do not want to satisfy this trigger on the last business day of the year or the first day of each month.

Restriction Mode

If both Simple Restriction and Complex Restriction are enabled, specifies whether you want to use both restriction types (AND) or one or the other (OR).

Options:

  • And
  • Or

Restriction Adjective

If Complex Restriction is enabled, the type of selection.

Options:

  • Every
  • 1st
  • 2nd
  • 3rd
  • 4th
  • Last
  • Nth

Example: The last business day of the month.

Restriction Noun(s)

If Complex Restriction is enabled, the day(s) you want to select.

Options:

Example: The last Business Day and Sunday of the month.

Restriction Qualifier(s)

If Complex Restriction is enabled, the period(s) you are selecting from.

Options:

Example: The last Day of Quarter, Year, and January.

Restriction Nth Amount

If Restriction Adjective is Nth, allows you to specify the value of N.

If Restriction Qualifier is Week, Restriction Nth Amount must be <= 7.

Self-Service Options  This section contains Self-Service specifications for the trigger.
Enforce Variables

Specifies whether or not to enforce Override Trigger Variables when using Trigger Now... from the User Interface.

Lock Variables

Specifies whether or not to prevent editing variables when using Trigger Now... from the User Interface.

Metadata

This section contains Metadata information about this record.

UUID

Universally Unique Identifier of this record.

Updated By

Name of the user that last updated this record.

Updated

Date and time that this record was last updated.

Created By

Name of the user that created this record.

Created

Date and time that this record was created.

Buttons

This section identifies the buttons displayed above and below the Trigger Details that let you perform various actions.

Save

Saves a new task record in the Controller database.

Save & New

Saves a new record in the Controller database and redisplays empty Details so that you can create another new record.

Save & View

Saves a new record in the Controller database and continues to display that record.

New

Displays empty (except for default values) Details for creating a new record.

Update

Saves updates to the record.

Enable

Activates this trigger and writes your User ID to the Enabled By field.

Disable

Deactivates this trigger.

Trigger Now...

Immediately triggers all the tasks specified in this trigger.
 
Optionally, you also can select to:

  • Launch the task(s) specified in the trigger with one or more variables.
  • Launch the task(s) specified in the trigger by a specified date and time.
  • Launch the task(s) specified in the trigger but place them in Held status; they will not run until they are released.


Note

If you click Trigger Now... for an Enabled trigger that does not have an assigned Execution User, the trigger will launch its task(s) under the context of the Enabled By user.
 
If you click Trigger Now... for a Disabled trigger that does not have an assigned Execution User, the trigger will launch its task(s) under the context of your user name and ID.
 
If you click Trigger Now... for an Enabled or Disabled trigger that has an assigned Execution User, the trigger will launch its task(s) under the context of the assigned Execution User.

List Qualifying Times

Lets you generate a list of future dates and times that the trigger will trigger the specified task (see Generating a List of Qualifying Times, below).

Copy

Creates a copy of this trigger, which you are prompted to rename.

Delete

Deletes the current record.

Refresh

Refreshes any dynamic data displayed in the Details.

Close

For pop-up view only; closes the pop-up view of this trigger.

Tabs

This section identifies the tabs across the top of the Trigger Details that provide access to additional information about the trigger.

Variables


Lists all user-defined variables associated with this record; that is, variables that have been defined for this specific record.

Instances

Lists all task instances that were triggered directly by this trigger.

Notes


Lists all notes associated with this record.

Versions


Stores copies of all previous versions of the current record. See Record Versioning.

Scheduling a Time Interval

A Cron trigger lets you schedule a time interval for how often a task will be triggered. You also can select a time frame that restricts the time during which the trigger is active, so that a task will be triggered only at the time intervals within that time frame.

The time interval for a Cron trigger resets at the end of the day; when the 24-hour clock expires, the time interval count begins again at 12 a.m. on the next specified day. Therefore, if you select a time interval for multiple days, the task will be triggered at the same times each day.

Although you also can use a Time trigger to schedule a time interval for a task to be triggered on multiple days, you should use a Cron trigger if the time interval is not one by which the 24-hour clock is even divisible (2, 3, 4, 6, 8, and 12), such as in the Cron criteria examples, above. Using a Time trigger to schedule this type of time interval could produce unexpected results, since the time interval for a Time trigger does not reset at the end of the day. It continues into the next day, regardless of the 24-hour clock (see Scheduling a Time Interval with a Time Trigger).

Conversely, if you want to trigger a task on multiple days at a time interval without regard to the time of day, and the interval is not one by which the 24-hour clock is even divisible, you must use a Time trigger, which will not reset at the end of the day. For example, if you want to trigger a task every 5 hours, from Monday to Friday, without regard to the time of day, a Time trigger will allow you to trigger the task on Monday at 12 a.m., 5 a.m., 10 a.m., 3 p.m., 8 p.m. and then next (5 hours later) on Tuesday at 1 a.m.. This time interval scheduling cannot be accomplished with a Cron trigger.

Generating a List of Qualifying Times

The Controller allows you to generate a list of future dates and times that a trigger will trigger the specified task.
 

Step 1

Click the List Qualifying Times button in the Cron Trigger Details. The List Qualifying Times Input dialog displays.
 

Step 2

Select a Number of Dates/Times (1 - 1000) that you want to list. The default is 30.

Step 3

Select a Start Date from when you want the list to begin.

Step 4

Click the Submit button to generate the list. For example: