# Automations


Most of what a site does for you happens while you are not looking: someone signs up
and the welcome sequence starts; a student finishes a module and gets the next one; a
hand-in lands and you hear about it. An automation is how you say what should happen
when — once — and let the site do it every time after.

On Omumu an automation is a small diagram: a trigger, the steps that follow, and the
lines between them. You can draw it in the builder or describe it to your assistant,
which writes the same diagram through the automation tools, checks it, and switches it
on. This chapter explains the pieces, shows the common automations in both forms, and is
plain about the one awkward fact of the current design: some of the wiring on your site
lives outside the builder, and the chapter tells you where to look for it. A path such as
*Settings → Automations* names a group in the admin's navigation and the page under it.

## Concepts

**Trigger, steps, connections.** Every automation starts with one trigger — the thing that
happens — and continues through steps joined by connections. A step either acts (start a
sequence, apply a tag, enrol in a course) or decides (*Has Tag* splits the flow into a yes
and a no branch). A *Wait* step holds the flow for a duration before the next step. The
diagram has no loops: a contact enters at the trigger and runs to the end.

**Triggers you can use.** Someone visits a page, submits an opt-in form, buys an offer,
gets a tag, watches a given share of a video lesson, completes a module or a course,
hands in work on an assignment, has that work rated by the AI or reviewed by your staff,
or finishes a quiz with a result (and an email address — anonymous quiz-takers never
trigger anything).

**Steps you can use.** Start or stop an email sequence, apply or remove a tag, grant
access to a course, unlock one module of a sequentially gated course, wait, and *Notify
Site Staff* — an email to one of your site's staff with a digest of what triggered the
run. There is deliberately no "send one email" step: write the email as a one-email
sequence and start that. Nothing an automation sends goes to an address outside your
staff except through a sequence, which is what keeps automations from becoming a mail
cannon.

**Tags are the glue.** A tag is a label on a contact, and it is also the one thing every
part of the platform can both set and react to: a form, a quiz result and an automation
can all apply one, and *Tag Applied* can start any automation. When two things need to
talk to each other, a tag is usually the way.

**Two systems, for now.** The builder is the automation engine. But some wiring predates
it and still runs on its own: the opt-in form editor's *Email Sequence* and *Course
Access* settings, and the invite's sequences, are stored as *tag actions* — "when this
tag is applied, do these jobs" — and listed on a separate page, also titled Automations
(it has no entry in the navigation yet; open `/admin/tag-actions`), by the tag's raw
name. Both systems fire. So a form can show "No
email sequence" while a builder automation starts one, and the builder knows nothing of
the form's own setting. Until the two are joined, check both when something sends twice
or not at all. (The engine's own notes call this the two vocabularies; the direction is
that new capability lands in the builder only.)

**Everything is validated before it runs.** Saving a diagram checks every step's settings
and every reference — the form, sequence, course, module, lesson, assignment, quiz or
offer it names must exist on your site — and switching it on checks again. Saving an
active automation takes effect at once.

## Hands-on

### When someone signs up, start the sequence

Mira has a "Time audit checklist" form and a welcome sequence. She says: *"When someone
submits the time-audit form, start the Welcome sequence and tell me."*

The assistant creates the automation, draws *Form Submitted (Time audit checklist) →
Start Sequence (Welcome to Automate Your Week) → Notify Site Staff (Mira)*, saves it,
runs a simulation of one sign-up to see the timeline, and switches it on.

Underneath, the authoring loop is five tools. `omumu_automation_options` lists every
sequence, course and module, tag, form, offer, quiz and staff recipient on the site,
with the settings each step type takes; `omumu_automation_create` makes an inactive
automation; `omumu_automation_generate_ids` hands out ids for steps and connections;
`omumu_automation_save` writes the whole diagram (steps with their settings, and the
connections between them) and returns any warnings; `omumu_automation_simulate` plays a
scenario — "this contact submits the form at t0" — against all of the site's
automations in memory and returns what would happen and when, without sending anything;
`omumu_automation_activate` switches it on or off. `omumu_automation_get` and
`omumu_automation_list` read what exists. There is no delete tool; delete in the admin.

In the admin: *Settings → Automations → Create New Automation* asks for a name and opens
the builder: a full-screen canvas with a palette of triggers, contact actions and
utilities on the left. Click or drag a step onto the canvas, join steps by dragging
between their connection points, select a step to fill in its settings, *Save*, then
*Activate*. The builder has its own *Back* link; it does not show the admin header or
navigation.

