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

# Building Workflows

> Create visual automation pipelines with the drag-and-drop workflow builder

## The Workflow Builder

The workflow builder is a visual canvas where you design automation pipelines by adding and connecting nodes.

***

## Creating a New Workflow

<Steps>
  <Step title="Navigate to Workflows">
    Go to **Workflows** from the main navigation (admin only).
  </Step>

  <Step title="Click New Workflow">
    Click the **"New Workflow"** button in the top right.
  </Step>

  <Step title="Choose a Starting Point">
    Select from:

    * **Blank workflow** - Start from scratch
    * **Template** - Pre-built workflows for common use cases
  </Step>

  <Step title="Name Your Workflow">
    Give it a descriptive name like "Enterprise Deal → CSM Assignment" or "SMB Onboarding Flow".
  </Step>
</Steps>

***

## Working with the Canvas

### Adding Nodes

**From the sidebar:**

1. Click the **"+"** button or open the node palette
2. Drag a node type onto the canvas
3. Drop it where you want it

**From existing nodes:**

1. Hover over a node's output handle
2. Drag to create a connection
3. Release to open the node picker

### Connecting Nodes

* **Drag from output to input** - Create connections between nodes
* **Click a connection** - Select it for deletion
* **Press Delete/Backspace** - Remove selected connection

<Tip>
  Nodes automatically validate connections. You can't connect incompatible node types.
</Tip>

### Selecting & Editing Nodes

* **Click a node** - Select it and open the properties panel
* **Double-click** - Open detailed editor
* **Drag a node** - Reposition it on the canvas
* **Delete key** - Remove selected node

***

## Node Types Reference

### Trigger Nodes

<AccordionGroup>
  <Accordion title="Start Node" icon="play">
    **Purpose:** Entry point that defines when the workflow triggers

    **Configuration:**

    1. Select CRM provider (HubSpot, Salesforce, or Notion)
    2. Configure trigger conditions:
       * **HubSpot:** Select pipeline and stage
       * **Salesforce:** Select opportunity stage
       * **Notion:** Select database, status property, and trigger values

    **Output:** Account data, CRM snapshot, contacts

    <Warning>
      Only connected CRM integrations appear as options. Connect your CRM in **Connectors** first.
    </Warning>
  </Accordion>
</AccordionGroup>

### Logic Nodes

<AccordionGroup>
  <Accordion title="Condition Node" icon="git-branch">
    **Purpose:** Branch workflow based on Yes/No conditions

    **Configuration:**

    * Select a variable to check (ARR, segment, custom field)
    * Choose comparison operator (equals, greater than, contains, etc.)
    * Set comparison value

    **Outputs:** Two paths - "Yes" (condition true) and "No" (condition false)

    **Example use cases:**

    * Route high-ARR accounts differently
    * Check if customer is in a specific segment
    * Verify required fields are present
  </Accordion>

  <Accordion title="Switch Node" icon="arrow-right-left">
    **Purpose:** Route to multiple paths based on value matching

    **Configuration:**

    * Select variable to switch on
    * Define multiple cases with values
    * Optionally set a default path

    **Outputs:** One path per case, plus optional default

    **Example use cases:**

    * Route by customer segment (Enterprise, Mid-Market, SMB)
    * Handle different product tiers
    * Geographic routing
  </Accordion>

  <Accordion title="Delay Node" icon="clock">
    **Purpose:** Pause workflow execution for a specified duration

    **Configuration:**

    * Duration amount (number)
    * Duration unit (minutes, hours, days)

    **Example use cases:**

    * Wait before sending follow-up email
    * Give time for external processes
    * Stagger notifications

    <Info>
      Delay nodes pause the entire workflow run. For time-based action scheduling within onboarding, use template action delays instead.
    </Info>
  </Accordion>
</AccordionGroup>

### Human Task Nodes

Human task nodes pause the workflow and create items in the Queue Dashboard for team members to complete.

