# Form workflows

URL: https://docs.sparklayer.io/help/forms/workflows

Automate SparkLayer Forms with workflows: run steps such as emails, conditions, API requests and customer creation when an entry is submitted or updated.

> **Quick summary**
>
> - A workflow is an automation that runs when something happens on a form, such as an entry being submitted or an admin clicking an **Approve** button. Typical uses are trade account approvals, internal notifications, order request processing and routing by customer data.
> - You build workflows on a visual canvas, with no code, from the **Workflows** tab of the form builder at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). The form templates come with workflows ready to use, such as the **Approve/Reject workflow** on the Wholesale Registration Form. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - Creating and editing workflows needs the Growth plan or above (see [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md)).
> - Workflows are part of the form version: changes only go live when you [publish](https://docs.sparklayer.io/help/forms/versions.md#publish-changes) the form.

## How it works

Every workflow starts with a **trigger**: the event that starts it. **Steps** follow: the actions it performs. **Connections** (paths) link the steps together on the canvas.

The shape of a workflow:

1. **Trigger**: For example, Form submitted.
2. **Step**: For example, a Condition that checks an answer.
3. **Step**: For example, Create customer.
4. **End**: The workflow run is recorded against the entry.

Steps run one after another, in order (synchronously). While it runs, a workflow can use the entry's answers, the form structure, outputs from earlier steps, and data tables or other stored values. It reads them through [data references](https://docs.sparklayer.io/help/forms/data-references.md).

The **Workflows** tab lists the form's workflows, each with **What it does** and a **Status** (such as **On**). Click **View** to open one. Forms made from a template already have these:

| Workflow | What it does |
| --- | --- |
| **Approve/Reject workflow** | Creates the customer in Shopify with the group's tag and emails them, or sends a polite no. (Wholesale Registration Form) |
| **Prevent duplicate email registrations** | Stops a second application from an email that already has an account. (Wholesale Registration Form) |
| **Notification of submission** | Emails your team when an entry comes in. |

## Example workflows

Most forms need one of these patterns. Build them with the steps in [Create a workflow](#create-a-workflow).

### Approve a trade account application

Add a decision and a button as [internal fields](https://docs.sparklayer.io/help/forms/setup.md#add-internal-fields). The button is a **Workflow trigger button** field. Then run a workflow when your team clicks it:

Approve a trade account application:

1. **Internal button clicked**: Your team approves the entry.
2. **Create customer**: Creates the customer in your store, with their customer group's tag.
3. **Send email**: Tells the customer their account is ready.

The **Wholesale Registration Form** [template](https://docs.sparklayer.io/help/forms.md#start-from-a-template) comes with this set up. Its **Approve/Reject workflow** creates the customer in Shopify with the chosen customer group's tag, so they see trade prices as soon as they sign in. You approve or reject from the entry: see [Approve or reject an application](https://docs.sparklayer.io/help/forms/entries.md#approve-or-reject-an-application).

For a full walkthrough of an approval process, see the [account credit request form](https://docs.sparklayer.io/help/forms/account-credit-request-form.md).

### Notify your team

Email your team about each new entry:

Notify your team:

1. **Form submitted**: Trigger
2. **Send email**: An internal email to your team.

### Route by answer

Send an entry to a different team depending on an answer:

Route by answer:

1. **Form submitted**: Trigger
2. **Condition**: Category equals "Sales"?
3. **Send email**: True path: the sales team. False path: the support team.

### Multi-step approval

Work out a value, record it, then ask for approval only when it's needed:

Multi-step approval:

1. **Form submitted**: Trigger
2. **Calculation**: Work out totals.
3. **Update entry or row**: Write the totals to the entry.
4. **Send email**: Confirm to the customer.
5. **Condition**: If the total is over a threshold, request approval.

### Reset a dependent field

Use this when one field controls the valid options for another. For example, a customer picks a country, and a second field shows that country's regions. If they change the country, the region they chose may no longer be valid, so the workflow clears it.

Reset a dependent field:

1. **Answer updated**: Watching Country.
2. **Clear answer**: Target: Region.
3. **Customer chooses again**: They pick a valid region for the new country.

Other pairs this suits: country and region, customer group and available products, product category and product, department and approval reason, order type and required supporting details.

## Create a workflow

1. Open your form from **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)) and go to the **Workflows** tab.
2. Click **Create workflow**. The canvas opens.
3. To rename the workflow, click the pencil icon next to its name at the top left.

### Add a trigger

1. Click **+ Add Trigger**.
2. Choose the trigger type (see [Triggers](#triggers)).
3. Set its options, for example which answers to watch for **Answer updated**.

### Add steps

1. Click the **+** on a trigger or step, or drag its path handle out onto the canvas. 
2. Choose a step type (see [Steps](#steps)).
3. Set up the step in the panel on the right. Click **Expand** for more room, or **Delete step** to remove it.
4. Connect further steps as needed. Steps with several paths, such as **Condition**, let you branch the workflow.

Click **Arrange steps** to tidy the layout. **Disable** turns the workflow off without deleting it. 

### Publish the workflow

Workflow changes stay in the draft until you publish the form.

1. Check your changes are saved.
2. Click **Publish** and include **Workflows** in what you publish.

Entries created before you publish keep using the workflows from their own version. See [How versions affect entries](https://docs.sparklayer.io/help/forms/versions.md#how-versions-affect-entries).

## Check workflow runs

SparkLayer records a run every time a workflow runs. Check it to see what happened.

1. Open an [entry](https://docs.sparklayer.io/help/forms/entries.md).
2. Go to **Workflow Runs**.
3. Select a run to see its details.

| Detail | What it shows |
| --- | --- |
| **Start and end time** | When the run happened. |
| **Duration** | How long it took. |
| **Status** | Completed or failed. |
| **Step logs** | Each step's inputs, outputs and results. |

### Debug a workflow

1. Open the workflow run.
2. Review each step. You can see exactly which path the run took, including conditional branches.
3. Check error messages and conditions that weren't met.
4. Fix the workflow or the entry data.

## Triggers

| Trigger | Runs the workflow when |
| --- | --- |
| **Form submitted** | A form is completed and submitted. |
| **Entry created** | A new entry is created, which is when someone starts filling in the form. |
| **Answer updated** | One or more selected answers change. |
| **Internal field updated** | One or more selected internal fields change. |
| **Page loaded** | A selected form page loads. |
| **Button clicked** | A button field on the form is clicked. |
| **Internal button clicked** | An admin clicks a button in the internal fields. |
| **API request** | It's called by an API request. |

For example: send an internal notification when a form is submitted, recalculate a value when an answer changes, start an approval when an admin clicks an internal button, update internal fields when review data changes, or start a workflow from another system with an API request.

## Steps

| Step | What it does |
| --- | --- |
| **Send email** | Sends an email to one or more recipients. |
| **Condition** | Branches the workflow based on rules. |
| **Calculation** | Calculates values using numbers, formulas and data references. |
| **For each loop** | Repeats a set of steps for each item in a list, such as line items, repeatable fields or data table rows. |
| **Update entry or row** | Updates a field on a form entry or a data table row. |
| **Clear answer** | Clears one or more values from a form entry or data table row, for example when related data changes. |
| **Read/Unread entry** | Marks an entry as read or unread. |
| **Create entry or row** | Creates a form entry or data table row. |
| **Delete entry or row** | Deletes a form entry or data table row. |
| **API request** | Sends data to another system, such as your ERP or CRM. Usually set up by a developer. |
| **Get customer** | Finds an existing SparkLayer customer by ID, platform ID or email. |
| **Create customer** | Creates a customer in your eCommerce platform and SparkLayer. |
| **Update customer** | Updates an existing SparkLayer customer. |

### Choose the right step

| Step | Use it when |
| --- | --- |
| **Condition** | The workflow needs to make a decision. |
| **Calculation** | You need totals, scores, discounts or other numbers. |
| **Update entry or row** | You want to write a value to the current entry, an internal field, another form's entry or a data table row. |
| **Clear answer** | A previous value is no longer valid, such as a selected option after the field that controls its options changes. |
| **For each loop** | You need to process every item in a list, such as repeatable fields, line items or filtered data table rows. |
| **API request** | Another system needs the form or workflow data. |
| **Get customer**, **Create customer**, **Update customer** | You need to find, create or update customer accounts. |

### Step paths

Some steps have more than one path out. The path decides what happens next.

| Step | Paths |
| --- | --- |
| **Condition** | True, False |
| **For each loop** | Loop body (for each item), After loop |
| **API request** | Success, Error |
| **Get customer** | Found, Not found, Error |
| **Create customer** | Success, Error |
| **Update customer** | Success, Error |
| Most other steps | Next |

For example, an API request continues on the **Success** path if the request works, or follows the **Error** path if it fails.

## The workflow canvas

You build a workflow by placing and connecting nodes on the canvas.

| Action | How |
| --- | --- |
| **Pan** | Click and drag the canvas. |
| **Zoom** | Scroll, or use the zoom controls at the bottom left. |
| **Select a node** | Click it. |
| **Select several nodes** | Shift-click, or drag. |

Triggers and steps appear as nodes, joined by connections. Click a node to edit its settings, see its input and output data, delete it or reconnect it. To connect steps, drag from one node to another. A step can branch into several paths:

| Path | Meaning |
| --- | --- |
| **Next** | Continue to the next step. |
| **True / False** | Conditional branching. |
| **Error** | Runs when a step fails. |
| **Loop** | Used in repeated processes. |

## Tips

- Keep each workflow to one process, and name it clearly. Don't combine unrelated automations.
- Before publishing, use the **Preview** tab, submit test entries and check the workflow runs for errors.
- Plan for errors: add **Error** paths where needed, log important outputs, and protect critical workflows.
- Avoid unnecessary API calls and very long chains of steps.