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
Exchange & Queue definition
Authentication & Authorization
Messages
System configuration
Constraints

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 x-message-ttl=86400000 //1day	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. Specifies the Rollouts component/entity affected by the event.	TARGET_EVENT
`topic`	Topic name identifying the event. Specifies the use case with a unique String.	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:

Click here to expand...

{
  "timestamp": long
  "softwareModules": [
    {
      "moduleId": long,
      "moduleType": String,
      "moduleVersion": String,
      "moduleName": String,
      "artifacts": [
        {
          "filename": String,
          "urls": {
            "COAP": String,
            "HTTP": String,
            "HTTPS": String
          },
          "hashes": {
            "md5": String,
            "sha1": String,
            "sha256": String
          },
          "size": long
        }
      ],
      "metadata": [
        {
          "key": String,
          "value": String
        }
      ]
    }
  ],
  "targets": [
    {
      "actionId": long,
      "controllerId": String,
      "targetSecurityToken": String,
      "type": String,
	  "confirmation": "String"
    }
  ]
}

Message example:

Header	type=TARGET_EVENT topic=UPDATE_ASSIGNMENT tenant=C3BA66FB-FE5F-44AB-835A-EF00436A1234
Message Properties	content_type=application/json
Payload	payload example `{` `"timestamp":` `1646928314964,` `"softwareModules": [` `{` `"moduleId":` `78,` `"moduleType":` `"application",` `"moduleVersion":` `"v1.0",` `"moduleName":` `"app",` `"artifacts": [` `{` `"filename":` `"simple_artifact.json",` `"hashes": {` `"sha1":` `"f0fd770816e8e479ca8ea703995a866be4798b58",` `"md5":` `"eaf6af2f1784fdff24b4d123aad4ef56",` `"sha256":` `"635626945ae8e25aa491267fe5b1b0f3661cf2801e4a53f77084cf77dfa57893"` `},` `"size":` `16,` `"urls": {` `"HTTP":` `"http://link-to-cdn/TENANT/example"` `}` `}` `],` `"metadata": [` `{` `"key":` `"key1",` `"value":` `"value1"` `},` `{` `"key":` `"key2",` `"value":` `"value2"` `}` `]` `}` `],` `"targets": [` `{` `"actionId":` `3,` `"controllerId":` `"device01",` `"securityToken":` `"504a291d05869fdda709ebbe83ded429",` `"type":` `"forced",` `"confirmation":` `"not_applicable"` `},` `{` `"actionId":` `4,` `"controllerId":` `"device02",` `"securityToken":` `"818904fe66ff9c1b4ac3b4ceacdfe15e",` `"type":` `"forced",` `"confirmation":` `"not_applicable"` `}` `]` `}` If the User Consent Flow feature has been enabled for the tenant, the `confirmation` value will be "`pending`" while the action state is WAIT_FOR_CONFIRMATION and once confirmed by the user, will be `"given"`.

System configuration

The SIE API can be enabled per tenant from the Bosch IoT Rollouts UI.

Open the Configuration view and scroll down to the end.
In the Configuration section, open the AMQP Configuration tab.
Check Service Integration Event (SIE) API enabled.
Verify / change the configuration.

images/confluence/download/attachments/2165582446/image-2024-10-31_17-16-52-version-1-modificationdate-1730387812000-api-v2.png

Constraints

This feature is currently available on region EU1 only.

This feature will have no effect when multi-assignment is enabled.