Consume messages from AMQP 1.0 endpoints via sources and send messages to AMQP 1.0 endpoints via targets.

Content-type

When messages are sent in Ditto Protocol (as UTF-8 encoded String payload), the content-type of AMQP 1.0 messages must be set to:

application/vnd.eclipse.ditto+json

If messages which are not in Ditto Protocol should be processed, a payload mapping must be configured for the AMQP 1.0 connection in order to transform the messages.

AMQP 1.0 properties and application properties

When set as external headers by outgoing payload or header mapping, the properties defined by AMQP 1.0 specification are set to the corresponding header value. Conversely, the values of AMQP 1.0 properties are available for incoming payload and header mapping as external headers. The supported AMQP 1.0 properties are:

  • message-id
  • user-id
  • to
  • subject
  • reply-to
  • correlation-id
  • content-type
  • absolute-expiry-time
  • creation-time
  • group-id
  • group-sequence
  • reply-to-group-id

External headers not on this list are mapped to AMQP application properties. To set an application property whose name is identical to an AMQP 1.0 property, prefix it by amqp.application.property:. The following target header mapping sets the application property to to the value of the Ditto protocol header reply-to:

{
  "headerMapping": {
    "amqp.application.property:to": "{{ header:reply-to }}"
  }
}

To read an application property whose name is identical to an AMQP 1.0 property, prefix it by amqp.application.property:. The following source header mapping sets the Ditto protocol header reply-to to the value of the application property to:

{
  "headerMapping": {
    "reply-to": "{{ header:amqp.application.property:to }}"
  }
}

Specific connection configuration

The common configuration for connections in Connections > Sources and Connections > Targets applies here as well. Following are some specifics for AMQP 1.0 connections:

Source format

Any source item defines an addresses array of source identifiers (e.g. Eclipse Hono’s Telemetry API) to consume messages from and authorizationContext array that contains the authorization subjects in whose context inbound messages are processed. These subjects may contain placeholders, see placeholders section for more information.

{
  "addresses": [
    "<source>",
    "..."
  ],
  "authorizationContext": ["ditto:inbound-auth-subject", "..."]
}

Target format

An AMQP 1.0 connection requires the protocol configuration target object to have an address property with a source identifier. The target address may contain placeholders; see placeholders section for more information.

Target addresses for AMQP 1.0 are by default handled as AMQP 1.0 “queues”. There is however the possibility to also configure AMQP 1.0 “topics” as well. In order to be more specific, the following formats for the address are supported:

  • the-queue-name (when configuring w/o prefix, the address is handled as “queue”)
  • queue://the-queue-name
  • topic://the-topic-name

Further, "topics" is a list of strings, each list entry representing a subscription of Ditto protocol topics, see target topics and filtering for more information on that.

Outbound messages are published to the configured target address if one of the subjects in "authorizationContext" has READ permission on the Thing, that is associated with a message.

{
  "address": "<target>",
  "topics": [
    "_/_/things/twin/events",
    "_/_/things/live/messages"
  ],
  "authorizationContext": ["ditto:outbound-auth-subject", "..."]
}

Specific configuration properties

The specific configuration properties are interpreted as JMS Configuration options. Use these to customize and tweak your connection as needed.

Establishing connecting to an AMQP 1.0 endpoint

Ditto’s Connectivity service is responsible for creating new and managing existing connections.

This can be done dynamically at runtime without the need to restart any microservice using a Ditto DevOps command.

Example connection configuration to create a new AMQP 1.0 connection:

{
  "id": "hono-example-connection-123",
  "connectionType": "amqp-10",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "amqps://user:password@hono.eclipse.org:5671",
  "sources": [
    {
      "addresses": [
        "telemetry/FOO"
      ],
      "authorizationContext": ["ditto:inbound-auth-subject"]
    }
  ],
  "targets": [
    {
      "address": "events/twin",
      "topics": [
        "_/_/things/twin/events"
      ],
      "authorizationContext": ["ditto:outbound-auth-subject"]
    }
  ]
}
Tags: protocol connectivity rql