Browse the docs

triggers

Adds events that start macros; the extension calls emit with a payload and returns an optional cleanup.

Details #

A trigger is an event that starts a macro. You declare it under adds.triggers and implement it with trigger(id, { start, stop }). Once the extension is installed, the trigger shows in a macro's When chooser under the extension's name. Its type is <extension id>.<trigger id>.

Switchboard calls start when a macro begins waiting for the trigger, with the params the person set. Call emit(payload) each time the event happens. Each call starts the macros waiting on it. start may return a cleanup function. stop, if given, runs when the macro stops waiting, after the cleanup.

{
  "adds": {
    "triggers": [{
      "id": "every-minute", "title": "Every minute",
      "params": { "type": "object", "properties": { "label": { "type": "string" } } },
      "output": { "type": "object", "properties": { "at": { "type": "string" } } }
    }]
  }
}
import { defineExtension, trigger } from '@switchboard/sdk';

export default defineExtension({
  triggers: [
    trigger('every-minute', {
      start(ctx, params: { label?: string }, emit) {
        const t = setInterval(() => emit({ at: new Date().toISOString() }), 60_000);
        return () => clearInterval(t);
      },
    }),
  ],
});

Use setInterval and setTimeout for polling. They are the only timers the sandbox has.

The declaration and the code must match. An extension that declares a trigger it does not implement, or implements one it does not declare, is refused when it loads.

Gotchas #

  • Always return a cleanup (or write stop) for anything you start. Otherwise a timer keeps running after the macro stops waiting.

  • start has 10 seconds to return and stop has 5. Start your timers and return, do not wait inside start.

  • An unhandled error thrown from a timer crashes the extension, which restarts at most 3 times a minute. Wrap timer callbacks that can fail in try/catch.

  • Do not emit faster than the macro can run. Every emit starts the macro.

What start gets and what emit does #

  • start(ctx, params, emit): params are the trigger's settings from the macro. Throw an Error if they are unusable; the trigger then does not start.

  • emit(payload): The payload should be an object. Its fields become the macro's inputs, so emit({ count: 3 }) gives the macro {{count}}. A payload that is not an object arrives as the single input payload.

  • Same settings, one run: Macros that use the trigger with the same params share one start. Switchboard starts it for the first such macro and stops it when the last one stops waiting.

  • When it runs: start is called when a macro using the trigger is turned on or edited, not when the extension loads.

Full example #

The sample below has two triggers: one that fires every few seconds with a count, and one that fires once a day at a chosen time. Both clean up their timers. You can download it from the Full example section and edit it into your own.

See also #