![]() |
Summary | Discourse Automation lets you automate actions through scripts and triggers. Customisation is made through an automatically generated UI. |
![]() |
Repository Link | https://github.com/discourse/discourse-automation |
![]() |
Install Guide | How to install plugins in Discourse |
Features
- Easy automation of complex workflows
- Triggers automations at specific dates, periodically, or on specific events
- Provides automatically generated UIs to specify options for your automation
Vocabulary
-
trigger: represents the name of the trigger, eg:
user_added_to_group
-
triggerable: represents the code logic associated to a trigger, eg:
triggers/user_added_to_group_.rb
-
script: represents the name of the script, eg:
send_pms
-
scriptable: represents the code logic associated to a script, eg:
scripts/send_pms.rb
Configuration
Automations can be created and updated from Admin ā Plugins ā Automations, or directly from /admin/plugins/discourse-automation
.
Available scripts
Script name | Plugin | Description |
---|---|---|
Banner Topic | automation |
convert a topic into a banner notice |
Flag post on Words | automation |
flag a topic on creation/edition if it contains specific words |
Gift Exchange | automation |
simple implementation of the secret santa game |
Pin Topic | automation |
pin and unpin a topic in the future |
Send PMs | automation |
send PMs with support for placeholders |
Suspend User By Email | automation |
suspend a user for a specified duration |
Topic required words | automation |
enforce the presence of at least one of the specified words in the posts of a topic |
Auto Responder | automation |
given a series of keywords and associated replies, automatically respond with the corresponding reply |
User Global Notice | automation |
presents a global notice on the site for a specific user |
Random Assign | assign |
assign a random user from a given group to the given topic |
Close topic | automation |
close a topic, optionally with a closing message |
Available triggers
Note that due to their nature, each script only supports certain triggers. For example it wouldnāt make sense for a script enforcing the content of a post to trigger when a user is added to a group.
Trigger name | Plugin | Description |
---|---|---|
API Call | automation |
triggers when a certain API endpoint is called |
Recurring | automation |
triggers at intervals ranging from every minute to every year |
Point in Time | automation |
triggers at a specific date and time |
Post created/edited | automation |
triggers when a post of a specified topic is created or edited |
User added to group | automation |
triggers when a user is added to a group |
User promoted | automation |
triggers when a user is promoted from one specified trust level to another, or for all of them |
Stalled wiki | automation |
triggers when a wiki hasnāt been edited for a while |
First accepted solution | solved |
triggers when a user achieves their first accepted solution |
More scripts and triggers to come!
Plugin API
add_automation_scriptable(name, &block)
add_automation_triggerable(name, &block)
Scriptable API
field
field :name, component:
lets you add a customisable value in your automationās UI.
List of valid components:
# foo must be unique and represents the name of your field.
field :foo, component: :text # generates a text input
field :foo, component: :list # generates a multi select text input where users can fill values
field :foo, component: :choices, extra: { content: [ {id: 1, name: 'your.own.i18n.key.path' } ] } # generates a combo-box with a custom content
field :foo, component: :boolean # generate a checkbox input
field :foo, component: :category # generates a category-chooser
field :foo, component: :group # generates a group-chooser
field :foo, component: :date_time # generates a date time picker
field :foo, component: :tags # generates a tag-chooser
field :foo, component: :user # generates a user-chooser
field :foo, component: :pms # allows to create one or more PM templates
field :foo, component: :categories # allows to select zero or more categories
field :foo, component: :key-value # allows to create key-value pairs
field :foo, component: :message # allows to compose a PM with replaceable variables
field :foo, component: :trustlevel # allows to select one or more trust levels
triggerables and triggerable!
# Lets you define the list of triggerables allowed for a script
triggerables %i[recurring]
# Lets you force a triggerable for you script and also lets you force some state on fields
field :recurring, component: :boolean
triggerable! :recurring, state: { foo: false }
placeholders
# Lets you mark a key as replaceable in texts using the placeholder syntax `%%sender%%`
placeholder :sender
Note that itās the responsibility of the script to provide values for placeholders and to apply the replacement using input = utils.apply_placeholders(input, { sender: 'bob' })
script
This is the heart of an automation and where all the logic happens.
# context is sent when the automation is triggered, and can differ a lot between triggers
script do |context, fields, automation|
end
Localization
Each field you will use will depend on i18n keys and will be namespaced to their trigger/script.
For example a scriptable with this content:
field :post_created_edited, component: :category
Will require the following keys in client.en.yml:
en:
js:
discourse_automation:
scriptables:
post_created_edited:
fields:
restricted_category:
label: Category
description: Optional, allows to limit trigger execution to this category
Note that description is optional here.