> ## 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.
Use Copilot to build workflows from a natural language description. Describe what you want to automate and Copilot generates the trigger, steps, and connections for you. Copilot cannot publish workflows directly. After Copilot builds a workflow, open the workflow editor to review and publish it.
## Create your first workflow
Open **Workflows** from your workspace sidebar, select or create a collection, then click **New → Workflow**. Ravenna creates an untitled draft and opens it in the builder. Rename the workflow from the header once you start designing it. To start from a pre-built structure instead, click **New → Template** (see [Templates](#templates)).
Select a trigger that defines what event starts your automation. Add filters to ensure the trigger only activates for relevant events, such as specific channels, ticket properties, or custom field values.
Connect actions that perform the tasks you want to automate. Set up each action with the appropriate inputs and use dynamic values to reference data from the trigger or previous steps.
Use manual triggers to verify each step works correctly, then [publish](/documentation/automate/workflows/publish) to make the workflow active
***
## Working with triggers and actions
Every workflow needs exactly one trigger and at least one action. Triggers respond to events in your workspace, external systems, or run on schedules. Actions perform tasks using information from the trigger and previous steps.
**Common trigger types:**
* **Ticket triggers**: Activate when tickets are created, updated, assigned, or change status
* **Slack triggers**: Respond to reactions or messages in Slack
* **Schedule triggers**: Run workflows at specific times or intervals
* **Agent triggers**: Allow AI agents to start workflows through natural language rules
* **Manual triggers**: Start workflows on demand for testing or batch operations
**Common action types:**
* **Ticket actions**: Create, update, assign, or manage tickets
* **Messaging actions**: Send messages to Slack, email, or other channels
* **Integration actions**: Create issues in Jira, Linear, or manage users in Okta
* **AI actions**: Summarize tickets, make decisions, or run custom prompts
* **Control flow**: Branch execution with conditional logic, wait for events, or loop
### Integration requirements
Some actions require configured integrations. Actions that depend on third-party services show a Setup Required badge. Hover to see which integration is needed, then connect it from your workspace settings.
See all available [triggers and actions](/documentation/automate/workflows/triggers-actions) with detailed configuration options
***
## Converging branches
Converging branches merge multiple parallel paths back into a single step. Use them when your workflow branches out for parallel work and then needs to rejoin for a shared next step, like sending notifications through multiple channels before updating a ticket.
### Connect and disconnect steps
You can only remove individual connections when a step has multiple parents. If a step has a single parent, delete the step itself to remove it from the workflow.
### Execution behavior
```mermaid theme={"system"}
graph TD
trigger[Trigger: Ticket created] --> slack[Send Slack message]
trigger --> jira[Create Jira issue]
slack --> update[Update ticket status]
jira --> update
style trigger fill:#E2EAEF,stroke:#E2EAEF,color:#000
style slack fill:#E2EAEF,stroke:#E2EAEF,color:#000
style jira fill:#E2EAEF,stroke:#E2EAEF,color:#000
style update fill:#22c55e,stroke:#22c55e,color:#fff
```
**Update ticket status** waits for both **Send Slack message** and **Create Jira issue** to finish before it runs. What happens next depends on how those paths resolved:
| Parent path results | Converged step behavior |
| ---------------------------- | ------------------------------------------------- |
| All parents completed | Executes using data from all paths |
| Some completed, some skipped | Executes using data from the completed paths only |
| All parents skipped | Skipped |
The workflow builder automatically prevents circular dependencies. You cannot create a connection that would cause a step to depend on itself, either directly or through a chain of other steps.
***
## Data flow and dynamic values
Reference data from triggers or previous actions using dynamic values. This lets workflows adapt to the specific event that triggered them.
### Trigger data
Access information from the event that started your workflow, including ticket properties (title, description, priority, status, Display ID, Short ID), requester information (name, email), custom field values, Slack thread data, and timestamps.
**Example:** Use ticket priority from the trigger to determine which Slack channel receives a notification.
**Example:** Include the Slack thread link in a webhook payload so external systems can link back to the original conversation. Access it via **Ticket > Slack > Thread > Link**.
#### Ticket identifiers
Tickets expose three identifiers in the variable picker. Use the one that matches what your downstream system or message expects:
| Variable | Example | When to use |
| -------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Display ID** | `BUGZ-123` | Human-readable identifier for messages, emails, and external system references. This is what users see in the Ravenna UI and Slack. |
| **Short ID** | `abc12345` | Stable 8-character identifier for URLs, deep links, and API lookups. Useful when you need a compact, unique reference that does not change if the ticket moves channels. |
| **Ticket ID** | `clx1a2b3c4d5e6f7g8h9i0j` | Full internal CUID. Use for API calls or integrations that require the canonical identifier. |
**Example:** Pass the Display ID into a Slack message body so the recipient sees `BUGZ-123` instead of an internal ID. Access it via **Ticket > Display ID**.
**Example:** Append the Short ID to an external URL (`https://example.com/?ref=abc12345`) so you can correlate the ticket later without exposing the channel prefix. Access it via **Ticket > Short ID**.
### Action outputs
Reference results from previous workflow actions, including created ticket IDs, Jira or Linear issue keys, Okta user IDs, Slack thread links, and API response data.
**Example:** Add a Jira issue link to the original ticket after creating it.
### Using the value picker
Click a field input in the workflow builder and select from available data sources. Values resolve when the workflow runs. The builder highlights invalid references before you publish.
***
## Managing steps
Right-click any step in the workflow builder to open a context menu with quick actions, or use the step menu (three-dot icon) on the step card.
### Reorder steps
Drag a step to reposition it in the workflow. Grab a step by its card and drop it onto a highlighted target to move it up or down within a linear chain, or to swap it with another step. Ravenna rewires the surrounding connections for you, so dynamic values from earlier steps keep resolving in the new order.
Some steps stay pinned and cannot be dragged:
* Trigger and placeholder steps
* Loop boundary markers
* Branch group roots, such as the top of an If/Else split or an approval branch
Reordering a step changes the order actions run in. Check that any [dynamic values](/documentation/automate/workflows/workflow-builder#data-flow-and-dynamic-values) referenced by a moved step still come from a step that runs before it.
### Duplicate a step
Copy a single step or an entire branch to reuse configuration:
* **Duplicate node** copies the selected step and inserts it directly below the original. Use the context menu or press ⌘ + D (Mac) / Ctrl + D (Windows/Linux).
* **Duplicate tree** copies the selected step and all of its downstream steps, preserving the branch structure. Use the context menu or press ⌘ + Shift + D (Mac) / Ctrl + Shift + D (Windows/Linux).
Steps inside loops cannot be duplicated.
### Delete a step
Remove steps from the workflow using the context menu or step menu. When deleting a step that has downstream steps, you can choose:
* **Delete node** removes only the selected step
* **Delete tree** removes the selected step and all of its downstream steps
Steps that other parts of the workflow depend on may be protected from deletion.
See all [keyboard shortcuts](/documentation/get-started/shortcuts#workflow-builder-shortcuts) including workflow builder shortcuts
***
## Testing workflows
Test workflows before publishing to verify they work correctly.
Manually trigger your workflow with test data
View detailed logs showing what happened at each step
Confirm each action produced the expected results
Try different scenarios like missing fields or error conditions
Draft workflows can be edited and tested but will not execute automatically. Publish your workflow to make it active.
***
## Templates
Start faster with pre-built templates. Templates provide ready-made workflow structures for common IT operations that you can deploy and customize.
From the workflows list, click **New → Template** to open the template library. Browse available templates filtered by tags or search by name.
Select a template and click **Create Workflow**. The template is copied to your workspace with a pre-filled name and description.
Fill in the step-specific inputs for your organization, such as selecting an Okta application, choosing a Google group, or specifying a Slack channel
Test the workflow to verify it works with your configuration, then publish to make it active
After deploying a template, you have full control over the workflow. Modify steps, add new actions, change the trigger, remove steps that are not needed, or rename the workflow to match your organization's terminology. Templates are starting points.
***
## Tips
* **Start simple.** Begin with linear workflows that handle one specific scenario. Add complexity gradually as you confirm each piece works.
* **Name steps descriptively.** Clear step names make workflows easier to understand and debug, especially when multiple team members work with them.
* **Test with realistic data.** Use data that represents actual conditions. Pay attention to edge cases and error conditions.
* **Plan for failures.** Add conditional logic that checks action results. Consider what should happen if external systems are unavailable.
* **Keep workflows focused.** Create separate workflows for distinct processes rather than one workflow that handles everything.
Learn more about [triggers and actions](/documentation/automate/workflows/triggers-actions), [publishing](/documentation/automate/workflows/publish), and [monitoring workflows](/documentation/automate/workflows/monitor)
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.
## 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.