Edit

Event notifications

  • Article

This article covers event notifications generated by Azure Digital Twins, their structure, and details about the various types that can be generated.

Different events in Azure Digital Twins produce notifications, which allow the solution backend to be aware when different actions are happening. These notifications are then routed to different locations inside and outside of Azure Digital Twins that can use this information to take action.

There are several types of notifications that can be generated, and notification messages may look different depending on which type of event generated them. This article gives detail about different types of messages, and what they might look like.

This chart shows the different notification types:

Notification type Routing source name Generated from...
Digital Twin Change Notification Digital Twin Change Notification any digital twin property change
Digital Twin Lifecycle Notification Digital Twin Lifecycle Notification any digital twin create or delete operation
Digital Twin Relationship Change Notification Digital Twin Relationship Change Notification any digital twin relationship change
Digital Twin Telemetry Messages Telemetry Messages any telemetry message

Notification structure

The structure of an event notification from Azure Digital Twins depends on the notification's destination.

Notifications sent to Event Grid conform to one of the following formats (dependent on the Event Grid settings):

Notifications sent to Event Hubs and Service Bus conform to the AMQP Protocol Binding for CloudEvents.

Digital twin change notifications

Digital twin change notifications are triggered when a digital twin is being updated, like:

  • When property values or metadata changes.
  • When digital twin or component metadata changes. An example of this scenario is changing the model of a digital twin.

Properties

Here are the fields in the body of a digital twin change notification.

Name Value
id Identifier of the notification, such as a UUID or a counter maintained by the service. source + id is unique for each distinct event
source Name of the IoT hub or Azure Digital Twins instance, like myhub.azure-devices.net or mydigitaltwins.westus2.azuredigitaltwins.net
data A JSON Patch document describing the update made to the twin. For details, see Body details below.
specversion 1.0
The message conforms to this version of the CloudEvents spec.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject ID of the digital twin
time Timestamp for when the operation occurred on the digital twin
traceparent A W3C trace context for the event

Body details

Inside the message, the data field contains a JSON Patch document containing the update to the digital twin.

Below are examples of this message type for each possible notification schema.

{
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "subject": "example-twin1",
    "data": {
      "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
          {
            "value": "new name",
            "path": "/room",
            "op": "replace"
          }
        ]
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-c28d665340fe5045-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.9795363Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Note

Azure Digital Twins currently doesn't support filtering events based on fields within an array. This includes filtering on properties within a patch section of a digital twin change notification.

Digital twin lifecycle notifications

Whether digital twins represent IoT Hub devices in Azure Digital Twins or not, they will all emit notifications. They do so because of lifecycle notifications, which are about the digital twin itself.

Lifecycle notifications are triggered when:

  • A digital twin is created
  • A digital twin is deleted

Properties

Here are the fields in the body of a lifecycle notification.

Name Value
id Identifier of the notification, such as a UUID or a counter maintained by the service. source + id is unique for each distinct event.
source Name of the IoT hub or Azure Digital Twins instance, like myhub.azure-devices.net or mydigitaltwins.westus2.azuredigitaltwins.net
data The data of the twin experiencing the lifecycle event. For details, see Body details below.
specversion 1.0
The message conforms to this version of the CloudEvents spec.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject ID of the digital twin
time Timestamp for when the operation occurred on the twin
traceparent A W3C trace context for the event

Body details

Below are examples of this message type for each possible notification schema.

{
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "subject": "example-twin1",
    "data": {
      "data": {
        "$dtId": "example-twin1",
        "$etag": "W/\"ecf81d6c-8c1a-4a95-afd8-13bd4cea436f\"",
        "room": "room name",
        "$metadata": {
          "$model": "dtmi:examplecom:interfaceName;1",
          "room": {
            "lastUpdateTime": "2021-12-09T20:28:52.6651216Z"
          }
        }
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-51f716e7397ec64b-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Create",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.6745538Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Digital twin relationship change notifications

Relationship change notifications are triggered when any relationship of a digital twin is created, updated, or deleted.

Properties

Here are the fields in the body of a relationship change notification.

Name Value
id Identifier of the notification, such as a UUID or a counter maintained by the service. source + id is unique for each distinct event
source Name of the Azure Digital Twins instance, like mydigitaltwins.westus2.azuredigitaltwins.net
data The payload of the relationship that was changed. For details, see Body details below.
specversion 1.0
The message conforms to this version of the CloudEvents spec.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject ID of the relationship, like <twin-ID>/relationships/<relationshipID>
time Timestamp for when the operation occurred on the relationship
traceparent A W3C trace context for the event

Body details

Inside the message, the data field contains the payload of a relationship, in JSON format. It uses the same format as a GET request for a relationship via the DigitalTwins API.

Below are examples of this message type for each possible notification schema.

{
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "data": {
    "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
        {
            "value": "new value",
            "path": "/prop1",
            "op": "replace"
        }
        ]
    },
    "contenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-c1fcf951f540ec44-01"
    },
    "eventType": "Microsoft.DigitalTwins.Relationship.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:53.2016395Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Digital twin telemetry messages

Digital twins can use the SendTelemetry API to emit telemetry messages and send them to egress endpoints.

Properties

Here are the fields in the body of a telemetry message.

Name Value
id Identifier of the notification, which is provided by the customer when calling the telemetry API.
source Fully qualified name of the twin that the telemetry event was sent from. Uses the following format: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1.0
The message conforms to this version of the CloudEvents spec.
type microsoft.iot.telemetry
data The telemetry message being sent from the twin. The payload does not need to align with any schema defined in your Azure Digital Twins instance.
dataschema The data schema is the model ID of the twin or the component that emits the telemetry. For example, dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent A W3C trace context for the event.

Body details

The body contains the telemetry measurement along with some contextual information about the twin. Below are examples of this message type for each possible notification schema.

{
    "id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "subject": "example-twin1",
    "data": {
        "data": {
        "prop": "hello from telemetry"
        },
        "dataschema": "dtmi:examplecom:interfaceName;1",
        "contenttype": "application/json-patch+json; charset=utf-8",
        "traceparent": "00-2aa957558db348f387ef704b37631a1d-e894098b46243743-01"
    },
    "eventType": "microsoft.iot.telemetry",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "0001-01-01T00:00:00Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Next steps

Learn about delivering events to different destinations, using endpoints and routes: