> 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 > **Who can build:** During the current rollout, Essential builds and publishes workflows with you. Everyone with Workflows enabled can see published workflows, run them, and work their tasks. 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. On desktop, **Edit with Essential** stays on the left with Publish directly beneath it, and the full-height step workspace appears on the right. A permanent panel beside the map shows the selected step's details and **Runs for** audience in one column. The testing form stays hidden until you select **Test**. The map shows every step and the explicit **Kicks off** arrows between them. A **Start** badge marks a step that begins from a business event or a manual run. Select a step to update the panel, including the released contracts it uses under **Starts when**, **Reads**, and **Can do**. Review these details carefully: they are the step's actual access, not a suggested future design. If a step has no action available, **Can do** shows **Nothing**; that placeholder disappears whenever the step lists an action. Use **Tidy layout** to redraw the map after moving steps around. Selecting empty space leaves the current step details open. 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. If Essential cannot produce a valid first draft, the workflow is marked **Needs another pass** instead of showing a technical error. Open it, optionally clarify the request, and select **Try again**. 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 **Rule-based**: 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 details show 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 in its details — the AI cannot reach anything the inspector 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 — select the step to see it 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). Skipping that pause for a workflow requires Essential to enable its outbound policy for your business; there is no customer-facing setting for it. ## 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 also requires **Email inspection reports** to be turned on in Settings → Work Management → Tasks → Task Documents; the step isn't available otherwise. 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. ## Steps that fill in forms A workflow can hand work to your team through Essential's own forms instead of writing records directly: * **Fill in a form when it opens.** A step that starts **when a form is opened** runs while someone on your team opens that form by hand, and its values appear in the fields a moment later. A short **Preparing from workflow** notice shows while it runs, the form stays editable, and anything the person has already typed is left alone. If preparation fails or times out, a message lets the person know they can continue filling in the form manually. Only one published workflow can fill a given form, and the person still saves it. * **Prepare a form for review.** A step can **prepare a form** and create a task in the **Workflows** folder. Whoever picks up the task selects **Review**, checks the values, and saves. The workflow waits until every prepared form in that step is saved, then continues with the saved records. See [Respond to a workflow task](/field-operations/tasks/respond-to-a-workflow-task.md). Both work with the core forms only: customers, properties, contacts, billing profiles, quotes, invoices, subscriptions, visits, and deficiency tasks. ## Add or change steps Steps are added and edited through **Edit with Essential**. Describe what the new step should do, when it should start, and which existing step should lead into it. 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 map and step details before testing. Added and changed steps and new kick-off arrows are highlighted after a revision. 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 Select **Test** at the top of the step details panel to reveal that step's testing controls. The form is hidden again when you select another step or reopen the page. 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. Choose the trigger to simulate. Simulating a hand-off trigger stands in for the earlier step starting or finishing this one. 3. 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. 4. 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 **Runs for** in the step details panel, immediately after **Hands off to**: * **Any customer** — the workflow applies to every customer, including 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. The builder hides the property and contact choices when the workflow's triggers cannot identify that record type. Essential also rejects an incompatible property- or contact-specific audience at publish time, 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 Under **Edit with Essential**, confirm that **Triggers tested** and **Audience chosen** are both complete, then select **Publish**. The trigger count expands into an indented list showing each trigger and its workflow step. A circle beside the trigger is empty before testing, green after a passing preview, or red after a failing preview. Hover over a disabled Publish button to see what remains. 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 stage, the number of executable steps, who it runs for, and when it was last updated. An unpublished draft shows an em dash under **Runs for**. A workflow that cannot run is marked **Paused**, while an invalid draft is marked **Needs another pass**. Use search to find a workflow by name or description, and select a row to review its draft or released contracts. **Manual runs** appears only when at least one published step can be run by hand. **Run history** records published activity. Filter it to **Failed** or **Waiting for approval**, and select **View** beside a result to read the complete message. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://learn.withessential.com/field-operations/workflows/build-test-and-publish-a-workflow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.