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

# Workflow builder

> Build automated Ravenna workflows in the visual workflow builder by connecting triggers and actions, configuring data flow, and publishing to run.

Create automated workflows using the visual builder. Connect a trigger to one or more actions, configure data flow between steps, and publish to start automating.

<Info>
  Copilot can build workflows from natural language descriptions but cannot publish or activate them directly. After Copilot generates a workflow, a human must open the workflow editor to review and publish it.
</Info>

## Workflow graph model

A workflow is a directed acyclic graph (DAG) with one root trigger node. Action nodes connect to the trigger or to other actions via directed edges. Edges can be unconditional (always follow) or conditional (follow when criteria match). The graph must have no cycles, no orphaned nodes, and every action must be reachable from the trigger.

***

## Connection patterns

**Sequential:** Trigger, then A, then B, then C. Simple pipeline. Use for straightforward automations where each step depends on the previous.

**Conditional branching:** Trigger, then Conditional or If/Else, then separate paths. Use If/Else for binary decisions. Use Conditional for expression-based evaluation.

**Parallel execution:** Trigger connects to multiple actions that start simultaneously. Use when actions are independent and can run concurrently (e.g., notify Slack AND create Jira issue AND send email).

**Parallel with convergence:** Trigger connects to actions A and B in parallel, both connect to action C. C waits for both A and B. Use when parallel work must complete before a shared next step.

**Approval gate:** Trigger, then Add Approvers, then Wait for Approval, then branch on approved vs. declined. The Wait for Approval step pauses execution until a human responds.

**Wait-and-branch:** Trigger, then action, then Wait for Message, then branch on response-received vs. timeout. Useful for follow-up flows.

### Converging branch behavior

A converging step waits for ALL parent paths to resolve:

* All parents completed: step executes with data from all paths available.
* Some parents completed, some skipped: step executes with data from completed paths only.
* All parents skipped: step is skipped.

Circular dependencies are not allowed. The workflow engine rejects them at validation time.

***

## Step management operations

Workflow steps can be duplicated or deleted to modify the graph structure.

### Duplication

* **Duplicate node:** Copies a single step and inserts it directly below the original, between the original and its child steps. The copy inherits all configuration from the original.
* **Duplicate tree:** Copies the selected step and all of its downstream steps, preserving the entire branch structure and configuration.

Constraints:

* Trigger nodes cannot be duplicated.
* Some step types may have duplication restrictions.
* Duplicated steps are independent copies. Modifying the original does not affect the copy.

### Deletion

Steps can be removed from the workflow graph. Steps that other nodes depend on (for example, steps referenced by dynamic values in downstream actions) may be protected from deletion. Remove dependent references first.

***

## Common workflow recipes

**Notification on ticket creation:**
Trigger: Ticket Created (filtered by channel or priority). Then Send Slack Message to team channel. Then Add Tags for tracking.

**Conditional routing:**
Trigger: Ticket Created. Then If/Else (check priority). High priority path: Assign to senior team, then Notify manager. Normal priority path: Assign via Round Robin.

**Approval gate with provisioning:**
Trigger: Form Submitted (access request form). Then Add Approvers (manager, Round Robin). Then Wait for Approval. Approved path: Provision Okta group, then Send confirmation. Declined path: Notify requester with reason.

**External system sync with link-back:**
Trigger: Ticket Created (filtered by category). Then Create Jira Issue (populated from ticket fields). Then Link Ticket (attach Jira URL to Ravenna ticket). Then Send Slack message with Jira link.

**Escalation after inactivity:**
Trigger: Ticket Created. Then Wait (2 hours). Then Check for New Messages. If no messages: Reassign to escalation team, then Notify manager. If messages exist: end.

**Parallel provisioning:**
Trigger: Form Submitted (onboarding form). Then parallel paths: Create Okta account, Add to Google Workspace, Invite to Slack channels. Converge, then Send summary to requester.

**Task handoff chain:**
Trigger: Task Completed. Then Conditional (has more tasks?). Yes path: Notify next task assignees. No path: Set ticket status to resolved.

**Round-robin assignment with notification:**
Trigger: Ticket Created. Then Add Assignee (team group, Round Robin). Then Send Slack DM to assignee with ticket details.

**Bulk stale ticket reminder (Loop):**
Trigger: Cron (daily). Then Search Tickets (status = open, last updated more than 7 days ago). Then Loop through results. Inside loop: Send Message on each ticket reminding the assignee to update or resolve.

**Scheduled access expiry (Wait Until):**
Trigger: Form Submitted (access request form). Then Provision access (add to Okta group). Then Wait Until (expiry date from form field). Then revoke access (remove from Okta group). Then Send Message notifying the user their access has expired.

***

## Data flow between steps

Data from the trigger and from each action's output is available to downstream steps. Reference earlier step data using dynamic value selectors when configuring action inputs.

* **Trigger data** includes all event context: ticket fields (including Display ID like `BUGZ-123` and Short ID like `abc12345`), user info, custom field values, timestamps, and event-specific data (e.g., which tags changed, which task completed).
* **Action output** varies by action type: created IDs, API response data, success/failure indicators, AI-generated text.
* **Scope:** A step can reference data from any step that is a direct ancestor in the graph. Steps in parallel branches cannot reference each other's data.
* **Converging steps** have access to data from all completed parent branches.
* The builder validates references and highlights broken ones before publish.

***

## Validation rules

Before publishing, the workflow engine validates:

* **One trigger:** Exactly one trigger node must exist.
* **Reachability:** All action nodes must be reachable from the trigger.
* **No cycles:** The graph must be acyclic.
* **No orphans:** No disconnected action nodes.
* **Required fields:** All required fields on each node must be populated.
* **Integration status:** Actions requiring integrations must have active connections.
* **Valid references:** Dynamic value references must point to existing upstream steps and valid fields.

***

## Templates

Templates are pre-built workflow structures for common IT operations. Creating a workflow from a template copies the entire structure (trigger, actions, connections) into a new workflow you can modify freely. Templates are starting points, not constraints.

***

## Integration requirements

Actions that interact with external systems (Jira, Okta, Linear, Slack, Google Workspace, PagerDuty, etc.) require configured and authenticated integrations. If an integration is disconnected or credentials have expired, the action fails at runtime even if it passes validation at publish time. Check integration health before publishing workflows that depend on external systems.

Prefer native integration actions over HTTP Request. Native actions handle authentication, error handling, and output parsing. Use HTTP Request only when no native action exists for the service you need.