Configure a Trigger

Triggers allow you to send webhook requests or emails for the following events:

• 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
• Conditional data ingestion: trigger any time data is captured from a specified component with a specified method and condition

For example, you can configure a trigger to send you a notification when your robot’s sensor collects a new reading.

To configure a trigger:

• Builder mode
• 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 some types you can configure additional attributes:

• Data synced to cloud
• Conditional data ingestion

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.

Select the component you want to capture data from and the method you want to capture data from. Then, add any conditions.

These can include a key, a value, and a logical operator. For example, a trigger configured to fire when data is captured from the motor motor-1’s IsPowered method when is_on is equal to True:

For more information, see Conditions.

Note

You must configure data capture for your component to use this trigger.

4. Add Webhooks or Emails.

• Webhooks
• Emails

Click Add Webhook. Add the URL of your cloud function or lambda. Configure the time between notifications.

Click Add Email. Add the email you wish to be notified whenever this trigger is triggered. Configure the time between notifications.

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 Template: Conditional Data Ingestion
• 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>
        }
       ]
    }
  ]

"triggers": [
    {
      "name": "<trigger name>",
      "event": {
        "type": "conditional_data_ingested",
        "conditional": {
          "data_capture_method": "<component>:<name-of-component>:<method>",
          "condition": {
            "evals": [
              {
                "operator": "<lt|gt|lte|gte|eq|neq>",
                "value": <object, string, or int>
              }
            ]
          }
        }
      },
      "notifications": [
        {
          "type": "email",
          "value": "<fill-in-email-here>",
          "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:

Conditions

The conditional object for the conditional_data_ingested trigger includes the following options:

Options for operator:

Examples:

"condition": {
  "evals": [
    {
      "operator": "lt",
      "value": {
        "Line-Neutral AC RMS Voltage": 130
      }
    }
  ]
}

{
  "readings": {
    "Line-Neutral AC RMS Voltage": 100
  }
}

"condition": {
  "evals": [
    {
      "operator": "lt",
      "value": {
        "coordinate": {
          "latitude": 50
        }
      }
    }
  ]
}

{
  "readings": {
    "coordinate": {
      "latitude": 40
    }
  }
}

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'),
           "Trigger-Condition": data.get("trigger_condition", '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"),
           "Trigger-Condition": data.get("trigger_condition", "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.