Trigger Object¶

Overview¶

Triggers define the configuration for automatically creating work orders in response to events, webhooks, or schedules. A Trigger combines a Trigger Provider (the method of invocation) with workflow configuration (blueprint, parameters, machine filters) to automate work order creation.

Relationship: Trigger Provider (how) + Trigger (what) = Work Order (execution)

Prerequisites¶

Digital Rebar Provision endpoint with appropriate permissions
drpcli installed and configured
Available Trigger Provider
Valid Blueprint for workflow execution
Machines in Work Order Mode for machine-targeted triggers

Architecture¶

A Trigger defines:

TriggerProvider: Which provider handles the trigger (cron, webhook, event)
Blueprint: Workflow to execute when triggered
Filter: Which machines receive work orders (optional)
Parameters: Configuration for both the provider and work order
Execution mode: How work orders are created (single, all, queued)

Trigger Lifecycle¶

Event occurs (webhook received, cron fires, event emitted)
Trigger Provider matches event to Trigger
Filter evaluates which machines qualify (if specified)
Work order(s) created with blueprint and parameters
Runners execute work orders

Execution Modes¶

Single machine: One work order for first matching machine (default)
All machines (AllInFilter: true): Work order for every matching machine
Limited batch (FilterCount: N): Work orders for N matching machines
Queue mode (QueueMode: true): Work order without machine assignment

Common Use Cases¶

Scheduled Maintenance Tasks¶

Run periodic maintenance on all production servers.

Bash

drpcli triggers create - <<EOF
{
  "Name": "weekly-patching",
  "TriggerProvider": "cron-trigger",
  "Enabled": true,
  "Blueprint": "patch-and-reboot",
  "Filter": "Environment=production",
  "AllInFilter": true,
  "Params": {
    "cron-trigger/schedule": "0 2 * * 0"
  },
  "WorkOrderParams": {
    "maintenance-window": "weekend"
  }
}
EOF

GitHub Push Deployment¶

Deploy updated content when code is pushed to main branch.

Bash

drpcli triggers create - <<EOF
{
  "Name": "auto-deploy-content",
  "TriggerProvider": "github-trigger-webhook-push",
  "Enabled": true,
  "Blueprint": "content-build-deploy",
  "QueueMode": true,
  "Params": {
    "github-trigger-webhook-push/repository": "myorg/drp-content",
    "github-trigger-webhook-push/branch": "main"
  },
  "StoreDataInParameter": "github-webhook-data"
}
EOF

Alert Response Automation¶

Respond to Prometheus alerts by running diagnostics.

Bash

drpcli triggers create - <<EOF
{
  "Name": "high-cpu-response",
  "TriggerProvider": "prometheus-trigger-alert-webhook",
  "Enabled": true,
  "Blueprint": "diagnostic-collection",
  "Filter": "Name=~prod-.*",
  "Params": {
    "prometheus-trigger-alert-webhook/alert-name": "HighCPUAlert"
  },
  "MergeDataIntoParams": true
}
EOF

Machine State Change Automation¶

Trigger workflow when machines reach specific stage.

Bash

drpcli triggers create - <<EOF
{
  "Name": "post-install-setup",
  "TriggerProvider": "event-trigger",
  "Enabled": true,
  "Blueprint": "finalize-configuration",
  "Filter": "Stage=complete-install",
  "Params": {
    "event-trigger/event-type": "machines.update",
    "event-trigger/event-filter": "Stage"
  }
}
EOF

Batch Processing¶

Process limited number of machines per trigger fire.

Bash

drpcli triggers create - <<EOF
{
  "Name": "rolling-updates",
  "TriggerProvider": "cron-trigger",
  "Enabled": true,
  "Blueprint": "upgrade-workflow",
  "Filter": "NeedsUpgrade=true",
  "FilterCount": 5,
  "Params": {
    "cron-trigger/schedule": "*/30 * * * *"
  }
}
EOF

Procedures¶

Create a Trigger¶

Bash

drpcli triggers create - <<EOF
{
  "Name": "my-trigger",
  "TriggerProvider": "cron-trigger",
  "Enabled": true,
  "Blueprint": "my-workflow",
  "Params": {
    "cron-trigger/schedule": "0 * * * *"
  }
}
EOF

List Triggers¶

Bash

drpcli triggers list

Filter by provider:

Bash

drpcli triggers list TriggerProvider=cron-trigger

