From bb77b2e07778a24a995e97c80be687d2b9d5af8d Mon Sep 17 00:00:00 2001 From: Chris Guidry Date: Wed, 20 Mar 2024 17:19:32 -0400 Subject: [PATCH] Documentation updates for event and metric triggers As part of our expansion of triggers to new use cases, I wanted to refresh the documentation for triggers to make room for docs about metric and composite triggers. Co-authored-by: nate nowack Co-authored-by: Bill Palombi --- docs/concepts/automations.md | 108 +++++++++++++++++++++++++++++++---- 1 file changed, 96 insertions(+), 12 deletions(-) diff --git a/docs/concepts/automations.md b/docs/concepts/automations.md index 4c0c3ae52a64..9744efe94ebe 100644 --- a/docs/concepts/automations.md +++ b/docs/concepts/automations.md @@ -16,7 +16,7 @@ search: Automations in Prefect Cloud enable you to configure [actions](#actions) that Prefect executes automatically based on [trigger](#triggers) conditions. -Potential triggers include the occurrence of events from changes in a flow run's state - or the absence of such events. You can event define your own custom trigger to fire based on an [event](/cloud/events/) created from a webhook or a custom event defined in Python code. +Potential triggers include the occurrence of events from changes in a flow run's state - or the absence of such events. You can even define your own custom trigger to fire based on an [event](/cloud/events/) created from a webhook or a custom event defined in Python code. Potential actions include kicking off flow runs, pausing schedules, and sending custom notifications. @@ -47,7 +47,7 @@ On the **Automations** page, select the **+** icon to create a new automation. Y ### Triggers -Triggers specify the conditions under which your action should be performed. Triggers can be of several types, including triggers based on: +Triggers specify the conditions under which your action should be performed. The Prefect UI includes templates for many common conditions, like: - Flow run state change - Note - Flow Run Tags currently are only evaluated with `OR` criteria @@ -104,28 +104,32 @@ Specify a name and, optionally, a description for the automation. ## Custom triggers -Custom triggers allow advanced configuration of the conditions on which an automation executes its actions. Several custom trigger fields accept values that end with trailing wildcards, like `"prefect.flow-run.*"`. +When you need a trigger that doesn't quite fit the templates in UI trigger builder, you can define a custom trigger in JSON. With custom triggers, you have access to the full capabilities of Prefect's automation system - allowing you to react to many kinds of events and metrics in your workspace. + +Every automation has a single trigger that, when fired, will cause all of its associated actions to run. That single trigger may be a reactive or proactive event trigger, a trigger monitoring the value of a metric, or a composite trigger that combines several underlying triggers. + +### Event triggers + +Event triggers are the most common types of trigger, and they are intended to react to the presence or absence of an event happening in your workspace. Event triggers are indicated with `{"type": "event"}`. ![Viewing a custom trigger for automations for a workspace in Prefect Cloud.](/img/ui/automations-custom.png) -The schema that defines a trigger is as follows: +The schema that defines an event trigger is as follows: | Name | Type | Supports trailing wildcards | Description | | ------------------ | ------------------ | --------------------------- | ----------- | | **match** | object | :material-check: | Labels for resources which this Automation will match. | | **match_related** | object | :material-check: | Labels for related resources which this Automation will match. | +| **posture** | string enum | N/A | The posture of this Automation, either Reactive or Proactive. Reactive automations respond to the presence of the expected events, while Proactive automations respond to the absence of those expected events. | | **after** | array of strings | :material-check: | Event(s), one of which must have first been seen to start this automation. | | **expect** | array of strings | :material-check: | The event(s) this automation is expecting to see. If empty, this automation will evaluate any matched event. | | **for_each** | array of strings | :material-close: | Evaluate the Automation separately for each distinct value of these labels on the resource. By default, labels refer to the primary resource of the triggering event. You may also refer to labels from related resources by specifying `related::