Automatically create things when a new device is registered

Bosch IoT Things supports the automatic creation of things and their policies for two scenarios:

• for edge or virtual devices, which communicate via a gateway,
• and for gateway or stand-alone devices, which use proper device certificates for authentication.

Both scenarios work in combination with Bosch IoT Hub, to enable automatic registration of a device, when it connects for the first time to the Bosch IoT Suite infrastructure.

As a subscription owner, you can configure the “Device via Bosch IoT Hub” connection to define which thing template should be applied, when automatically creating the thing.

The configuration can be enabled and customized either via the HTTP API or via the Things UI.

A - Edge or virtual devices behind a gateway

Edge or virtual devices that are managed behind a gateway and are automatically created in Bosch IoT Hub, can automatically create a thing and its policy using this functionality.

The Things service will create:

• a thing with the given device ID (received via the header device_id),
• a policy, using the function to copy the policy of the gateway,
• and an attribute named Info, which documents the gateway ID.

B - Gateway or stand-alone devices authenticating with proper device certificates

In case a device is not registered yet as a thing, and the event received does not contain a header with the “gateway-id”, Bosch IoT Things will assume you want to automatically create a thing and its policy based on the second template.

The Things service will create:

• a thing with the given device ID (received via the header device_id),
• and policy with default settings (like if you use the Device Provisioning API).

Supported placeholders for the thing template

The thing template supports header and solution placeholders as well as placeholder functions.

Header placeholders

{{ header: }}

This placeholder supports any external protocol header or Things header.

Examples

{{ header:correlation_id }}

{{ header:device_id }}

Solution placeholders

{{ solution:id }}

The ID of the solution that owns the connection.

{{ solution:service-instance-id }}

The service instance ID of the solution.

{{ solution:package-service-instance-id }}

The service instance ID of the package to which the solution belongs (i.e. the service instance ID without _things suffix).

Placeholder functions

fn:default(<string|placeholder> defaultValue)

This placeholder function will pass the defaultValue if the previous expression in a pipeline has been resolved to empty (e.g. due to a non-defined header placeholder key).

Another placeholder may be specified, which is resolved to a string and inserted as defaultValue.

Examples

{{ header:my-optional-header | fn:default('fallback') }}

{{ header:my-optional-header | fn:default("fallback") }}

{{ header:gatway-id | fn:substring-before(':') | fn:default(header:device-id) }}

fn:substring-before(<string> givenString)

This placeholder function will parse the result of the previous expression, then it will pass along only the characters before the first occurrence of the givenString.

If givenString is not contained, this function will resolve to empty.

Examples

{{ header:device-id | fn:substring-before(':') }}

{{ header:device-id | fn:substring-before(":") }}

{{ header:gateway-id | fn:substring-before(':') | fn:default(header:device-id) }}

fn:substring-after(<string> givenString)

This placeholder function will parse the result of the previous expression, then it will pass along only the characters after the first occurrence of givenString.

If givenString is not contained, this function will resolve to empty.

Examples

{{ header:device-id | fn:substring-after(':') }}

{{ header:device-id | fn:substring-after(":") }}

{{ header:gateway-id | fn:substring-after(':') | fn:default(header:device-id) }}

fn:lower()

This placeholder function makes the string result of the previous expression lowercase in total.

Examples

{{ header:device-id | fn:lower() }}

fn:upper()

This placeholder function makes the string result of the previous expression uppercase in total.

Examples

{{ header:device-id | fn:upper() }}

Enable and configure the template via Things UI

The default configuration for the “Device via Bosch IoT Hub” connection is active for both, edge devices behind an edge gateway and standalone devices with proper device certificates.

You can activate and deactivate the automatic creation for edge or virtual devices using the checkbox General > Enable automatic thing creation for edge or virtual devices via gateway.

The creation of gateway or stand-alone devices can be toggled using the checkbox General > Enable automatic thing creation for gateway or stand-alone devices.

To align with your use-case, you can also update the thing template inside the textbox below the respective checkbox.

Enable and configure the template via HTTP API

Find an example at HTTP API > Changelog for the HTTP API.

Find additional information on the ImplicitThingCreation mapper at Eclipse Ditto.

Example of all steps when using a Bosch IoT Suite package

Find an example at Bosch IoT Suite for Device Management > Device provisioning examples > Register a device automatically.