Filter by enabled state:

Bash

drpcli triggers list Enabled=true

View Trigger Details¶

Bash

drpcli triggers show my-trigger

Get webhook URL for webhook-based triggers:

Bash

drpcli triggers show my-webhook-trigger | jq -r '.Meta.URL'

Update Trigger¶

Enable/disable trigger:

Bash

drpcli triggers update my-trigger '{"Enabled": false}'

Update blueprint:

Bash

drpcli triggers update my-trigger '{"Blueprint": "new-workflow"}'

Update filter:

Bash

drpcli triggers update my-trigger '{"Filter": "Stage=production"}'

Add Parameters¶

Set provider parameter:

Bash

drpcli triggers set my-trigger param cron-trigger/schedule to "0 */2 * * *"

Set work order parameter:

Bash

drpcli triggers update my-trigger - <<EOF
{
  "WorkOrderParams": {
    "custom-param": "value",
    "another-param": 42
  }
}
EOF

Add Profiles to Trigger¶

Profiles provide additional parameters to work orders:

Bash

drpcli triggers addprofile my-trigger shared-config
drpcli triggers addprofile my-trigger environment-specific

View profiles:

Bash

drpcli triggers show my-trigger | jq .Profiles

Remove profile:

Bash

drpcli triggers removeprofile my-trigger shared-config

Delete Trigger¶

Bash

drpcli triggers destroy my-trigger

Machine Filtering¶

The Filter field uses DRP filter syntax to select machines. Filters automatically include WorkOrderMode=true and Runnable=true.

Filter Examples¶

By name pattern:

JSON

"Filter": "Name=~web-.*"

By stage:

JSON

"Filter": "Stage=production-ready"

By parameter:

JSON

"Filter": "Param.datacenter=us-west"

Multiple conditions:

JSON

"Filter": "Environment=production AND Stage=complete"

No filter (queue mode):

JSON

"Filter": "",
"QueueMode": true

Data Handling¶

Store Webhook Data in Parameter¶

Capture incoming webhook data:

JSON

{
  "StoreDataInParameter": "webhook-payload",
  "Params": {}
}

Access in template:

Text Only

{{.Param "webhook-payload"}}

Merge Data into Params¶

Automatically merge webhook fields into work order parameters:

JSON

{
  "MergeDataIntoParams": true
}

If webhook sends {"version": "1.2.3", "environment": "prod"}, these become available as {{.Param "version"}} and {{.Param "environment"}}.

Advanced Configuration¶

Work Order Profiles¶

Profiles apply in order during parameter lookup:

JSON

{
  "WorkOrderProfiles": ["base-config", "environment-prod", "app-specific"],
  "Profiles": ["trigger-defaults"]
}

Profile precedence (highest to lowest): 1. WorkOrderParams 2. WorkOrderProfiles (in order) 3. Trigger Profiles 4. Trigger Params

Execution Control¶

Process all matching machines:

JSON

{
  "AllInFilter": true
}

Limit machines per trigger fire:

JSON

{
  "FilterCount": 10
}

Queue mode (no machine assignment):

JSON

{
  "QueueMode": true,
  "Filter": ""
}

Validation¶

Verify Trigger Created¶

Bash

drpcli triggers exists my-trigger && echo "Trigger exists"

Check Trigger Status¶

Bash

drpcli triggers show my-trigger | jq '{Name, Enabled, TriggerProvider, Blueprint}'

Test Trigger Manually¶

For webhook triggers, send test payload:

Bash

WEBHOOK_URL=$(drpcli triggers show my-trigger | jq -r '.Meta.URL')
curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

Verify Work Order Creation¶

Bash

drpcli work_orders list | jq '.[] | select(.Blueprint=="my-blueprint")'

Check work order parameters:

Bash

drpcli work_orders show <work-order-id> | jq .Params

Monitor Trigger Execution¶

Watch trigger events:

Bash

drpcli events watch triggers

Watch work order creation:

Bash

drpcli events watch work_orders

Troubleshooting¶

Trigger Not Firing¶

Verify trigger is enabled:

Bash

drpcli triggers show my-trigger | jq .Enabled

Enable if disabled:

Bash

drpcli triggers update my-trigger '{"Enabled": true}'

Check trigger provider exists:

Bash

drpcli trigger_providers exists $(drpcli triggers show my-trigger | jq -r .TriggerProvider)

Validate provider parameters:

