Integrate IoT Hub with Event Grid

Lab Scenario

Contoso management is impressed with the prototype solutions that you’ve created using Azure IoT services, and they feel comfortable assigning additional budget the capabilities that you have already demonstrated. They are now asking that you explore the integration of certain operational support capabilities. Specifically, they would like to see how the Azure tools support sending alert notifications to the managers who are responsible for specific work areas. Alert criteria will be defined by the business area managers. The telemetry data arriving at IoT hub will be evaluated to generate the notifications.

You’ve identified a business manager, Nancy, that you’ve had success working with in the past. You’ll work with her during the initial phase of your solution.

Nancy informs you that her team of facility technicians is responsible for installing the new connected thermostats that will be used to monitor temperature across different cheese caves. The thermostat devices function as IoT devices that can be connected to IoT hub. To get your project started, you agree to create an alert that will generate a notification when a new device has been implemented.

To generate an alert, you will push a device created event type to Event Grid when a new thermostat device is created in IoT Hub. You will create a Logic Apps instance that reacts to this event (on Event Grid) and which will send an email to alert facilities when a new device has been created, specifying the device ID and connection state.

The following resources will be created:

Lab 9 Architecture

In This Lab

In this lab, you will complete the following activities:

  • Verify that the lab prerequisites are met (that you have the required Azure resources)
  • Create a Logic App that sends an email
  • Configure an Azure IoT Hub Event Subscription
  • Create new devices to trigger the Logic App

Exercise 1: Verify Lab Prerequisites

This lab assumes the following Azure resources are available:

Resource Type Resource Name
Resource Group AZ-220-RG
IoT Hub AZ-220-HUB-_{YOUR-ID}_

If these resources are not available, you will need to run the lab09-setup.azcli script as instructed below before moving on to Exercise 2. The script file is included in the GitHub repository that you cloned locally as part of the dev environment configuration (lab 3).

The lab09-setup.azcli script is written to run in a bash shell environment - the easiest way to execute this is in the Azure Cloud Shell.

  1. Using a browser, open the Azure Shell and login with the Azure subscription you are using for this course.

  2. Verify that the Azure Cloud Shell is using Bash.

    The dropdown in the top-left corner of the Azure Cloud Shell page is used to select the environment. Verify that the selected dropdown value is Bash.

  3. To upload the setup script, in the Azure Shell toolbar, click Upload/Download files (fourth button from the right).

  4. On the Azure Shell toolbar, click Upload/Download files (fourth button from the right).

  5. In the dropdown, click Upload.

  6. In the file selection dialog, navigate to the folder location of the GitHub lab files that you downloaded when you configured your development environment.

    In Lab 3: Setup the Development Environment, you cloned the GitHub repository containing lab resources by downloading a ZIP file and extracting the contents locally. The extracted folder structure includes the following folder path:

    • Allfiles
      • Labs
        • Lab 09: Integrate IoT Hub with Event Grid
          • Setup

    The lab09-setup.azcli script file is located in the Setup folder for lab 9.

  7. Select the lab09-setup.azcli file, and then click Open.

    A notification will appear when the file upload has completed.

  8. To verify that the correct file has uploaded in Azure Cloud Shell, enter the following command:

     ls
    

    The ls command lists the content of the current directory. You should see the lab09-setup.azcli file listed.

  9. To create a directory for this lab that contains the setup script and then move into that directory, enter the following Bash commands:

     mkdir lab9
     mv lab09-setup.azcli lab9
     cd lab9
    
  10. To ensure that lab09-setup.azcli has the execute permission, enter the following command:

     chmod +x lab09-setup.azcli
    
  11. On the Cloud Shell toolbar, to edit the lab09-setup.azcli file, click Open Editor (second button from the right - { }).

  12. In the FILES list, to expand the lab9 folder and open the script file, click lab9, and then click lab09-setup.azcli.

    The editor will now show the contents of the lab09-setup.azcli file.

  13. In the editor, update the {YOUR-ID} and {YOUR-LOCATION} assigned values.

    Referencing the sample below as an example, you need to set {YOUR-ID} to the Unique ID you created at the start of this course - i.e. CAH191211, and set {YOUR-LOCATION} to the location that makes sense for your resources.

     #!/bin/bash
    
     YourID="{YOUR-ID}"
     RGName="AZ-220-RG"
     IoTHubName="AZ-220-HUB-$YourID"
    
     Location="{YOUR-LOCATION}"
    

    Note: The Location variable should be set to the short name for the location. You can see a list of the available locations and their short-names (the Name column) by entering this command:

    az account list-locations -o Table
    
    DisplayName           Latitude    Longitude    Name
    --------------------  ----------  -----------  ------------------
    East Asia             22.267      114.188      eastasia
    Southeast Asia        1.283       103.833      southeastasia
    Central US            41.5908     -93.6208     centralus
    East US               37.3719     -79.8164     eastus
    East US 2             36.6681     -78.3889     eastus2
    
  14. In the top-right of the editor window, to save the changes made to the file and close the editor, click , and then click Close Editor.

    If prompted to save, click Save and the editor will close.

    Note: You can use CTRL+S to save at any time and CTRL+Q to close the editor.

  15. To create a resource group named AZ-220-RG and an IoT Hub named AZ-220-HUB-{YourID} enter the following command:

     ./lab09-setup.azcli
    

    This will take a few minutes to run. You will see JSON output as each step completes.

