Signals which are emitted to subscribers via WebSocket API, HTTP SSEs or established connections may be enriched by extraFields to also be included in the sent message.

Events, for example, only contain the actually changed data by default, so when they are subscribed to via one of the APIs listed above, the data they contain may be as sparse as: “temperature value was changed to 23.4 for the thing with ID xx”.

Often it is helpful to additionally include some extra fields as context to be included when subscribing (e.g. via WebSocket or a connection). For example in order to include static metadata stored in the attributes.

Therefore, it is possible to define extraFields to include when subscribing for:

How the extraFields are specified is depending on the API, please find the specific API information here:

The extra data is added to the extra field in Ditto Protocol messages being an JSON object containing all selected fields.

Example

For example a Thing could look like this:

{
  "thingId": "org.eclipse.ditto:fancy-thing",
  "policyId": "org.eclipse.ditto:fancy-thing",
  "attributes": {
    "location": "Kitchen"
  },
  "features": {
    "temperature": {
      "properties": {
        "value": 23.42,
        "unit": "Celcius"
      }
    }
  }
}

Now whenever its temperature is modified you normally only get the following information in the event (this is a Ditto Protocol message):

{
  "topic": "org.eclipse.ditto/fancy-thing/things/twin/events/modified",
  "headers": {},
  "path": "/features/temperature/properties/value",
  "value": 23.42,
  "revision": 34
}

What you could want is to:

  • additionally add the attributes
  • additionally add the unit value of the temperature

In that case you would define to include extraFields (syntax is the same as for retrieving partial things with field selector):

extraFields=attributes,features/temperature/properties/unit

In that case, each emitted Ditto Protocol event would include an extra section containing the selected data:

{
  "topic": "org.eclipse.ditto/fancy-thing/things/twin/events/modified",
  "headers": {},
  "path": "/features/temperature/properties/value",
  "value": 23.42,
  "revision": 34,
  "extra": {
    "attributes": {
        "location": "kitchen"
    },
    "features": {
      "temperature": {
        "properties": {
          "unit": "Celcius"
        }
      }
    }
  }
}

Enrich and filter

In combination with event filtering enriched data can also be used to filter. For example, when selecting extraFields=attributes/location, an additional filter may define to only emit events for a certain location: extraFields=attributes/location&filter=eq(attributes/location,"kitchen").

Tags: protocol