Workflow Editor

Overview

The Editor tab of a workflow's details page opens the workflow canvas, where you build the states a document can be in and the transitions that move it between them. Reach it by opening a workflow from the Workflows list and selecting the Editor tab, or by selecting Editor after creating a new workflow.

While the canvas loads, a "Loading workflow..." message is shown; if it fails to load, a red error message appears in its place instead. A brand new workflow opens the canvas empty, with no states or transitions yet, ready for you to build the workflow from scratch.

The Canvas

The canvas fills the space below the workflow's tab strip. It shows every state in the workflow as a node, connected by lines representing the transitions between them, as in the Standard workflow's approval process pictured above: a document starts at Drafting Changes, moves through Send for Review to an Approval decision node, then branches to either Release as Master or Release in Project, ending at Master or Approved. A Rejected, Revoke, and Correct Rejection path loops back to Drafting Changes.

A States panel lists the types of node available to place on the canvas: Start, Process, Decision, End, and Sticky Note. Drag a type onto the canvas to add it, then double-click it to edit it. Select the x on the panel to close it, and select the States button beside the canvas to open it again.

Controls in the bottom left corner of the canvas zoom in, zoom out, fit the whole workflow in view, and toggle interactivity. The undo and redo buttons in the top bar, also available as Ctrl+Z and Ctrl+Shift+Z, step back and forward through your changes, and the theme button switches the editor between light and dark.

Building a Workflow

1. Drag a state type from the States panel onto the canvas. Repeat for each state.

2. Drag from a connection point on one state to another state to create a transition between them. The connection points are the small dots on each side of a state. A new transition is named Transition and has no actions.

3. Double-click each state and transition to set its properties. See Editing a State and Editing a Transition.

4. Select Validate on the Workflow toolbar, then select Save on the File toolbar.

To remove a state or transition, select it and press Backspace, or select Delete in its panel.

The Toolbar

The toolbar above the canvas has three menus, File, View, and Workflow. Select a menu name to show its buttons.

File

• New replaces the workflow on the canvas with an empty one.
• Save submits the workflow. See Saving a Workflow.
• Import opens a file picker for a workflow JSON file and replaces the workflow on the canvas with its contents.
• Export downloads the workflow as a JSON file.
• Mermaid opens an Export to Mermaid dialog that generates the workflow in Mermaid format for use in documentation. Select Copy Code to copy it, or Open in Mermaid Live Editor to view it online. The code works in Markdown files on platforms that support Mermaid, such as GitHub and GitLab.
• Load under Examples lists the sample workflows Review, Archive, Quick Change, and Drawing Change. Select one to replace the workflow on the canvas with it.
• Saved lists the workflows saved from the editor, each with its name and the date and time it was saved. The number in brackets is how many there are.

View

• Fit View zooms the canvas so the whole workflow is visible.
• Vertical and Horizontal rearrange the states into a top-to-bottom or left-to-right layout.
• More layouts opens a dropdown list of further arrangements: Process Flowchart, Multi-directional, Standard Workflow, and Compact.

Workflow

• Validate checks the workflow and removes any orphaned states and transitions it finds. See Validating a Workflow.
• Setup Actions opens the actions that run when a document enters the workflow. See Initialisation Actions.
• Groups, Tags, Repositories, and Projects, listed under Define, each open a dialog where you select the records the workflow can use. The records you select are the choices offered in the fields on states and transitions, for example the groups offered by Assign to Group and the tags offered by Add Custom Tags.

Editing a State

Double-click a state to open the Edit State panel. Select Save to apply your changes, Cancel to discard them, or Delete to remove the state.

• Label is the name shown on the state.
• Description is the text shown beneath the label.
• Node Type is one of Start, Process, Decision, or End.
• Colour Theme is one of 20 colours: Slate, Grey, Zinc, Blue, Indigo, Purple, Violet, Fuchsia, Pink, Rose, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, or Sky.
• Notes is a field for internal notes about the state.
• Allow file uploads controls whether files can be uploaded while a document is in the state.
• Entry state marks the state a document enters when it joins the workflow. A workflow needs exactly one entry state. Selecting the Start node type enables Entry state and selecting End disables it.
• Review state marks the state as a review. When it is enabled, a Review Type dropdown list appears.

The Review Type options are:

• Serial (one at a time)
• Parallel (all at once)
• Any (first approval wins)
• Squadcheck Review
• Checksheet Squadcheck

Consensus Mode

