Skip to content

Commit

Permalink
DOCS-2244: Document part data ingesting header info (viamrobotics#2921)
Browse files Browse the repository at this point in the history
  • Loading branch information
@skyleilani
skyleilani committed Jul 18, 2024
1 parent 0a4cedf commit bc85e10
Showing 1 changed file with 97 additions and 45 deletions.
142 changes: 97 additions & 45 deletions docs/build/configure/triggers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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**.
Expand All @@ -29,60 +29,64 @@ 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" %}}

```json {class="line-numbers linkable-line-numbers"}
"triggers": [
{
"url": "<Insert your own cloud function or lambda URL for sending the event>",
"name": "<trigger 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": <number of seconds>
}
]
}
]
```
Expand All @@ -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": "<Insert your own cloud function or lambda URL for sending the event>",
"name": "<trigger name>",
"event": {
"type": "part_online",
"attributes": {
"type": "part_online"
},
"notifications": [
{
"type": "webhook",
"value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
"seconds_between_notifications": <number of seconds>
}
}
]
}
]
```
Expand All @@ -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": "<Insert your own cloud function or lambda URL for sending the event>",
"name": "<trigger name>",
"event": {
"type": "part_offline",
"attributes": {
"type": "part_offline"
},
"notifications": [
{
"type": "webhook",
"value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
"seconds_between_notifications": <number of seconds>
}
}
]
}
]
```
Expand Down Expand Up @@ -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": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
"seconds_between_notifications": 0
}
]
}
]
}
Expand All @@ -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:

<!-- prettier-ignore -->
| Name | Type | Required? | Description |
| ---- | ---- | --------- | ----------- |
| `name` | string | **Required** | The name of the trigger |
| `event` | object | **Required** | The trigger event object: <ul><li>`type`: The type of the event to trigger on. Options: `"part_online"`, `"part_offline"`, `"part_data_ingested"`.</li><li>`data_types`: Required with `type` `"part_data_ingested"`. The data types that trigger the event. Options: `"binary"`, `"tabular"`, `"file"`, `"unspecified"`.</li></ul> |
| `notifications` | object | **Required** | The notifications object: <ul><li>`type`: The type of the notification. Options: `"webhook"`.</li><li>`value`: The URL to send the request to.</li><li>`seconds_between_notifications`: The interval between notifications in seconds.</li></ul> |

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
Expand All @@ -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 = "<paste in your own 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:

<!-- prettier-ignore -->
| Trigger type | HTTP Method |
| ------------ | ----------- |
| `part_data_ingested` | POST |
| `part_online` | GET |
| `part_offline` | GET |

The request includes the following headers:

<!-- prettier-ignore -->
| 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/" %}}
Expand Down

0 comments on commit bc85e10

Please sign in to comment.