# Automations
{{< tier level="sovereign" note="Automations start workflows and run installed user tools from reusable schedules and task-created triggers." >}}

Put recurring work on a schedule and keep its results close to the rest of your work. An automation can start your morning reporting workflow, run an installed check every hour, or send a newly created task into a preparation workflow. Configure the trigger once, then inspect each execution in **Workflows > Automations**.

This guide covers choosing a trigger, creating a workflow automation, declaring a direct user-tool automation, and managing pauses and failures. For exact fields and agent calls, use the [pm_automation reference](/valdr/docs/valdr-mcp/automations/).

{{< thumbcard src="/images/workflows/automations/automation-flow.svg" fit="contain" alt="An interval, calendar schedule, or task-created event starts a workflow or runs a user tool, with results available in automation activity." caption="Reuse a reviewed workflow or tool on a schedule, then inspect what happened from one place." >}}

## Before you start

- Install or save the workflow or user tool you want to run. Workflow targets must have an active release version, such as `1.0.0`.
- Check its required inputs, provider presets, and any runtime or CLI sign-ins it needs.
- Try the target with safe inputs before scheduling repeated execution. Creating an automation enables it.

**Local-first:** Valdr runs on your machine. Automation configuration and history live in your local workspace. Keep the machine awake and Valdr running for triggers to execute; closing a browser tab does not stop the Valdr server. Automations do not run in a hosted cloud service.

## Choose a trigger and action

| Trigger | Use it for | Example |
| --- | --- | --- |
| **Interval** | A check at a fixed cadence | Every `30m`, `2h`, or `1d` |
| **Calendar schedule** | Work at a particular local time | Weekdays at 09:00 |
| **Internal event** | Reacting to new work in Valdr | When a task is created in one project |

Intervals accept whole minutes, hours, or days, from one minute through 365 days. The first run is due after one full interval. A `1d` interval means every 24 hours; use a calendar schedule for a fixed local time.

Calendar schedules use five numeric cron fields: **minute, hour, day of month, month, weekday**. Supply an explicit timezone, such as `Europe/London` or `UTC`.

| Expression | Schedule in the selected timezone |
| --- | --- |
| `0 9 * * 1-5` | Weekdays at 09:00 |
| `0 */2 * * *` | Every two hours, on the hour |
| `30 16 * * 5` | Fridays at 16:30 |