Exercise 2: Create HTTP Web Hook Logic App that sends an email

Azure Logic Apps is a cloud service that helps you schedule, automate, and orchestrate tasks, business processes, and workflows when you need to integrate apps, data, systems, and services across enterprises or organizations.

In this exercise, you will create a new Azure Logic App that will be triggered via an HTTP Web Hook, then send an email using an Outlook.com email address.

Task 1: Create a Logic App resource in the Azure portal

  1. If necessary, log in to the Azure portal using the Azure account credentials that you are using for this course.

    If you have more than one Azure account, be sure that you are logged in with the account that is tied to the subscription that you will be using for this course.

  2. On the Azure portal menu, click + Create a resource.

  3. On the New blade, in the Search the Marketplace box, enter logic app

  4. In the search results, click Logic App.

  5. On the Logic App blade, click Create.

  6. On the Basics tab, under Project details, select the Subscription that you are using for this course.

  7. In the Resource group dropdown, under Select existing, click AZ-220-RG.

  8. Under Instance details, in the Name field, enter AZ-220-LogicApp-_{YOUR-ID}_

    For example: AZ-220-LogicApp-CP191218

    The name of your Azure Logic App must be globally unique because it is a publicly accessible resource that you must be able to access from any IP connected device.

  9. In the Location dropdown, select the same Azure region that was used for the resource group.

  10. Leave Log Analytics set to Off.

  11. Click Review + create.

  12. On the Review + create tab, click Create.

    Note: It will take a minute or two for the Logic App deployment to complete.

  13. Navigate back to your Azure portal Dashboard.