Bash

# List required parameters
drpcli trigger_providers show cron-trigger | jq .RequiredParameters

# Check trigger has required params
drpcli triggers show my-trigger | jq .Params

No Machines Match Filter¶

Test filter:

Bash

FILTER=$(drpcli triggers show my-trigger | jq -r .Filter)
drpcli machines list "$FILTER" WorkOrderMode=true Runnable=true

Check machine state:

Bash

drpcli machines list | jq '.[] | {Name, WorkOrderMode, Runnable}'

Verify machines in work order mode:

Bash

drpcli machines update <machine-name> '{"WorkOrderMode": true, "Runnable": true}'

Blueprint Not Found¶

Verify blueprint exists:

Bash

BLUEPRINT=$(drpcli triggers show my-trigger | jq -r .Blueprint)
drpcli blueprints exists "$BLUEPRINT"

List available blueprints:

Bash

drpcli blueprints list | jq -r '.[].Name'

Work Orders Created But Not Executing¶

Check runner availability:

Bash

drpcli machines list WorkOrderMode=true Runnable=true Available=true

Review work order status:

Bash

drpcli work_orders show <work-order-id> | jq '{State, Status, Errors}'

Check machine capacity:

Bash

drpcli machines show <machine-name> | jq '.Meta.WorkOrderCount'

Webhook Authentication Issues¶

Check webhook secret configuration (provider-specific):

Bash

drpcli triggers show my-trigger | jq .Params

Review webhook request logs:

Bash

drpcli events watch triggers | jq 'select(.Object=="triggers")'

Parameter Not Available in Template¶

Verify parameter precedence:

Bash

drpcli triggers show my-trigger | jq '{Params, WorkOrderParams, Profiles, WorkOrderProfiles}'

Check if data was stored:

Bash

drpcli work_orders show <work-order-id> | jq '.Params["webhook-payload"]'

Verify MergeDataIntoParams:

Bash

drpcli triggers show my-trigger | jq .MergeDataIntoParams

Field Reference¶

Field	Definition
AllInFilter	AllInFilter if true cause a work_order created for all machines in the filter
Blueprint	Blueprint is template to apply
Description	Description is a string for providing a simple description
Documentation	Documentation is a string for providing additional in depth information.
Enabled	Enabled is this Trigger enabled
Filter	Filter is a "list"-style filter string to find machines to apply the cron too Filter is already assumed to have WorkOrderMode == true && Runnable == true
FilterCount	FilterCount defines the number of machines to apply the work_order to. Only one work_order per trigger fire.
MergeDataIntoParams	MergeDataIntoParams if true causes the data from the trigger to be merged into the Params of the work_order.
Meta	Meta contains the meta data of the object. The type of this field is a key / value map/dictionary. The key type is string. The value type is also string. The general content of the field is undefined and can be an arbritary store. There are some common known keys: color - The color the UX uses when displaying icon - The icon the UX uses when displaying * title - The UX uses this for additional display information. Often the source of the object. Specific Object types use additional meta data fields. These are described at: https://docs.rackn.io/stable/redirect/?ref=rs_object_metadata
Name	Name is the key of this particular Trigger. required: true
Params	Params holds the values of parameters on the object. The field is a key / value store of the parameters. The key is the name of a parameter. The key is of type string. The value is the value of the parameter. The type of the value is defined by the parameter object. If the key doesn't reference a parameter, the type of the object can be anything. The system will enforce the named parameter's value's type. Go calls the "anything" parameters as "interface {}". Hence, the type of this field is a map[string]interface{}.
Profiles	Profiles is an array of profiles to apply to this object in order when looking for a parameter during rendering.
QueueMode	QueueMode if true causes work_orders to be created without a machine, but with a filter for delayed operation
StoreDataInParameter	StoreDataInParameter if set tells the triggers data to be stored in the parameter in the Params of the work_order.
TriggerProvider	TriggerProvider is the name of the method of this trigger
WorkOrderParams	WorkOrderParams that have been directly set on the Trigger and will be moved to the work order.
WorkOrderProfiles	WorkOrderProfiles to apply to this machine in order when looking for a parameter during rendering.

References¶

Trigger Provider - Defines how triggers are invoked
Work Orders - Execution units created by triggers
Blueprints - Workflows executed by work orders
Machines - Runner objects that execute work orders
Execution Objects - Overview of execution model
Filter Syntax - Machine filter documentation