Automation
This page is for administrators. Automation rules do routine work for you — "when this happens, and these things are true, do that" — without anyone writing code. Rules live under Administration → Automation.
What a rule is made of
Every rule has three parts:
| Part | What it decides |
|---|---|
| Trigger | What starts the rule. |
| Conditions | Whether it should proceed this time. |
| Actions | What it does. |
Triggers
An event — something happened in the system. The list in the form is grouped:
Group What it covers Issue Created, transitioned, updated (an assignee change included), deleted, commented on, a comment edited or deleted, an attachment, a link or a watcher added or removed. Project Created, updated, deleted, a role member added or removed. Board Created, updated, deleted, a column updated or reordered. Webhook An inbound webhook arrived. Other An upload finished; plus events brought in by enabled features — an incoming email, for instance. Issues, projects and boards also offer an “any event of this group” option — handy when a rule cares about everything that happens to an object.
A schedule — the rule runs periodically, without waiting for anything to happen; it can walk a selection of issues.
By hand — you run it yourself with the Run button in the rule list.
A schedule over a selection
A scheduled rule has an Issue selection field — the list of saved filters. Pick one and every tick walks each issue it finds: the conditions and actions run for that issue, and the run log gets a separate line per issue.
That is how a regular sweep is built: "label everything overdue", "return approvals stuck for over a week", "archive what was closed a month ago". Previously this needed an external script — a scheduled rule fired once and knew about no issue at all.
- No selection (single run) is the old behaviour: one run, with no issue in the context.
- The number of issues per pass is capped (200 by default) so that a filter with no conditions cannot turn into a walk over the whole database. The cap is set in the configuration.
- Issues are processed one after another, not all at once.
- If the filter is deleted or becomes unavailable, the log says the selection is unavailable — the tick itself does not fail.
A scheduled run has no author
Nobody triggered the event, so the actions use service access. Anything that needs no author works: labels, fields, statuses, emails, external calls. Adding a comment does not — a comment must have an author. That is why the "Nightly overdue scan" template sets a label instead of commenting.
An inbound webhook as a trigger
An event produced by an inbound webhook starts a rule exactly like an internal one. The order is:
- Create the hook in Admin → Webhooks and hand the issued address to the external system.
- Wait for a real call and inspect the request body in the call log.
- In the rule pick the webhook trigger and name your own hook instead of
*. Otherwise the rule fires on every webhook the instance receives — rarely what you want. - Take the body apart with conditions: webhook fields are a group of their own, and any other place in the body is reachable through Custom path — see Conditions.
An incoming email as a trigger
If mail intake is on, a customer's message becomes an event too. The rule can read the sender and their domain, the recipient address, the subject, the text, the authenticity verdicts (DMARC, SPF, DKIM), the “spam” and “auto-reply” flags, and In-Reply-To — which is how a first request is told apart from a reply in an existing thread.
Conditions
Conditions are a tree, not a flat list: you combine them with and / or and can negate any branch, so a rule can express "high priority and either unassigned or overdue" without contortions. A wide set of comparison operators is available — equality, ordering, containment, emptiness, changed/unchanged, and so on — with the ones offered depending on the field you're comparing.
Fields are grouped: fields of the event (what changed, from which status to which), of the issue, the project, the actor, the comment, plus the webhook and email fields when the rule is triggered by those. A separate group holds feature conditions, contributed by enabled features — see below.
Custom path — when the field you need isn't listed
The ✎ enter a path manually… entry lets you compare any value from the event. That is how an arbitrary webhook body is taken apart: the body sits at payload.body and the headers at payload.headers, so a path looks like payload.body.action. What the sender actually sent is visible in the call log on Admin → Webhooks.
Actions
There are two dozen built-in actions, grouped in the form:
| Group | What it can do |
|---|---|
| Issue | Assign and unassign, set co-assignees; change status, priority, type, due date, estimate; add and remove a label; add a comment (internal ones included); add and remove a watcher; link issues; create a new issue, including a subtask. |
| External | Send an email; call an external address — your own method, headers and body. Tokens for the call are best kept as secrets: {{secret.NAME}} gets the real value only here, and shows as *** in the log and in a dry run. |
| Flow | Stop if — abandon the rest of the rule when a condition holds. Pause — pause, then continue later: deferred steps are picked up when they come due, so "if still untouched after 2 days, escalate" is a single rule. |
| Debug | Write text into the run log — so you can see the rule reached this point and with what values. Also an arbitrary API call here, as a last resort for what the other actions don't cover. |
Action fields accept substitutions such as {{issue.key}}, {{actor.id}}, {{mail.subject}} — the value comes from the event the rule ran for.
Type two opening braces
The fields that take substitutions prompt you themselves: type {{ and a list of available paths with descriptions drops down; the braces button in the field's corner opens the same list with a search box and grouping. You can search by the translated label ("priority") as well as by the raw path. Below the field you get a breakdown of what you typed and a preview of the value.
The list does not restrict input: a path that isn't in it is marked as unknown to the catalogue but still accepted — otherwise the body fields of an arbitrary webhook would be out of reach.
These are not the notification email placeholders
Same braces, different and non-overlapping sets of names: in a rule it is a path into the event ({{issue.key}}), while in a notification email template it is a short name from a closed dictionary ({{issueKey}}). A name from the wrong set resolves to an empty string.
Beyond these, enabled features contribute their own actions — see below.
A rule acts with the rights of whoever caused the event
Changes are made on behalf of the event's actor, not of an administrator. If that person lacks the right, the step fails — which is visible in the run log. Email and the data reads needed for conditions use service access, so conditions do not depend on who pressed the button.
Form and diagram
The rule form comes in two views, switched in its header:
| View | What it shows |
|---|---|
| Form | The familiar lists: conditions in one, actions in the other. |
| Diagram | The rule as a chain: Trigger → Conditions → Action 1 → Action 2 …. Clicking a node opens its settings on the right. |
These are two views of one rule, not two editors: switching loses nothing and saves nothing — you save with the usual button. The diagram makes visible what lists hide: a required parameter left blank is highlighted, and an action from a disabled feature is marked "no handler" — such a rule will log an error.
The order of actions is the chain: drag a link from one action onto another to put it next; the Delete key removes the selected action.
The diagram has no branches, deliberately
A rule executes its actions in order and knows nothing about forks. A conditional stop is the Stop if action, not a second branch on the canvas: drawing a fork that execution will never take would promise behaviour that does not exist.
If the instance core is not fully updated, the Diagram tab may be absent altogether — the form keeps working as usual.
Rule templates
Above the rule list sits a Rule templates card with common patterns — clicking one drops a ready-made recipe into the form and saves nothing until you save it yourself. Starting from a template and adjusting it is usually quicker than building a rule from scratch, and it shows you how the pieces fit together.
| Template | What it does |
|---|---|
| Assign on start | Whoever moves an issue into progress becomes its assignee. |
| Escalate critical | A critical issue gets a label and a notification on creation. |
| Customer reply reopens | A customer's comment brings a closed request back into work. |
| Stale issue label | An issue untouched for a long time gets labelled. |
| Watch my changes | Whoever changes an issue starts watching it. |
| Nightly overdue scan | Labels issues on a schedule. Pick an issue selection — a saved filter such as "due before the start of today and not done". |
| Delayed follow-up | Two days later checks the issue is still resolved and comments. |
| Subtask comment — to the parent | Copies a comment from a child issue into its parent. |
| Issue from a webhook | A starting point for an external system: replace * with your hook's name, set the project and the paths into the body. |
| Issue from a customer email | An email from a trusted sender with a passing DMARC becomes an issue. Set the project and your customers' domains. |
| Customer reply into the thread | A reply is appended as a comment. How to find the right issue is up to you — the issue key in the subject, for instance. |
| Email quarantine | Spam, mail without DMARC and auto-replies go to a separate project for a human to sort out. |
A template is a starting point, not a finished rule
The last three deliberately arrive with an empty project and an empty list of trusted domains: an empty list means “from nobody”, which beats a rule that creates issues from any message on the internet out of the box. Fill them in with your own values and check with a dry run.
Actions and conditions from other features
Automation isn't limited to what the automation feature itself knows. Other features register their own actions and conditions, and those appear in the rule form automatically once the feature is enabled:
| Feature | Adds conditions | Adds actions |
|---|---|---|
| Custom fields | Compare the value of a field by key | Set the value of a field |
| SLA | SLA breached; minutes remaining before breach; timer running | — |
| Service Desk | Approval status; CSAT rating | Start an approval |
| Portfolios | Project RAG status; number of overdue milestones in the project | — |
| Release waves | — | Set a brand's status in a wave |
| Notifications | — | Notify issue participants — assignees, watchers or both, through their usual channels |
Features also bring their own events for the trigger: portfolios — RAG status changed, milestone overdue or approaching; release waves — wave created, an issue or a brand added to or removed from a wave, a brand's status changed. The fields of such an event (brand name, previous and new status and so on) are available to conditions and substitutions like any other.
If a feature is disabled or unavailable, its conditions evaluate as not met and its actions fail with an error in the run log. A feature that has quietly stopped will not cause rules to fire wholesale.
Testing a rule
Two buttons, and the difference matters:
- Test — a dry run. Conditions are evaluated against real data, but actions only report what they would have done. Nothing is changed.
- Run — a real run, with real consequences.
You can also replay a past run from the log — useful when a rule failed because of something you've since fixed.
The run log
Every run is recorded: what triggered it, whether the conditions matched, which actions executed, and the error when one failed. When a rule "doesn't work", the log almost always says why — most often a condition that didn't match the data, or an action belonging to a feature that's switched off.
Sending email from a rule
The Send email action needs a mail transport, chosen on this page. Until one is assigned, rule email isn't delivered — the attempt is recorded in the delivery log. See Email → Assignments.
The run log shows that the rule did its part, but doesn't follow the message any further: if the provider refuses it later, that is only visible on Admin → Mail — in the outgoing queue and the delivery log. Mind the priority, too: rule email has the lowest one, so when mail is congested a bulk mailout goes last and doesn't hold up password resets and notifications.
Loops and runaway rules
Rules change issues, and changed issues trigger rules. TaskFlow guards against that in three independent ways: it limits how deep a chain of rule-caused changes may keep triggering further rules; it stops a rule from reacting to an event it caused itself, unless the rule's Allow self-trigger box is ticked; and it caps how often one rule may run against one issue within a time window. The defaults of the first and third guards are sensible; they're adjustable in Configuration → Automation limits if you have a reason.
Even so, when you write a rule that edits the same kind of issue it reacts to, add a condition that makes the second pass a no-op. The guards are a safety net, not a design.
Where to go next
- Webhooks — how to let external events in and send your own out.
- Email — transports for rule email, and mail intake.
- Plugins — enabling the features that contribute conditions and actions.
- Project configuration — the statuses and fields rules act on.
- Filters & saved views — where the issue selections for scheduled rules come from.
See also
- Agent guide → SLAs — the SLA conditions available to rules, and why a breach notifies nobody by itself.
- Issues & tasks → Watchers — one of the typical rule actions, seen from the user's side.
- Features & settings → Audit log — where you can see what a rule changed.
- Configuration → Automation limits — the loop guards and the deferred-step interval.