Cron jobs

A CronJob runs a hook on a schedule, once for every workspace that has your app. In its action, settings, context.org and storage.org are that workspace's:

app.ts

import { CronJob, settings } from "@examplary/apps";
 
app.addCapability(
  new CronJob({
    id: "sync-rosters",
    schedule: "0 3 * * *", // every night at 03:00 UTC
    action: async () => {
      await syncRosters(settings.apiToken);
    },
  }),
);

Property	Description
`id`	Unique within your app. Keep it the same between versions.
`schedule`	A cron expression with 5 fields, in UTC. Examplary checks schedules every 5 minutes.
`action`	Runs for each workspace.
`orgs`	Optional: the workspaces to run for, see below. All of them by default.

There's no user behind a cron job, so with API scopes, context.examplary acts as your app, with an admin's access to the workspace.

An action can run for up to 299 seconds, with 1 GB of memory: longer than other hooks. When it throws, that workspace's run fails, and the others carry on. A failed run isn't retried; the action runs again at its next scheduled time.

Choosing the workspaces

Often only some workspaces need the work, like those that turned a feature on. Return their IDs from orgs, which runs once before every scheduled run. It runs for your own workspace, so read the list from storage.app:

app.ts

import { CronJob, settings, storage } from "@examplary/apps";
 
const syncing = storage.app.collection<{ org: string }>("syncing-workspaces");
 
app.addCapability(
  new CronJob({
    id: "sync-rosters",
    schedule: "0 3 * * *",
    orgs: async () => {
      const orgs = [];
      for await (const { value } of syncing.all()) orgs.push(value.org);
      return orgs;
    },
    action: async () => {
      await syncRosters(settings.apiToken);
    },
  }),
);

Examplary only runs the action for returned workspaces that have your app installed, so orgs can leave workspaces out, but never add any.

Trying it out

While you run dev, the Cron jobs panel of the developer toolbar lists your app's cron jobs with their last and next run. Run now runs one for your own workspace straight away; its result and logs show up in the Hook calls panel.