The purpose of the Service Integration Event API (hereinafter referred to as the SIE API) is to integrate external services and notify them of events occurring in Bosch IoT Rollouts.

The events published through this API are described below under Messages. As this list of events may be extended in the future, consumers are advised to ignore any 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 places to receive messages. Bindings determine how messages are delivered to them. Queues can also be bound to multiple exchanges.

Exchanges are for publishing messages. The user decides who can publish to the exchange and who can create bindings on it for delivery to a specific queue.

Exchange & Queue definition

Enabling the SIE API for a tenant automatically creates the necessary queues, exchanges, and bindings for the user. 

The queue name for receiving event messages from 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

(tick)

(error)

(error)

Queues

Queue

Use case

Durable

Exclusive

Auto-delete

Arguments

User permissions

sievent_queue

Receiving the assignment events 

(tick)

(error)

(error)

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

Properties

Header

Description

type

Type of the message.
Specifies the Rollouts component/entity affected by the event.

topic

Topic name identifying the event.
Specifies the use case with a unique String.

tenant

The tenant this target belongs to.

Message Properties

Description

content_type

The content type of the payload



TARGET_CREATED

A message for this topic is published to the queue when a new Target is registered.

Message example:

Header

type=TARGET_EVENT
topic=TARGET_CREATED
tenant=C3BA66FB-FE5F-44AB-835A-EF00436A1234

Message Properties

content_type=application/json

Payload

payload example

{
"controllerId": "test_device",
"updateStatus": "REGISTERED",
"timestamp": 1234567890123
}


TARGET_UPDATED

A message for this topic is published to the queue when an Existing Target changes.

Check out the possible Target Update Status


Message example:

Header

type=TARGET_EVENT
topic=TARGET_UPDATED
tenant=C3BA66FB-FE5F-44AB-835A-EF00436A1234

Message Properties

content_type=application/json

Payload

payload example

{
"controllerId": "test_device",
"updateStatus": "PENDING",
"timestamp": 1234567890123
}

TARGET_DELETED

The message for this topic is published to the queue when an existing Target is deleted.

Message example:

Header

type=TARGET_EVENT
topic=TARGET_DELETED
tenant=C3BA66FB-FE5F-44AB-835A-EF00436A1234

Message Properties

content_type=application/json

Payload

payload example

{
"controllerId": "test_device",
"updateStatus": "UNKNOWN",
"timestamp": 1234567890123
}


ACTION_CREATED

The message for this topic is published to the queue when a new Action has been created.

Message example:

Header

type=ACTION_EVENT
topic=ACTION_CREATED
tenant=C3BA66FB-FE5F-44AB-835A-EF00436A1234

Message Properties

content_type=application/json

Payload

payload example

{
"actionId": 99,
"actionStatus": "RUNNING",
"lastActionStatusCode": "N/A",
"actionActive": true,
"controllerId": "test_device",
"distributionSetName": "test_distro",
"distributionSetVersion": "1.0.0",
"timestamp": 1234567890123
}


ACTION_UPDATED

The message for this topic is published to the queue when the existing Action changes (i.e., intermediate status or final status).

Check out the possible Action Update Status.


Message example:

Header

type=ACTION_EVENT
topic=ACTION_UPDATED
tenant=C3BA66FB-FE5F-44AB-835A-EF00436A1234

Message Properties

content_type=application/json

Payload

payload example

{
"actionId": 99,
"actionStatus": "FINISHED",
"lastActionStatusCode": "200",
"actionActive": false,
"controllerId": "test_device",
"distributionSetName": "test_distro",
"distributionSetVersion": "1.0.0",
"timestamp": 1234567890123
}


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 multiple messages.

When messages are not fetched right away, they will reside in the queue for 24 hours and will be deleted after that.

Payload template:

{
"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, it will be "given".


System configuration

Enable/Disable Service Integration Event API

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

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

Configure Service Integration Event API supported Topics 

If the SIE API is enabled, all SIE API Topics are supported by default.

Temporary, until UI supports the configuration, SIE Enabled Topics could be configured only via the REST API