Appearance

EU
US

Service Integration Event API ​

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.

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 ​

ExchangeUse caseQueue bindingTypeDurableAuto-deleteUser permissions
sievent.exchangeSend assignment events to a clientsievent_queueFanout✅❌❌

Queues ​

QueueUse caseDurableExclusiveAuto-deleteArgumentsUser permissions
sievent_queueReceiving 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 ​

Properties ​

HeaderDescription
typeType of the message.
Specifies the Rollouts component/entity affected by the event.
topicTopic name identifying the event.
Specifies the use case with a unique String.
tenantThe tenant this target belongs to.
Message PropertiesDescription
content_typeThe 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
json
{
"controllerId": "test_device",
"updateStatus": "REGISTERED",
"timestamp": 1234567890123
}

TARGET_UPDATED ​

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

TIP

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
json
{
"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
json
{
"controllerId": "test_device",
"updateStatus": "UNKNOWN",
"timestamp": 1234567890123
}

TARGET_POLL_UPDATED ​

Fires when one or more targets poll the server (via DDI or DMF). A single event may contain multiple controller IDs if polls are batched.

Header

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

Message Properties

content_type=application/json

Payload

payload example
json
  {
    "controllerIds": ["device-001", "device-002"],
    "lastPollTime": 1711540800000,
    "timestamp": 1711540800123
  }

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
json
{
"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).

TIP

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
json
{
"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.

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: ​

Click here to expand...
json
{
  "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
json
{
    "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"
          }
    ]
}

NOTE

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.

AMQP Configuration tab with the SIE API toggle

Configure Service Integration Event API supported Topics ​

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

WARNING

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

Swagger UI request to change the SIE enabled topics of a tenant