 |
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, 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 move them between sites. See Exporting and importing workflows below for what is and isn’t transferred.
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 |
{{ $workflow_vars.my_variable }} |
The value of a workflow variable named my_variable |
{{ $vars.my_variable }} |
The value of a global 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.
Exporting and importing workflows
Use the three-dot menu in the top right corner of the workflow builder to Export a workflow as a JSON file, and Import to load one. Common uses: sharing a workflow with teammates, or moving it from a staging site to production.
Importing adds the file’s nodes to the workflow you have open; it does not create a new workflow. To copy a workflow, create an empty workflow first, then import into it. Imported changes are saved as a draft until you publish.
Included in the export: nodes and their configuration, connections, sticky notes, and workflow variable definitions.
Not transferred, so set these up on the destination site before publishing:
- Credentials: credential references are removed on import. Create the credentials on the destination site and select them again in each node.
- Data tables: tables, columns, and rows are not exported. Recreate them and select them in the Data table nodes.
- Variable values: workflow variable definitions are imported, but not their values. Set them in the workflow’s Variables tab. If a variable with the same key already exists, the import keeps the existing one and shows which keys were skipped. Global variables are not exported.
- Workflow settings: the error workflow and timezone are not applied. Set them again in the Settings tab.
- Site-specific references: IDs, names, and URLs for categories, groups, users, chat channels, Data Explorer queries, and called workflows are kept as-is and may not match the destination site. Workflow variables make these easier to change.
Variables
There are two kinds of variables:
- Workflow variables are scoped to a single workflow. Define them in the workflow’s Variables tab and reference them with
{{ $workflow_vars.key_name }}. They have a type (string, integer, boolean, enum, category, category list, group, group list, tag list, or list), so values are validated and picked with the right selector. Changes to definitions and values follow the workflow’s draft/publish flow. - Global variables are shared by all workflows. Define them in Workflows → Variables and reference them with
{{ $vars.key_name }}.
Use workflow variables for values that change between sites or uses, such as a category, a group, or a recipient, so you can reuse the workflow without editing its nodes.
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.