A state with the Squadcheck Review type also shows a Consensus mode section. Consensus mode skips the human approver and fires an outgoing transition automatically, based on the reviewers' votes. Tag each outgoing transition with its role using Consensus mode role in the Edit Transition panel.

• Skip on unanimous approval fires the transition tagged Approve path when every reviewer approves.
• Skip on any rejection fires the transition tagged Reject path on the first reviewer rejection.

When neither option is enabled, an approver finalises every review cycle.

Editing a Transition

Double-click a transition to open the Edit Transition panel. Select Save to apply your changes, Cancel to discard them, or Delete to remove the transition.

• Label is the name of the option the user selects to move the document.
• Display order sets the position of the option in the user's workflow options list. Lower values appear first.
• Transition Message is a message shown beneath the transition's name where users nominate reviewers for a change request.
• Notification Template is the text of the notification sent when the transition runs. Use {actor} for the person who ran the transition and {date} for the date. Leave the field blank to use the default template.
• Enable CR Default Reviewers assigns the Change Request default reviewers during the transition. When it is enabled, CR Form Display order sets the position of the trigger on the change request create and overview pages, with lower values first, and Reviewer selection required makes users nominate reviewers for the trigger before they submit the change request.
• Consensus mode role appears only on a transition that leaves a Squadcheck Review state. Choose Manual override (default) for a transition that only fires when a user chooses it, Approve path for one that fires automatically when reviewers reach unanimous approval, or Reject path for one that fires automatically on the first reviewer rejection. The state's Consensus Mode options decide whether the automatic transitions fire.

Actions

The Actions list shows every action available for the transition. Select the box beside an action to add it to the transition, and drag an action by its handle to change its position in the list. Settings for an action appear when you add it. Many actions also offer Optional (user can skip), which lets the user skip that action when they take the transition.

See the Workflow Actions Reference for what each action does and the settings it offers.

Initialisation Actions

Select Setup Actions on the Workflow toolbar to open the Workflow Initialisation Actions panel. The actions you add here run automatically when a new document enters the workflow, to set up its initial state, permissions, and notifications. Select the box beside an action to add it, and select Save to apply your changes.

The panel lists the same actions as a transition, but some actions offer fewer settings here. These settings are available only on a transition:

• Assign to Group offers only the specific groups you select. User-Selected Group and Tag-Based Assignment show no further settings, and Allow multiple users is not available.
• User Comment has no Comment is required setting.
• Add Custom Tags has no Required Tags list.
• Email Notification has no Notify assignees, Notify reviewers, or Notify group settings. The email goes to the relevant person as selected by the workflow rules, and you cannot choose another recipient.
• Custom Email Message has no Notify assignees, Notify reviewers, or Notify group settings.
• Merge with Parent has no Merge all revisions setting.
• Clear Tag Values and Clear Parent Tag Values have no list of tags to clear.
• Assign User (User Picker) has no Default to current user setting.
• Remember current reviewer and Return to remembered reviewer have no Slot name field.

All other actions offer the same settings as on a transition. See the Workflow Actions Reference for what each action does and the settings it offers.

Validating a Workflow

Select Validate on the Workflow toolbar to check the workflow. Validate checks that:

• Every state has at least one transition connected to it, apart from start states, entry states, and sticky notes.
• Every transition connects two states that exist.
• The workflow has at least one start or entry state.
• The workflow has at least one end state, which is a state of the End type or any other state with no transitions leaving it.

A Workflow Valid message confirms the workflow passes.

Validate also cleans up as it checks. It removes every orphaned state, meaning a state with no transitions connected to it, and every transition that points to a state that does not exist, then shows a Workflow Cleaned message with the number of items removed. Use the undo button, or Ctrl+Z, if you removed something you wanted to keep. Validate cannot add a missing start or end state, so if one is missing the message lists it, for example "Found missing end node. Please add the missing nodes manually." Validate does not check that the workflow has exactly one entry state. Lunr checks that when you save. Validate before you save.

Referencing Groups, Tags, Repositories, and Projects

Fields on the canvas that pick a group, a tag, a document repository, or a project are populated from lookup lists fetched when the editor loads. Groups are each assigned a colour automatically, since groups do not otherwise carry a colour of their own.

Saving a Workflow

Select Save on the File toolbar to submit the workflow. Lunr parses and validates the submitted workflow on the server. A workflow must have exactly one state with Entry state enabled and at least one state of the End type. A successful save shows a Saved message reading "Workflow saved successfully." If the server rejects the workflow, a Save failed message appears instead, but it does not say which check failed. Run Validate, then check the entry state and end state yourself.