Build

Events

An event is something that happens in your app: a deal is won, a form is sent, a build fails. You declare your events in your manifest and report them when they happen. In a space where your app has a tab, people can make a trigger that starts a task when your event is reported: "when Acme CRM says a deal was won, a task to thank the customer, for Ada".

#How it goes

1. Something happens in your app, and you report it: from your tab's page, or from your server while it answers an action.
2. The workspace checks it against your manifest: the event's name, and its fields.
3. Triggers in that space listening for it start their task, for the person who made the trigger. The task says what happened, and can use your event's fields.

Your app is never told about the task: triggers are the space's own.

#Declaring an event

{
  "events": {
    "deal_won": {
      "description": "A deal was won",
      "fields": {
        "title": { "type": "string", "required": true, "description": "The deal" },
        "amount": { "type": "number" },
        "stage": { "type": "string", "enum": ["new", "renewal"] }
      }
    }
  }
}

• description is what people see when they choose your event in a trigger: say what happened, in a few words.
• fields take the same types as collections, and are checked when you report the event.
• A field called title, name or subject names what the event is about, in the trigger's history.

See The manifest for every rule.

#Reporting from your tab

import { connect } from "@tabs-and-spaces/sdk";

const tands = await connect();
await tands.emit("deal_won", { title: "Globex", amount: 12000, stage: "renewal" });

It's reported for the person looking, in the space your tab is in. Only people in the space can report events (someone only looking at a public space can't).

#Reporting from your server

While your server answers an action, it can report events with the key the action's request carries:

import { dataClient } from "@tabs-and-spaces/sdk/server";

const data = dataClient(body);
await data.emit("deal_won", { title: body.input.title });

#In a trigger

In a Tasks tab, When… → Something happens in an app lists the space's Custom tabs whose app reports events. People choose your event, and optionally a value one of its fields must have ("only when stage is renewal"). The task's title and description can use your fields by name, like {{title}} or {{amount}}, as well as {{summary}} (what it's about) and {{details}} (every field, one per line).

#Your actions in workflows

The same space's workflows can use your actions as steps: Use an app picks one of your Custom tabs here and an action, with its inputs written out (they may say {{previous}}, the last step's result, and {{task}}). An action that changes something asks the person the workflow runs for first, on a card in the task's thread; one that only reads runs at once. What your server answers becomes the next step's {{previous}}.

#Limits

An app can report up to 60 events a minute in a workspace; more are refused (429). A trigger that fires more than 20 times in an hour pauses until someone resumes it.