Bosch IoT Insights

Creating a device via API

You can create a device via the Bosch IoT Insights API. As the created device will only have the limited default policy, this chapter also shows how to adjust the policy to grant other users access of the device.

Determining the namespace and the default policy

The thing's namespace of your project needs to be determined.

Proceed as follows

  1. Open the Project Management Service API.

  2. Open Projects: Access, configure and bootstrap projects.
    → A list of requests is displayed.

  3. Open the GET /v1/projects/{project}/thingsConfig request.

    1. In the Parameters pane, enter the project name in the project field.

  4. Click the Try it out! button to determine the namespace.
    → The namespace is displayed in the namespace field (e.g. <test_project>) and the default policy in the defaultPolicyId field (e.g. <test_project:default>).

    If you already have a device, you can use the device's thing ID to determine the namespace. The thing ID is prefixed with the project namespace, e.g. <test_project:test-type_test-device>.

Creating a device type

If you want to use a device type for your device, you can create a device type beforehand, refer to Creating a device type via API.

Creating a device

Before you create a new device, the thing ID needs to be composed.

The thing ID consists of the following parts:

  • Project's namespace, e.g. <test_project>

  • Device type created in Creating a device type via API, e.g. <test_type>

  • Name of the device to be created, e.g. <test_device>

The thing ID would look like this: <test_project:test-type_test-device>.

The device can now be created in the Bosch IoT Insights Swagger UI.

Proceed as follows

  1. Open the Service API: IoT Things.

  2. Open Things: Manage every thing.
    → A list of requests is displayed.

  3. Open the PUT /iot-things-api/{project}/2/things/{thingId} request.

    1. In the Parameters pane, enter the project name in the project field.

    2. In the thingId field, enter the thing ID as composed above.

    3. In the body box, enter the data for the device as follows and replace the values with your project-specific values:

      {
      "attributes":{
      "type":"test-type"
      },
      "features":{
      "general":{
      "definition":[
      "insights:general:1"
      ],
      "properties":{
      "test-property":1,
      "name":"test-device"
      }
      }
      }
      }

      It is necessary to provide the created device type in the type attribute to associate the device with the device type.

      The test-property will be added to General information block. To not display the thing ID in the Bosch IoT Insights UI, provide the device name in the general feature block under properties.

  4. Click the Try it out! button to create the device.

Updating the device policy

The device was created with a very limited policy that only grants rights for the user or the technical client that was used for the creation. The entire policy of your device needs to be updated to be compliant with Bosch IoT Insights.

As a first step, check the policy that was initially created.

Proceed as follows

  1. Open the GET /iot-things-api/{project}/2/things/{thingId} request.

    1. In the Parameters pane, enter the project name in the project field.

    2. In the thingId field, enter the thing ID.

    3. In the fields field, enter the _policy value.

      This parameter will adjust the policy to the result of your request.

  2. Click the Try it out! button to display the policy with one subject.

    The subject is either a user or a technical client depending on how you were authorized when creating the device.

  3. Check the policy ID in the result.

    The policy ID should be the same as the device ID/thing ID.

To update the policy, the default policy of the project can be used as a template and adjusted accordingly.

Proceed as follows

  1. To inspect the default policy, open Policies: Control access to your things.

  2. Open the GET /iot-things-api/{project}/2/policies/{policyId} request.

    1. In the Parameters pane, enter the project name in the project field.

    2. In the policyId field, enter the default policy ID.

  3. Click the Try it out! button to display the default policy of your project.
    → The default policy is displayed.

    {
    "policyId": "test_project:default",
    "entries": {
    "manage": {
    "subjects": {
    "iot-suite:/ext-iam.insights.test-project.power_user": {
    "type": "iot-insights-role"
    },
    "iot-suite:/ext-iam.insights.test-project.manager": {
    "type": "iot-insights-role"
    },
    "iot-suite:/ext-iam.insights.test-project.admin": {
    "type": "iot-insights-role"
    },
    "iot-suite:/ext-iam.insights.admin": {
    "type": "iot-insights-role"
    },
    "iot-suite:/service-instance.11111111-2222-3333-4444-555555555555.iot-things@66666666-7777-8888-9999-000000000000": {
    "type": "creator"
    }
    },
    "resources": {
    "thing:/": {
    "grant": [
    "READ",
    "WRITE"
    ],
    "revoke": []
    },
    "policy:/": {
    "grant": [
    "READ",
    "WRITE"
    ],
    "revoke": []
    },
    "message:/": {
    "grant": [
    "READ",
    "WRITE"
    ],
    "revoke": []
    }
    }
    },
    "see": {
    "subjects": {
    "iot-suite:/ext-iam.insights.things_monitoring": {
    "type": "iot-insights-role"
    }
    },
    "resources": {
    "thing:/": {
    "grant": [
    "READ"
    ],
    "revoke": []
    }
    }
    }
    }
    }

  4. Use the default policy to adjust the policy to your own needs.

  5. Remove the policyId entry and enter the policy ID of the device, e.g. <test_project:test-type_test-device>.

  6. Open the PUT /iot-things-api/{project}/2/policies/{policyId} request.

    1. In the Parameters pane, enter the project name in the project field.

    2. In the policyId field, enter the policy ID as mentioned in step 5.

  7. Click the Try it out! button to update the policy of the device.
    → The device policy is updated.