Workflows

Workflows let you react to events in your workspace by chaining together checks and actions. A workflow has one Trigger (the event that starts it), zero or more Conditions (gates that decide which branch to follow), and one or more Actions (what actually happens). You build them visually on the workflows canvas — drag a node from the palette on the left, drop it on the canvas, click to configure, and connect the nodes with edges.

How a workflow runs

When something happens in your workspace — a warning is issued, a quota is missed — RankGun checks every active workflow for that trigger and runs each matching workflow in the background. For each workflow it walks the graph top-to-bottom in execution order: a trigger fires, then any conditions evaluate against the event data, and actions on the live branch are executed in order.

Workflows are evaluated against the event data captured at the moment the trigger fired. They don't re-poll the database, so if something changes after the trigger fires the workflow doesn't notice.

Rate limits

To protect your workspace, the Roblox API, and your Discord channels from runaway automation, the following caps are enforced:

When the workspace or per-workflow hourly cap is hit, additional triggers are silently dropped until the hour rolls over. When the per-execution Roblox-API cap is hit, subsequent ranking actions in that run are marked skipped in the execution log.

Triggers

Exactly one trigger per workflow. The trigger decides what kind of event starts the run and what data is available to the rest of the graph.

logbook.comment — Comment Created

Fires every time someone adds a comment entry to a logbook record.

Internal trigger data also includes targetMemberId, targetRobloxId, and authorId — actions can use these (e.g. promote/demote will target the same member).

logbook.warning — Warning Issued

Fires when a warning entry is added.

logbook.promote — Promote Logged

Fires when a promote entry is added to the logbook (i.e. a promote action was recorded for the member).

logbook.demote — Demote Logged

Fires when a demote entry is added.

logbook.notice — Notice Added

Fires when a notice entry is added.

quota.missed — Quota Missed

Fires when the daily quota-evaluation cron records a failed period for a member. Fires on every miss, regardless of whether the quota's "Demote after" threshold has been reached — so you can use this trigger for soft notifications even on the first miss.

Conditions

Conditions are optional. They sit between the trigger and the actions and produce a boolean result. Connect the condition's "true" handle to actions you want to run when the condition matches, and the "false" handle to actions you want to run otherwise. (Unconnected handles simply drop the branch.)

Warning Count

Compare the target member's current warning count against a number. Operators: gt, gte, lt, lte, eq, neq.

Example: Warning Count gte 3 — only continue if the member has 3 or more warnings.

Member Role

Check the target member's workspace role. Operators: eq, neq. Values: owner, admin, moderator, viewer.

Content Contains

Match against trigger text (the logbook entry's content). Operators: contains, eq, neq. Case-insensitive.

Actions

Actions are what the workflow actually does when its branch is reached. You can chain as many actions as you want, up to the 50-node limit.

Send Notification

Posts a notification inside RankGun. Recipient options:

• Target Member — the member referenced by the trigger.
• Workspace Admins — every owner and admin in the workspace.
• All Moderators — every moderator in the workspace.

Configure a Title and a Message. Both support template variables.

Send Discord Message

Posts a message to a Discord channel via an incoming-webhook URL. Configure:

• Discord Webhook URL — must be https://discord.com/api/webhooks/... (or the ptb. / canary. variants). Create one in any Discord channel: Channel Settings → Integrations → Webhooks → New Webhook.
• Message — the text to post. Supports all template variables.

Promote Member

Calls the Roblox API to promote the trigger's target member to the next rank. Configure an optional Reason (used for the audit log). Counts against the 5-API-actions-per-execution cap.

Demote Member

Calls the Roblox API to demote the trigger's target member to the previous rank. Same shape as Promote.

Set Rank

Calls the Roblox API to set the trigger's target member to a specific rank. Configure the Target Roblox role with the rank selector and an optional Reason.

Create Audit Log

Writes an entry to the workspace audit log. Configure an Action Name (e.g. workflow.custom_action). Useful for marking that a workflow ran without taking a visible action.

Add Logbook Entry

Adds an entry to the trigger member's logbook. Configure the Entry Type (comment, warning, promote, demote, notice) and the Content. The author is set to whoever caused the trigger.

Template variables

Anywhere a field says "supports template variables", you can drop in one of these placeholders and it'll be replaced with the corresponding value from the trigger:

Variables that aren't available for the current trigger render as ? or empty string, so a template like {{quotaName}} in a logbook workflow won't crash — it just produces an empty section. Stick to the variables listed for your trigger and the output will be clean.

Worked example: warn three times, ping Discord, and demote

A common request: when a staff member crosses three warnings, ping a Discord channel and demote them automatically.

1. Drag a Warning Issued trigger onto the canvas.
2. Drag a Warning Count condition. Configure it: operator gte, value 3. Connect the trigger to the condition.
3. Drag a Send Discord Message action. Configure the webhook URL and a message like {{memberName}} just received warning #{{warningCount}} — demoting now. Connect the condition's true handle to this action.
4. Drag a Demote Member action. Set a reason like 3-warning auto-demote. Connect the true handle (or the Discord action, since multiple downstream actions on the same branch all run) to this action.
5. Toggle the workflow Active and save.

The first two warnings on a member will run the workflow but stop at the condition (warningCount is 1, then 2, both less than 3). On the third warning the condition becomes true and both actions fire.

Worked example: quota miss ping

To ping a Discord channel any time someone misses a weekly quota:

1. Drag a Quota Missed trigger.
2. Drag a Send Discord Message action and connect them.
3. Configure the webhook URL and a message like {{memberName}} missed {{quotaName}} — {{actualMinutes}}/{{requiredMinutes}} min ({{consecutiveMisses}} in a row).
4. Save and activate.

Now every failed quota period emits a Discord ping. If you only want to ping on the second consecutive miss (e.g. you tolerate one bad week silently), put the message in a quota.missed workflow that runs every miss — there's no built-in consecutive-miss condition yet, but the {{consecutiveMisses}} value in the message makes the streak obvious to whoever's reading.

Troubleshooting

• My workflow didn't run. Check the executions log on the workflow detail page. If you see nothing, the trigger may not have fired (e.g. the logbook entry was edited rather than created), the workflow may be inactive, or you may have hit the per-hour cap.
• A condition is always false. Re-check the operator and value. Condition values are strings unless the type is "Warning Count" (number) or "Member Role" (enum) — sending "3 " with a trailing space will mismatch.
• Discord message didn't arrive. Confirm the webhook URL is still valid (Discord lets you regenerate or delete it from the channel settings). Webhook failures are logged but do not fail the rest of the workflow.
• Roblox action was skipped. You've exceeded the 5-API-actions-per-execution cap. Move some actions to a follow-up workflow with a different trigger, or remove unnecessary ranking steps.