diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml index b6efc80bb..2375eb14d 100644 --- a/site/guide/_sidebar.yaml +++ b/site/guide/_sidebar.yaml @@ -197,6 +197,7 @@ website: - guide/monitoring/review-monitoring-results.qmd - guide/monitoring/work-with-metrics-over-time.qmd - guide/monitoring/set-thresholds-and-alerts.qmd + - guide/monitoring/trigger-workflows-on-threshold-breach.qmd - text: "---" - section: "Attestation" contents: diff --git a/site/guide/monitoring/ongoing-monitoring.qmd b/site/guide/monitoring/ongoing-monitoring.qmd index dc1966793..e48cc7c8e 100644 --- a/site/guide/monitoring/ongoing-monitoring.qmd +++ b/site/guide/monitoring/ongoing-monitoring.qmd @@ -16,6 +16,7 @@ listing: - review-monitoring-results.qmd - work-with-metrics-over-time.qmd - set-thresholds-and-alerts.qmd + - trigger-workflows-on-threshold-breach.qmd - id: ongoing-monitoring-code-samples type: grid grid-columns: 2 diff --git a/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd b/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd new file mode 100644 index 000000000..b21da45d0 --- /dev/null +++ b/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd @@ -0,0 +1,109 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Trigger workflows on threshold breach" +date: last-modified +--- + +When an ongoing monitoring metric breaches its threshold, you can start a workflow automatically in addition to the email alert notifications stakeholders already receive.[^1] This lets remediation, review, or escalation begin without anyone having to notice the alert first. + +Because the workflow starts from a metric logged against an inventory record, this trigger is available for record workflows only. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] Metrics over time have already been logged via the {{< var validmind.developer >}} for your record.[^2] +- [x] Your metrics set the `passed` parameter.[^1] +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to perform the tasks in this guide.[^3] + +::: + +## Set up the trigger + +Add a record workflow[^4] and under **Workflow Start**, select **On Monitoring Threshold Breach**. Then choose which metrics the workflow watches: + +| Option | Description | +|---:|---| +| **Any metric breach** | Enabled by default. The workflow starts when any ongoing monitoring metric on the record breaches its threshold. | +| Specific metrics | Disable **Any metric breach**, then select one or more metrics under **Metrics to monitor**. The workflow starts only for the metrics you select. | +: **On Monitoring Threshold Breach** configuration {.hover tbl-colwidths="[30,70]"} + +The **Metrics to monitor** list offers the metrics already logged by records in your organization, along with metrics included in a monitoring template. Metrics that appear because they are in a template but have no readings yet are marked as not yet recorded — you can still select one, and the workflow starts once that metric is logged and breaches. + +::: {.callout} +More than one workflow can use this trigger, so you can route different metrics to different processes — for example, sending a drift breach to a recalibration workflow and a performance breach to a review workflow. +::: + +## When the workflow starts + +The workflow starts when a metric **enters** a breached state, that is when a metric is logged with `passed=False` and the previous reading for that same metric on that same record was not already failing. + +This means: + +- A metric that goes from passing to failing starts the workflow. +- The first reading ever logged for a metric starts the workflow if it is already failing. +- A metric logged as failing again, having already failed, does **not** start the workflow a second time. A monitoring job that runs hourly and keeps reporting the same breach starts one workflow, not one per run. +- A metric returning to passing and later failing again starts the workflow again. + +The trigger reads the `passed` parameter you set and does not re-evaluate your thresholds. A metric that defines thresholds but never sets `passed` does not start a workflow, in the same way that it does not send an alert notification.[^1] + +::: {.callout} +While a workflow started this way is still in progress for a record, a further breach does not start a second run of that same workflow on that record. Later breaches start a new run once the first one completes. +::: + +## Review the breach that started a workflow + +For a workflow started by a breach, the execution details show which reading was responsible: + +- The metric name and the value that breached +- The thresholds defined for that metric +- When the reading was recorded +- A link to the record's monitoring document + +## Include breach details in notifications + +A [{{< fa bullhorn >}} Broadcast]{.bubble} step[^5] in a breach-triggered workflow can include the breach in the email it sends, so recipients know which metric is at fault without opening the record first. When the workflow uses this trigger, these variables become available under **Monitoring Breach**: + +| Variable | Description | +|---:|---| +| Breached Metric Name | The metric that breached, named as it appears when you select it: its display name followed by its full key, unless the two are the same. Two metrics can share a display name, so the key is what tells them apart. | +| Breached Metric Key | The full key of the metric, as logged. | +| Breached Metric Value | The value recorded for the breaching reading. | +| Breached Metric Thresholds | The thresholds defined for that metric. | +| Monitoring Document URL | A link to the record's monitoring document. | +: **Monitoring Breach** broadcast variables {.hover tbl-colwidths="[35,65]"} + +Since these variables can be resolved only for a workflow started by a breach, they are offered for this trigger only. For the same reason, once a broadcast message uses one of them, you cannot change the workflow's start trigger to something else — the save is rejected and names the variable to remove or replace first. + +## What a breach sends + +The alert email and the workflow follow different rhythms, so it is worth knowing what a breach produces before you add a [{{< fa bullhorn >}} Broadcast]{.bubble} step to a breach-triggered workflow: + +- The **alert email** is sent for every breaching reading.[^1] A metric that keeps failing keeps sending it. +- The **workflow** starts only on the transition into breach. A metric that was already failing does not start it again. + +One person can therefore receive three things for a single breach: the alert email, the broadcast email your workflow sends, and the in-app broadcast notification. + +To reduce that, a [{{< fa hand >}} Customer Admin]{.bubble} can turn off **Monitoring breach** or **Broadcast notifications** under {{< fa gear >}} Settings.[^6] Two limits are worth knowing: the toggles apply to your whole organization rather than to a single record or workflow, and they suppress emails only — the in-app notification is unaffected. + +## What's next + +- [Set thresholds and alerts](/guide/monitoring/set-thresholds-and-alerts.qmd) +- [Working with workflows](/guide/workflows/working-with-workflows.qmd) + + + +[^1]: [Set thresholds and alerts](/guide/monitoring/set-thresholds-and-alerts.qmd#alert-notifications) + +[^2]: [Work with metrics over time](/guide/monitoring/work-with-metrics-over-time.qmd) + +[^3]: [Manage permissions](/guide/configuration/manage-permissions.qmd) + +[^4]: [Add new workflows](/guide/workflows/configure-workflows.qmd#add-new-workflows) + +[^5]: [Workflow step types](/guide/workflows/workflow-step-types.qmd#broadcast) + +[^6]: [Customize email notifications](/guide/configuration/manage-platform-notifications.qmd#customize-email-notifications) diff --git a/site/guide/workflows/_add-new-workflows.qmd b/site/guide/workflows/_add-new-workflows.qmd index a2d704b1a..0b05285db 100644 --- a/site/guide/workflows/_add-new-workflows.qmd +++ b/site/guide/workflows/_add-new-workflows.qmd @@ -30,6 +30,7 @@ iii. Under **Workflow Start**, select when the workflow should be initiated: - **Manually** — Start this workflow manually.^[[Initiate workflows](/guide/workflows/manage-workflows.qmd#initiate-workflows)] - **On Inventory Record Registration** — Start this workflow when a record is registered in your inventory.[^on-registration] - **On Field Change** — Start this workflow on a change to a specific record inventory field.[^on-field-change] To configure, select a field under **Inventory Record Field To Monitor**. +- **On Monitoring Threshold Breach** — Start this workflow when an ongoing monitoring metric breaches its threshold.[^on-threshold-breach] To configure, keep **Any metric breach** enabled, or disable it and select the metrics to watch under **Metrics to monitor**. - **Via Webhook** — Start this workflow when a webhook event is received. iv. Under **Workflow Expected Duration**, define the SLA for the workflow based on the start date in days, weeks, months, or years. @@ -98,6 +99,12 @@ v. Click **Save Draft** to save your blank workflow, and then [configure your wo

