Migrating from Release 3.8 to 3.9

Simplified labels for devices by removing the key and keeping only value

Usage Example

Before After

Before this change, device labels were key value pairs. Every key could be assigned once per device:

{
  {
    "id": "manufacturer:nke",
    "key": "manufacturer",
    "value": "nke"
  },
  {
    "id": "measurement:temperature",
    "key": "measurement",
    "value": "temperature"
  },
  {
    "id": "location:office",
    "key": "location",
    "value": "office"
  }
}

CODE

With version 3.8 and later, labels are simple strings, more akin to tags:

{
  "nke",
  "temperature",
  "office"
}

CODE

Migration of Existing Data

Existing labels are migrated to the new schema by concatenating key and value with an underscore:

Required Actions

Consumers of the REST-API need to adapt their data model as described above.
Queries to the REST API which use query parameters to filter by device labels need to be adapted to use the new style of labels.

Added Endpoints for Easily Creating/Updating/Deleting Labels on a Device

Usage Example

	Before / From	After / To
Usage Example	Up to version 3.7, labels were managed using the API endpoint for the device which they label: `PUT /api/v3/devices/:device-id { "labels": [ { "key": "X", "value": "Y" }, { "key": "A", "value": "B" ] }` CODE	Starting with version 3.8, labels are managed with dedicated endpoints using the CRUD pattern. E.g. labels are created with the verb POST to the resource /api/v3/device/:id/labels: `POST /api/v3/devices/:device-id/labels?labels=foo,bar` CODE Retrieving labels `GET /api/v3/devices/:device-id/labels` CODE Deleting a label: `DELETE /api/v3/devices/:device-id/labels/:label-id` CODE

Data Migration

N/A

Required Actions

Consumers of the REST API need to be migrated to the new interface.

Added Selectors for Integrations That Will Match Devices Labels

	Before / From	After / To
Usage Example	Previously, device selection happened by an integration's label. `{ "labels": [ { "key": "foo", "value": "bar" }, { "key": "myxl", "value": "plyx" } ], ... }` CODE	From 3.6 on device selection happens by dedicated selectors. As of now, only logical disjunction (with `$or` is supported). `{ "selectors": { "$or": [ "foo_bar", "myxl_plyx", ] }, ... }` CODE

Data Migration

N/A

Required Actions

Consumers of the REST API need to be migrated to the new interface.

Disabled Public Endpoints for Device Information and Device Activation

To the best of our knowledge, this API has not been in use.

Required Actions

Adapt consumers of the REST API to manually create devices.

Migrating from Release 3.7 to 3.8

Device ID are now unique strings instead of integers

Valid IDs have a maximum length of 63 characters and may contain alphanumeric characters and dashes.

	Before / From	After / To
Usage Example	Before 3.6, devices used numerical IDs. `{ "id": 4, ... }` CODE	Starting with 3.7, devices use strings as IDs. `{ "id": "device-4", ... }` CODE

Data Migration

Existing devices IDs are converted to IDs of the pattern device-<int>, e.g. the numeric ID 4 of a device is transformed to the string device-4.
Device created through auto-activation will get an ID of the pattern <network-server-id>-<network-device-id>-<unique-int>, where the network server ID is the thingsHub's ID of the network server and the network device ID is the network server's device ID. A unique integer is appended to ensure collision cannot happen.

Required Actions

Consumers of the REST API need to be migrated to the new interface.
User-created Queries to the time series database, e.g in the visualizer, which reference devices by ID need to be modified to use the new device ID schema.

Disabled Public Endpoints for Device Information and Device Activation

To the best of our knowledge, this API has not been in use.

Required Actions

Adapt consumers of the REST API to manually create devices.