Building Workflow Templates
A workflow template is a versioned graph of nodes, edges and configuration. The builder compiles the canvas into the workflow model used by the runtime.
Open New → Workflow Setup → Templates.
Template register
The Templates view contains the workflow families the current user is allowed to see.
Register controls
| Control | Behaviour |
|---|---|
| Search templates | Filters by template name. |
| Project filter | Limits the register by project where applicable. |
| Create Template | Opens a new workflow builder. |
| Create Group | Creates a template group. Groups can be nested. |
| Enabled Only | Shows only enabled template families when selected. |
Template card actions
Current template cards expose:
| Control | Behaviour |
|---|---|
| Enabled | Controls whether the root template family is available for normal use. |
| Edit | Opens the current template in the workflow builder. |
| Test | Opens the dedicated Workflow Test Runner. |
Template deletion is not exposed as a normal card action in the current builder.
Groups and group security
Workflow templates can be organised into nested groups.
A group can have explicit user and group security. If a group has no security rows, it is visible to otherwise-authorised users. If security is configured, the user must either be explicitly included or belong to one of the allowed groups.
Deleting a template group does not delete the templates inside it. Those templates become ungrouped.
When changing group security, take care not to remove the only access path for the administrators who still need to maintain the templates.
Template settings
The builder stores template metadata separately from the graph itself.
Typical settings include:
| Setting | Behaviour |
|---|---|
| Template Name | User-facing template name. |
| Workflow Type | Selects the workflow family/type represented by the template. |
| Document Type / subtype | Scopes document workflows where configured. |
| Project | Optional project scope. |
The exact saved type must be verified in the target environment when using less-common workflow types. The documentation audit tracks this explicitly because the UI and persistence paths have changed over time.
Nodes and canvas
The Nodes tab in the left panel holds the node palette; the canvas fills the rest of the builder. See Workflow Nodes.
Nodes can be added from the palette or the canvas right-click menu, and connected through their input/output handles. The builder saves both:
- the visual builder JSON — nodes, positions, edges and sections; and
- compiled workflow rows — node inputs and outputs used by the execution engine.
A workflow is therefore not considered correctly saved merely because the canvas looks right: the compiled graph must match it.
Edges and branching
Every connection records a source node, target node and the relevant source/target handles.
Some nodes expose one output; others expose several. Examples include Action Request replies, the Conditional node's True and False, Input Checker's Satisfied and Not Satisfied, View Batch branches, API failure routes, GitHub result routes, Forge function routes and sub-workflow outputs.
The builder normalises older saved handle formats when loading templates so historical workflows continue to render correctly.
Workflow sections
Sections are visual groupings of nodes on the canvas. They have a label and a set of member nodes and are saved with the builder JSON.
Sections are documentation/organisation constructs: changing a section label or boundary does not change the execution order of the nodes inside it.
Saving creates a new template version
Save Workflow does not overwrite the currently executing graph in place.
A normal builder save creates a new template version. During this process:
- a new template row is created;
- the graph is serialised again;
- node GUIDs are reallocated for the new version;
- the new compiled node/input/output rows are stored;
- future workflow starts resolve to the newly published version.
Workflow instances that are already running remain pinned to the TemplateID they started with. Publishing a newer version therefore does not silently move an in-flight workflow onto the new graph.
Versions tab
The Versions tab shows earlier versions in the template lineage.
Selecting a previous version loads that graph into the builder for inspection. Saving after opening an older version creates another new version; it does not rewrite the historical version.
This distinction is important when troubleshooting old workflow instances: the version they are executing may differ from the newest version shown in the builder.
Enabling and disabling a template
The register's Enabled control applies to the root template family used by normal template listings and start flows.
Disabling a family prevents normal new starts through those listings. It does not rewrite or migrate workflows already running on an earlier version.
Sub-workflows
A Sub Workflow Node references another workflow template and exposes that child workflow's declared outputs to the parent graph.
Parent routing is persisted using stable output labels rather than relying solely on child node GUIDs. This allows the child workflow to be saved as a new version — which regenerates its internal node GUIDs — without breaking parent edges when the output labels remain the same.
When changing child output names, review every parent workflow that routes on those outputs.
Workflow Test Runner
Select Test on a template card to open the dedicated Workflow Test Runner. It runs the latest saved version of the template against one test document. The run is marked as a test for the user who starts it, and sub-workflows inherit that test context.
A test run is not a transactional rollback sandbox.
Configured API requests and data updates execute normally during a test run. Do not point a workflow test at production-like external endpoints or mutable data unless those side effects are acceptable.
For the runner's sections and what a test run does, see Testing and Launching Workflows.
Editing a node on a running workflow
The Inbox can expose Edit node settings for supported completed workflow tasks.
This is a different operation from a normal builder save.
A live node edit uses the Workflows - Monkey Patch capability and updates inputs on the existing pinned template version. It does not:
- create a new template version;
- reallocate the node GUID; or
- move the running workflow onto a newer graph.
Because multiple running workflow instances can share that template version, the dialog reports the blast radius and records a reason for the change.
Use normal builder publishing for design changes. Use live edit only when an intentional in-place change to the running version is required.
Validation
Validation occurs at more than one layer:
- builder-side field and node configuration checks;
- serializer checks while creating the compiled graph;
- API/schema validation when the template is saved;
- node-specific validation for settings the engine cannot execute.
For example, invalid OCR setting combinations are rejected at the shared template-input schema so they cannot be persisted through an alternate write path.
Recommended authoring workflow
- Define reusable Action Requests.
- Create or select a template group and configure group security if required.
- Create the template and set its metadata/scope.
- Add nodes and connect all execution branches.
- Configure assignments, due dates, email behaviour and node-specific settings.
- Save the template and confirm a new version is created.
- Use the dedicated Test action with safe test data and endpoints.
- Enable the template when it is ready for normal starts.
- After later edits, remember that existing in-flight workflows continue on the version they started with.