Canonical page: https://tellenze.com/help/automations

# Automate the repeatable work

Choose a trigger, preview the effects, and enable a rule with confidence.

## Before you start

An automation responds to an event, checks its conditions, and performs one or more actions. It is useful for repeatable coordination such as watching newly created work or notifying someone when work changes.

Automations must be enabled for your installation. Administrators manage workspace rules under **Admin → Automations**. Administrators and the project creator can manage project rules under **Project settings → Automations**. Project rules stay within that project. Rules run with their owner’s current permissions; enabling one does not grant extra access.

## Create and preview a rule

1. Choose **New automation**, then enter a name and description that explain its purpose.
2. Use the default **Guided** view: choose **When this happens**, select **Only for this work**, then choose the actions under **Then do this**. Projects, stages, labels, and people appear by name. Optional conditions narrow which work matches; leaving a condition empty adds no restriction. Actions run in the order shown, and you can add, reorder, or remove them.
3. Switch to **JSON** whenever you want to inspect or edit the underlying definition. Both views edit the same rule, and switching views alone preserves your changes and preview. Expand **Definition reference** for the identifiers available to you when writing JSON.
4. Choose **Preview rule**. Read the matching targets and proposed changes. The preview shows a sample of at most 50 authorized targets; a larger match count is not a promise that every target appears in the sample.
5. Choose **Save draft**. This saves the definition without enabling it. Editing the definition clears its preview, so preview it again before saving.

The preview checks the definition against current work. It does not execute actions or replay old events.

For example, in a project rule choose **Work becomes blocked**, add a **Bug** work-type condition, then choose **Remind the rule owner** with a delay of **60** minutes. Preview the rule and save the draft. No JSON is needed.

The guided view supports all current triggers and action types, optional conditions, and template events. In workspace rules, choose one project before using stages, labels, or specific people. Advanced rules covering multiple explicit projects or using cross-project mappings stay in JSON. Unsupported fields and malformed JSON also stay intact in JSON, with an explanation when you try to switch to Guided. Correct the syntax or continue editing there. References that are no longer available remain visible until you change them; preview checks their validity and access.

## Example: watch new work

Paste this definition into a project automation to add the rule owner as a watcher when a task is created in that project:

```json
{
  "trigger": { "type": "task.created" },
  "conditions": {},
  "actions": [
    { "type": "watch", "watching": true }
  ]
}
```

In a project rule, the project boundary is applied automatically. In a workspace rule, empty conditions are much broader: they can match authorized work across projects. Start with a project rule while learning.

Conditions can narrow the rule by projects, stage keys, workflow categories, work types, labels, assignees, assignment status, milestones, event sources, or GitLab states. When using stage, label, or member references in a workspace rule, explicitly name the projects it can target. Guided selectors fill in the identifiers for you. When editing JSON, copy identifiers from **Definition reference**, rather than substituting display names.

## Example: assign work to the person who picks it up

In a project rule, choose **Work moves to a stage**. Under **Add conditions (optional)**, select the **In progress** stage and **Unassigned (nobody is assigned)**. Add the **Add assignees** action, then set **Who to assign** to **The person who triggered the event**. Preview, save the draft, and review and enable that version.

When someone moves unassigned work to In progress, the rule assigns that person. Work that already has an assignee is left alone, including work assigned while the event waits for processing. Without the Unassigned condition, the action adds the triggering person alongside existing assignees.

The triggering person comes from the recorded event, so it can differ from the rule owner. Preview describes this choice without guessing a person. If the event has no active member, or that person can no longer access the work, the target is skipped. System, automation, and GitLab events do not supply a person for this action.

## How quickly rules run

Task-event rules run after a matching event; they do not repeatedly scan every ticket. Background delivery normally checks for pending events every minute, then a worker executes the rule. Allow roughly a minute plus queue processing time. Due-date and forecast events are generated by separate hourly processing.

If there are no runs after a new matching event, your administrator should check the delivery dispatcher and the automation queue worker. Both must be running. For local development, restart `composer run dev` after updating the application so it starts the delivery processes too.

## Review, enable, and inspect

Open **Review & enable** on the saved rule. Preview the current version in that dialog, check its effects, then choose **Enable reviewed version**. Future matching events can now run the rule. Saving an edit returns the rule to draft and requires another enable review.

Open **Runs** to inspect per-target results and diagnostics. Use **Pause** to stop an enabled rule, or archive it when it is no longer needed. **Include archived** lets you find archived rules and restore them when permitted. Restoration does not replace the review needed to enable a draft.

Automation-originated events are excluded to prevent self-triggering loops, and chains are bounded. Duplicate delivery of an event is handled without intentionally repeating the same action.

Events from applying templates are also excluded by default. Select **Also include events from applying templates** in Guided, or add `"include_template_events": true` at the definition’s top level in JSON, only when you intend to include them. Then preview and review that version before enabling it.

## Choose a trigger and an action

Task triggers include creation, assignment, stage moves, completion, reopening, blocking, unblocking, and approaching a due date. **Work item refined** (`task.refined`) runs when a facilitator applies an approved refinement. Milestone and GitLab triggers are also available where their features and integrations are configured.

Actions include moving, completing or reopening work, changing labels or assignees, watching, setting a reminder, and sending an in-app notification. Choose completion actions carefully: they change the work item’s completion state.

For exact field names, all trigger types, condition matching, action behavior, and cross-project mappings, use the [automation definition reference](https://tellenze.com/help/automation-reference).

Due-date and forecast events depend on the installation’s scheduled processing. GitLab events need a configured integration and identifiable linked work. Ask your administrator to check that setup if these events never appear.

## When something does not work

- **No matching targets:** check project scope, conditions, archived work, and the owner’s access. A new project may legitimately have no current targets to preview.
- **A definition is rejected:** check JSON syntax, supported fields, and the IDs in Definition reference. Stage keys and label names are not interchangeable.
- **The rule never runs:** verify that it is enabled, that a new matching event occurred, and that the rule owner still has access. Previewing and saving alone do not run it.
- **A preview or version is stale:** reopen the rule and preview its current definition. Do not reuse an old review after another person edits it.
- **A run is skipped or fails:** inspect Runs for the affected target. Work may have changed, been archived, or become inaccessible. Correct the cause before expecting a later event to succeed.