From bc85e10393966e35fb12c5e56ee096e2f8e6ea05 Mon Sep 17 00:00:00 2001 From: sky leilani <45158875+skyleilani@users.noreply.github.com> Date: Thu, 18 Jul 2024 16:47:57 -0400 Subject: [PATCH] DOCS-2244: Document part data ingesting header info (#2921) --- docs/build/configure/triggers.md | 142 +++++++++++++++++++++---------- 1 file changed, 97 insertions(+), 45 deletions(-) diff --git a/docs/build/configure/triggers.md b/docs/build/configure/triggers.md index 09c7894194..770990af89 100644 --- a/docs/build/configure/triggers.md +++ b/docs/build/configure/triggers.md @@ -20,7 +20,7 @@ Viam provides three trigger types depending on the event you want to trigger on: To configure a trigger: {{< tabs >}} -{{% tab name="Config Builder" %}} +{{% tab name="Builder mode" %}} 1. Go to the **CONFIGURE** tab of your machine on the [Viam app](https://app.viam.com). Click the **+** (Create) button in the left side menu and select **Trigger**. @@ -29,46 +29,43 @@ To configure a trigger: 2. Name the trigger and click **Create**. -3. Select the type of event to trigger on from the **Type** dropdown. - -4. Follow the instructions depending on the type of trigger you want to implement: +3. Select trigger **Type**. + For the respective type, configure the respective attributes: {{< tabs name="Types of Triggers" >}} {{% tab name="Data synced to cloud" %}} -5. Select the types of data you want to trigger on from the dropdown. - Whenever any data of the type you select is synced from any component on your machine, the trigger will trigger. +Select the data types for which the Trigger should send requests. +Whenever data of the specified data types is ingested, a `POST` request will be sent. {{% alert title="Note" color="note" %}} -Be sure to configure [data capture](/services/data/capture/) and [cloud sync](/services/data/cloud-sync/) for the relevant components. + +You must have [data capture](/services/data/capture/) and [cloud sync](/services/data/cloud-sync/) configured for the relevant components to use this trigger and the component must return the type of data you configure in the trigger's **Data Types**. For example, if you want to trigger a trigger on temperature readings, configure data capture and sync on your temperature sensor. -Be aware that the component must return the type of data you configure in the trigger's **Data Types**. {{% /alert %}} {{% /tab %}} {{% tab name="Part is online" %}} -5. While your part is online, the trigger action executes at a specified interval. - Edit the **Time between notifications** attribute to set this interval according to your preferences. +Edit the **Time between notifications** attribute to set the interval at which this trigger will send `GET` requests when the part is online. {{% /tab %}} {{% tab name="Part is offline" %}} -5. While your part is offline, the trigger action executes at a specified interval. - Edit the **Time between notifications** attribute to set this interval according to your preferences. +Edit the **Time between notifications** attribute to set the interval at which this trigger will send `GET` requests when the part is offline. {{% /tab %}} {{< /tabs >}} -6. Replace the URL value with the URL of your cloud/lambda function. +4. Replace the **URL** value with the URL of your cloud function or lambda. ![The trigger configured with an example URL in the Viam app.](/build/configure/trigger-configured.png) {{% /tab %}} -{{% tab name="Raw JSON" %}} +{{% tab name="JSON mode" %}} -If you prefer to configure your trigger with raw JSON instead of the config builder, you can paste one of the following JSON templates into your JSON config. -`"triggers"` is a top-level section like `"components"` or `"services"`. +To configure your trigger by using **JSON** mode instead of **Builder** mode, paste one of the following JSON templates into your JSON config. +`"triggers"` is a top-level section, similar to `"components"` or `"services"`. {{< tabs >}} {{% tab name="JSON Template: Data Synced" %}} @@ -76,13 +73,20 @@ If you prefer to configure your trigger with raw JSON instead of the config buil ```json {class="line-numbers linkable-line-numbers"} "triggers": [ { - "url": "", + "name": "", "event": { "type": "part_data_ingested", - "attributes": { + "data_ingested": { "data_types": ["binary", "tabular", "file"] } - } + }, + "notifications": [ + { + "type": "webhook", + "value": "https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws", + "seconds_between_notifications": + } + ] } ] ``` @@ -93,13 +97,17 @@ If you prefer to configure your trigger with raw JSON instead of the config buil ```json {class="line-numbers linkable-line-numbers"} "triggers": [ { - "url": "", + "name": "", "event": { - "type": "part_online", - "attributes": { + "type": "part_online" + }, + "notifications": [ + { + "type": "webhook", + "value": "", "seconds_between_notifications": } - } + ] } ] ``` @@ -110,13 +118,17 @@ If you prefer to configure your trigger with raw JSON instead of the config buil ```json {class="line-numbers linkable-line-numbers"} "triggers": [ { - "url": "", + "name": "", "event": { - "type": "part_offline", - "attributes": { + "type": "part_offline" + }, + "notifications": [ + { + "type": "webhook", + "value": "", "seconds_between_notifications": } - } + ] } ] ``` @@ -160,13 +172,20 @@ If you prefer to configure your trigger with raw JSON instead of the config buil ], "triggers": [ { - "url": "https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws", + "name": "trigger-1", "event": { "type": "part_data_ingested", - "attributes": { - "data_types": ["binary", "tabular"] + "data_ingested": { + "data_types": ["binary", "tabular", "file"] } - } + }, + "notifications": [ + { + "type": "webhook", + "value": "", + "seconds_between_notifications": 0 + } + ] } ] } @@ -178,8 +197,17 @@ If you prefer to configure your trigger with raw JSON instead of the config buil {{% /tab %}} {{< /tabs >}} -7. Write your cloud/lambda function to process the request from `viam-server`. - The following example function sends a Slack message with a machine's details, such as robot and location IDs, when it receives a request: +The following attributes are available for triggers: + + +| Name | Type | Required? | Description | +| ---- | ---- | --------- | ----------- | +| `name` | string | **Required** | The name of the trigger | +| `event` | object | **Required** | The trigger event object:
  • `type`: The type of the event to trigger on. Options: `"part_online"`, `"part_offline"`, `"part_data_ingested"`.
  • `data_types`: Required with `type` `"part_data_ingested"`. The data types that trigger the event. Options: `"binary"`, `"tabular"`, `"file"`, `"unspecified"`.
| +| `notifications` | object | **Required** | The notifications object:
  • `type`: The type of the notification. Options: `"webhook"`.
  • `value`: The URL to send the request to.
  • `seconds_between_notifications`: The interval between notifications in seconds.
| + +5. Write your cloud function or lambda to process the request from `viam-server`. + The following example function prints the received headers: ```python {class="line-numbers linkable-line-numbers"} import functions_framework @@ -193,26 +221,50 @@ If you prefer to configure your trigger with raw JSON instead of the config buil "Location-ID": request.headers['location-id'] if 'location-id' in request.headers else 'no value', "Part-ID": request.headers['part-id'] if 'part-id' in request.headers else 'no value', "Robot-ID": request.headers['robot-id'] if 'robot-id' in request.headers else 'no value', - "Machine-Name": request.headers['machine-name'] if 'machine-name' in request.headers else 'no value', - "Location-Name": request.headers['location-name'] if 'location-name' in request.headers else 'no value', - "Organization-Name": request.headers['organization-name'] if 'organization-name' in request.headers else 'no value' + "Component-Type": request.headers['component-type'] if 'component-type' in request.headers else 'no value', + "Component-Name": request.headers['component-name'] if 'component-name' in request.headers else 'no value', + "Method-Name": request.headers['method-name'] if 'method-name' in request.headers else 'no value', + "Min-Time-Received": request.headers['min-time-received'] if 'min-time-received' in request.headers else 'no value', + "Max-Time-Received": request.headers['max-time-received'] if 'max-time-received' in request.headers else 'no value', + + "Data-Type": request.args['data_type'] if 'data_type' in request.args else 'no value' } - slack_url = "" - headers = {} + print(payload) - response = requests.post(slack_url, json=payload, headers=headers) + return 'Received headers: {}'.format(payload) - request_json = request.get_json(silent=True) - request_args = request.args + ``` - return 'Sent request to {}'.format(slack_url) +## Returned headers - ``` +When a trigger occurs, Viam sends a HTTP request to the URL you specified for the trigger: + + +| Trigger type | HTTP Method | +| ------------ | ----------- | +| `part_data_ingested` | POST | +| `part_online` | GET | +| `part_offline` | GET | + +The request includes the following headers: + + +| Header Key | Description | +| ---------- | ----------- | +| `Part-ID` | The part of the machine that triggered the request. | +| `Robot-ID` | The machine that triggered the request. | +| `Location-ID` | The location of the machine that triggered the request. | +| `Org-ID` | The organization that triggered the request. | +| `Component-Type` | The type of component for which data was ingested. Only for `part_data_ingested` triggers. | +| `Component-Name` | The name of the component for which data was ingested. Only for `part_data_ingested` triggers. | +| `Method-Name` | The name of the method from which data was ingested. Only for `part_data_ingested` triggers. | +| `Min-Time-Received` | Indicates the earliest time a piece of data was received. | +| `Max-Time-Received` | Indicates the latest time a piece of data was received. | -## More examples +## Next steps -The [Monitor Job Site Helmet Usage with Computer Vision tutorial](/tutorials/projects/helmet/#configure-a-trigger-on-your-machine) uses triggers to send email notifications. +To see an example project that uses triggers to send email notification, see the [Monitor Job Site Helmet Usage with Computer Vision tutorial](/tutorials/projects/helmet/#configure-a-trigger-on-your-machine). {{< cards >}} {{% card link="/tutorials/projects/helmet/" %}}