> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Builder User Guide

> The Encore Health OS Visual Workflow Builder allows you to create complex automation workflows using a drag-and-drop interface. Workflows can include condition…

## Overview

The Encore Health OS Visual Workflow Builder allows you to create complex automation workflows using a drag-and-drop interface. Workflows can include conditional branching, parallel execution, loops, human approvals, and reusable subflows.

***

## Getting Started

### Creating Your First Workflow

1. Navigate to **Forms & Workflow** → **Automations**
2. Create a new automation rule or edit an existing one
3. Click **"Visual Editor"** to open the workflow builder
4. Drag nodes from the left palette onto the canvas
5. Connect nodes by dragging from one node's output to another's input
6. Configure each node by clicking it and editing properties in the right panel
7. Click **"Save Workflow"** to persist your changes

***

## Node Types

### Triggers

#### Start Node

* **Purpose:** Entry point for every workflow
* **Configuration:** None required
* **Outputs:** One (continues to next node)

### Actions

#### Action Node

* **Purpose:** Execute automation actions (send email, create record, etc.)
* **Configuration:**
  * **Action Type:** send\_email, send\_notification, update\_record, create\_record, call\_webhook
  * **Action Config:** Type-specific configuration (email addresses, webhook URLs, etc.)
* **Dynamic Values:** Use `{{submission_data.field_name}}` to reference form data
* **Outputs:** One (continues after execution)

### Control Flow

#### Branch Node

* **Purpose:** Conditional if/else routing
* **Configuration:**
  * Add conditions (field, operator, value)
  * Each condition creates a new output path
  * Default "else" path for unmatched conditions
* **Outputs:** One per condition + default

#### Switch Node

* **Purpose:** Multi-way routing based on exact field value
* **Configuration:**
  * Select field to switch on
  * Add cases with expected values
  * Default case for unmatched values
* **Outputs:** One per case + default

#### Loop Node

* **Purpose:** Repeat actions for each item in a collection
* **Configuration:**
  * **Collection Field:** Path to array (e.g., `submission_data.items`)
  * **Item Variable:** Variable name for current item (default: `item`)
  * **Max Iterations:** Safety limit (default: 100)
* **Outputs:** Two ("body" for loop content, "done" after completion)

#### Parallel Fork Node

* **Purpose:** Execute multiple branches simultaneously
* **Configuration:** Number of parallel branches
* **Outputs:** N outputs (one per branch)

#### Parallel Join Node

* **Purpose:** Wait for parallel branches to complete
* **Configuration:** Join mode (all/any)
* **Outputs:** One (continues after branches complete)

### Human Interaction

#### Approval Node

* **Purpose:** Pause workflow for human decision
* **Configuration:**
  * **Assignee:** User ID or role (org\_admin, site\_admin, etc.)
  * **Timeout:** Optional deadline (auto-approve/reject after timeout)
  * **Instructions:** Message for approver
* **Outputs:** Two ("approved" and "rejected")

### Reusability

#### Subflow Node

* **Purpose:** Call reusable workflow fragment
* **Configuration:**
  * **Subflow:** Select from available subflows
  * **Input Mapping:** Map parent variables to subflow inputs
  * **Output Mapping:** Map subflow outputs to parent variables
* **Outputs:** One (continues after subflow completes)

### Utilities

#### Delay Node

* **Purpose:** Wait before continuing (production feature)
* **Configuration:** Duration in milliseconds
* **Outputs:** One (continues after delay)
* **Note:** Currently skipped in executor (requires job queue)

#### End Node

* **Purpose:** Terminate workflow execution
* **Configuration:** None required
* **Outputs:** None

***

## Canvas Features

### Navigation

* **Pan:** Click and drag on empty canvas space
* **Zoom:** Mouse wheel or zoom controls (bottom-right)
* **MiniMap:** Overview of large workflows (bottom-right corner)

### Node Operations

* **Add:** Drag from palette or click "+" on palette items
* **Select:** Click node to view/edit properties
* **Delete:** Select node and press Delete key
* **Move:** Drag node to reposition
* **Connect:** Drag from output handle (right) to input handle (left)

### Saving

* **Auto-save:** Changes are saved automatically 1 second after editing
* **Manual Save:** Click "Save Workflow" button
* **Status:** Watch for "Saving..." indicator

***

## Best Practices

### Workflow Design

1. **Start Simple:** Begin with linear workflows, add control flow as needed
2. **Name Nodes:** Give descriptive labels to action nodes
3. **Use Subflows:** Extract reusable logic into subflows
4. **Limit Complexity:** Keep workflows under 50 nodes for performance
5. **Test Incrementally:** Save and test after each major change

### Error Handling

1. **Validation:** Check for disconnected nodes before saving
2. **Default Paths:** Always provide default/else branches
3. **Max Iterations:** Set reasonable limits on loops
4. **Timeout Approvals:** Configure timeouts for approval nodes

