DOCS-4389: Add triggers examples to top

Author: npentrel

docs/data-ai/_index.md

@@ -39,7 +39,7 @@ You can also monitor your machines through teleop, power your application logic,
 {{< cards >}}
 {{% card link="/data-ai/data/query/" noimage="true" %}}
 {{% card link="/data-ai/data/visualize/" noimage="true" %}}
-{{% card link="/data-ai/data/advanced/alert-data/" noimage="true" %}}
+{{% card link="/data-ai/data/alert-data/" noimage="true" %}}
 {{% card link="/data-ai/data/export/" noimage="true" %}}
 {{< /cards >}}
 {{< /how-to-expand >}}

docs/data-ai/data/advanced/_index.md

@@ -1,11 +1,13 @@
 ---
 linkTitle: "Trigger on data events"
 title: "Trigger on data events"
-weight: 60
+weight: 200
 layout: "docs"
 type: "docs"
 description: "Use triggers to send email notifications or webhook requests when data from the machine is synced."
 date: "2025-09-12"
+aliases:
+  - /data-ai/data/advanced/alert-data/
 ---
 
 You can use triggers to send webhooks or email alerts when data syncs from a machine.
@@ -74,7 +76,7 @@ You can configure triggers to fire in the following scenarios:
 
 The following JSON configuration shows how to set up a trigger that fires when any data is synced to the cloud:
 
