10.0: Create recurring weekday tasks with automation timers

[jstanden]

Introduction

Automation timers run an automation in the future -- either once or on a repeating schedule.

In this guide we'll build an automation timer that creates a set of daily tasks on weekdays.

Build the automation

First, let's create the automation we want to run every weekday.

Navigate to Search >> Automations as an administrator and click the (+) icon in the top right of the worklist.

Use the following field values:

Field	Value
Name:	wgm.example.createDailyTasks
Description:	Create a set of daily tasks
Trigger:	automation.timer

For the automation script, we can create a simple task record:

start:
  record.create/coffee:
    output: task_coffee
    inputs:
      record_type: task
      # See: https://cerb.ai/docs/records/types/task/
      fields:
        title: Get coffee
        due@date: today 8am America/Los_Angeles

An automation.timer can optionally use continuations to pause and resume at a later time while preserving its state. We don't need that feature here, but it's useful to repeat a timed sequence of actions.

Timer automations can also return: a delete: key to delete their record after running. This is useful for one-time, non-repeating timers. When a timer doesn't repeat or delete itself, it will be disabled after it runs.

We also need to set up the automation policy to allow record creation.

Switch to the Policy tab at the bottom of the editor and paste the following:

commands:
  record.create:
    deny@bool: {{inputs.record_type is not record type ('task')}}
    allow@bool: yes

This allows the automation to create task records.

Now we can test the automation.

Switch back to the Run tab at the bottom of the editor.

Our automation doesn't need any inputs, so you can just click the "run" icon:

In the Output panel you should see the dictionary of the newly created task.

You can also verify that a new task was created from Search >> Tasks:

Click the Save Changes button at the bottom of the automation editor.

Configure the automation timer

Now we'll create the timer to run our automation every weekday.

Navigate to Search >> Automation Timers and click the (+) icon in the top right of the worklist.

Field	Value
Name:	Create daily weekday tasks
When:	(leave blank)
Status:	enabled

Check the box to the right of Repeat:.

Automation timers use cron syntax to define one or more schedules. Cron expressions are in the format:

[minute] [hour] [day of month] [month of year] [day of week]

A value of * means "every". You can step values like */5 for "every 5th", use 1,3,5 for sets, or 1-5 for ranges.

Here are a couple examples:

# [min] [hour] [dom] [month] [dow]

# Every minute of every day
* * * * *

# Once every hour from 9am to 6pm, every day
0 9-18 * * *

# At 5pm on Sunday and Wednesday
0 17 * * 0,3

# Once every Christmas
0 0 25 12 *

You can also use helpful online tools like https://crontab.guru/ to create expressions.

The timer will run at the next soonest interval of any of the expressions.

We've provided some shortcuts for common patterns. Click the mouse cursor on Line 3 of the repeat editor and click the (+) icon in the toolbar:

Select Once every weekday and click the blue button to continue.

This inserts the expression:

# Once every weekday
0 0 * * 1-5

The "day of week (dow)" expression is Americanocentric, so it starts on Sunday (0) and ends on Saturday (6). The weekdays are 1-5.

You can select the Timezone: of automation timer schedules.

Now we can configure the automation we want to run when the timer ends.

In the Automation Timer (KATA) editor, click the (+) button in the toolbar and select the wgm.example.createDailyTasks automation we created earlier.

Click the blue button to continue.

It's possible to run different automations from a single timer, but that's not something we need in this example.

Click the Create button to create the automation timer.

The timer worklist shows when each timer is scheduled to run next:

Your timer will now repeat automatically at the start of every weekday.

You can manually test the automation timer by editing it, changing When: to now, and saving it.

Then navigate to Setup >> Configure >> Scheduler and click run now in the Automations job.

Conclusion

You learned how to create a timer to repeat automations on a schedule. This can be used to perform any actions.

You now know about using Cron expressions to describe time intervals in a terse syntax.