Claiming

A claiming process may enable an end-user to claim Things and proof ownership thereof. Such a process is initially triggered via a claim message. This message can be sent to the Things service with the REST-like HTTP API or the things-client.

The following figure sketches such a workflow.

claiming

Claim a Thing at the REST API

An authenticated user [1] starts the claiming process by sending a (blocking) claim message [2a] to the Thing he wants to claim with the REST API. The message defines a timeout during which the request must be completed, and may carry additional custom payload.

tip The payload of the message is specified by the solution to implement a custom process using the Integration Client API.
The Bosch IoT Things service is only responsible for routing the message to the things-client [2b] which operates the Thing to be claimed.
Find details regarding the claim message at Events and Messages resources.

The Solution interprets [3] and reacts respectively upon the received claim message.
When the communication with the device terminates successfully, e.g. the user pushes the correct button sequence on the device, the Solution updates the ACL [4] of the Thing and replies to the message [5a].
The response may contain a custom payload and a HTTP status code. The message is routed back to the REST API and completes the request [5b] with the specified status code and payload.
If the request is not handled in time, the Things service completes the request with a timeout.

Example

Our example provided on GitHub at RegisterForClaimMessages.java encapsulates within just one class the most simple way to simulate the device integration side for such a claiming process. The business implementation can be simulated by using the UI for trying out our REST-like API.

  1. Run RegisterForClaimMessages.registerForClaimMessagesToSingleThing() from within the ExampleLauncher class locally. This will create a Thing and log it’s ID.

  2. The example assumes that you have already a Solution registered with our service (for the API Token) and a User to authenticate [1] at the REST-like API.

  3. Trigger a claim message [2a] (e.g. via HTTP API > Messages resource > POST /things/{thingId}/inbox/claim)

    1. Copy the Thing ID logged in the previous step.
    2. The default timeout would be 60 seconds, however, you can set it up to 600 seconds.
    3. The payload field is not necessary, as the consumer (i.e. RegisterForClaimMessages.java) does not expect any payload.
    4. Try it out.
  4. The RegisterForClaimMessages handles the message (see code line 92) (In the figure above these would be [3], [4] and [5a].)

  5. Upon success the message “Thing ‘{}’ claimed from authorization subject ‘{}’” will be logged. From now on, the user should have permission to interact with “his” Thing.

Imprint Legal info Privacy statement