Automations

An automation says what happens when an event fires: send an email, create an in-app notification, or add the person to a list or take them off one. Admins set them up on the Automations page; your code can add events of its own.

What it is

Arc CMS and your code emit events, such as user.signed_up. Each event can have a mapping: an on/off switch and one or more rules. A rule has a name, an optional condition, and actions. When the event fires, every rule that applies runs its actions.

Arc CMS also emits user.deleted when a user record is deleted, and user.signInDeleted when a sign-in is deleted outside Arc CMS while its record stays. They carry no email address, so their rules cannot send email or change lists. They, and any event your own code emits, show on the page only once a mapping for it exists.

Emails from a rule go through the Email engine: the master switch, the template's active switch and a disabled contact apply to every rule email. A marketing email also needs consent and is blocked by any suppression entry; a transactional one is blocked only by a bounce or a complaint. Rule emails have no switch of their own under Email Features.

Turn it on or off

Automations are always on: they are core, not a switchable feature. Each event has its own switch on the page, and each rule can be turned off on its own. Every event starts switched off, so nothing runs until an admin turns it on. With Email marketing on, the Event mappings tab on Email, Announcements switches events on and off too.

Events of a feature that is off are not offered, and never fire. Their saved mappings stay, for when the feature is on again. Without Audience, list actions are hidden, and a saved list action is recorded as not run.

Set it up

Nothing to set up beyond a working Email engine for rules that send email. The built-in events are listed from the start, switched off. An event's mapping is created by its first save, or, for the built-in events, when the email system's defaults are seeded (opening Email, Announcements does this). The seeded user.signed_up and payment.succeeded mappings come with a Default rule that adds the person to All Users or All Customers.

Use it

1. Open Admin, Settings, Automations (/admin/settings/automations) and open an event.

2. Turn on Run this event's rules.

3. Click Add rule, name it, and choose its actions: tick Send an email and pick a template and its Email type (transactional or marketing); tick Create a notification, pick a type and write the title, message and optional link; or pick lists under Add to lists or Remove from lists.

4. For a field change (app_user.changed.<field>), set a condition on the old value (was), the new value (becomes), or both: anything, exactly, any of, or none of. Separate several values with commas.

5. Save. Each event saves on its own, and a change saved meanwhile on another event is kept.

A rule needs a name and at least one action, an email needs a template, and a notification needs a type and a title; the page will not save until they are there.

Conditions compare values as text and ignore case, and treat empty, null and missing as the same empty value. So exactly true matches a stored true, exactly pro matches Pro, and any of: , free matches a free plan written either way.

An email template, and a notification's title and body, can use the event's data as ##KEY## tags, for example ##WAITLIST_ID## in an email on waitlist.joined. Only events with a userId (user.signed_up, the payment events, or your own) can create a notification.

Extend it

Emit your own events from your Cloud Functions in functions/src/custom/. The event is stored and processed by onAppEventCreate; the admin decides what it does:

import { emitAppEvent } from '../email-core/appEvents.js';

await emitAppEvent('order.shipped', {
  userId: uid,                          // the Firebase Auth uid, for notifications
  contactEmail: email,                  // where an email goes
  data: { TRACKING: 'AB123' },          // fills ##TRACKING## in a notification
}, { id: `order-shipped-${orderId}` }); // optional: the same id is processed once

To make the event appear on the Automations page, give it a mapping: add a key for it under mappings in the Settings/event_mappings document, for example "order.shipped": { "enabled": false, "rules": [] }. From then on, admins edit it like any other event.

An event with no userId gets no notification. An event with no email address (neither contactEmail nor a user with an email) sends no email and changes no lists.

What it stores

The function is onAppEventCreate, a Firestore trigger on AppEvents, deployed as arccms-onAppEventCreate. See Data model and Cloud Functions.

Who can do what

Troubleshooting

Every processed event records what happened in results on its AppEvents document. Read it in the Firebase console, or for app user events on the person's Recent activity. status is at the top; each rule's outcome is under its name, for example results['Rule 1'].email.