Automations

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.

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

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.

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 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. Import that tool first, and replace cwd with an existing absolute directory on your machine.

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 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.

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, 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 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:

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.

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 to validate and apply your first reusable declaration.