<AccordionGroup>
  <Accordion title="CSM Assignment Node" icon="user-check">
    **Purpose:** Pause for a human to manually select and assign a CSM

    **Configuration:**

    * Queue to route to
    * Instructions for the reviewer
    * Optional: Pre-filter CSM list

    **What the reviewer sees:**

    * Account details and context
    * List of available CSMs
    * Selection interface

    **Output:** Selected CSM ID flows to downstream nodes
  </Accordion>

  <Accordion title="Triage Node" icon="route">
    **Purpose:** Human reviews account and makes routing decision

    **Configuration:**

    * Queue to route to
    * Decision options (e.g., "Approve", "Reject", "Needs Review")
    * Instructions and context to show reviewer

    **What the reviewer sees:**

    * Full account context
    * CRM data snapshot
    * Decision buttons

    **Outputs:** Multiple paths based on decision options
  </Accordion>

  <Accordion title="Approval Node" icon="check-square">
    **Purpose:** Request approval from a specific person or role

    **Configuration:**

    * Title and description
    * Request from: Specific user OR role (admin, user)
    * Optional: Auto-approve after timeout

    **What the approver sees:**

    * Approval request with context
    * Account details
    * Approve/Reject buttons with optional comment

    **Outputs:** Two paths - "Approved" and "Rejected"
  </Accordion>

  <Accordion title="Handoff Form Node" icon="file-edit">
    **Purpose:** Wait for AE to complete handoff form with account context

    **Configuration:**

    * Select handoff template to use
    * Instructions for AE

    **What happens:**

    * AE receives email with link
    * AE fills in answers (with AI suggestions)
    * AE assigns CSM
    * Workflow continues with collected data

    **Output:** Handoff answers, assigned CSM
  </Accordion>
</AccordionGroup>

### Action Nodes

Action nodes execute automatically without human intervention.

<AccordionGroup>
  <Accordion title="Assign CSM Node" icon="user-plus">
    **Purpose:** Automatically assign a CSM to the account

    **Configuration:**

    * Source: Variable (from upstream node) OR specific user OR round-robin

    **Example use cases:**

    * Apply CSM selected in CSM Assignment node
    * Auto-assign to a specific CSM for a segment
    * Round-robin distribution

    <Info>
      This node writes the assignment to the account. Use CSM Assignment (human task) to let someone choose, then Assign CSM to apply it.
    </Info>
  </Accordion>

  <Accordion title="Select Template Node" icon="file-stack">
    **Purpose:** Choose which onboarding template to apply

    **Configuration:**

    * Source: Specific template OR variable from upstream

    **Example use cases:**

    * Apply different templates based on segment
    * Use template selected during triage
    * Default template for all accounts
  </Accordion>

  <Accordion title="Send Email Node" icon="mail">
    **Purpose:** Send automated email during workflow execution

    **Configuration:**

    * Recipients (to, cc, bcc) - can use variables
    * Subject line with variable support
    * Email body with rich text and variables

    **Variables available:**

    * `{{account.company_name}}` - Company name
    * `{{account.arr}}` - Annual recurring revenue
    * `{{csm.name}}` - Assigned CSM name
    * `{{csm.email}}` - Assigned CSM email
    * Plus custom fields from CRM

    <Tip>
      Use the variable picker (click **{x}**) to insert variables without typing. This prevents typos and shows available fields.
    </Tip>
  </Accordion>

  <Accordion title="AI Transform Node" icon="sparkles">
    **Purpose:** Use AI to transform, classify, or analyze data

    **Transform types:**

    * **Classify** - Categorize accounts (e.g., segment, risk level)
    * **Extract** - Pull specific information from text
    * **Summarize** - Create summaries of CRM notes
    * **Score** - Generate numeric scores based on criteria

    **Configuration:**

    * Transform type
    * Input fields to analyze
    * Instructions for the AI
    * Output variable name

    **Example use cases:**

    * Auto-classify accounts by segment based on CRM data
    * Extract key information from deal notes
    * Score account complexity for routing
  </Accordion>
</AccordionGroup>

### Terminal Nodes

<AccordionGroup>
  <Accordion title="End Node" icon="flag">
    **Purpose:** Mark workflow completion

    **Configuration:**

    * Label (e.g., "Success", "Rejected", "Needs Follow-up")

    **Notes:**

    * Workflows can have multiple End nodes for different outcomes
    * Each End node can have a different label for reporting
    * Reaching an End node marks the run as "completed"
  </Accordion>
</AccordionGroup>

***

## Configuring Nodes

When you select a node, the properties panel opens on the right side.

