Build a workflow in the visual designer

A workflow is a chain of steps that xMatix runs when something happens, such as a record being created, updated or deleted, or a customer messaging your business chat number. You draw it in a visual designer. A business rule acts inside one save. A workflow can run several steps after the save, wait for something (an approval decision, a background job, a customer's reply), and then carry on. This page covers building, publishing, testing and retiring a workflow, and the limits you should design around.

Overview

Workflows live in Setup → Process Studio → Workflows. Each workflow has:

• a trigger, the step that starts it. When entity record changes reacts to record saves. When a customer messages starts a designed chat conversation (see Conversation workflows);
• steps connected on a canvas: send an email or message, submit for approval, queue a background job, create or change records, branch, and so on;
• versions. Every save writes a new version, and only the published version's triggers are live.

When to use it

• Use a workflow when the requirement has a "then, later" in it: notify a team after an order is created, queue follow-up work, or run a guided conversation with a customer.
• Use a business rule instead for validation, defaults and status guards that fit inside one save. A rule is easier for other administrators to read on the entity, and it can wait up to seven days before acting.
• Use a scheduled job, an automation script or an integration for anything on a timetable ("every night at two") or anything that calls an external system. Workflows have no timer trigger and no outbound HTTP step.

How xMatix handles it

Triggers and phases

The When entity record changes trigger has three settings:

• Entity name: the entity's API name, not its display label. Matching ignores upper and lower case.
• Operations: any of Create, Update and Delete. Leave it empty to react to all three.
• Phase: After save (async, default) or Before save (sync — can cancel).

After save runs once the save has committed. It runs in the background, so the user's save returns straight away and never waits for the workflow. If the workflow fails, only that workflow's run fails.

Before save runs inside the save, before it commits, and is the only phase in which a Cancel entity operation step can stop the save. It only runs for creates and updates. Deletes always run in the After save phase. A Before save dispatch is limited to about eight seconds. If the workflow runtime is slower than that, the save goes ahead without the workflow's verdict rather than hanging.

Records that a workflow writes don't start workflows again, which prevents loops.

Versions, drafts and publishing

Every save writes a new version (v1, v2, …) of the same workflow. Only the published version registers triggers.

• A workflow that has never been published shows Draft. Its saves are drafts, and nothing fires.
• Once a workflow is Published, the designer's primary button becomes Publish changes. Saving there makes the new version live immediately. The designer has no "save as draft" for a published workflow.
• Unpublish (in the designer) or clicking the Published tag (in the list) retracts the workflow: it stops starting new runs. Runs already in progress carry on.

Values are fixed text

Each step field has a syntax switch showing Text, Liquid and JS. Only Text values are supported: the Liquid and JavaScript expression engines are not switched on for xMatix workflows. So a step can't compute a value from the record that triggered it. For example, Submit for Approval takes a fixed record id, and a Decision (If) condition is a fixed true or false. Conversation steps get around this with their own named answers and ports (see below).

Ordering against rules and scripts

A workflow with no Sequence runs in the shared workflow slot of the save, after the platform's own handlers. The order between several workflows on the same entity is not defined. Give a workflow a Sequence (in Edit JSON, see Configuration) to place it at a specific point among business rules, scripts and other workflows. The entity's Execution Plan shows where each number lands.

Prerequisites

• The Manage workflows capability (see Permissions).
• The API name of the entity you want to trigger on.
• For a Send Message step, the channel is set up under Messaging channels (email, in-app and push need no setup).
• For Submit for Approval, an active approval process on the entity.

Procedure

Step 1 — Create the workflow

1. Go to Setup → Process Studio → Workflows.
2. Select New in the page header, once. This immediately creates a draft called Untitled workflow at v1 and opens the designer. Selecting New again creates a second draft.
3. In the designer, open the ⋯ menu and choose Workflow settings. Enter a Name that states the trigger and the outcome (for example "Email operations on new orders") and an optional Description. For a conversation workflow, the name is what the customer sees on the menu.

The designer has three areas: Activities on the left (grouped as Triggers, Control flow, Messaging, Data, Notifications, Approvals and Logging, with a search box), the canvas in the middle, and the inspector for the selected step on the right.

Step 2 — Add the trigger

1. Drag When entity record changes from Triggers onto the canvas.
2. In the inspector, set Entity name, Operations and Phase (see Triggers and phases).

The trigger provides these outputs to later steps: EventEntityName, EventOperation, EventPhase, EventChangedFields (the fields changed on an update), EventRecordId and EventStamp. They are listed on the step's Output tab.

Step 3 — Add and connect the steps

Drag each step onto the canvas and connect the trigger's port to it, then each step to the next. A step with several ports (for example Decision (If) with True and False) is connected once for each branch you need.

The conversation steps (Ask the customer, Reply to the customer, Hand off to a person) only make sense after When a customer messages.

Step 4 — Configure each step

Select a step to open it in the inspector. Label is the name shown on the canvas. The Input tab holds the step's fields and the Output tab lists what the step produces. Use Delete step to remove it. Undo and Redo are in the designer header.

Workflow variables are added under ⋯ → Workflow settings → Variables → Add variable. Each has a Name and a type: Text, Whole number, Decimal, Yes / No or Object.

Step 5 — Save a draft, then publish

• For a workflow that has never been published, select Save draft. The header shows Saved, or Unsaved changes while you have edits. Each save adds a version.
• When the workflow is ready, select Publish workflow. The header then shows Published, and the list's Status changes from Draft to Published.
• Later edits to a published workflow show Draft changes. Publish changes saves them and makes them live in one step. It is greyed out (No changes to publish) until you change something.

Keep the first version small, a trigger and one or two steps. Get one clean run before you add branches.

Step 6 — Trigger it and check the run

1. Cause the trigger event with a test record (for example, create a test order).
2. Select Runs in the designer header, or View runs on the workflow's row in the list.
3. The Runs dialog lists up to 50 runs, newest first, with Started, Status (Running, Finished, Cancelled or Faulted), Sub-status, Version, Incidents, Finished and Instance Id.

A Finished run with 0 incidents, plus the result you expected (the email arrived, the approval request exists), proves the workflow works. Then delete the test record.

Step 7 — Change, retire or delete it

• Change: edit in the designer and select Publish changes. The new version replaces the old one in a single step, with no gap.
• Retire: choose ⋯ → Unpublish and confirm Unpublish this workflow?, or click the Published tag in the list. The list shows Draft again. New events no longer start runs, but runs already waiting (for example on an approval) continue.
• Delete: on the list row, select Delete workflow and confirm Delete this workflow?. This removes the workflow and all its versions. Unpublish it first and keep any run evidence you need, because deleting can't be undone.

Fields

Workflows list

When entity record changes

Edit JSON dialog

Business rules

• Every save, from the designer, Edit JSON, the CLI or the API, creates a new version. Only the published version's triggers are live.
• In the designer, saving a published workflow publishes the new version. Saving from Edit JSON (or the CLI or API) without publishing creates a new draft version. The list then shows Draft, but the version published earlier keeps firing until the new one is published.
• After save workflows run in the background after the commit and never delay or fail the user's save. Before save workflows run inside the save and can cancel it with Cancel entity operation. The user then sees the reason you entered as the error, or "Operation cancelled by workflow." when the reason is blank. If several workflows cancel the same save, the reasons are joined with |.
• A Before save dispatch is limited to about eight seconds. After that the save goes ahead without the workflow's verdict.
• Records written by a workflow don't trigger workflows.
• A dry run (for example the entity's Execution Plan dry run) lists the workflows that would start but never runs them, so a cancelling workflow isn't simulated.
• Workflows belong to one organization. Another organization's workflows are never listed and never fire on your records.
• Create record, Update record, Delete record and Run record action go through the same numbering, validation, business rules and permissions as a user's save. A refusal takes the step's Failed port.

Example

An operations team wants an email every time an order is created.

1. The administrator selects New, opens Workflow settings, and names the workflow "Email operations on new orders".
2. They drag in When entity record changes: Entity name Order, Operations Create, Phase After save.
3. They add Send Email: To orders-desk@example.com, Subject "New order created", Text body "A new order has been created. Open Sales → Orders to review it." They connect the trigger's Done port to it.
4. They select Save draft, then Publish workflow. The list shows the workflow at v2, Published.
5. They create a test order. Under Runs, a new run shows Finished with 0 incidents, and the email arrives. They delete the test order.

Later they change the subject line and select Publish changes. The list shows v3, still Published, and new orders use the new subject from then on.

Training

Practice exercise

In a sandbox, build a workflow that refuses to save a Lead without a description.

1. Create a workflow named "Practice — block leads", trigger When entity record changes, Entity name Lead, Operations Create, Phase Before save (sync — can cancel).
2. Add Cancel entity operation with Reason "Practice workflow: lead creation is blocked." and connect it to the trigger.
3. Publish it, then try to create a Lead.

Expected result: the save is refused with your reason, and no Lead is created. Now Unpublish the workflow and create the Lead again. This time the save succeeds. Finally, delete the practice workflow. (In real work, a check like this belongs in a business rule. The exercise shows how the phase and publishing work.)

Quick reference

• Setup → Process Studio → Workflows → New creates a draft and opens the designer straight away.
• Only the Published version fires. Every save adds a version.
• On a published workflow, Publish changes makes the edit live immediately.
• Entity name = API name. Empty Operations = all three.
• Before save can cancel a save, but never fires for deletes. After save never delays the user.
• Step values are fixed text. Liquid and JS are not available.
• Check results under Runs: Finished with 0 incidents is clean.
• Unpublish stops new runs. Runs already in progress continue.

Permissions

A user without Manage workflows doesn't see Workflows under Process Studio. Treat this capability as authority to change automation: whoever holds it can make the system send messages and change records on every save. The same applies to anyone who can publish workflows with the CLI.

Configuration

• Workflows register: Setup → Process Studio → Workflows. Search, refresh, New, and the row actions.
• Designer header: Back to workflows, Undo, Redo, Save draft (unpublished workflows only), Runs, the ⋯ menu (Workflow settings, Unpublish, and under Developer Edit source (JSON)), and the primary Publish workflow or Publish changes button. Leaving with unsaved changes asks you to confirm.
• Edit source (JSON) (designer) replaces the canvas with the JSON you apply. It is saved with the next save or publish.
• Edit JSON (list row) is the only place to set Sequence and Show in the customer menu. See the Edit JSON dialog fields.
• Execution Plan: Setup → Design Studio → Entities → (entity) → Logic → Execution Plan shows where a workflow's Sequence sits among the entity's rules and scripts.
• Messaging channels: Setup → Feature Hub → Platform → Messaging channels. Needed before a Send Message step can use SMS or the business chat app. See Messaging channels.
• Source control: workflows can be pulled and pushed as files with the CLI.

Conversation workflows

A workflow that starts with When a customer messages runs a guided conversation with a customer on your business chat number. The customer is identified from their mobile number.

• Trigger: Keywords (whole words, any case) start it. The workflow's Name is also its label on the customer's numbered menu. Channel defaults to the business chat app.
• Steps: Ask the customer sends a question and waits for the reply. It can expect Any text, One of the options (number), Yes / No or A number, and has ports Done, Yes, No, Finished, Cancelled and Invalid. Each answer is stored under the name in Save answer as, which later steps can insert into their text. Reply to the customer answers without a recipient to configure. Hand off to a person creates a follow-up task for your team and keeps the bot quiet for the handoff period. Find records, Update list and Create record let the conversation look up items, build a list (such as order lines) and create a record with its lines in one save.
• Channel settings: on the Messaging channels screen, edit the business chat app row. Under Inbound ordering (customers message you), set Customers are served by to Designed conversations (workflows), so the menu lists your published conversation workflows. Then set Designed conversations run as to a user whose security profile may create the records your workflow creates. If you leave it empty, the workflow runs as the system user, which has no security profile, so Create record is refused and the run shows Faulted.
• Menu order and visibility: use Sequence and Show in the customer menu in Edit JSON.

Common problems

Nothing happened when I saved the record

1. Check that the list says Published. A draft never fires. If you last saved from Edit JSON with Publish on save off, your change is an unpublished draft, and any earlier published version is still the one running.
2. Check the trigger. Is the Entity name the API name, not the label? Do the Operations include the one you tested? Is the Phase what you expect? Before save never fires for a delete.
3. Open Runs. No run at all means the trigger didn't match. Go back to step 2.

The run shows Faulted or has incidents

A step failed: a missing template, a recipient that resolved to nothing, a bad job type, or a refused record write. Fix the step, select Publish changes, and test again with a new event. Runs that already faulted are not retried.

The run Finished but no message arrived

In a record-triggered workflow, the Send Message step doesn't pass the triggering record to the messaging service. So owner and field:<FieldName> recipients resolve to nothing, and no message is created. Use a literal address or user:<user id>. The Message Log shows what was actually sent.

My Decision step always takes the same branch

Conditions written in Liquid or JS are not evaluated, because those engines are not available. A Decision (If) condition is a fixed true or false. Branch on step ports instead (for example Done/Failed on record steps, or the conversation ports), or move the condition into a business rule.

Saves now fail with my workflow's message

A published Before save workflow reached Cancel entity operation. Unpublish it to stop the cancellations straight away, then correct the path that leads to the cancel step.

The workflow became Published or Draft without my doing it

Clicking the Status tag in the list toggles publishing, and another administrator may have clicked it. Saving from Edit JSON with Publish on save off makes the list show Draft even though the earlier published version is still live. Refresh the list before acting.

A conversation workflow asks its questions but never creates the record

Designed conversations run as is empty, or that user's security profile can't create the entity. The run shows Faulted. Set a suitable user on the business chat app channel.

Common questions

When is a workflow the wrong tool?

When the whole requirement fits inside one save, such as validation, defaults or status guards, a business rule does it with less machinery and no publishing lifecycle, and any administrator can read it on the entity. When the requirement is a schedule ("every morning"), a workflow can't express it, because there is no timer trigger, so use a scheduled job or an automation script. When it needs to call an external API, use an integration or a script. Workflows have no HTTP step.

Can a workflow submit the record that triggered it for approval?

Not from the designer. Submit for Approval takes a fixed record id, and step values can't be computed from the triggering record, so the step can only submit one specific record. To submit records automatically as they are saved, turn on Enable Auto-Submit on the approval process and pick its Event Type. See Approval processes.

Does unpublishing stop runs that are already waiting?

No. Unpublishing only stops new events from starting runs. A run waiting on an approval decision, a background job or a customer reply continues when that event arrives. That is usually what you want, because a half-finished process is harder to clean up than a finished one. Check Runs to see which runs are still in progress.

Does editing a published workflow take effect immediately?

Yes. In the designer, a published workflow's only save button is Publish changes, which saves a new version and makes it live in one step. There is no separate draft to review first. For a risky change, test it on a copy: create a new workflow, paste the definition in through Edit source (JSON), point it at test data, and publish the real change only once the copy behaves.

Why does the version number go up when I only saved?

Every save writes a new version, whether or not it is published. The list's Version shows the latest version, and Runs shows which version each run used. That lets you tell runs from before and after a change apart.

Related topics

• Business rules
• Approval processes
• Messaging channels and the Message Log
• Your first automation script
• Workflows with the CLI
• The customization ladder