> For the complete documentation index, see [llms.txt](https://learn.withessential.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.withessential.com/field-operations/workflows/build-test-and-publish-a-workflow.md).

# Build, test, and publish a workflow

Use the workflow builder to describe a customer automation in plain language, inspect the steps Essential creates, test them safely, and publish the workflow.

> **Where to find it:** Open **Automations**, then select **Workflows**, once Workflows is enabled for your business.

## Create a draft

1. Select **New Workflow**.
2. Describe when the workflow should start, which customer information it should use, and what should happen.
3. Select **Build draft**.

Essential builds only with triggers, customer data, and actions supported by the current workflow runtime. Each step shows the released contracts it uses under **Starts when**, **Reads**, and **Can do**. Review this list carefully: it is the step's actual access, not a suggested future design.

Essential also responds in **Edit with Essential** with a concise summary of what it authored and any important safeguards, approval requirements, AI costs, or unsupported parts of the request. That feedback stays with the draft so it is available when you return.

A workflow is the business process you see in the table. Its executable units are steps, and one workflow can hold several. Steps connect only through explicit hand-offs:

* A step can **start another step** immediately — the earlier step shows the later one under **Hands off to**, and the later step starts when it is handed off.
* A step can **react to another step finishing**, including filtering on whether that step succeeded or found nothing to do.
* A step can **wait** by scheduling a timer and continuing later.

A step marked **Emits a message** passes a short note to the steps that follow it. Steps cannot form a loop — Essential rejects a draft whose steps would start each other forever.

## AI-driven steps

Most steps are **Deterministic**: they run fixed logic and behave identically on every run. When a step genuinely requires judgment — interpreting a note or hand-off message, composing situation-specific wording, or deciding between actions from unstructured information — Essential can make it **AI-driven** instead. The step card shows an **AI-driven** badge and, under **Instructions the AI follows**, the exact instructions applied on every run. Refine those instructions through the chat like any other part of the step.

An AI-driven step still only ever uses the triggers, customer data, and actions listed on its card — the AI cannot reach anything the card does not show, cannot write links into messages, and treats customer data strictly as information, never as instructions. Because each run consults the AI, AI-driven steps take a little longer, and each business has a daily AI budget for workflow runs; runs beyond the budget are held and reported rather than run.

## Steps that email or text customers

When your request involves emailing or texting, Essential writes the message template as part of the step — you'll see it on the step card under **Email it sends** or **SMS it sends**. The template is the literal message with `{{ placeholder }}` slots for the values the step computes each run (a customer name, an amount, a date); everything else is fixed wording you can refine through the chat, just like the rest of the step.

When you ask for a styled email, Essential can format its body with headings, emphasis, lists, simple tables, colors, spacing, borders, and other basic inline styling. The styled preview appears on the step and in **Preview results** with the real test values applied. Emails still go out inside your business's branded frame. Links, images, scripts, stylesheets, and advanced Liquid logic are not available yet.

Sending stays under your control: publishing an emailing or texting workflow does not authorize outbound messages on its own. When a run reaches a send (or another higher-risk action) that has not been pre-authorized, it pauses and creates an **Approve / Decline** task in the Workflows folder of the Tasks inbox — nothing goes out until someone approves that exact run. See [Respond to a workflow task](/field-operations/tasks/respond-to-a-workflow-task.md). A workflow whose outbound policy has been enabled for your business sends without the approval step.

## Steps that send inspection reports

Essential can use a customer's 10 most recent submitted inspection reports and send one through the same email action available on the report page. Draft reports are never available to a workflow. When the trigger identifies a property, the step can choose the newest report for that property.

The action uses the inspection-report email template saved for your business and attaches the report's current PDF. It sends to one customer contact or email address per action. Like every outbound action, it pauses for an **Approve / Decline** task unless outbound sending has been explicitly enabled for the workflow.

## Steps that use customer custom fields

A step can read the customer custom fields configured for your business, including choice options and the selected customer's current values. It can set an existing text, number, checkbox, date, or choice value. If the field does not exist, the step can create an optional, back-office-only field first and then set its value.

Creating a field changes business-wide configuration, so the first run pauses for an **Approve / Decline** task unless higher-risk actions have been explicitly enabled for the workflow. Creation is idempotent: later runs reuse the same field by name and can add missing choice options without creating duplicates.

When a workflow starts from a custom-field change, it should set a value only when the current value is different. This lets the workflow converge without repeatedly triggering itself.

## Add or change steps

Steps are added and edited through the chat. Select **Add step** (or just ask in **Edit with Essential**) and describe what the new step should do and when it should start. Essential decomposes the request into the fewest steps that keep each one single-purpose — many requests fit one step doing several actions, so asking for "another step" may extend an existing step instead when that is the better design.

## Revise a draft

Open a draft from the Workflows table, then use **Edit with Essential** to describe the change you want in plain language. Essential keeps your request and its feedback with the draft, and replaces the displayed candidate with the revised version.

Each workflow opens at its own browser address. Select **Workflows** in the side navigation, or **Back to workflows**, to return to the workflow table.

Review the revised contracts and steps before testing. Each revision needs a new successful preview before it can be published.

Published workflows stay editable: the conversation drafts the next version while the released version keeps running. Publish the new draft to replace it — released versions themselves are never changed in place, and the workflow always runs its latest published version.

For a live workflow, you can also tell Essential to run it for all customers. Essential commits that audience immediately and confirms the saved result without creating a new workflow version. Requests for specific customers, properties, or contacts stay in the **Runs for** picker so you can confirm the exact records; choose them there and select **Save audience**.

## Test the steps

1. Choose a test customer whose data is representative of the workflow. The test customer is sample data only — it does not decide who the workflow runs for.
2. If the workflow has more than one step, choose the **Step to test**.
3. Choose the trigger to simulate. Simulating a hand-off trigger stands in for the earlier step starting or finishing this one.
4. Supply any additional fields Essential shows for that trigger. If the step starts when a property is created, choose a real **Property** to represent the newly created property during the test. If a manual workflow needs a property, use the same customer-scoped picker. Triggers that carry a message — manual runs and hand-offs — can also include an optional test message.
5. Select **Preview**.

The preview reads the selected customer's current data and runs the draft exactly as a live run would — deterministic steps run in the same sandbox, and AI-driven steps consult the same AI with the same instructions. It validates the proposed actions but does not execute them or change customer data. **Preview results** show the values the step produced. For email and SMS actions, this includes the recipients and the complete subject and message after the step's placeholder values have been applied. Other actions show the fields they would use. A preview can instead report that nothing would happen or that the step would fail. If the step emits a completion message, the preview shows it too.

The workflow cannot be published until every step's triggers each have a preview that succeeds or safely reports that there is nothing to do.

The property choice is only for the preview. After publication, a **property created** trigger automatically supplies the property that was just created; staff do not choose it again.

## Choose who it runs for

Before publishing, choose the workflow's audience under **Runs for**:

* **All customers, including future ones** — the workflow applies to every customer, and automatically covers customers created after publication. A "customer is created" workflow should almost always use this.
* **Specific customers** — the workflow runs only for the selected customers.
* **Specific properties** — the workflow runs only when the triggering event identifies one of the selected properties. Belonging to the same customer is not enough, so this option is available only when every trigger identifies a property.
* **Specific contacts** — the same rule for selected contacts.

Essential rejects a property- or contact-specific audience when one of the workflow's triggers never identifies that record type, because the workflow would never run.

The audience can be changed at any time after publication from the workflow's page — select the new audience and **Save audience**. You can also add a single customer or property to a published workflow's audience from that customer's or property's own page: open its **Workflows** tab and select **Add workflow**.

## Publish the workflow

Select **Publish** after every step's triggers have a successful preview and an audience is chosen.

Publishing creates immutable versions of the workflow and every step, and the workflow always runs its latest published version. If the workflow is manually runnable, it appears under **Manual runs** for customers in its audience. Automatic triggers begin applying after publication; publishing does not replay older events.

A live workflow reacts within seconds of the change that triggers it — for example, a workflow that starts when a quote is signed runs right after the signature is saved. Steps that wait on a timer instead run once their scheduled time arrives.

Customer-facing sends and higher-risk changes are never taken silently. Publishing or previewing a workflow does not authorize those actions: a run that reaches one pauses and creates an **Approve / Decline** task so your team decides that specific run, unless the applicable outbound or gated policy has been explicitly enabled for the workflow.

## Run a published workflow manually

Select **Run** beside a published step under **Manual runs**, choose a customer from the workflow's audience, and complete the fields the workflow requires. Essential creates this form automatically; authors do not design a separate form. If the workflow needs a property, the Property picker contains only properties owned by the selected customer. For property- or contact-specific audiences, the owning customers are the ones offered.

Use **Preview** to inspect the proposed actions with current customer and property data without executing them. Select **Run** when the preview is correct. Essential confirms that the selected property belongs to the selected customer before running the workflow.

## What the Workflows table shows

The table lists each workflow group, its Draft or Live stage, the number of executable steps, who it runs for, and when it was last updated. Use search to find a workflow by name or description, and select a row to review its draft or released contracts.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learn.withessential.com/field-operations/workflows/build-test-and-publish-a-workflow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.