-```json {class="line-numbers linkable-line-numbers" data-line="32-49"}
+```json {class="line-numbers linkable-line-numbers" data-line="32-54"}
 {
   "components": [
     {

docs/data-ai/data/advanced/alert-data.md renamed to docs/data-ai/data/alert-data.md

@@ -6,29 +6,45 @@ type: "docs"
 tags: ["data management", "trigger", "webhook"]
 description: "Detailed information about how to configure triggers and webhooks."
 date: "2025-05-05"
+updated: "2025-09-18"
 ---
 
-Triggers can alert you by email or webhook when the following events occur:
+Triggers can alert you by email or webhook when any of the following events occur:
 
 - [machine telemetry data syncs from your local device to the Viam cloud](/manage/troubleshoot/alert/)
-- [data syncs from a machine](/data-ai/data/advanced/alert-data/)
+- [data syncs from a machine](/data-ai/data/alert-data/)
 - [service detects a specified object or classifies a specified label](/data-ai/ai/alert/)
 
-## Trigger attributes
+This page provides a reference for the Trigger attributes.
+For step-by-step configuration information, see the links above instead.
 
-Triggers support the following attributes:
+## JSON configuration templates
 
-<!-- prettier-ignore -->
-| Name | Type | Required? | Description |
-| ---- | ---- | --------- | ----------- |
-| `name` | string | **Required** | The name of the trigger |
-| `event` |  object | **Required** | The trigger event object, which contains the following fields: <ul><li>`type`: The type of the event to trigger on. Options: `part_data_ingested`, `conditional_data_ingested`.</li><li>`data_types`: Required with `type` `part_data_ingested`. An array of data types that trigger the event. Options: `binary`, `tabular`, `file`, `unspecified`. </li><li> `conditional`: Required when `type` is `conditional_data_ingested`. For more information about this field, see [Conditional attributes](/data-ai/reference/triggers-configuration/#conditional-attributes). </li></ul> |
-| `notifications` |  object | **Required** | The notifications object, which contains the following fields: <ul><li>`type`: The type of the notification. Options: `webhook`, `email`</li><li>`value`: The URL to send the request to or the email address to notify.</li><li>`seconds_between_notifications`: The interval between notifications in seconds.</li></ul> For more information on webhooks, see [Webhook attributes](#webhook-attributes). |
-| `notes` | string | Optional | Descriptive text to document the purpose, configuration details, or other important information about this trigger. |
+### Part status trigger template
+
+The following template demonstrates the structure of a JSON configuration for a trigger that alerts when a part is online or offline:
+
+```json {class="line-numbers linkable-line-numbers"}
+"triggers": [
+  {
+    "name": "<trigger name>",
+    "event": {
+      "type": "part_online|part_offline"
+    },
+     "notifications": [
+      {
+        "type": "webhook|email",
+        "value": "<webhook URL or email address>",
+        "seconds_between_notifications": <number of seconds>
+      }
+     ]
+  }
+]
+```
 
 ### Data sync trigger template
 
-The following template demonstrates the form of a JSON configuration for a trigger that alerts when data syncs to the Viam cloud:
+The following template demonstrates the structure of a JSON configuration for a trigger that alerts when data syncs to the Viam cloud:
 
 ```json {class="line-numbers linkable-line-numbers"}
   "triggers": [
@@ -51,31 +67,9 @@ The following template demonstrates the form of a JSON configuration for a trigg
   ]
 ```
 
-## Conditional attributes
-
-The `conditional` object for the `conditional_data_ingested` trigger type includes the following attributes:
-
-<!-- prettier-ignore -->
-| Name | Type | Required? | Description |
-| ---- | ---- | --------- | ----------- |
-| `data_capture_method` | string | **Required** | The method of data capture to trigger on. <br> Example: `sensor:<name-of-component>:Readings`. |
-| `conditions` | object | Optional | Conditions that, when true, fire the trigger. Evaluated each time data syncs from the linked component. When this object is empty or not present, the trigger fires each time data syncs from the linked component. <br> Options: <ul><li>`evals`:<ul><li>`operator`: Logical operator for the condition. </li><li>`value`: An object containing a single field and value. The field specifies the path, in the synced data, to the left operand of the conditional. For nested fields, use periods as separators or define the nested structure in JSON. The value specifies an object, string, boolean, regular expression, or integer used as a right operand in the conditional. </li></ul></li></ul> |
-
-The `operator` attribute supports the following values:
-
-| Name    | Description                |
-| ------- | -------------------------- |
-| `lt`    | less than                  |
-| `gt`    | greater than               |
-| `lte`   | less than or equal to      |
-| `gte`   | greater than or equal to   |
-| `eq`    | equal to                   |
-| `neq`   | not equal to               |
-| `regex` | matches regular expression |
-
 ### Conditional trigger template
 
-The following template demonstrates the form of a JSON configuration for a conditional trigger:
+The following template demonstrates the structure of a JSON configuration for a conditional trigger:
 
 ```json {class="line-numbers linkable-line-numbers"}
 "triggers": [
@@ -106,6 +100,40 @@ The following template demonstrates the form of a JSON configuration for a condi
 ]
 ```
 
+## Trigger attributes
+
+Triggers support the following attributes:
+
+<!-- prettier-ignore -->
+| Name | Type | Required? | Description |
+| ---- | ---- | --------- | ----------- |
+| `name` | string | **Required** | The name of the trigger |
+| `event` |  object | **Required** | The trigger event object, which contains the following fields: <ul><li>`type`: The type of the event to trigger on. Options: <ul><li>`part_data_ingested`: fire when data syncs</li> <li>`conditional_data_ingested`: fire when data that meets a certain condition syncs</li> <li>`part_online`: fire when the part is online</li> <li>`part_offline`: fire when the part is offline</li></ul></li><li>`data_types`: Required with `type` `part_data_ingested`. An array of data types that trigger the event. Options: `binary`, `tabular`, `file`, `unspecified`. </li><li> `conditional`: Required when `type` is `conditional_data_ingested`. For more information about this field, see [Conditional attributes](/data-ai/reference/triggers-configuration/#conditional-attributes). </li></ul> |
+| `notifications` |  object | **Required** | The notifications object, which contains the following fields: <ul><li>`type`: The type of the notification. Options: `webhook`, `email`</li><li>`value`: The URL to send the request to or the email address to notify.</li><li>`seconds_between_notifications`: The interval between notifications in seconds.</li></ul> For more information on webhooks, see [Webhook attributes](#webhook-attributes). |
+| `notes` | string | Optional | Descriptive text to document the purpose, configuration details, or other important information about this trigger. |
+
+## Conditional attributes
+
+The `conditional` object for the `conditional_data_ingested` trigger type includes the following attributes:
+
+<!-- prettier-ignore -->
+| Name | Type | Required? | Description |
+| ---- | ---- | --------- | ----------- |
+| `data_capture_method` | string | **Required** | The method of data capture to trigger on. <br> Example: `sensor:<name-of-component>:Readings`. |
+| `conditions` | object | Optional | Conditions that, when true, fire the trigger. Evaluated each time data syncs from the linked component. When this object is empty or not present, the trigger fires each time data syncs from the linked component. <br> Options: <ul><li>`evals`:<ul><li>`operator`: Logical operator for the condition. </li><li>`value`: An object containing a single field and value. The field specifies the path, in the synced data, to the left operand of the conditional. For nested fields, use periods as separators or define the nested structure in JSON. The value specifies an object, string, boolean, regular expression, or integer used as a right operand in the conditional. </li></ul></li></ul> |
+
+The `operator` attribute supports the following values:
+
+| Name    | Description                |
+| ------- | -------------------------- |
+| `lt`    | less than                  |
+| `gt`    | greater than               |
+| `lte`   | less than or equal to      |
+| `gte`   | greater than or equal to   |
+| `eq`    | equal to                   |
+| `neq`   | not equal to               |
+| `regex` | matches regular expression |
+
 ### Example
 
 The following condition defines a trigger that fires based on the value of the `cpu` field of synced data:
@@ -168,7 +196,7 @@ The following sensor reading fires the trigger, since `40 < 50` is `true`:
 
 ### Request types
 
-When an event occurs, Viam sends a HTTP request to the URL you specified for the trigger:
+When an event occurs, Viam sends an HTTP request to the URL you specified for the trigger:
 
 <!-- prettier-ignore -->
 | Trigger type | HTTP Method |
@@ -189,7 +217,7 @@ The request includes the following headers:
 | `Organization-Name` | The name of the organization that triggered the request. | `part_online`, `part_offline` |
 | `Location-Id` | The location of the machine that triggered the request. | all |
 | `Location-Name` | The location of the machine that triggered the request. | `part_online`, `part_offline` |
-| `Part-Id` |  The part of the machine that triggered the request. | all |
+| `Part-Id` | The part of the machine that triggered the request. | all |
 | `Machine-Name` | The name of the machine that triggered the request. | `part_online`, `part_offline` |
 | `Robot-Id` | The ID of the machine that triggered the request. | all |
 
@@ -205,11 +233,10 @@ The request body includes the following data:
 | `method_name` | The name of the method from which data was ingested. | `part_data_ingested`, `conditional_data_ingested` |
 | `min_time_received` | Indicates the earliest time a piece of data was received. | `part_data_ingested` |
 | `max_time_received` | Indicates the latest time a piece of data was received. | `part_data_ingested` |
-| `method_name` | The name of the method that triggered the request. | `conditional_data_ingested` |
 | `machine_name` | The name of the machine that triggered the request. | `part_data_ingested`, `conditional_data_ingested` |
 | `location_name` | The location of the machine that triggered the request. | `part_data_ingested`, `conditional_data_ingested` |
 | `org_name` | The name of the organization that triggered the request. | `part_data_ingested`, `conditional_data_ingested` |
-| `file_id` | The id of the file that was ingested. | `part_data_ingested` |
+| `file_id` | The ID of the file that was ingested. | `part_data_ingested` |
 | `trigger_condition` | The condition that triggered the request. | `conditional_data_ingested` |
 | `data` | The ingested sensor data. Includes `metadata` with `received_at` and `requested_at` timestamps and `data` in the form `map[string]any`. | `part_data_ingested`, `conditional_data_ingested` (sensor data) |
 
@@ -222,7 +249,7 @@ The following example function prints the received headers:
 {{< tabs >}}
 {{% tab name="Flask" %}}
 
-```python {class="line-numbers linkable-line-numbers" }
+```python {class="line-numbers linkable-line-numbers"}
 from flask import Flask, request
 
 app = Flask(__name__)
@@ -309,3 +336,13 @@ def hello_http(request):
 
 {{% /tab %}}
 {{< /tabs >}}
+
+### Troubleshooting
+
+If the HTTP request Viam sends results in an error, you can see this error logged in the machine logs.
+
+For example:
+
+```txt
+9/18/2025, 12:52:59 PM error app.trigger.trigger-1     Trigger failed to notify https://testurl.com for robotPartId abc1234d-1a23-1a23-123a-1abc23d45e67. Component: N/A, Method: N/A, TriggerType: part_online, NotificationType: webhook, Error: received unretryable status code: 404 in webhook response, ResponseCode: 404
+```

docs/data-ai/reference/triggers-configuration.md

@@ -736,7 +736,7 @@ You can visualize any data, such as sensor readings, that you have [synced](/dat
 
 {{% changelog date="2024-01-31" color="added" title="Use triggers to trigger actions" %}}
 
-You can now configure [triggers](/data-ai/data/advanced/alert-data/) (previously called webhooks) to execute actions when certain types of data are sent from your machine to the cloud.
+You can now configure [triggers](/data-ai/data/alert-data/) (previously called webhooks) to execute actions when certain types of data are sent from your machine to the cloud.
 
 {{% /changelog %}}
 

docs/dev/reference/changelog.md

@@ -53,7 +53,7 @@ Other common inputs include the methods of a [board](/dev/reference/apis/compone
 You can also use camera input, for example to detect objects and pick them up with an arm.
 See [Act based on inferences](/data-ai/ai/act/) for relevant examples.
 
-If you want to send alerts based on computer vision or captured data, see [Alert on inferences](/data-ai/ai/alert/) or [Alert on data](/data-ai/data/advanced/alert-data/).
+If you want to send alerts based on computer vision or captured data, see [Alert on inferences](/data-ai/ai/alert/) or [Alert on data](/data-ai/data/alert-data/).
 
 {{% /tablestep %}}
 {{% tablestep %}}

docs/operate/mobility/use-input-to-act.md

@@ -57,7 +57,7 @@
   [plugins.inputs]
 
   # change this key to a new one any time you need to restart from scratch
-  cacheKey = ["Sep102025"]
+  cacheKey = ["Sep182025"]
   # either "warn" or "error"
   failBuildOnError = true