When selecting date or date time fields, check **Schedule workflow start for this date** to set the workflow to trigger on the existing date captured in the field rather than when its value changes. +[^on-threshold-breach]: + + [Trigger workflows on threshold breach](/guide/monitoring/trigger-workflows-on-threshold-breach.qmd) +

+ The workflow starts when a metric enters a breached state, not on every breaching reading — a monitoring job that keeps reporting the same breach starts one workflow, not one per run. + [^on-artifact-field-change]: [Manage artifact fields](/guide/validation/manage-artifact-fields.qmd) @@ -156,6 +163,7 @@ iii. Under **Workflow Start**, select when the workflow should be initiated: - **Manually** — Start this workflow manually. - **On Inventory Record Registration** — Start this workflow when a record is registered in your inventory. - **On Field Change** — Start this workflow on a change to a specific record inventory field. To configure, select a field under **Inventory Record Field To Monitor**. +- **On Monitoring Threshold Breach** — Start this workflow when an ongoing monitoring metric breaches its threshold. To configure, keep **Any metric breach** enabled, or disable it and select the metrics to watch under **Metrics to monitor**. - **Via Webhook** — Start this workflow when a webhook event is received. iv. Under **Workflow Expected Duration**, define the SLA for the workflow based on the start date in days, weeks, months, or years. diff --git a/site/guide/workflows/_workflow-step-types.qmd b/site/guide/workflows/_workflow-step-types.qmd index f95ddc78e..06921638d 100644 --- a/site/guide/workflows/_workflow-step-types.qmd +++ b/site/guide/workflows/_workflow-step-types.qmd @@ -312,7 +312,8 @@ Sends a HTTP request with optional additional conditions.^[[Conditional step req [^broadcast]: Use the rich text editor to compose your **Subject** and **Message**: 1. Include optional details about the record or artifact the workflow is running on using the **{ } Insert Variable** drop-down. - 2. Click on the **Preview** tab and choose a record or artifact under **Select {inventory record/artifact} for Preview** to confirm how the notification will appear when rendered. + 2. In a workflow started by a monitoring threshold breach, a **Monitoring Breach** group also offers the metric that breached, its value, and its thresholds — see [Trigger workflows on threshold breach](/guide/monitoring/trigger-workflows-on-threshold-breach.qmd#include-breach-details-in-notifications). + 3. Click on the **Preview** tab and choose a record or artifact under **Select {inventory record/artifact} for Preview** to confirm how the notification will appear when rendered. [^wait]: diff --git a/site/llm/chatbot-product-map.md b/site/llm/chatbot-product-map.md index c3274b8f1..cb775bd35 100644 --- a/site/llm/chatbot-product-map.md +++ b/site/llm/chatbot-product-map.md @@ -627,14 +627,14 @@ - Sections: Can I customize workflows within }?; What record stages are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; 1. Configure workflow in }; 2. Start workflow from external system; Trigger a paused workflow to continue; 1. Configure workflow in }; 2. Trigger workflow to continue from external system +- `/guide/monitoring/trigger-workflows-on-threshold-breach.html` + - Sections: Prerequisites; Set up the trigger; When the workflow starts; Review the breach that started a workflow; Include breach details in notifications; What a breach sends; What's next - `/guide/risk-tiering/set-up-risk-tiering-workflows.html` - Sections: Prerequisites; About risk tiering workflows; Define governance stages; Add a risk tiering workflow; Configure risk tiering steps; Track governance on the assessment or template; How governance runs behave; What's next - `/guide/workflows/conditional-step-requirements.html` - Sections: Prerequisites; Configure conditional requirements - `/guide/workflows/configure-workflows.html` - Sections: Prerequisites; Create custom workflows; 1. Add new workflows; 2. Configure workflow steps; 3. Link workflow together; Workflow steps relationship unclear on your canvas?; 4. Publish workflow; Clone existing workflows -- `/guide/workflows/introduction-to-workflows.html` - - Sections: Workflow elements; What's next #### `/settings/workflows` — Workflows @@ -649,14 +649,14 @@ - Sections: Can I customize workflows within }?; What record stages are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; 1. Configure workflow in }; 2. Start workflow from external system; Trigger a paused workflow to continue; 1. Configure workflow in }; 2. Trigger workflow to continue from external system +- `/guide/monitoring/trigger-workflows-on-threshold-breach.html` + - Sections: Prerequisites; Set up the trigger; When the workflow starts; Review the breach that started a workflow; Include breach details in notifications; What a breach sends; What's next - `/guide/risk-tiering/set-up-risk-tiering-workflows.html` - Sections: Prerequisites; About risk tiering workflows; Define governance stages; Add a risk tiering workflow; Configure risk tiering steps; Track governance on the assessment or template; How governance runs behave; What's next - `/guide/workflows/conditional-step-requirements.html` - Sections: Prerequisites; Configure conditional requirements - `/guide/workflows/configure-workflows.html` - Sections: Prerequisites; Create custom workflows; 1. Add new workflows; 2. Configure workflow steps; 3. Link workflow together; Workflow steps relationship unclear on your canvas?; 4. Publish workflow; Clone existing workflows -- `/guide/workflows/introduction-to-workflows.html` - - Sections: Workflow elements; What's next ## Main application @@ -709,10 +709,10 @@ - Sections: Prerequisites; Steps; Example monitoring test results; [} Satisfactory]; [} Requires Attention] - `/guide/monitoring/set-thresholds-and-alerts.html` - Sections: Prerequisites; Use a custom function; Set the `passed` parameter; Output examples; Alert notifications +- `/guide/monitoring/trigger-workflows-on-threshold-breach.html` + - Sections: Prerequisites; Set up the trigger; When the workflow starts; Review the breach that started a workflow; Include breach details in notifications; What a breach sends; What's next - `/guide/monitoring/work-with-metrics-over-time.html` - Sections: **Log metrics over time }**; Prerequisites; Add metrics over time; Add integration metrics; Use the global time range; View metric over time metadata -- `/faq/faq-reporting.html` - - Sections: What analytic features are offered by }?; How can I export platform data on a schedule to cloud storage?; Learn more - *No direct help link in frontend; related docs inferred from keywords.* @@ -786,14 +786,14 @@ - Sections: Can I customize workflows within }?; What record stages are available for use in workflows?; Can we work with disconnected workflows?; You can also leverage the } once you are ready to document a specific record (model) for review and validation.; Learn more - `/guide/integrations/integrations-examples/use-webhooks-with-workflows.html` - Sections: Prerequisites; Start a workflow via webhook; 1. Configure workflow in }; 2. Start workflow from external system; Trigger a paused workflow to continue; 1. Configure workflow in }; 2. Trigger workflow to continue from external system +- `/guide/monitoring/trigger-workflows-on-threshold-breach.html` + - Sections: Prerequisites; Set up the trigger; When the workflow starts; Review the breach that started a workflow; Include breach details in notifications; What a breach sends; What's next - `/guide/risk-tiering/set-up-risk-tiering-workflows.html` - Sections: Prerequisites; About risk tiering workflows; Define governance stages; Add a risk tiering workflow; Configure risk tiering steps; Track governance on the assessment or template; How governance runs behave; What's next - `/guide/workflows/conditional-step-requirements.html` - Sections: Prerequisites; Configure conditional requirements - `/guide/workflows/configure-workflows.html` - Sections: Prerequisites; Create custom workflows; 1. Add new workflows; 2. Configure workflow steps; 3. Link workflow together; Workflow steps relationship unclear on your canvas?; 4. Publish workflow; Clone existing workflows -- `/guide/workflows/introduction-to-workflows.html` - - Sections: Workflow elements; What's next - *No direct help link in frontend; related docs inferred from keywords.*