Manage your connections

Use this dialog to configure connections to and from your Things service instance.

These connections allow the messaging-based integration of other services or applications for the purpose of device integration (e.g. using Bosch IoT Hub) or interaction of business applications with the Things service.

In contrast to ad hoc connections - that you can establish from you applications using the HTTP or WebSocket APIs - these connections are permanent, and managed by the Things service to allow a long-lasting, message-based integration with external systems.

Click the Connections tab to get an overview of the connections configured for your service instance so far.

  • To create a new connection click Add.
  • To read or edit an existing connection click its name in the left list of connections.

Things UI to manage your connections

Find the basic concepts of a connection at Eclipse Ditto:
https://www.eclipse.org/ditto/basic-connections.html .

General

This section holds general parameters to manage your connection.

  • Connection ID: Each connection is stored with a technical unique identifier.
    You can use it for API level access on the connection configuration (see HTTP API description).
  • Connection name: This is the name, which will be displayed at the left side in the list of connections.
    The list orders the connections alphabetically.
  • Connection type: The type defines which underlying transport protocol is used.
    At the time we support:
    • Bosch IoT Hub - the Hub service uses AMQP 1.0, however some settings can be set by our service automatically.
    • AMQP 0.9.1 - e.g. for a RabbitMQ message broker
    • AMQP 1.0 - e.g. a generic AMQP 1.0 message broker like Apache ActiveMQ Artemis
    • Kafka 2.x - e.g. to publish messages to an Apache Kafka cluster infrastucture
      Please note the we support Kafka topics only one-way as targets, i.e. you will not be able to configure Kafka as a source.
    • MQTT 3.1.1 - for an MQTT server or service
    • AWS IoT - for an MQTT endpoint Amazon’s web services
      Note: WebSocket connections are not displayed here because such connections are opened and closed ad hoc, and do not need explicit configuration.
  • Enable payload mapping: Via this parameter, you can enable or disable the payload mapping behavior.
    Tip: Check the checkbox, if your device or business solutions are not compatible with the Eclipse Ditto protocol.
    The UI will then provide a Payload mapping section.
  • Enable automatic re-connect: Via this parameter, you can enable or disable the failover behavior.
    By enabling, the automatic re-connect, in case a connection closes unexpectedly or fails to establish, the Things service will automatically try to re-connect.
  • Validate certificates: Via this parameter, you can enable or disable the SSL certificate validation.
  • Client count: Number of clients to be instantiated for this connection
    • Free plan subscribers can use 1 client
    • Starter and Standard plan subscribers are allowed to increase to max. 2 clients.
      When you configure more than one client, a load balancing for you connection will be used.

Coordinates

The URI of a connection endpoint is composed of various parts, and its syntax might differ depending on the messaging library.

Examples:

  • Example URI for AMQP
    amqp://user:pw@host:port

    or in case of secure messaging

    amqps://user:pw@host:port
  • Examples for the Bosch IoT Hub: the messaging endpoint is:
    amqps://messaging.bosch-iot-hub.com:5671


    Note: In case of the Hub connections, the UI will prefill the host name with the correct address of the Bosch IoT Hub service.
    Due to the restriction on outgoing traffic in Bosch IoT Cloud, external connections do not work without a manual whitelisting process. Please contact us to whitelist your broker.

Authorization

In Sources and Targets, you can configure who is allowed to read and write messages.

A connection needs at least 1 and may have multiple authorization subjects. The user interface will support you to edit 1 to 9 entries.

The subjects you define here will control which Things are able to publish or receive messages through this connection.

  • If an authorization subject has READ permission for one Thing, messages from the Thing will be sent through the connection.
  • If an authorization subject has WRITE permission for one Thing, messages from the connection will be forwarded to the Thing.

To distinguish the connection specific authorization subjects from others, the effective authorization subject will be “integration:the-solution-ID-of-this-instance:each-subject-ID”.

The following figure summarizes the concepts described in this section.

Authorization for connection messages

Find details on our authorization concept at Policies.
Find an example on how you can provide your Things with authorization subjects at Hub Connection.

Both sections Sources and Targets support placeholder which you can use. Find details below.

Sources

This section holds information about the emitters of messages (where you get messages from).

Multiple sources are supported.

The sources are identified by a queue name (AMQP 0.9.1) or a source (AMQP 1.0), thus this field will allow any string.

Example: telemetry/<hub-tenant-ID>

Placeholders

