Configure a Trigger

Triggers allow you to trigger webhooks when certain types of data are sent from your machine to the cloud, or when the your machine parts connect to Viam. For example, you can configure a trigger to send you a notification when your robot’s sensor collects a new reading. Viam provides three trigger types depending on the event you want to trigger on:

• Data has been synced to the cloud: trigger when data from the machine is synced
• Part is online: trigger continuously at a specified interval while the machine part is online
• Part is offline: trigger continuously at a specified interval while the machine part is offline

To configure a trigger:

• Builder mode: Create menu
• Builder mode: Resource card
• JSON mode

1. Go to the CONFIGURE tab of your machine on the Viam app. Click the + (Create) button in the left side menu and select Trigger.

   

2. Name the trigger and click Create.

3. Select trigger Type. For the respective type, configure the respective attributes:

• Data synced to cloud
• Part is online
• Part is offline

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.

Note

You must have data capture and 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.

Edit the Time between notifications attribute to set the interval at which this trigger will send GET requests when the part is online.

Edit the Time between notifications attribute to set the interval at which this trigger will send GET requests when the part is offline.

4. Replace the URL value with the URL of your cloud function or lambda.

   

You can also configure a trigger for a resource in Builder mode on the CONFIGURE tab by navigating to the resource’s configuration panel, selecting the … menu in the upper right corner, and selecting Create trigger.

This creates a trigger that’s configured to fire on an event occurring from a specific resource. You must configure the method of activation and any relevant Conditions, as well as any Webhooks and Emails for notifications.

For example, the following triggers when data is ingested from the sensor’s Readings method:

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".

• JSON Template: Data Synced
• JSON Template: Part Online
• JSON Template: Part Offline
• JSON Example

  "triggers": [
    {
      "name": "<trigger name>",
      "event": {
        "type": "part_data_ingested",
        "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>
        }
      ]
    }
  ]

  "triggers": [
    {
      "name": "<trigger name>",
      "event": {
        "type": "part_online"
      },
      "notifications": [
        {
          "type": "webhook",
          "value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
          "seconds_between_notifications": <number of seconds>
        }
      ]
    }
  ]

  "triggers": [
    {
      "name": "<trigger name>",
      "event": {
        "type": "part_offline"
      },
       "notifications": [
        {
          "type": "webhook",
          "value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
          "seconds_between_notifications": <number of seconds>
        }
       ]
    }
  ]

{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "my_temp_sensor",
      "model": "bme280",
      "type": "sensor",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
      "service_configs": [
        {
          "type": "data_manager",
          "attributes": {
            "capture_methods": [
              {
                "method": "Readings",
                "additional_params": {},
                "capture_frequency_hz": 0.017
              }
            ]
          }
        }
      ]
    }
  ],
  "triggers": [
    {
      "name": "trigger-1",
      "event": {
        "type": "part_data_ingested",
        "data_ingested": {
          "data_types": ["binary", "tabular", "file"]
        }
      },
      "notifications": [
        {
          "type": "webhook",
          "value": "<https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws>",
          "seconds_between_notifications": 0
        }
      ]
    }
  ]
}

The following attributes are available for triggers:

5. Write your cloud function or lambda to process the request from viam-server. You can use your cloud function or lambda to interact with any external API such as, for example, Twilio, PagerDuty, or Zapier. The following example function prints the received headers:

   • Flask
   • functions_framework

   from flask import Flask, request
   
   app = Flask(__name__)
   
   
   @app.route("/", methods=['GET', 'POST'])
   def trigger():
       headers = request.headers
       data = {}
       if request.data:
           data = request.json
       payload = {
           "Org-Id": headers.get('org-id', 'no value'),
           "Organization-Name": headers.get('organization-name', '') or
           data.get('org_name', 'no value'),
           "Location-Id": headers.get('location-id', 'no value'),
           "Location-Name": headers.get('location-name', '') or
           data.get('location_name', 'no value'),
           "Part-Id": headers.get('part-id', 'no value'),
           "Part-Name": headers.get('part-name', 'no value'),
           "Robot-Id": headers.get('robot-id', 'no value'),
           "Machine-Name": headers.get('machine-name', '') or
           data.get('machine_name', 'no value'),
           "Component-Type": data.get('component_type', 'no value'),
           "Component-Name": data.get('component_name', 'no value'),
           "Method-Name": data.get('method_name', 'no value'),
           "Min-Time-Received": data.get('min_time_received', 'no value'),
           "Max-Time-Received": data.get('max_time_received', 'no value'),
           "Data-Type": data.get('data_type', 'no value'),
           "File-Id": data.get('file_id', 'no value'),
           "Data": data.get('data', 'no value')
       }
       print(payload)
   
       return payload
   
   
   if __name__ == '__main__':
       app.run(host='0.0.0.0', port=8080)
   

   import functions_framework
   import requests
   import time
   
   
   @functions_framework.http
   def hello_http(request):
       headers = request.headers
       data = {}
       if request.data:
           data = request.json
       payload = {
           "Org-Id": headers.get("org-id", "no value"),
           "Organization-Name": headers.get("organization-name", "")
           or data.get("org_name", "no value"),
           "Location-Id": headers.get("location-id", "no value"),
           "Location-Name": headers.get("location-name", "")
           or data.get("location_name", "no value"),
           "Part-Id": headers.get("part-id", "no value"),
           "Part-Name": headers.get("part-name", "no value"),
           "Robot-Id": headers.get("robot-id", "no value"),
           "Machine-Name": headers.get("machine-name", "")
           or data.get("machine_name", "no value"),
           "Component-Type": data.get("component_type", "no value"),
           "Component-Name": data.get("component_name", "no value"),
           "Method-Name": data.get("method_name", "no value"),
           "Min-Time-Received": data.get("min_time_received", "no value"),
           "Max-Time-Received": data.get("max_time_received", "no value"),
           "Data-Type": data.get("data_type", "no value"),
           "File-Id": data.get('file_id', 'no value'),
           "Data": data.get('data', 'no value')
       }
       print(payload)
   
       return 'Received headers: {}'.format(payload)
   

Returned headers

When a trigger occurs, Viam sends a HTTP request to the URL you specified for the trigger:

The request includes the following headers:

The request body includes the following data:

Next steps

To see an example project that uses triggers to send email notification, see the Monitor Job Site Helmet Usage with Computer Vision tutorial.