### Common Properties

* **Name** - Display name for the node (shown on canvas)
* **Description** - Optional notes about what this node does

### Node-Specific Properties

Each node type has unique configuration options. See the node type reference above for details.

### Using Variables

Many node properties support variables - dynamic values from earlier in the workflow:

1. Click the **{x}** button to open variable picker
2. Select from available variables
3. Variable is inserted at cursor position

**Available variable sources:**

* **Account data** - Company name, ARR, domain, etc.
* **CRM snapshot** - All fields from the triggering CRM record
* **Contacts** - Contact list from CRM
* **Upstream nodes** - Data output by previous nodes

***

## Validating Workflows

Before activating, Thread validates your workflow:

### Automatic Validation

Click **"Validate"** to check for issues:

* ✅ All nodes are connected
* ✅ Start node has valid trigger configuration
* ✅ All paths lead to End nodes
* ✅ Required node properties are filled
* ✅ Variables reference existing data

### Validation Errors

| Error Type                | Meaning                 | Fix                        |
| ------------------------- | ----------------------- | -------------------------- |
| **Disconnected node**     | Node has no connections | Connect or delete it       |
| **Missing configuration** | Required field empty    | Fill in the property       |
| **Invalid variable**      | Variable doesn't exist  | Update or remove reference |
| **No path to end**        | Branch doesn't complete | Add End node or connection |

***

## Testing Workflows

Before activating, test your workflow with sample data.

<Steps>
  <Step title="Open Test Panel">
    Click **"Test"** button in the toolbar.
  </Step>

  <Step title="Configure Test Data">
    Either:

    * Select an existing account to use as test data
    * Create synthetic test data manually
  </Step>

  <Step title="Run Test">
    Click **"Run Test"** to execute the workflow with test data.
  </Step>

  <Step title="Watch Execution">
    Nodes highlight as they execute. Human tasks pause until you complete them in the test interface.
  </Step>

  <Step title="Review Results">
    Check final state, data transformations, and any errors.
  </Step>
</Steps>

<Warning>
  Test runs with real accounts don't actually modify the account or send real emails. They simulate execution safely.
</Warning>

***

## Saving and Activating

### Save as Draft

Click **"Save"** to save changes without activating. Draft workflows don't respond to CRM triggers.

### Activate Workflow

<Steps>
  <Step title="Validate">
    Ensure validation passes with no errors.
  </Step>

  <Step title="Test">
    Run at least one successful test.
  </Step>

  <Step title="Click Activate">
    Click **"Activate"** in the toolbar.
  </Step>

  <Step title="Confirm">
    Review the trigger summary and confirm activation.
  </Step>
</Steps>

<Warning>
  Active workflows immediately start responding to CRM events. Ensure your trigger conditions are correct to avoid processing unwanted records.
</Warning>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Start Simple" icon="seedling">
    Begin with a linear workflow, then add branching as needed
  </Card>

  <Card title="Name Clearly" icon="tag">
    Use descriptive names that explain what each node does
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    Test all paths before activating, including edge cases
  </Card>

  <Card title="Document Decisions" icon="file-text">
    Use node descriptions to explain why branches exist
  </Card>
</CardGroup>

### Common Patterns

<AccordionGroup>
  <Accordion title="Segment Routing">
    ```
    Start → AI Transform (classify segment) → Switch (by segment)
      → Enterprise path → CSM Assignment → Assign CSM → Select Template → End
      → SMB path → Auto-assign → Select Template → End
    ```
  </Accordion>

  <Accordion title="Approval Gate">
    ```
    Start → Condition (ARR > threshold)
      → Yes → Approval (manager)
        → Approved → Continue...
        → Rejected → End (rejected)
      → No → Continue without approval...
    ```
  </Accordion>

  <Accordion title="AE Handoff">
    ```
    Start → Handoff Form (to AE) → Assign CSM (from handoff) → Select Template → Send Email (welcome) → End
    ```
  </Accordion>
</AccordionGroup>

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Running Workflows" icon="play" href="/csm-guide/workflows/running-workflows">
    Monitor execution and debug issues
  </Card>

  <Card title="Queue Dashboard" icon="inbox" href="/csm-guide/workflows/queues">
    Process human tasks from workflows
  </Card>
</CardGroup>