 |
Summary | Discourse Workflows lets admins create advanced automations through a visual builder to automate almost anything in your community. |
 |
Install Guide | This plugin is bundled with Discourse core. There is no need to install the plugin separately. |
Workflows is a visual automation builder that lets admins create advanced, multi-step automations using a drag-and-drop canvas — connecting triggers, conditions, actions, and flow-control nodes to automate almost anything on your Discourse site.
Discourse Workflows is available on the Business or Enterprise plans.
Key concepts
If you’re familiar with other automation tooling, you will likely recognize most of the vocabulary used in Workflows:
- Workflow: A saved automation made up of connected nodes.
- Node: A single step in a workflow: triggers, conditions, actions, and flow-control / utilities.
- Trigger: The starting point of a workflow. A trigger can be manual or initiated by a specific event — topic being created, a schedule firing, or an incoming webhook.
- Condition: A routing node that evaluates a rule and splits the flow into branches. For example, an If node routes the flow based on a true or false evaluation.
- Action: A node that does something specific — creating a post, granting a badge, calling an external API, etc.
- Item: The data that flows between nodes. Items are JSON objects that you can inspect in execution logs and reference using expressions.
- Expression: A dynamic value written as
{{ ... }}that resolves at runtime and is used to reference data from earlier nodes, workflow variables, or site settings.
Creating a workflow
To build a workflow:
- Go to Admin > Plugins > Workflows and click New workflow.
- Name your workflow.
- Click Add first step and choose your trigger.
- Use the + button to add additional nodes.
- Double-click on a node to configure it. In the configuration panel, details about inputs for the node will be shown on the left side and details about the outputs of the node will be shown on the right side of the screen. You may need to run the workflow once before seeing all the various details.
- When you’re ready to go live, click Publish.
Tips:
- Use sticky notes, located in the three-dot menu in the top right of the builder, to document what your workflow does. Stickies don’t have any effect on the workflow but make templates and shared workflows easier to understand.
- Use the log node during development to send debug values into the execution log without impacting the workflow’s behavior.
- You can export and import workflows as JSON to share them with teammates or recreate workflows from other sites.
Expressions and dynamic data
Fields that accept expressions show a {/} button in the editor. Click it to browse available data from the trigger and earlier nodes and insert a reference.
Common expressions
| Expression | What it returns |
|---|---|
{{ $json.topic.title }} |
The title of the topic from the current item |
{{ $json.post.url }} |
The URL of the post from the current item |
{{ $json.user.username }} |
The username of the user associated with the current item |
{{ $vars.my_variable }} |
The value of a workflow variable named my_variable |
{{ $site_settings.title }} |
Your site’s title |
{{ $execution.id }} |
The unique ID of the current execution |
{{ $('Node Name').item.json.property }} |
Output from a specific upstream node, referenced by its canvas name |
Static and dynamic values
Fields that start with = are treated as expressions. Fields without a leading = are treated as plain text. The expression picker handles this for you automatically.
Managing workflows
There are a number of features that help you manage your existing workflows.
Executions
Every time a workflow runs, Discourse records an execution. Go to Workflows → Executions to see the history.
Each execution shows the date and time when it was completed and its status:
- Completed: Ran to completion without error.
- Error: Failed at a specific node; click into the execution to see the error and the data that caused it.
- Running: Currently processing.
- Waiting: Paused due to a Wait node; waiting for a response in a form, modal, chat approval; or a Call Workflow node waiting for a sub-workflow to complete.
- Rate limited: The workflow was skipped due to rate limiting.
- Skipped: The trigger fired but the workflow was unpublished.
You can click the Show button for a more in depth look at the workflow’s execution. This shows each step of the workflow, which you can expand to view the exact details, and the duration of that step.
At the bottom of the page, you can see the overall duration of the workflow. You can also Export the log if needed for sharing or troubleshooting purposes.
Settings
On the Workflows → Settings tab, you can:
- Configure an error workflow that should trigger if there are any failures when this workflow runs. If the workflow has an error trigger, it will handle errors as defined by that trigger.
- Set the timezone for schedule triggers. The workflow will default to using the site timezone if this is unset.
- Delete the workflow.
This is permanent so you should consider exporting your workflow (accessible in the three-dot menu on the top right corner of the workflow builder) before proceeding.
Versions
Every time you make an update to the workflow, we’ll save the previous version(s). This makes it easy to Revert changes that didn’t work as you expected.
Variables
Variables are key-value pairs scoped to a single workflow. Define them in the workflow’s Variables panel and reference them anywhere with {{ $vars.key_name }}. Use variables to store configuration values (like a category ID or a recipient username) that you want to be able to change without editing the workflow graph.
Credentials
Some nodes — like HTTP request or AI Agent — need to authenticate with external services. Store API keys and secrets in Workflows → Credentials rather than pasting them directly into node fields. Credentials are encrypted at rest and can be reused across workflows.
Supported credential types:
- Basic Auth (username + password)
- Bearer token
- Header auth (custom header name and value)
Data tables
Data tables are persistent, structured tables internal to the Workflows plugin. Use the Data table node to read from or write to them. They support string, number, boolean, and date column types.
Data tables are useful for:
- Deduplication — record which users or topics a workflow has already processed
- State — track whether a topic is in a particular stage of a process
- Lookups — store mappings (like topic ID → assigned staff member) that your workflows can query
Executions
You can view all the executions of all workflows from the Executions tab. The format and function is very similar to the workflow-specific executions, but shows across all workflows for easier monitoring.
Templates
When you create a new workflow, you can start from a template instead of a blank canvas. Templates are pre-built workflows for common use cases — they’re annotated with sticky notes explaining how they work and are a good way to learn the system.
Interested in seeing more templates? We will work to expand the library of available templates over time, but please let us know if there’s a template that you’d like to see here to make your use of Workflows easier.
You can also export any workflow as a JSON file to share it with others or use it as your own starting point.
