From 75f3ffd487a67014d33ef9788ed1b0aa74701031 Mon Sep 17 00:00:00 2001 From: Chris Guidry Date: Thu, 21 Mar 2024 13:38:55 -0400 Subject: [PATCH] Documentation updates for event and metric triggers (#12366) Co-authored-by: nate nowack Co-authored-by: Bill Palombi Co-authored-by: Jeff Hale --- docs/concepts/automations.md | 126 +++++++++++++++++++++++++++++------ 1 file changed, 105 insertions(+), 21 deletions(-) diff --git a/docs/concepts/automations.md b/docs/concepts/automations.md index 4c0c3ae52a64..8cb52049b46e 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,10 +47,10 @@ 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, such as: - Flow run state change - - Note - Flow Run Tags currently are only evaluated with `OR` criteria + - Note - Flow Run Tags currently are only evaluated with `OR` criteria - Work pool status - Work queue status - Deployment status @@ -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. -![Viewing a custom trigger for automations for a workspace in Prefect Cloud.](/img/ui/automations-custom.png) +Each 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 -The schema that defines a trigger is as follows: +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"}`. -| 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. | -| **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::