Manage a policy via Things HTTP API
In general, the digital twin layer regards the policy as something that will change very seldom.
The policy document describes who is allowed to see and/or manipulate a device, or only parts of it.
For example, think about a machine sending errors, and you need to invite the repair service to read some parts, e.g. only the attributes.
Goal
Let us assume, your hello world thing needs a new policy entry called REPAIRSERVICE.
Procedure
Your entry point is again the Bosch IoT Things - HTTP API.
Authenticate
In order to use the Things HTTP API, you will need to authenticate. In this example we authenticate with a bearer token, using the client created in Provisioning via Device Provisioning API.
Close the pop-up.
Retrieve a specific policy
This request simulates how your business application - in admin or support view - might request for the current policy, e.g. if a customer complains, that his device "does not work properly".
Navigate to Policies > GET /policies/{policyId}.
Set the policyId - in our example it is example.dm:hello-world-device-01.
The other fields are optional and will stay empty for now.
Click Execute.
The response is the complete policy, which is by default structured in the sections DEVICE, DEFAULT, DEVICE-MANAGEMENT and maybe CUSTOMER .
A section REPAIRSERVICE has not bee created yet, so you need to create it with a next request.
Create or update a specific property of a feature
This request simulates how your business application - admin or support view - might change the policy to give the REPAIRSERVICE access to the attributes where the location is stored.
Navigate to Policies > PUT /policies/{policyId}/entries/{label}.
Click Try it out.
Set the policyId - in our example example.dm:hello-world-device-01.
Set the label - in our example REPAIRSERVICE.
The other fields are optional and will stay empty for now.
Set the request body - in our example:
{"subjects": {"bosch:x-x-x-bosch-ID-xxx": {"type":"bosch-id"}},"resources": {"thing:/attributes/manufacturer/": {"grant": ["READ"],"revoke": []}}}Click Execute.
The response is 201, meaning the policy was successfully modified.
Result
The repair service is now allowed to see the manufacturer attributes of the device.
Check your work
You can either use the Bosch IoT Suite Console to see if the policy is changed, or you can request again the policy using the HTTP API.
In case you have entered a valid subject, you can also log with that ID and should be able to see the attributes.
Such a request simulates how your repair service might try to read the device data.
A GET things request in the context of the repair service would respond only with the Thing ID and the location value.
Since the user is not allowed to see the features path, the GET things request would not reveal the resources "thing:/features/" and also hide the other sets of attributes except the manufacturer.
The same applies in case the thing will have more attributes or features in the future: the repair service user can not see them, but only those specified in the policy.