Canonical page: https://tellenze.com/help/automation-reference

# Automation definition reference

Look up every trigger, condition, action, and project mapping with a working JSON example.

## Start with a working rule

Use this reference while editing **Definition (JSON)**. New rules start in **Guided**, where you can select events, conditions, and actions by name. Switch between **Guided** and **JSON** to edit the same definition; advanced multi-project rules and mappings use JSON. The [automation walkthrough](https://tellenze.com/help/automations) explains both views, previewing, saving a draft, reviewing, and enabling it. A saved draft does not run.

This project rule watches blocked bugs and schedules a reminder for its owner one hour after the event is processed:

```json
{
  "trigger": { "type": "task.blocked" },
  "conditions": { "types": ["bug"] },
  "actions": [
    { "type": "watch", "watching": true },
    { "type": "reminder", "offset_minutes": 60 }
  ]
}
```

Choose a project you can manage, paste the example, and preview it. Once enabled, a new matching block event can run it. The reminder delay starts when the action runs; it is not measured backwards from the task’s due date.

## Definition structure

Every definition needs a `trigger` object with a supported `type`, a `conditions` object, and an `actions` array containing one to ten actions. Use `{}` for no extra conditions. Project rules automatically receive their project boundary; workspace rules need deliberate scoping.

The optional top-level `include_template_events` boolean defaults to `false`. Set it to `true` to include events created by applying templates. Automation-originated events remain excluded to prevent loops. The optional `mappings` array translates references for rules spanning projects.

Definitions support the fields below. They are not scripts and do not accept arbitrary expressions, custom code, email bodies, or outbound webhook actions.

## Supported triggers

| Event | Trigger type |
| --- | --- |
| Work created, refinement applied, or assignment changed | `task.created`, `task.refined`, `task.assigned` |
| Work moved, completed, or reopened | `task.moved`, `task.completed`, `task.reopened` |
| Work blocked or unblocked | `task.blocked`, `task.unblocked` |
| Due date approaching | `task.due_soon` |
| Work linked to a milestone | `milestone.linked` |
| Milestone status or forecast band changed | `milestone.status_changed`, `milestone.forecast_band_changed` |
| Linked GitLab activity received | `gitlab.merge_request`, `gitlab.pipeline` |

Scheduled events require the installation’s background processing. GitLab triggers require the [GitLab integration](https://tellenze.com/help/gitlab). A trigger describes an incoming event; previewing against current work does not manufacture that event or replay history.

## Conditions and identifiers

Each condition is an array. All nonempty condition fields must match; within one field, any listed value can match. For example, types `bug` and `incident` together with a label filter means either type must also have one of the specified labels. An empty array adds no restriction.

| Field | Accepted values |
| --- | --- |
| `project_ids` | Project IDs, up to 50. Use IDs from Definition reference, not project keys. |
| `stage_keys` | Workflow stage keys, up to 50. These are different from display names. |
| `categories` | `backlog`, `ready`, `in_progress`, `review`, `done`. |
| `types` | Up to 100 work-type keys that exist in your workspace, including custom types. Omit the filter to include every type. |
| `label_ids` | Up to 100 project label IDs. |
| `assignee_ids` | Up to 100 active member IDs, as integers. |
| `assignment_status` | `unassigned` (no assignees) or `assigned` (at least one). Selecting both or neither adds no restriction. |
| `milestone_ids` | Up to 100 accessible milestone IDs. |
| `sources` | `web`, `app`, `mcp`, `looper`, `emi` (historical records), `automation`, `template`, `gitlab`, `system`, `import`, `backfill`. Source filters cannot override the event exclusions above. |
| `gitlab_states` | Up to 20 lowercase state names from integration events, such as `merged` or `success`. |

Copy current IDs and stage keys from the editor’s **Definition reference**. Workspace rules using stage, label, or member references must explicitly list every project they can target. The rule owner must retain access to those projects and referenced objects.

## Actions and their effects

Each action includes `type` and the fields shown here. Actions run in the order listed.

| Type | Additional fields | Effect |
| --- | --- | --- |
| `move` | `stage_key` | Move work to that workflow stage. |
| `complete` | None | Complete work through its normal completion behavior. |
| `reopen` | None | Reopen completed work. |
| `labels` | `label_ids`: array of IDs | Add labels while retaining existing labels. |
| `assign` | Either `assignee_ids`: array of integer IDs, or `assignee_source`: `trigger_actor` | Add specific assignees or the member who caused the event, retaining existing assignees. Do not combine the two fields. |
| `watch` | `watching`: boolean; optional `user_ids`: integer array | Start or stop watching for those members; omitting `user_ids` targets the rule owner. |
| `reminder` | `offset_minutes`: integer from 0 to 10080 | Schedule an in-app task reminder for the owner after that many minutes. |
| `notify` | `recipient_ids`: integer array; `message_key` | Send an in-app notification to accessible recipients. |

For `notify`, choose `automation_rule_matched`, `task_due`, or `milestone_risk` as the message key. Member and label arrays allow up to 100 entries. Access, completion requirements, and the task’s current state can still prevent an action; check **Runs** for its outcome.

To assign unassigned work to the member who moves it to In progress, use this project rule (replace the stage key if your workflow uses a different one):

```json
{
  "trigger": { "type": "task.moved" },
  "conditions": {
    "stage_keys": ["in_progress"],
    "assignment_status": ["unassigned"]
  },
  "actions": [{ "type": "assign", "assignee_source": "trigger_actor" }]
}
```

`trigger_actor` resolves the event's recorded member at execution time. It never falls back to the rule owner. Missing or suspended members cause `trigger_actor_unavailable`; members who have lost access cause `trigger_actor_inaccessible`. System, automation, import, and GitLab events have no eligible member for this action. Preview reports this as a dynamic assignment rather than a fixed member ID. Member mappings are unnecessary for this dynamic target; other fixed references still require their usual mappings. Normal version checks skip stale events, and the Unassigned condition also excludes work that gained an assignee before processing.

## Rules across projects

When a workspace rule spans multiple projects and references stages, labels, or members, supply one mapping for every scoped project. Each mapping has `project_id` and `stages`, `labels`, and `assignees` objects. Their keys are the original references used by the rule and their values are the references to use in that destination project.

Every referenced operand needs exactly one mapped target, including references in conditions, watcher lists, and notification recipients. Targets must belong to the destination workflow or project and remain accessible. Empty mapping objects are appropriate for dimensions the rule does not use.

Start with separate project rules if you do not need this translation. After workflow, membership, or label changes, regenerate the preview and review the current version before enabling it.