> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflows
> Automate emails, Slack messages, credits and entitlements when something happens in Metrifox, or on a schedule.
## **Overview**
Workflows automate work that would otherwise be manual. A workflow starts from a **trigger** (something happens in Metrifox, or a schedule is reached), then runs one or more **automations**. Each automation can check conditions and then take actions such as sending an email, posting to Slack, issuing a credit note or assigning a promotional entitlement.
Navigate to **Workflows** in the main menu to see and create workflows.
Workflows belong to an environment. Workflows you create in **Sandbox** are separate from the ones in **Production**, so you can build and test in Sandbox first. See [Getting Started in Minutes](/quickstart) for how the two environments differ.
## **The Workflows List**
The list shows each workflow's name, status, trigger type (**Event** or **Scheduled**), the trigger and when it was created. Use the **All**, **Active** and **Inactive** tabs to filter, or search by workflow name.
| Status | Meaning |
| :- | :- |
| **Draft** | The workflow has never been published, so it does not run. |
| **Active** | A version is published and the workflow runs when its trigger fires. |
| **Inactive** | The workflow has been deactivated and does not run until a version is published or activated again. |
## **Creating a Workflow**
1. Navigate to **Workflows** and click **Create workflow**.
2. Choose how the workflow starts:
* **Metrifox events**: runs when something happens in your account.
* **Schedule**: runs at a specific time or on a recurring interval.
3. Set the trigger (see [Triggers](#triggers)), then click **Create workflow**.
4. In the builder, click **Add automation** and define what the workflow does (see [Automations](#automations)).
5. Use **Run test** to try it without side effects (see [Testing a Workflow](#testing-a-workflow)).
6. Click **Publish** to make it live (see [Publishing and Versions](#publishing-and-versions)).
Click the workflow name at the top of the builder, or use **Actions → Edit name**, to rename it. New workflows are named "Untitled workflow".
## **Triggers**
### **Event triggers**
Select **Metrifox events**, then choose the event that starts the workflow. Use the search box to find an event quickly.
| Category | Event | Runs when |
| :- | :- | :- |
| **Credit** | Credit is purchased | A customer purchases credits. |
| **Customer** | Customer is created | A new customer record is saved. Useful for onboarding sequences and welcome communications. |
| | Customer is updated | Any field on an existing customer record is modified. |
| | Customer is deleted | A customer record is permanently removed. |
| **Order** | Order is created | A new order is placed. Useful for fulfillment workflows, confirmations or finance notifications. |
| **Subscription** | Subscription is created | A new subscription is provisioned for a customer. |
| | Subscription is cancelled | A customer's subscription is cancelled. |
| | Subscription cancel is scheduled | A subscription cancellation is scheduled. |
| **Invoice** | Invoice is created | A new invoice is generated for a customer. |
| | Invoice is paid | A customer pays an invoice in full. Invoices settled entirely by credits, or with nothing to pay, do not trigger it. |
| **Feature** | Feature limit is approaching | A customer's usage reaches the configured warning threshold for a feature. |
| | Feature limit is exceeded | A customer's usage goes beyond their feature entitlement. |
| **Dunning** | Dunning process is started | A failed payment starts a [dunning](/dunning) sequence. |
| | Dunning retry attempt is failed | A payment retry within the dunning sequence fails. It runs on every failed retry. |
| | Dunning process is completed | A dunning sequence ends, either through successful recovery or a final failure. |
Several of these events are also available as [webhooks](/webhooks) if you prefer to handle them in your own systems: customer created, updated and deleted, order created, subscription created, cancelled and cancel scheduled, invoice created, and credit purchased.
### **Schedule triggers**
Select **Schedule** to run a workflow at a specific time or on a recurring interval. Choose a **Frequency**, then fill in the fields that frequency needs:
| Frequency | Fields |
| :- | :- |
| **Once** | **Run date** (today or a future date) and **Time** |
| **Daily** | **Time** |
| **Weekly** | **Day of week** and **Time** |
| **Monthly** | **Day of month** and **Time** |
| **Yearly** | **Month of the year**, **Day of month** and **Time** |
### **Changing a trigger**
You can change a workflow's trigger later, but doing so deletes all of its existing automations and paths, and deactivates the workflow if it is active. You are asked to confirm before this happens.
## **Automations**
A workflow can have several automations, and each one decides independently what to do. Click **Add automation** to add one, give it a description (for example "Handle onboarding for new Pro customers"), then define its paths.
Each automation is made of **paths**:
| Path | What it does |
| :- | :- |
| **Default (Always)** | Runs its actions every time the trigger fires. Use this when there are no conditions. |
| **If / Then** | Runs its actions only when its conditions are met. |
| **Else if** | Another conditional path, checked when the paths before it did not match. |
| **Otherwise** | Runs when none of the other paths' conditions are met. |
### **Conditions**
Click **Start by adding a condition (If/then)** to build a condition. Each condition has three parts:
* **Field**: the value to check. The list is searchable and shows each field's type. For customer events, it is the fields of the customer record.
* **Operator**: how to compare it.
* **Value**: what to compare against.
| Operator | Meaning |
| :- | :- |
| **is** | Equal to |
| **is not** | Not equal to |
| **greater than** | Greater than |
| **less than** | Less than |
| **greater than or equal** | Greater than or equal to |
| **less than or equal** | Less than or equal to |
Click **Add another condition** to combine checks, joined with **AND** or **OR**. Use **Add condition group** to group related checks. Date fields can be compared with a date picker or with relative dates such as "Start of month" or "7 days ago".
### **Actions**
After the conditions, click **Add actions** (or **Add a default action** for an Always path) and choose what happens. You can add several actions to one path with **Add another action**. Click **Add this flow** to save.
| Action | What you set |
| :- | :- |
| **Send Email** | **Recipient email**, **Email subject**, optional **From name**, optional **Reply to**, and the **Email body**. |
| **Send Slack Message** | The Slack **Channel id** and a **Text template**. Connect Slack first under **Integrations → Notifications**. |
| **Assign Credit** | **Customer key**, **Amount**, **Currency**, **Title** and an optional **Description**. This issues a credit note to the customer. See [Credit Notes](/credit-notes). |
| **Assign Promotional Entitlement** | The **Customer keys** (separate several with commas) and the **Promotional entitlement** to assign. See [Promotional Entitlements](/promotional-entitlement). |
### **Using variables**
Every text field has an **Add variable** button. Variables are placeholders that Metrifox replaces with real values from the event that started the workflow when the action runs. They are written like this:
```text theme={null}
{{context.customer.primary_email}}
```
For customer events, the variable list includes the customer record's fields, such as `primary_email`, `display_name`, `customer_key` and `currency`, and workspace figures such as `customer_count` and `active_subscription_count`. Use the search box in the picker to find a variable.
For example, a welcome email could use `{{context.customer.primary_email}}` as the recipient, `Welcome, {{context.customer.display_name}}` as the subject, and `Hi {{context.customer.display_name}}, welcome to our platform.` in the body.
### **Writing emails**
The email body has two formats:
* **Rich text**: a visual editor with bold, italic, underline, bullet and numbered lists, headings, quotes and images (paste an image URL and press Enter).
* **HTML**: your HTML is sent as-is. Use the variable button to personalize it.
Click **Preview** to see the email. Placeholders are shown as written in the preview and are replaced with each recipient's real values when the email is sent.
## **Testing a Workflow**
Click **Run test** to try a workflow before you publish it. The test dialog has:
* **Dry run (skip actual actions)**: on by default. A dry run goes through the workflow's logic and shows what would happen, without sending emails, posting to Slack or changing any customer. Turn it off only when you want the actions to actually run.
* **Context data**: sample data in JSON that the workflow runs against, pre-filled with a sample record for the trigger. Edit any field to test different scenarios.
Click **Run Test** to see the results. Each automation shows whether it **Completed**, and each action step shows its status and how long it took. If the data matches none of your paths, you see "No branches matched the given context". Invalid JSON in the context data is rejected.
With **Dry run** turned off, the test runs the actions for real, so it can send emails and Slack messages, issue credit notes and assign entitlements using the context data.
## **Publishing and Versions**
A workflow is a **draft** until you publish it.
1. Click **Publish**.
2. Confirm with **Publish draft**.
The workflow becomes **Active** and starts running when its trigger fires.
Workflows are versioned (**v1**, **v2** and so on). Use the version selector beside the workflow name to see each version, whether it is a **Draft** or **Published**, and when it was saved.
### **Editing a live workflow**
You cannot change a published version directly.
1. Open the workflow and click **Edit**.
2. Confirm **Create draft and edit**. Your changes are saved as a new draft version.
3. Make your changes, then **Publish** again.
The workflow keeps running on the current published version until you publish the new draft. When you publish, the previous version is archived and stays in the version history. To throw away unpublished changes, click **Discard draft**. This cannot be undone.
### **Deactivating and reactivating**
* **Deactivate** (from **Actions** or the list's **⋮** menu) archives the published version. The workflow stops running until a new version is published.
* When you view an archived version, you can choose **Activate this version** to bring it back, or **Go back to published version**.
## **Monitoring Runs**
Click **Activity** on a published workflow to see its **Runs**. Each run shows its **Status** (**Pending**, **Running**, **Completed** or **Failed**), the **Rule** that ran, its **Duration** and when it **Started**. Open a run to see its **Action steps**, such as who an email was sent to.
Until the trigger fires, the page shows "No runs yet". The **Builder** tab returns you to the canvas.
## **Deleting**
* **Delete a workflow** from **Actions → Delete** or the list's **⋮** menu. This cannot be undone.
* **Delete an automation** or a path from its trash icon in the builder. This also cannot be undone.
## **Example: welcome new customers**
1. Create a workflow with the **Customer is created** event.
2. Add an automation with a **Default (Always)** path and a **Send Email** action. Use `{{context.customer.primary_email}}` as the recipient and a subject such as `Welcome, {{context.customer.display_name}}`.
3. Click **Run test** with **Dry run** on and check that the automation completes.
4. Click **Publish**.
From then on, every new customer receives the email, and each send appears under **Activity**.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.