Skip to content

Triggers

A Trigger is a DRP automation object that watches for machine state changes and automatically creates Work Orders when a Filter matches. Triggers are the "when" of automated workflows — they connect conditions to Blueprints, which define the "what."

The relationship:

Text Only
TriggerProvider detects state change
    → Trigger.Filter evaluated against machines
        → Matching machines become WorkOrders
            → Blueprint tasks execute on each WorkOrder

What is a Trigger?

A Trigger object contains:

Field Type Purpose
Name string Unique identifier
Filter string List-style filter expression selecting which machines qualify
Blueprint string Name of the Blueprint to apply to matching machines
AllInFilter bool If true, create work orders for ALL matching machines (not just the first)
FilterCount int Limit work orders to N matching machines (default: 1)
QueueMode bool If true, create work orders without machine assignment for queue-based execution
Enabled bool Toggle trigger on/off without deleting it

Triggers are fired by a TriggerProvider — either the built-in state-change tracker or an external event source. When a trigger fires, DRP evaluates Filter against all machines, and each machine that matches becomes a WorkOrder.

Step-by-Step: Building a Trigger

1. Create the Blueprint first

A trigger needs a blueprint to reference. See Blueprints for how to create one. For this example assume a blueprint named install-agent.

2. Define the trigger filter

Decide which machines should match. See Filter Syntax below — trigger filters use the same list-style syntax as drpcli machines list.

3. Create the Trigger object

Bash
drpcli triggers create '{
    "Name": "new-machine-install",
    "Filter": "WorkOrderMode=true Runnable=true Params.desired-state=agent-installed",
    "Blueprint": "install-agent",
    "AllInFilter": true,
    "Enabled": true
}'

4. Test the filter

Before enabling, verify which machines the filter matches:

Bash
drpcli machines list WorkOrderMode=true Runnable=true

For example:

Bash
drpcli machines list Params.desired-state=agent-installed WorkOrderMode=true Runnable=true

This returns the machines that would become WorkOrders. Review the list before enabling the trigger.

5. Enable and verify

Bash
drpcli triggers update new-machine-install '{"Enabled": true}'
drpcli triggers show new-machine-install

Filter Syntax

Trigger filters use the same list-style syntax as drpcli <models> list commands. This is not the await composable syntax used by drpcli <models> await.

Note

The event trigger provider uses the await syntax for complex event matching (via its event-trigger/event-object-match parameter). The Filter field on a Trigger uses the standard list-style syntax.

Filter expression examples

Use case Syntax Example
Match by Param value Params.name=value Params.os=ubuntu
Match by top-level field FieldName=value Name=myhost
Multiple conditions (AND) space-separated Params.os=ubuntu Runnable=true
Regex match FieldName=~pattern Name=~web-.*

What works in trigger filters

Text Only
# Match by Param value
Params.desired-state=provisioned

# Match by top-level field
Name=worker-01
BootEnv=sledgehammer

# Match multiple conditions (AND)
Params.role=compute Runnable=true WorkOrderMode=true

# Match by Stage
Stage=discover

For more on the underlying filter expression language, see API Filter Expansion.

Execution Fields

AllInFilter, FilterCount, and QueueMode control how the Filter result is used to create work orders:

Field Type Behavior
AllInFilter bool Creates a WorkOrder for every machine matching the filter
FilterCount int Creates work orders for at most N matching machines (default: 1)
QueueMode bool Creates work orders without machine assignment for queue-based processing

These fields are independent. Set AllInFilter: true to process all matching machines. Set FilterCount: 5 to process up to 5 machines per trigger fire. Set QueueMode: true for provider-driven triggers that don't need machine assignment.

Cross-references