> ## 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.
# Workflows
> Build no-code automated workflows that respond to ticket and Slack events and execute actions across your integrated tools using a visual builder.
Build automated workflows that respond to events and execute actions across your integrated systems. The visual builder connects triggers and actions without any coding required.
## System overview
A workflow is a background automation: one trigger connected to one or more actions. When the trigger event fires and passes its filters, the workflow engine creates a run and executes the action graph. Actions can run sequentially, in parallel branches, or through converging paths that wait for all parents to complete.
| | Workflows | Agent rules |
| -------------------- | ---------------------------------------------- | -------------------------------- |
| **Execution** | Background, asynchronous | Conversational, real-time |
| **State** | Multi-step with wait states, approvals, delays | Stateless, single-turn responses |
| **Triggers** | Events, schedules, agent handoff | User messages |
| **Branching** | Conditional paths, parallel execution | Linear rule matching |
| **External systems** | Native integration actions, HTTP requests | Tool calls |
**Use workflows when you need:** approval gates, parallel execution across systems, scheduled automation, wait states (for messages, approvals, inactivity), multi-step orchestration with error handling.
**Use agent rules when you need:** conversational information gathering, simple ticket updates, interactive dialogue, single-action responses.
***
## Available building blocks
**Triggers:** Ticket lifecycle (created, assigned, status changed, tags changed, archived, approval decision), form submitted, task events (completed, template applied), message sent, Slack reactions (added/removed), cron schedule, and third-party integration events.
**Actions by category:**
* **Ticket management:** Create Ticket, Update Ticket, Set Status, Set Priority, Add Assignee, Add Followers, Add Approvers, Add Tags, Move Ticket, Share Ticket, Search Tickets, Publish Ticket, Link Ticket, Apply Task Template, Send CSAT
* **Wait and monitoring:** Wait (duration), Wait Until (absolute date), Wait for Approval, Wait for Message, Wait for Inactivity, Monitor Ticket, Check for New Messages
* **Control flow:** Conditional, If/Else, Goto, Loop
* **AI:** Summarize Ticket, AI Decision Maker, Custom Prompt
* **Messaging:** Send Message, Send Email
* **HTTP:** HTTP Request (external API calls)
* **Integrations:** Okta, Google Workspace, Slack, Jira, Linear, Fleet, Jamf, and others (see integration docs)
For detailed descriptions and use cases for each trigger and action, see the triggers and actions reference.
***
## Agent-workflow integration
Agents cannot trigger workflows directly. Connect the two through ticket state: have the agent create or update a ticket, and configure a workflow that fires on that change.
Common handoff patterns:
* **Form submission.** The agent asks the user for details and submits a form on the ticket. Configure a Form Submitted workflow to run backend processing (provisioning, approvals, external system sync).
* **Category assignment.** The agent classifies the request with `@Set Category`. Configure a Category Assigned workflow to route the ticket or kick off category-specific automation.
* **Tag or status change.** The agent applies a tag or moves the ticket to a status. Configure a Tags Changed or Status Changed workflow to react.
* **Ticket creation.** The agent publishes a ticket into the appropriate queue. Configure a Ticket Created workflow (filtered by queue, category, or form) to take it from there.
**Recommended pattern:** Use the agent to handle the conversation (collecting information, answering questions, categorizing) and use workflows for the backend execution that follows. Ticket events are the handoff.
***
## Common patterns and recommended approaches
**Approval flows:**
Trigger on ticket creation or form submission. Add approvers (use Round Robin for load balancing or All for any-available approval). Add a Wait for Approval step, then branch into approved, declined, and timeout paths. The approved path provisions access or executes the request. The declined path notifies the requester with the reason. The timeout path escalates the request, reassigns to a backup approver, or auto-closes the ticket as expired.
**Employee onboarding and provisioning:**
Trigger on form submission in the IT queue. Use parallel branches to provision across systems simultaneously: Okta group assignment, Google Workspace account, Slack channel invites. Converge the branches, then send a summary notification. Each branch is independent, so one failure does not block the others.
**Ticket escalation:**
Trigger on status change or inactivity. Use a conditional to check priority or SLA status. Escalation path reassigns the ticket, notifies management, and optionally creates an incident in PagerDuty or Incident.io. Non-escalation path sends a reminder.
**External system sync:**
Trigger on ticket creation. Create an issue in Jira, Linear, or another system. Use the Link Ticket action to attach the external issue URL back to the Ravenna ticket. This maintains bidirectional traceability.
**Scheduled maintenance:**
Use a Cron trigger for recurring tasks like checking for stale tickets, sending digest reports, or running periodic cleanup. Cron-triggered workflows do not have ticket context, so you cannot reference ticket fields in downstream steps.
**Wait-then-follow-up:**
After an action (like sending a message or requesting info), add a Wait for Message or Wait for Inactivity step. Branch based on whether a response was received (timeout vs. success). Use this for follow-up reminders or auto-resolution after inactivity.
***
## Constraints and gotchas
* **One trigger per workflow.** If you need the same actions for multiple events, create separate workflows or use a broad trigger with conditional branching.
* **Cron triggers have no ticket context.** You cannot use ticket dynamic values in workflows triggered by a schedule. Use cron workflows for batch operations that query or iterate over tickets via other means.
* **Agents cannot trigger workflows directly.** Hand off through ticket state (form submitted, category assigned, tags changed, status changed) and let a workflow fire on that event.
* **Converging branches wait for all parents.** A converging step does not execute until every parent branch completes or is skipped. Design parallel branches to be independent so one slow branch does not delay the entire workflow.
* **Wait steps have timeouts.** Wait for Message and Wait for Approval both default to 3 days. Wait for Approval branches into On Approved, On Declined, and On Timeout, so always plan a path for stalled approvals (escalate, reassign, or auto-close).
* **Published workflows are live immediately.** There is no staging environment. Test thoroughly in draft mode before publishing.
***
## Building guidance
* **One workflow per process.** Do not combine unrelated automations into a single workflow. Separate workflows are easier to debug, monitor, and maintain.
* **Start linear, add complexity later.** Build a straight-line workflow first (trigger, then action, then action). Add conditional branches and parallel paths only after the linear version works.
* **Name workflows descriptively.** The agent references workflows by name in rules. Clear names like "IT Access Provisioning" or "Jira Sync for Engineering" make rules more readable.
* **Generate complex workflows from descriptions.** For multi-branch workflows with many actions, generating the structure from a natural language description and then reviewing the result is more efficient than building step by step.
* **Prefer native integration actions over HTTP Request.** If an integration has a dedicated action (Okta, Jira, Linear, etc.), use it instead of calling the API via HTTP Request. Native actions handle authentication, error handling, and output parsing automatically.