In case a fixed authorization subject is not flexible enough for your scenario (e.g. you don't want to grant one authorization subject write access to all things), placeholders can be used in the configuration of a source to allow more fine-grained per-device access control.

Given that the message headers contain some information about the origin (e.g. a device ID), you can specify the authorization subject as follows:
integration:<solution-id>:{{ header:device_id }}”.

The placeholder {{ header:device_id }} is replaced by the value from the headers and the message is further processed under this authorization subject. If the specified header cannot be resolved, the sender receives an error response (if a reply-to header was given) or dropped otherwise.

Find a detailed description of all placeholders Connection sources.


Enforcement

Messages received from external systems are mapped to the Bosch IoT Things service internal format for further processing, either by applying some custom mapping or the default mapping for Ditto protocol messages. During this mapping the specific thing which is accessed or modified as a result of the message is determined.
By default no sanity check is done if this thing corresponds to the device that originally sent the message. For some use cases this might be valid, but in other scenarios you might want to enforce that a device only sends data to its associated thing. Note that this could also be achieved by assigning a specific policy to each thing and using placeholders in the authorization subject. However, this can get cumbersome to maintain for a large number of things.
With an enforcement, you can use a single policy for all things and still make sure that a device only modifies its associated thing representation (aka digital twin). Enforcement is only feasible if the message contains the verified identity of the sending device (e.g. in a message header). This verification has to be done by the external system e.g. by properly authenticating the devices and providing the identity in the messages sent to Ditto.

Currently enforcement can be enabled for Hub/AMQP 1.0 and AWS IoT/MQTT connections.

Targets

This section holds information about what destinations the messages have.

Multiple targets are supported.

The targets are identified by an exchange name and routing key (AMQP 0.9.1) or a target (AMQP 1.0). Therefore the field provided here allows you to set any string.

Additionally you can choose which types of messages should be sent to this target, e.g. Twin events or Live commands.

Find details at Bosch IoT Things Protocol.

Placeholders

Similar to the placeholders for source authorization subjects, a target address may also contain placeholders. They can be used to control where the messages are pusblished to. Instead of using one fixed target address, the target address can be made dependent of thing specific information.

The following placeholders are available:

Placeholder Description Example
{{ thing:id }} Full ID composed of namespace + : as a separator + name com.bosch:thing-42
{{ thing:namespace }} Namespace (i.e. first part of an ID) com.bosch
{{ thing:name }} Name (i.e. second part of an ID ) thing-42

Find a detailed description of all placeholders Connection targets.




Payload mapping

In case your device or business solutions are not compatible with the Eclipse Ditto protocol, you can use this section to define the mapping.
In case your connection does not display such a section, you need to go back to the General section and check the respective checkbox.

Payload mapping helps developers to define transformations from one protocol to another:

  • In case the incoming messages would not be compatible to the Eclipse Ditto Protocol, please use the sub-section Incoming.
  • In case the messages from our service would not be compatible to your solution’s messaging protocol, please use the sub-section Outgoing.

The code to transform from and to arbitrary binary or text representations of message payloads needs to be set in this section as JavaScript.
Using this field the mapping can be done without the need for you to setup/provide a separate runtime environment.

Find details about connection mapping at Eclipse Ditto:
https://www.eclipse.org/ditto/connectivity-mapping.html .

The tabular arrangement of metrics should help you to find out if the connection is working properly.

  • Connection Metrics - gives an overview on sources as well as targets and responses
  • Source Metrics - details the data by source
  • Target Metrics - details the data by target
  • Response Metrics - details the data for responses

You can reset the values captured so far, to more easily track a specific type of event, telemetry data, message, or response.
Also, in case a real device is configured to use the connection, check the box Refresh automatically.

connection metrics example

The Log entries view allows you to get more insights in your connections.

Start by enabling the logging for one hour. The service will automatically renew the expiration date each time you have a look at the logs.

This view does not only contain a list of the latest log entries for the connection, but also allows a full-text search on all log entries, and to add filters for different fields of the log messages.

If you need more details about a specific log entry, simply click on it.

You can reset the values captured so far, to more easily track a specific type of event, telemetry data, message, or response.
Also, in case a real device is configured to use the connection, check the box Refresh automatically.

Please note, that we will only maintain a restricted number of log entries. Thus, older entries will be replaced by newer entries. Therefore, this list of logs might be incomplete.
If you are interested in one particular message, you should block all other messages, to make sure, that your desired message shows up in the list.

connection logs example

Currently, it is not possible to change the duration for which logging will be enabled.

Logging will not cause any costs itself. Note however, that all requests and all responses (e.g. retrieving the log entries) used in the UI are counted as transactions, and are reported for billing purposes.