Choose when a routine runs
Run a routine on a schedule, after a dataset is edited, when another system calls it, or by hand, and the limits on how often it can run.
A routine can be started by the clock, by an edit to a dataset, or by another system. Choose by what should set the job off. One routine can have more than one: a weekly schedule and a run after every edit, say. You set them in the routine's form; see Set up a routine. Run now on the routine's page starts it at any time.
On a schedule
For a job that belongs at set times: a Monday refresh, a daily check.
| Choice | When it runs |
|---|---|
| Once | At the date and time you set, then the routine switches itself off |
| Hourly | Every hour |
| Daily | Every day at the time you set |
| Weekdays | Monday to Friday at the time you set |
| Weekly | Once a week, on the day and at the time you set |
You set times in your own time zone; the form shows it as an offset from GMT. A repeating routine starts within a few minutes of its time, not on the minute: each routine has its own small delay, so routines set for the same time do not all start together.
There is no monthly schedule. For a monthly job, use Run now each month, have another system start it, or run it weekly.
When a dataset is edited
For a job that should follow the data: rebuild a summary after someone updates the register, re-check the sites after a new batch is added.
Choose the dataset, and how long to wait after the last edit before the routine runs: 5 minutes, 15 minutes (recommended) or 1 hour. Every further edit starts the wait again, so the routine runs once, after the editing stops. A short wait reacts sooner, and a pause in the middle of your editing can set it off on half-finished data. A long wait lets a whole editing session finish.
While a run is waiting, the routine's page says so and offers Skip this run, for edits you don't want acted on. The next edit sets it waiting again.
The run treats the edit as the new data. It does not look for newer data elsewhere unless the instructions name a source.
A routine watches a dataset in Mapstack. It cannot watch a file in Google Drive, OneDrive or Dropbox for changes: for that, run it on a schedule and name the file in the instructions.
When another system starts it
For a job that something outside Mapstack knows is due: a nightly export finishing, a form being submitted. Choose When another system starts it (API). A routine can have one.
- The address. The form shows the URL to call, which takes a POST request, and an Example request to copy.
- The token. It is shown once, when you create the routine or generate a new one, so copy it then. Send it in the request's Authorization header as a Bearer token. It can start this routine and nothing else. Regenerate gives a new one, and anything still using the old one stops working.
- Text with the call. The request can carry a JSON field named text (see Sizes and limits for its length), and no file. Mapstack treats the text as data, and acts on it only when the instructions say to.
The call starts the run and returns. It does not wait for the result or send it back. The run acts as the Creator who made the routine, whoever sent the call.
Limits
| Limit | |
|---|---|
| Schedules | At most once an hour |
| After a dataset edit | No sooner than 5 minutes after the last edit |
| Runs a day | 50 for the workspace, across all its routines. The Routines page shows the count, which starts again at midnight UTC |
| Runs at once | Two runs of the same routine never overlap, and nor do runs of routines that watch the same dataset. A run that would overlap waits, then starts |
When a routine does not run
- It is paused. It does not run on its schedule, and a call from another system is refused. Switch it back to Active.
- The dataset it watched was deleted. The routine's page says that way of running can no longer work. Edit the routine and remove it.
In these cases a run is recorded on the routine's page as failed, with the reason:
- The day's 50 runs are used. Runs start again after midnight UTC.
- The Creator who made it has used their allowance. See Your allowance.
- The Creator who made it has left, or can no longer make things in the workspace. A routine runs as the person who made it, and editing it does not change that. Someone with a Creator seat sets up a new one.
- The workspace is on Free. Routines need a Creator seat on a paying workspace.
Where is Custom? The form offers Custom only on a routine that already has a custom schedule. It takes a cron expression in UTC, and still runs at most once an hour.