Enrichment of events and messages

Subscribers of events and messages may request data from the related digital twins attached to each event and message.

This way, you can add e.g. attributes or feature properties of your things, which are not included in the original payload, but are helpful for your consumers.

The selection of information to be added is defined using the parameter extraFields, which could point to one or multiple JSON fields of the things.

WebSocket

Set the query parameter extraFields when requesting events and messages to receive extra data from the digital twins. The extra data will appear in the field extra.

Example subscription request:

START-SEND-EVENTS?extraFields=attributes/location

Example event:

{
  "topic": "fancy/thermostat/things/twin/events/modified",
  "headers": {},
  "path": "/features/temperature/properties/value",
  "value": 23.42,
  "revision": 34,
  "extra": {
    "attributes": {
      "location": "kitchen"
    }
  }
}

Server Sent Events (SSE)

Set the query parameter extraFields in the server-sent-events request to receive extra data from the digital twins. The extra data will be merged into the thing change.

Example request:

GET /api/2/things?extraFields=attributes/location HTTP/1.1
Accept: text/event-stream

Example response:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Connection: keep-alive
 
data:
{
  "thingId": "fancy:thermostat",
  "attributes": {
    "location": "kitchen"
  },
  "features": {
    "temperature": {
      "properties": {
        "value": 23.42
      }
    }
  }
}

Connections

Configure extra fields to receive for each target topic (twin events, live events, live commands, messages) in the target editor. To open a target editor, edit a target in the connection editor on the Connections tab of the dashboard.

images/confluence/download/attachments/1945515199/connection-enrichment.png

Enrichment and filtering of events can be of course combined for WebSocket and SSE too. Find details on filtering in section Protocol - event filter

For a detailed explanation of the signal-enrichment concept, see the corresponding documentation for Eclipse Ditto.