Task 2: Configure Your Logic App

  1. On your resource group tile, click the link to the Logic App resource that was just deployed.

    If the AZ-220-LogicApp-_{YOUR-ID}_ Logic app is not displayed, refresh the resource group tile.

    Note: When navigating to the Logic App for the first time, the Logic Apps Designer pane will be displayed. If this page doesn’t come up automatically, click Logic app designer under the Development Tools section on the Logic App blade.

  2. Under the Start with a common trigger section, click When a HTTP request is received.

    Starting out with one of the commonly used triggers is a convenient way to get started on your Logic App.

  3. Notice that the visual designer opens with the When a HTTP request is received trigger selected.

  4. On the When a HTTP request is received trigger, under the Request Body JSON Schema textbox, click the Use sample payload to generate schema link.

    Note: In the next step you will be adding the DeviceCreated sample event schema to the Request Body JSON Schema textbox. This sample, along with a couple of other event schema samples and some associated documentation, can be found at the following link for those who want to learn more: Azure Event Grid event schema for IoT Hub.

  5. Use a copy-and-paste operation to add the following sample JSON to the Request Body JSON Schema textbox, and then click Done.

     [{
       "id": "56afc886-767b-d359-d59e-0da7877166b2",
       "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
       "subject": "devices/LogicAppTestDevice",
       "eventType": "Microsoft.Devices.DeviceCreated",
       "eventTime": "2018-01-02T19:17:44.4383997Z",
       "data": {
         "twin": {
           "deviceId": "LogicAppTestDevice",
           "etag": "AAAAAAAAAAE=",
           "deviceEtag": "null",
           "status": "enabled",
           "statusUpdateTime": "0001-01-01T00:00:00",
           "connectionState": "Disconnected",
           "lastActivityTime": "0001-01-01T00:00:00",
           "cloudToDeviceMessageCount": 0,
           "authenticationType": "sas",
           "x509Thumbprint": {
             "primaryThumbprint": null,
             "secondaryThumbprint": null
           },
           "version": 2,
           "properties": {
             "desired": {
               "$metadata": {
                 "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
               },
               "$version": 1
             },
             "reported": {
               "$metadata": {
                 "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
               },
               "$version": 1
             }
           }
         },
         "hubName": "egtesthub1",
         "deviceId": "LogicAppTestDevice"
       },
       "dataVersion": "1",
       "metadataVersion": "1"
     }]
    

    This sample JSON is an example of the JSON that Event Grid will POST to the Web Hook endpoint for the Logic App once it’s created. This sample includes the IoT Hub Message Telemetry properties for the IoT Device that will be sending telemetry messages.

  6. Notice that the Request Body JSON Schema textbox is now populated with a JSON schema that was automatically generated based on the sample JSON that you provided.

  7. Below the When a HTTP request is received trigger, click + New step.

  8. Below Choose an action, in the search textbox, enter Outlook.com

  9. In the list of Actions, scroll down to the Send options, and then click Send an email (V2).

    Note: These instructions walk through configuring the Logic App to send an email using an Outlook.com email address. Alternatively, the Logic App can also be configured to send email using the Office 365 Outlook or Gmail connectors as well.

  10. On the Outlook.com connector, click Sign in, and then follow the prompts to authenticate with an existing Outlook.com account.

  11. If prompted to Let this app access your info, click Yes.

  12. On the Send an email (V2) action, in the To field, enter an email address to send email messages to.

    For the purposes of this lab, you will provide an email address where you can receive the email notification. You can enter the Outlook.com account used for this connector, or another email account that is easy for you to access.

    The Outlook.com account that was authenticated in the step above will be used to send the emails.

  13. In the Subject field, enter IoT Hub alert:

  14. In the Body field, enter the following message content:

     This is an automated email to inform you that:
    
     {eventType} occurred at {eventTime}
    
     IoT Hub: {hubName}
     Device ID: {deviceID}
     Connection state: {connectionState}
    
  15. Take a moment to examine the message body that you just entered.

    You may have realized that the curly-braces entries are intended to represent dynamic content. You will need to replace these placeholder entries with the actual Dynamic content values.

    Note: If the Add dynamic content tools are not displayed to the right of the connector, click the Add dynamic content hyperlink located directly under the Body text box. If it doesn’t list the fields you need, click See more in the Dynamic content pane to include the fields included in the message body that you entered.

    In the next step you will replace each placeholder value with the corresponding Dynamic content value.

  16. For each dynamic content placeholder, delete the entry and then replace it with the corresponding Dynamic content field.

    When you add the first dynamic content value, because the input data schema is for an array, the Logic Apps Designer will automatically change the e-mail action to be nested inside of a For each action. When this happens, the Send an email (V2) action will collapse. To reopen your email message, click Send an email (V2), and then continue editing the message body.

    When you have completed this step you should see a message body that is similar to the following:

    Fill out email information

  17. At the top of the designer, to save all changes to the Logic App Workflow, click Save .

  18. To expand the When a HTTP request is received trigger, click When a HTTP request is received.

  19. Copy the value for the HTTP POST URL that is displayed.

    The HTTP POST URL will look similar to the following:

     https://prod-87.eastus.logic.azure.com:443/workflows/b16b5556cbc54c97b063479ed55b2669/triggers/manual/paths/invoke?api-version=2016-10-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=ZGqYl-R5JKTugLG3GR5Ir1FuM0zIpCrMw4Q2WycJRiM
    

    This URL is the Web Hook endpoint that is used to call the Logic App trigger via HTTPS. Notice the sig query string parameter and it’s value. The sig parameter contains the shared access key that is used to authenticate requests to the Web Hook endpoint.

  20. Save the URL for future reference.

Exercise 3: Configure Azure IoT Hub Event Subscription

Azure IoT Hub integrates with Azure Event Grid so that you can send event notifications to other services and trigger downstream processes. You can configure business applications to listen for IoT Hub events so that you can react to critical events in a reliable, scalable, and secure manner. For example, build an application that updates a database, creates a work ticket, and delivers an email notification every time a new IoT device is registered to your IoT hub.

In this exercise, you will create an Event Subscription within Azure IoT Hub to setup Event Grid integration that will trigger a Logic App to send an alert email.

  1. Navigate back to your Azure portal dashboard.

  2. On your resource group tile, to navigate to your IoT Hub, click AZ-220-HUB-_{YOUR-ID}_.

  3. On the IoT Hub blade, on the left side navigation menu, click Events.

  4. On the Events pane, at the top, click + Event Subscription.

  5. On the Create Event Subscription blade, in the Name field, enter MyDeviceCreateEvent

  6. Ensure that the EventSchema filed is set to Event Grid Schema.

  7. Leave the TOPIC DETAILS section unchanged.

    This section is informational and read-only

  8. Under EVENT TYPES, open the Filter to Event Types dropdown, and then de-select all of the choices except Device Created.

  9. Under ENDPOINT DETAILS, open the Endpoint Type dropdown, and then click Web Hook.

  10. Under ENDPOINT DETAILS, click Select an endpoint.

  11. In the Select Web Hook pane, under Subscriber Endpoint, paste the URL that you copied from your logic app, then click Confirm Selection.

    Important: Do not click Create!

    You could save the event subscription here, and receive notifications for every device that is created in your IoT hub. However, for this lab we will use the optional fields to filter for specific devices.

  12. At the top of the pane, click Filters .

    You will be using filters to filter for specific devices.

  13. Under ADVANCED FILTERS, click Add new filter, and then fill in the fields with these values:

    • Key: Enter Subject

    • Operator: Select String begins with

    • Value: Enter devices/CheeseCave1_

    We will use this value to filter for device events associated with the Cheese Cave 1 location (CheeseCave1).

  14. To create a second filter, click Add new filter, and then fill in the fields with these values:

    • Key: Enter Subject

    • Operator: Select String ends with

    • Value: Enter _Thermostat

    We will use this value to filter for device events related to temperature.

  15. To save the event subscription, click Create.

Exercise 4: Test Your Logic App with New Devices

Test your logic app by creating a new device to trigger an event notification email.

  1. In your Azure portal, if needed, navigate to your IoT Hub blade.

  2. On the left side navigation menu, under Explorers, click IoT Devices.

  3. At the top of the IoT devices blade, click + New.

  4. In the Device ID field, enter CheeseCave1_Building1_Thermostat

  5. Leave all other fields at the defaults, and then click Save.

  6. To test the event subscription filters, create additional devices using the following device IDs:

    • CheeseCave1_Building1_Thermostat
    • CheeseCave1_Building1_Light
    • CheeseCave2_Building1_Thermostat
    • CheeseCave2_Building2_Light

    If you added the four examples total, your list of IoT devices should look like the following image:

    IoT Hub device list

  7. Once you’ve added a few devices to your IoT hub, check your email to see which ones triggered the logic app.