### Performance

1. **Parallel Execution:** Use parallel forks for independent actions
2. **Conditional Logic:** Use branches to skip unnecessary actions
3. **Subflows:** Organize complex workflows into manageable pieces

***

## Dynamic Values

Use double curly braces to reference workflow variables:

```
{{submission_data.email}}          // Form field
{{submission_data.address.city}}   // Nested field
{{trigger_data.submitted_by}}      // Submitter user ID
{{item.name}}                      // Loop item variable
```

**Supported Locations:**

* Email addresses (to, from, cc)
* Email subject and body
* Notification title and body
* Record field values
* Webhook payloads

***

## Version History & Rollback

### Publishing Versions

Workflows support version control to track changes and enable rollback:

1. Click **"Publish Version"** button in the workflow editor header
2. Add optional notes describing the changes (e.g., "Added approval gates")
3. Add optional tags (e.g., "production", "staging", "v2.0")
4. Version is created as an immutable snapshot

**Why Publish Versions?**

* Create restore points before major changes
* Compliance audit trail (who, what, when, why)
* Enable quick rollback if issues occur
* Compare versions to understand changes

### Viewing Version History

1. Click **"History"** button in the workflow editor header
2. Side panel opens showing all versions (newest first)
3. View version details:
   * Version number (v1, v2, v3, etc.)
   * Published by (user name)
   * Published at (timestamp)
   * Notes and tags
   * Node/edge count
4. Current version is highlighted with a badge

### Rolling Back

To restore a previous version:

1. Click the rollback icon (rotate left) next to any previous version
2. Review the warning dialog:
   * Current workflow will be replaced
   * Rollback creates a NEW version (preserves history)
   * Changes are permanent
3. Add optional rollback notes (recommended for audit trail)
4. Click **"Rollback to Version X"** to confirm

**Important:** Rollback creates a new version (e.g., v4) that's identical to the target version (e.g., v2). This preserves the complete history without deleting anything.

### Comparing Versions

To see what changed between versions:

1. Click the compare icon (split view) next to any version
2. Visual diff dialog shows:
   * **Added Nodes** (green) - New nodes in the selected version
   * **Removed Nodes** (red) - Nodes deleted from the current version
   * **Modified Nodes** (yellow) - Nodes with configuration changes
   * **Added Connections** - New edges between nodes
   * **Removed Connections** - Deleted edges

Use comparison to:

* Understand what changed in a version
* Review changes before rollback
* Debug issues by identifying when a change was introduced

### Best Practices

**Before Publishing:**

* Test workflow changes thoroughly
* Add descriptive notes (not just "changes")
* Use tags to mark production-ready versions

**Publishing Frequency:**

* Publish before major refactors
* Publish after completing a feature
* Publish before deploying to production

**Tags:**

* Use environment tags: `development`, `staging`, `production`
* Use release tags: `v1.0`, `v1.1`, `hotfix`
* Use feature tags: `feature-approvals`, `feature-notifications`

**Rollback:**

* Always review diff before rolling back
* Add notes explaining why you're rolling back
* Test the rolled-back version before publishing again

***

## Execution & Monitoring

### Triggering Workflows

Workflows execute automatically when:

* Form is submitted (trigger\_type: `form_submitted`)
* Form is updated (trigger\_type: `form_updated`)
* Schedule triggers (trigger\_type: `schedule`)
* Webhook received (trigger\_type: `webhook`)
* Manual execution (trigger\_type: `manual`)

### Monitoring Execution

1. View **Automation Logs** for execution history
2. Check **Execution Trace** for node-by-node progress
3. Review **Node States** for action results and errors
4. Check **workflow\_version** field to see which version was used

### Approvals

1. Navigate to **Approvals** page
2. View pending approval tasks
3. Review workflow context
4. Approve or reject with optional notes

***

## Troubleshooting

### Workflow Not Executing

* Verify automation rule status is **Active**
* Check trigger conditions match event
* Review RLS policies on affected tables
* Check automation logs for errors

### Node Configuration Errors

* Ensure all required fields are configured
* Verify field names match form data structure
* Check dynamic value syntax (use `{{...}}`)
* Validate email addresses and URLs

### Performance Issues

* Reduce number of nodes (target: \<30 nodes)
* Limit loop iterations
* Use parallel execution for independent actions
* Consider breaking into multiple workflows

***

## Keyboard Shortcuts

| Shortcut                 | Action               |
| ------------------------ | -------------------- |
| **Ctrl/Cmd + S**         | Save workflow        |
| **Delete**               | Delete selected node |
| **Ctrl/Cmd + Z**         | Undo (limited)       |
| **Ctrl/Cmd + Shift + Z** | Redo (limited)       |
| **Escape**               | Deselect node        |

***

## Need Help?

* Review **Workflow Examples** for common patterns
* Check **API Reference** for advanced usage
* Contact support for assistance