Bosch IoT Device Management

Trigger de-provisioning via a live message

This example assumes that you need to delete a thing via a live message.

We recommend using the Device Provisioning API, because the de-provisioning not only deletes the thing but also its associated policy and the entities existing in Bosch IoT Hub (namely the device and its credentials).

In this example, we will create a managed connection and configure it to react on a live message to a thing, by triggering its de-provisioning via the Device Provisioning API.

Connection setup

The connection wizard of the Connections UI assists the creation of such a connection.

  1. Click Add to create a new connection.

  2. Choose the template and name

    1. Select the connection category HTTP: Template for de-provisioning via Device Provisioning API.

      images/confluence/download/attachments/2006069139/add-connection-de-provisioning.png
    2. Add a Connection name as you like, e.g. Remove things

    3. Click Continue.

  3. The second wizard page requires the following inputs:

    1. Authorization subject - to define who can use this connection to receive the live messages which trigger the de-provisioning.
      The subject is pre-filled with integration:<service-instance-id>_things: , thus you only need to add a suffix.
      In general, this subject additionally needs to be set into the policy of the things.
      In our example, we set the suffix to remove and add the complete subject later to the thing's policy.

    2. The Message subject: the subject of the message which triggers the de-provisioning.
      In our example we have set remove.

    3. The Service Instance ID is already prefilled with the value for your subscription.

      images/confluence/download/attachments/2006069139/add-connection-de-provisioning-2.png
    4. Click Continue.

  4. The third wizard page requires the OAuth2 client credentials.
    These credentials are used to get an access token, which is required to make the de-provisioning request to the Device Provisioning API.
    See Create a Suite Auth client in case you have not configured one yet.

    1. The OAuth Token Endpoint is pre-filled to the default value.

    2. Set the Client ID as configured for your client.

    3. Set the Client secret as configured for your client.

    4. The Requested scopes are pre-filled to hub and things.

    5. Click Continue.
      images/confluence/download/attachments/2006069139/add-connection-de-provisioning-3.png

  5. Click Test connection.

  6. Confirm creating the connection with Create.
    images/confluence/download/attachments/2006069139/add-connection-de-provisioning-4.png

The created connection is an HTTP connection which configures the Device Provisioning API as an endpoint with the given OAuth2 client credentials.

It contains a single target that is configured to trigger a DELETE request at the resource
/{service-instance-id}/devices/{device-id}, whenever it receives a live message with the specific subject.

The HTTP response received from the Device Provisioning API will be forwarded as the live message response including its response status and body.

The wizard creates a pre-configured connection, but you can of course adjust the connection to your needs before saving it, e.g. change the message subject that triggers the de-provisioning.

Adjust the policy

Use the Policy section of the thing which is to be deleted and create a separate entry for the Subject of the connection created above.

The example shows the permission to read and write messages with subject "remove" directed to the thing (i.e. inbox) as well as from the thing (i.e. outbox).
However, you would only need one line, depending on the Direction you choose in the next section, where you send the message, which will in fact be used as the trigger for the de-provisioning request.

images/confluence/download/attachments/2006069139/connection-authorization-in-policy.png

Trigger the de-provisioning

The de-provisioning is triggered by sending a live message with the configured subject to the thing that should be deleted, together with its associated policy and the entities stored in Bosch IoT Hub (device and its credentials).

This can be achieved by making a POST request to the messages resource of a thing at the Things HTTP API:
/things/{thingId}/inbox/messages/{messageSubject}, where

  • {thingId} must be replaced with the ID of the thing that should be deleted, and

  • {messageSubject} must be replaced with the configured live message subject.

The request body is not used and can be left empty.

images/confluence/download/attachments/2006069139/remove-message.png

The live messages can also be sent via another channel e.g. WebSocket or a different connection.

Result

The message is routed to the "Remove things" connection, which you have created in the first section.

From there, the DELETE request at the Device Provisioning API is triggered, according to the specific subject.

Upon success, the thing and all its associated entities (policy, device, device credentials) are deleted.