From e886b06d7e5543e1c0504cc93d1bb1375721148c Mon Sep 17 00:00:00 2001 From: Juan Date: Tue, 11 Aug 2026 14:35:08 +0200 Subject: [PATCH 1/2] docs: document monitoring threshold breach workflow trigger [sc-16661] Adds a guide page for starting a record workflow automatically when an ongoing monitoring metric enters a breached state, listed under Ongoing monitoring below Set thresholds and alerts. Also adds the trigger to the Workflow Start list in the workflows guide, in both the HTML and RevealJS variants of the shared include, so the enumeration of triggers stays complete. --- site/guide/_sidebar.yaml | 1 + site/guide/monitoring/ongoing-monitoring.qmd | 1 + .../trigger-workflows-on-threshold-breach.qmd | 96 +++++++++++++++++++ site/guide/workflows/_add-new-workflows.qmd | 8 ++ 4 files changed, 106 insertions(+) create mode 100644 site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml index f4117d20dc..9abbcd1e85 100644 --- a/site/guide/_sidebar.yaml +++ b/site/guide/_sidebar.yaml @@ -195,6 +195,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 dc19667935..e48cc7c8e6 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 0000000000..784dae7eb8 --- /dev/null +++ b/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd @@ -0,0 +1,96 @@ +--- +# 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 display name of the metric that breached. | +| 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. + +## 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) diff --git a/site/guide/workflows/_add-new-workflows.qmd b/site/guide/workflows/_add-new-workflows.qmd index 0304160abf..f175a2f32e 100644 --- a/site/guide/workflows/_add-new-workflows.qmd +++ b/site/guide/workflows/_add-new-workflows.qmd @@ -29,6 +29,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. @@ -81,6 +82,12 @@ vi. Click **Save Draft** to save your blank workflow, and then [configure your w

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) @@ -124,6 +131,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. From b4db59bb8aff151bb90c7587caca75527762f0a0 Mon Sep 17 00:00:00 2001 From: Juan Date: Wed, 12 Aug 2026 15:10:15 +0200 Subject: [PATCH 2/2] Document what a threshold breach actually notifies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The alert email and the workflow run on different rhythms — the email fires for every breaching reading, the workflow starts only on the transition into breach — so one person can receive three things for a single breach: the alert email, the workflow's broadcast email, and the in-app broadcast. Nothing said so, and the difference is worth knowing before adding a broadcast step. Names the toggles that reduce it, and both of their limits: they apply to the whole organization rather than to one record or workflow, and they suppress emails only, so the in-app notification arrives either way. Also corrects the Breached Metric Name row. It described a bare display name, which is only the last dot segment of a metric's key and collides between metrics — the variable now resolves to the name followed by the key, matching how the metric is labelled where you pick it. Co-Authored-By: Claude Opus 5 (1M context) --- .../trigger-workflows-on-threshold-breach.qmd | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd b/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd index 784dae7eb8..4267491aee 100644 --- a/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd +++ b/site/guide/monitoring/trigger-workflows-on-threshold-breach.qmd @@ -69,7 +69,7 @@ A [{{< fa bullhorn >}} Broadcast]{.bubble} step[^5] in a breach-triggered workfl | Variable | Description | |---:|---| -| Breached Metric Name | The display name of the metric that breached. | +| 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. | @@ -78,6 +78,17 @@ A [{{< fa bullhorn >}} Broadcast]{.bubble} step[^5] in a breach-triggered workfl Since these variables can be resolved only for a workflow started by a breach, they are offered for this trigger only. +## 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) @@ -94,3 +105,5 @@ Since these variables can be resolved only for a workflow started by a breach, t [^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)