Automation triggers

Each automation is triggered by an event. An event can be time based (cron) or linked to a record change.

Time based events

onCourse automations can be triggered by a cron expression for firing at a repeating interval. cron is a Unix tool that has existed since the 1970s and is extremely powerful and flexible.

Some pre-defined cron expressions are available to select from the drop down list in the automation (daily, weekly or hourly), or you can create your own custom cron using this simple tool http://www.cronmaker.com/?0

You need only write six fields separated by spaces to describe the recurring timing. For example, you can specify "every Monday at 9am" or "1am on the first Sunday of every month".

Seconds
Allowed values: 0-59

Minutes
Allowed values: 0-59

Hours
Allowed values: 0-23

Day of month
Allowed values: 1-31

Special characters: ?
L W

Month
Allowed values: 1-12 or JAN-DEC

Day of week
Allowed values: 1-7 or MON-SUN

Special characters: ?
L #

Every field allows the special option '' which means all values. For example, '' in the minute field means every minute. In each field you can also use ranges. For example '13-15' in the hour field means 1pm, 2pm and 3pm. And ',' can be used for multiple values such as 'mon,wed,fri' in the day of week field. You can specify a repeating increment in a field with a '/'. For instance "0/15" in the hour field means every 15 minutes starting at the hour. Or "2/3" in the day of month field means every three days starting on the second day of the month.

? ("no value")
Because day-of-month and day-of-week overlap in meaning, one of those two fields should always be '?'.

L ("last")
has different meaning in each of the two fields in which it is allowed. For example, the value "L" in the day-of-month field means "the last day of the month" - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means "7" or "SAT". But if used in the day-of-week field after another value, it means "the last xxx day of the month" - for example "6L" means "the last Friday of the month". When using the 'L' option, it is important not to specify lists, or ranges of values, as you’ll get confusing results.

W ("weekday")
used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify "15W" as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month". So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify "1W" as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month’s days. The 'W' character can only be specified when the day-of-month is a single day, not a range or list of days.

The 'L' and 'W' characters can also be combined in the day-of-month field to yield 'LW', which translates to "last weekday of the month".

#
used to specify "the nth" XXX day of the month. For example, the value of "6#3" in the day-of-week field means "the third Friday of the month" (day 6 = Friday and "#3" = the 3rd one in the month). Other examples: "2#1" = the first Monday of the month and "4#5" = the fifth Wednesday of the month. Note that if you specify "#5" and there is not 5 of the given day-of-week in the month, then no firing will occur that month.

The legal characters and the names of months and days of the week are not case-sensitive. MON is the same as mon.

Examples

0 0 12 * * ?	Fire at 12pm (noon) every day
0 15 10 ? * *	Fire at 10:15am every day
0 15 10 * * ?	Fire at 10:15am every day
0 15 10 * ?	Fire at 10:15am every day
0 15 10 * * ? 2005	Fire at 10:15am every day during the year 2005
0 14 * ?	Fire every minute starting at 2pm and ending at 2:59pm, every day
0 0/5 14 * * ?	Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day
0 0/5 14,18 * * ?	Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day
0 0-5 14 * * ?	Fire every minute starting at 2pm and ending at 2:05pm, every day
0 10,44 14 ? 3 WED	Fire at 2:10pm and at 2:44pm every Wednesday in the month of March.
0 15 10 ? * MON-FRI	Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
0 15 10 15 * ?	Fire at 10:15am on the 15th day of every month
0 15 10 L * ?	Fire at 10:15am on the last day of every month
0 15 10 ? * 6L	Fire at 10:15am on the last Friday of every month
0 15 10 ? * 6L	Fire at 10:15am on the last Friday of every month
0 15 10 ? * 6L 2002-2005	Fire at 10:15am on every last Friday of every month during the years 2002, 2003, 2004 and 2005
0 15 10 ? * 6#3	Fire at 10:15am on the third Friday of every month
0 0 12 1/5 * ?	Fire at 12pm (noon) every 5 days every month, starting on the first day of the month.
0 11 11 11 11 ?	Fire every November 11th at 11:11am.

Entity events

Rather than a specific time, the trigger for a automation can instead be a record change, otherwise known as an entity event. You are able to specify the entity name and the type of change to trigger the automation: create, update, create or update, or remove. Note that entity names are mostly the same as database table names, but there is a difference. Some entities don’t map directly to the database.

You can even set this to trigger when a specific entity attribute is edited; for example you could easily create a script that sends out an email the moment a contact allows for email marketing, or a confirmation email of a last name change.

For more details of what entities are available, please consult our detailed API documentation.

onCourse events

There are also specific events in onCourse that can be used to trigger automations, called onCourse events. These events relate entirely to cancellation and/or creation of enrolments as well as the publishing and/or cancelling of classes. The events types are specified as: enrolment successful, enrolment cancelled, class published and class cancelled.

On Demand automations

When a automation is set as On Demand it means the automation can only be triggered manually by the user via the cogwheel menu in onCourse. The entity class defines from which screen in onCourse the automation can be triggered. If an entity is not defined, then the automation can only be run from the main navigation menu under 'Favourites'. This latter function only appears for users with admin priveliges. You can also add the script to your Favourites by clicking the heart icon that appears when you hover your mouse over it.

Click the automation icon in the list to open a new dialog box. For some automation, this will shows some questions to be answered, depending on the automation definitions. Click Run Now to run it. The run history is shown as a series of ticks and crosses representing each time the automation has run either successfully or failed. Hovering your mouse over the icon will show you the corresponding date and time it was run.

Figure 566. Look for the above icon after clicking