Service Integration Event API
This API is only available if you are using Bosch IoT Rollouts as a standalone service.
Currently, it is not available if you are using Bosch IoT Rollouts as part of your Bosch IoT Device Management subscription.
The purpose of the Service Integration Event API (hereafter referred to as SIE API) is to integrate external services and notify them about events occurring in Bosch IoT Rollouts.
The events that are published through this API are described below under Messages. As this list of events may be extended with further events in the future, consumers are advised to ignore unknown events.
The message transport is AMQP 0-9-1 compatible with message bodies in JSON.
Table of contents:
AMQP basics
There are three basic concepts of AMQP:
Exchanges - what you publish to.
Queues - what you consume from.
Bindings - configuration that maps an exchange to a queue.
Queues are just a place for receiving messages. Bindings determine how messages get into them. Queues can also be bound to multiple exchanges.
Exchanges are for publishing messages. The user decides who can publish on the exchange and who can create bindings on that exchange for delivery to a specific queue.
Exchange & Queue definition
By enabling the SIE API for a tenant, the necessary queues, exchanges and the bindings are automatically created for the user.
The queue name to receive messages about events in Bosch IoT Rollouts is sievent_queue.
Bosch IoT Rollouts sends event messages to the sievent.exchange which is bound to the sievent_queue.
As the SIE API is designed to notify consumers about events occurring within Bosch IoT Rollouts, it is not bidirectional and therefore it is not possible to send any messages to Bosch IoT Rollouts through this API.
Exchanges
Exchange |
Use case |
Queue binding |
Type |
Durable |
Auto-delete |
User permissions |
sievent.exchange |
Send assignment events to a client |
sievent_queue |
Fanout |
|
|
|
Queues
Queue |
Use case |
Durable |
Exclusive |
Auto-delete |
Arguments |
User permissions |
sievent_queue |
Receiving the assignment events |
|
|
|
x-max-length=1000 |
READ |
Authentication & Authorization
You can connect to the queue in RabbitMQ using the same credentials as for the DMF API. See Authorization.
The credentials are provided via the Bosch IoT Suite portal, as part of the Access Credentials of your Bosch IoT Rollouts subscription.
Messages
UPDATE_ASSIGNMENT
A message of this topic is published to the queue when a distribution set is assigned to one or more targets, i.e. by manual assignment, auto-assignment or when a rollout group is executed.
This feature will have no effect when multi-assignment is enabled.
One message will be published per assignment even if the assignment involves multiple targets.
However, keep in mind that the published message can contain up to 1000 targets. Therefore, if a rollout group consists of more than 1000 targets, the event will be split into several messages.
When messages are not fetched right away, they will reside in the queue for 24 hours and will be deleted after that.
Properties
Header |
Description |
Type |
type |
Type of the message. |
TARGET_EVENT |
topic |
Topic name identifying the event. |
UPDATE_ASSIGNMENT |
tenant |
The tenant this target belongs to. |
<String> |
Message Properties |
Description |
Type |
content_type |
The content type of the payload |
application/json |
Payload template:
Message example:
Header |
type=TARGET_EVENT |
Message Properties |
content_type=application/json |
Payload |
System configuration
The SIE API can be enabled per tenant from the Bosch IoT Rollouts UI.
Open the System Configuration view and scroll down to the end.
In the Service section, open the APIs tab.
Check Service Integration Event (SIE) API enabled.
Save the configuration.
Constraints
This feature is currently available on region EU1 only.
This feature will have no effect when multi-assignment is enabled.