Skip to main content

​
Prerequisites

  • The workflow feature must be enabled for your tenant
  • You need workflow-engine.manage or workflow-engine.admin — the designer lives under Settings → Admin Settings → Workflow → Designer

​
Designer at a glance

The designer has three areas:
  • A toolbar with view toggle (Canvas / JSON), Add Node, Auto Layout, History, Validate, Discard, Save draft, and Publish
  • A canvas showing the workflow as a graph — drag nodes to arrange them, draw edges between nodes to create transitions, and right-click for context menus
  • A property panel on the right that edits whatever is selected: the definition itself, a node, or a transition
You can switch to the JSON view at any time to edit the underlying definition directly; both views edit the same draft.
Use the canvas to check the path from the initial node to each terminal outcome.

Use the canvas to check the path from the initial node to each terminal outcome.

​
Creating a definition

1

Start a new definition

Open Designer (or choose New workflow in the Definitions list). Give it a name; the ID is derived automatically as a kebab-case slug and is locked after the first save.
2

Choose the anchor and scope

Pick the anchor type — Document, Caseflow, or System — and its scope: one or more document types, an application and class, or no item scope for a System workflow. The anchor cannot be changed once saved, and actions and expressions can only reference data inside the scope.
3

Add nodes and transitions

Add nodes for each step of the process, name them, and draw transitions between them. Mark the final step(s) as terminal.
4

Set the initial node

In the definition panel, pick the initial node — every instance starts there. Optionally pick an error node as the fallback when an action fails.
5

Configure triggers

On the definition’s Triggers tab, subscribe the workflow to the events that should start it. No triggers means the workflow can only be started manually or by another workflow.
6

Validate, save, and publish

Run Validate to check the draft, Save draft it, then Publish. Only published workflows react to triggers.

​
Definition settings

​
Nodes

A node is one step of the process. Select it to edit it in the property panel, which has two tabs. The General tab holds:
  • A name — required and unique within the workflow (case-insensitive). This is the label end users and administrators see everywhere; internal IDs never surface outside the designer.
  • A terminal toggle — entering a terminal node completes the instance.
  • An Initial node row — Set as initial makes this node the one every instance starts at, the same as choosing it as the Initial node in the definition panel. A terminal node cannot be the initial node: Set as initial is unavailable on a terminal node, and the initial node cannot be made terminal.
  • An optional error node override for failures in this node’s actions.
The Actions tab holds an ordered chain of actions that run every time an instance arrives at the node, regardless of which transition brought it in.

​
Transitions

A transition connects one node to another. Select an edge to configure it in the property panel:
  • Guard — an optional condition, written in the formula editor (for example $instance.amount >= 10000); the transition is only available when it evaluates truthy. Guards are evaluated once, when the instance enters the node.
  • Actions — an ordered chain that runs when the transition fires, before the target node is entered.
  • Kind — one of four:
Two structural rules apply: a transition cannot point back at its own node (no self-loops), and a node cannot have two transitions to the same target.

​
Task transitions

A task transition becomes a button in the end user’s inbox. Configure:
  • Label (required) — the button text
  • Style — primary (default), neutral, or critical button variant
  • Icon — an optional icon name
  • Visible to groups — user groups allowed to see and complete the task; leave empty, with the next switch off, to allow everyone
  • Visible to the person who started the workflow — also lets the run’s owner see and complete the task; with no groups selected, only the owner can. See who sees a task
  • Also show on the document or object — also offers the task on the page of the document or Caseflow object the workflow runs on. See tasks on the document or Caseflow object
  • Inputs — an optional form the user fills in when completing. Each input has a name (becomes the instance variable instance.<name> after completion), a label, a type (string, number, boolean, or date), and a required toggle.
A Task transition defines its label, audience, and button appearance.

A Task transition defines its label, audience, and button appearance.

​
Triggers

Document and Caseflow triggers auto-start instances from platform events. System workflows instead support scheduled triggers. The event gates below apply to document and Caseflow triggers. Each trigger subscribes to one event type, chosen to match the anchor: An instance starts when all three gates pass:
  1. The event type matches the trigger
  2. The item is inside the workflow’s scope
  3. The trigger’s optional filter (a formula condition against the event) evaluates truthy — no filter means every in-scope event of that type starts an instance
Only one active instance per workflow per document/object exists at a time; events for an item that already has a running instance of that workflow do not start a second one. A document.deleted trigger is scoped by the document type the delete event carries, because the deleted document itself can no longer be read: a workflow scoped to type X starts when a type X document is deleted and not for any other type. An older Insight version that does not send the document type on delete events makes the scope gate look the document up instead, and a deleted document is no longer found, so such a delete starts nothing. Caseflow object deleted is scoped by the class ID the event carries. An event from an older Insight version has no class ID, so it is matched by the application and class names instead, and then the scope must name the Caseflow application as well as the class. Mail imported starts after the mailbox importer has saved the complete mail archive. Scope it to the EML or HTML mail document type; the event also supplies mail metadata and the IDs of separate attachment documents. Follow Route imported mail into workflows for configuration and filtering. A document.created event can also carry an answer the person storing the document gave to a question. Where an interaction rule names this definition, the filter can test that answer and the instance starts with the rule’s mapped variables already set.
A trigger filter runs before any instance exists, so it reads the event — not workflow state. Document filters use the same $document.kw.<Name> paths as the rest of the workflow, plus event fields like $document.documentTypeId; the filter editor suggests the fields of the trigger’s event type. On a delete trigger the document or Caseflow object is already gone, so the editor offers no $document or $object references there and warns about any the filter uses. See filter references for the details.

​
Validation and publishing

Validate runs the same checks as publish, without committing anything. Issues appear in a bar below the toolbar in two severities:
  • Errors block publishing — for example: no initial node, missing or duplicate node names, a transition with an undefined target, a self-loop, a missing required action parameter, an invalid timer duration, a task transition without a label, or a secret referenced in a guard.
  • Warnings are advisory — for example: a non-terminal node with no outgoing transitions (instances can get stuck there), an unknown action parameter (likely a typo), or a keyword referenced in an expression that doesn’t exist on the scoped document types.
Publish is available once the draft is saved with no unsaved changes. The publish dialog confirms the definition and version and accepts an optional release note. Published versions are immutable and live — triggers start matching as soon as the version is published.

​
Drafts and versions

  • A definition has at most one open draft at a time, edited in place by Save draft
  • Publish freezes the draft as an immutable published version
  • Editing a published version forks a new draft; the published version keeps running until the new one is published
  • The History button lists all versions and lets you open any of them

Action reference

Every workflow action — keywords, documents, Caseflow objects, variables, email, scripts, and workflow control — with parameters and behavior.

References & expressions

The reference paths, templating syntax, and condition rules used throughout the designer.