Schedule Execution of an Actor

Abaco’s cron schedule is a tool to automatically execute your actor based on a schedule. Each actor has two user-defined parameters associated with the cron execution: cronSchedule and cronOn. The scheduler has another variable, cronNextEx, which holds the next execution time of the actor. This is an internal variable and cannot be edited by users. To create a schedule, set the cronSchedule parameter when registering a new actor or updating an existing actor. The value of cronSchedule should be a string in the following format:

yyyy-mm-dd hh + <number> <unit of time>

where the first part is the datetime when the first execution will happen, and the second part is the time increment for each subsequent execution. Note that the spaces, plus characters (+) and dash characters (-) in the template above are meaningful and are a required part of the format. Abaco’s cron schedule also has an alias called now, which lets you execute the actor at the current UTC time. For example, if an actor was registered with this schedule:

"cronSchedule": "now + 1 hour"

The actor would execute at the current time, and then again at the top of the hour every hour. The highest granularity is the hour, and the units of time that can be used are hour, day, week, and month. The cron schedule runs on the UTC timezone.

To create an actor with a schedule, make a request like the following:

$ tapis actors update --repo tacc/hello-world:latest \
                        --cron-on \
                        --cron-schedule "now + 1 hour" \
                        $ACTOR_ID
+----------------+----------------------------+
| Field          | Value                      |
+----------------+----------------------------+
| id             | MKq3mpRm7aDDQ              |
| name           | example-actor              |
| owner          | urrutia                    |
| image          | tacc/hello-world:latest    |
| lastUpdateTime | 2021-08-24T16:26:20.955770 |
| status         | READY                      |
| cronOn         | True                       |
+----------------+----------------------------+

The --cron-on flag turn on cron job for an actor, and --cron-schedule sets the intervals for which the cron job runs. For this example, an execution will recur every hour until the user changes the cron schedule, turns off the cron schedule, or deletes the actor.

To turn off the schedule, use the cronOn switch like so:

$ tapis actors update --repo tacc/hello-world:latest \
                        --cron-off \
                        $ACTOR_ID
+----------------+----------------------------+
| Field          | Value                      |
+----------------+----------------------------+
| id             | MKq3mpRm7aDDQ              |
| name           | example-actor              |
| owner          | urrutia                    |
| image          | tacc/hello-world:latest    |
| lastUpdateTime | 2021-08-24T17:01:54.536957 |
| status         | READY                      |
| cronOn         | False                      |
+----------------+----------------------------+

By turning off the schedule, the actor will no longer execute itself at each increment. You can turn it on again at any time, and the actor will resume incrementing as before. For example, if an actor is set to execute every hour, and then the cron switch is turned off, the actor will stop executing itself. After a week, the switch can be turned back on, and the actor will resume executing on the hour.

Cron Schedule - Error Messages

If users supply a value for cronSchedule in an incorrect format, they will receive an error letting them know to check the format. The API also checks that the schedule sent in has not already past. For example, if you pass in the year 1955, you will get an error message saying the cron schedule has already passed. The error message will also tell you the current UTC time for reference.

Cron Message and Execution

When it is time to execute an actor configured with a cronSchedule, Abaco’s internal cron agent simply queues a message on the actor’s internal message queue, just as if a client had sent a message to the actor using the /messages API. If the actor already has (unprocessed) messages in its queue, these messages will be processed first before the cron message. This means that there could be some delay between the time Abaco internally queues the message and the actor starts executing it.

Currently, the cron message sent to the actor is the static string:

This is your cron execution

You cannot change this incoming message, but you can change how the actor responds to it.