Two honesty notes for exactly this automation. The form editor has its own *Email
Sequence* setting that does the same thing through a tag action — pick one path, not
both, or the contact is subscribed twice. And every opt-in submission already emails the
site's support address, whether or not you add *Notify Site Staff*; there is no switch for
that email yet.

### Celebrate a finished module

Mira says: *"When someone completes Week 1, tag them 'week-1-done' and start the Week 2
teaser sequence."*

*Module Completed (Automate Your Week, Week 1) → Apply Tag → Start Sequence*. The same
shape works for *Course Completed*, for *Video Watched* at a chosen percentage of a
lesson, and for *Purchase Made* on an offer. On a sequentially gated course the next
module opens by itself when the previous one is complete; *Unlock Module* exists for the
case where you want to open a module for another reason — a hand-in reviewed, a tag
earned.

### Get told when something happens

Mira says: *"Email me when a student hands in the Week 1 assignment, and again if the AI
rates it below 5."*

*Submission Received (Your time audit) → Notify Site Staff*. The email says what
triggered the run. *Submission Rated* and *Submission Reviewed* trigger the same way;
the recipient must be a Headmaster or staff member on the site, and the address is checked
again at send time. The Teaching & Feedback chapter covers the built-in hand-in emails
that need no automation.

### Branch on a tag, wait before you act

Mira says: *"Two days after someone gets the checklist, if they haven't bought, start the
offer sequence."*

*Form Submitted → Wait (2 days) → Has Tag (customer)*, with the *no* branch going to
*Start Sequence*. "Customer" here is a tag the purchase automation applies; that is the
tag-as-glue pattern. Wait takes a duration; the simulation shows you whether a purchase
during the wait changes the outcome, because all of the site's automations run together
in it.

### Try it before it runs

In the builder, *Test Run* takes the email of an existing contact and a trigger and walks
the diagram step by step, saying what would execute without doing it. Over the
connection, `omumu_automation_simulate` does the same for several contacts and several
events on one timeline. Once live, the *Executions* page under each automation lists
every run with its contact, status and timing, and expands to the steps.

### What you cannot do yet

Stated plainly: there is no send-one-email step, no branching on email opens or clicks,
no scheduled or manual trigger and no inbound-email trigger (those belong to a workflow
family not offered to creators), and no outbound webhook. Your assistant cannot delete
an automation; do that in the admin. The tag-actions page lists wiring by raw tag names, and
the form editor does not show which builder automations its submissions start. And the
built-in email to the site's support address on every form submission cannot be switched
off.

## Reference

### `omumu_automation_activate`

Activates or deactivates an automation. Active automations will trigger when their conditions are met. Before activating, run automation_simulate for each contact journey that matters and resolve any timing-trap warnings from the save/activate response — activation is the last step of the authoring loop (save, check warnings, simulate, activate).

- **Write category:** standard write
- **Access:** requires the `AUTOMATION_WRITE` permission

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `active` | boolean | no | true to activate, false to deactivate (default: true) |
| `automationId` | string | yes | The automation ID |

### `omumu_automation_create`

Creates a new automation (inactive by default). Recommended authoring loop: 1) automation_save the nodes and connections, 2) read any timing-trap warnings in the save response, 3) automation_simulate the contact journeys that matter (especially 'contact does X, then Y during a delay'), 4) only then automation_activate.

- **Write category:** standard write
- **Access:** requires the `AUTOMATION_WRITE` permission

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | no | Description of what this automation does |
| `name` | string | yes | The automation name |

### `omumu_automation_generate_ids`

Generates unique IDs for use when creating new nodes and connections in canvas state

- **Write category:** standard write
- **Access:** requires the `AUTOMATION_WRITE` permission

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `count` | integer | no | Number of IDs to generate (default: 5, max: 50) |

### `omumu_automation_get`

Gets an automation with its full canvas state (nodes, connections, configs). Use this to inspect or modify an existing automation.

- **Write category:** read-only
- **Access:** requires the `AUTOMATION_READ` permission

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `automationId` | string | yes | The automation ID |

### `omumu_automation_list`

Lists all automations for the current site with their status

- **Write category:** read-only
- **Access:** requires the `AUTOMATION_READ` permission