Use numbers, `*`, lists, ranges, and steps. Seconds fields and names such as `MON` are not supported. During daylight-saving changes, a nonexistent local time is skipped and a repeated local minute runs once. [Preview the schedule](/valdr/docs/valdr-mcp/automations/#validate-and-preview) before applying it.

Currently, **task created** (`task.created`) is the only supported event trigger. Optional filters match exact values; all supplied filters must match.

The event-field choices—`taskId`, `taskKey`, `projectId`, `projectKey`, and `status`—are values from that task-creation event, not additional event types. You can use them to fill string inputs. `status` is the task's initial status; changing an existing task's status does not trigger this automation.

To prevent loops, task-creation events from a workflow launched by an automation are skipped when they would trigger that same automation again.

Each automation performs one action:

- **Start a workflow** when you need several steps, agents, decisions, or approvals.
- **Run a user tool** when one installed action completes the job. Its result appears directly in automation activity.

## Create a workflow automation in the UI

1. Open **Workflows > Automations** and select **New automation**.
2. Enter a unique **Automation key**, such as `local.morning-report`.
3. Choose the **Workflow** and **Workflow version**. Select **Latest active release** to follow the highest active release, or pin a version.
4. Choose **Interval**, **Calendar schedule**, or **Internal event** and fill in its settings. For events, expand **Filter matching events** to limit the tasks that qualify.
5. Configure each **Workflow input**. Use **Default** when a workflow default or an omitted optional value is appropriate, **Fixed** for a value you supply, or **Event** to choose a field supplied by task creation.
6. Review the trigger, version, and inputs, then select **Create automation**.

The new automation is enabled. Select it to check **Next run**, then inspect **Recent activity** after it triggers. Event automations wait for new matching tasks; they do not process tasks that already existed when you created the rule.

Fixed inputs are literal values. A string such as `${event.taskKey}` is not a reference in an automation declaration. Use **Event**, or the YAML `eventInputs` mapping, to pass event data.

The form creates and edits local workflow automations. Use YAML and MCP for direct user-tool automations, advanced policies, or repeatable setup. Both action types appear in the Automations panel.

## Declare automations in YAML

Keep reusable automation definitions alongside your pack's workflows and tools, or ask an agent to apply them with `pm_automation`. The same declaration works with either route.

### Run a user tool every hour

This example calls the Node text summary action from the [user-tool starter pack](/valdr/docs/workflows/user-tools/starters/). Import that tool first, and replace `cwd` with an existing absolute directory on your machine.

```yaml
schemaVersion: "1.0"
automation:
  key: local.hourly-summary
  trigger:
    type: interval
    every: 1h
  action:
    type: user_tool.run
    toolId: valdr-tools.user.node
    toolAction: summarize
    cwd: /absolute/path/to/your/project
    inputs:
      text: "Scheduled text summary"
  policy:
    overlap: skip
    misfire: once
```

Omitting `revision` selects the most recently installed visible tool revision for each new execution. Add `revision` to select a particular installed version label. A label does not prevent its contents being replaced during an approved pack overwrite; publish changed tools under a new revision.

Tools run as your user with their configured environment. The directory, runtime, dependencies, and CLI credentials must exist on the machine running Valdr. See [Requests and Execution](/valdr/docs/workflows/user-tools/runtime/) for setup.

### Start a workflow when a task is created

This example assumes you have installed your own `my-pack.prepare-task` workflow with a string input named `taskKey`. Replace the workflow key and project filter with your own.

```yaml
schemaVersion: "1.0"
automation:
  key: local.prepare-new-task
  trigger:
    type: event
    event: task.created
    match:
      projectKey: example
  action:
    type: workflow.start
    workflow:
      key: my-pack.prepare-task
      version: 1.0.0
    eventInputs:
      taskKey: taskKey
  policy:
    overlap: queue
```

The left `taskKey` names the workflow input; the right names the event field. Add other required fixed values under `action.inputs`. A destination input cannot appear in both `inputs` and `eventInputs`.

Omit `workflow.version` to follow the highest active release. Pin it when you want to review a new workflow version before future executions use it.

### Apply locally or include in a pack

For local setup, [validate and preview the declaration](/valdr/docs/valdr-mcp/automations/#validate-and-preview), then apply it through MCP. Validation and preview do not run the action; applying a new automation enables it.

For a pack, save the declaration as `*.automation.yaml` or `*.automation.yml` beneath a directory listed in `pack.yaml`'s `includes`. Follow [Pack structure](/valdr/docs/valdr-packs/how-packs-work/pack-structure/) to validate, generate, and import the archive.

**Importing a pack activates its new automations after the import succeeds.** Review triggers, targets, and working directories before confirming the import. Pack configuration can be shared through files; execution and history remain local to each installation.

Pack-managed rules can be paused and resumed in the UI. To change their configuration, edit and reimport the owning pack. Removing a declaration from that pack disables its rule on reimport; resume cannot restore a withdrawn declaration. Existing operator pauses are preserved across pack updates.

## Control overlap and missed schedules

An automation runs one action at a time. Its policy decides what happens when another trigger arrives during active work:

| Policy | Behavior |
| --- | --- |
| `overlap: skip` | Skip the new occurrence while the previous action is still active. Default for schedules. |
| `overlap: queue` | Keep the occurrence pending and run it after the previous action finishes. Default for events. |
| `misfire: once` | After downtime or a pause, allow one catch-up for the latest missed time. Default for schedules. |
| `misfire: skip` | Skip missed times and continue at the next scheduled time. |

`misfire` applies only to intervals and calendar schedules. It does not replay every missed time. Queuing overlap also does not turn missed schedule times into a full backlog.

A workflow waiting for input or approval still counts as active. Resolve or cancel that run before expecting queued work from the same automation to start.

## Inspect, pause, and recover

Select a rule in **Workflows > Automations** to see its trigger, target, selected version, next run, and source. **Recent activity** shows individual occurrences, including skipped or failed work.

Choose **View details** for execution information. Workflow occurrences link to **View run**; direct tools show their result and available diagnostics. **View all activity** and **Load older activity** reveal earlier entries.

**Pause automation** stops new executions without cancelling work already started. For event triggers, tasks created while paused are ignored. Events accepted before the pause remain queued. **Resume automation** keeps the existing cadence and applies the missed-schedule policy.

Use **Edit automation** for a local workflow rule. Saving preserves its pause status and checkpoint state. Changing the trigger starts a new cadence; changing inputs alone preserves the schedule.

| What you see | What to do |
| --- | --- |
| **Engine stopped** | Keep Valdr running with automations enabled before expecting executions. |
| **Dependency blocked** | Restore the selected workflow or tool and its dependencies, or update the declaration to an available target. |
| **Source disabled** | Restore the declaration in its owning pack and reimport it. |
| **Paused** after a tool problem | Inspect the failed occurrence and check any external effects. Follow the [tool recovery procedure](/valdr/docs/valdr-mcp/automations/#recover-a-user-tool-automation) before resuming. |
| **Skipped** or queued activity | Check overlap policy and the previous action, including workflows waiting for approval. |

Removing a local rule through MCP stops future executions and cancels pending occurrences. Work already started continues, and retained activity remains inspectable. Removing a rule is not a way to cancel its workflow runs.

## Next step

Open **Workflows > Automations** and schedule a workflow you have already tested, or use the [MCP reference](/valdr/docs/valdr-mcp/automations/) to validate and apply your first reusable declaration.