No parameters.

### `omumu_automation_options`

Returns all available sequences, courses (with lessons), tags, forms, offers, quizzes, staff recipients, and supported node types. Use this to find valid IDs when building automation configs. Each supported node type carries a settings array describing its config keys: key, required, type, allowed values (when enumerated), and refersTo (which list above an id-valued key must be found in, e.g. "sequences" or "courses[].modules"). quizzes lists the site's quizzes (id + name) for the quiz_completed trigger. staffRecipients lists who may receive notify_site_staff emails (name + email); defaultRecipient is the authoring user's email. There is no send_email node: to send a single email to a contact, create an email sequence containing one message with zero initial delay and start it with the start_sequence action.

- **Write category:** read-only
- **Access:** requires the `AUTOMATION_READ` permission

No parameters.

### `omumu_automation_save`

Saves the full canvas state (nodes + connections) for an automation. Saving takes effect immediately, including on an already-active automation — there is no need to deactivate first. Canvas state format: {"nodes": [{"id": "...", "type": "tag_applied", "x": 0, "y": 0, "config": {...}}], "connections": [{"id": "...", "from": "nodeId", "to": "nodeId", "type": "default"}]}. Use automation_generate_ids to get IDs for new nodes/connections. Use automation_options to get valid IDs for sequences, courses, tags, forms, offers, quizzes, staff recipients — and, for every node type, its settings (config keys, required or optional, allowed values, and what catalog list an id refers to). Completion triggers (module_completed, course_completed) are side-effects only (celebrate, tag, follow up) — on a SEQUENTIAL course the next module unlocks by itself, so do not wire module_completed to unlock_module for gating. Pair submission_received with unlock_module to open the next module when a student posts their work. Pair quiz_completed (or form_submit) with notify_site_staff to email a staff member a digest of every answer, the bucket, and the score. There is no send_email node: to send a single email to a contact, create an email sequence containing one message with zero initial delay (omumu_email_sequence_create, initialDelay PT0S) and start it with the start_sequence action. The response includes timing-trap warnings (e.g. stop-sequence-before-delayed-start: a STOP_SEQUENCE may fire before a WAIT-delayed START_SEQUENCE and silently no-op; fix by starting the sequence immediately and moving the delay into the sequence's initialDelay). Warnings are non-blocking, but do not activate past one without first proving the funnel correct with automation_simulate.

- **Write category:** standard write
- **Access:** requires the `AUTOMATION_WRITE` permission

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `automationId` | string | yes | The automation ID |
| `canvasState` | object | yes | The full canvas state JSON with nodes and connections |

### `omumu_automation_simulate`

Runs a scenario against the site's automations in memory (no emails sent, nothing written) and returns the effect timeline plus any timing-trap warnings. All of the site's automations run together so cross-flow races (e.g. a purchase stopping a delayed abandonment sequence) are visible. 'events' is an array of {"at": duration, "trigger": triggerType, "contact": alias}: 'at' is a duration from t0 as ISO-8601 (PT5M) or a friendly form (0s, 5m, 1h, 2d, 1w); 'trigger' is a contact trigger type (form_submit, purchase, tag_applied, page_visit); 'contact' is an optional alias (default 'contact') so several events can describe one contact's journey. Each timeline entry is {atSeconds, at, contact, kind, target, effective}: kind is APPLY_TAG, REMOVE_TAG, START_SEQUENCE, STOP_SEQUENCE, EMAIL_SENT, ENROLL_COURSE, UNLOCK_MODULE, GRANT_ROLE or NODE_REJECTED; 'effective' is false for a no-op (e.g. a stop with no live subscription). Use this to verify a funnel behaves before activating it: don't just look for the expected effects — scan the timeline for effective=false on stops/removals and for EMAIL_SENT entries the contact should NOT receive (an ineffective STOP_SEQUENCE followed by a later EMAIL_SENT is the classic cart-abandonment race). Simulating is step 3 of the authoring loop: save, check warnings, simulate the journeys that matter, then activate.

- **Write category:** read-only
- **Access:** requires the `AUTOMATION_READ` permission

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `automationId` | string | yes | The automation ID to simulate (its site's automations all run together) |
| `events` | array | yes | Ordered scenario events: [{"at": "5m", "trigger": "purchase", "contact": "buyer"}] |