Bosch IoT Insights: Things History Improvements and Breaking Changes

Bosch IoT Insights is preparing a service update with improvements and breaking changes in the next two weeks.
We would like to inform you in advance about an upcoming update of our feature to track  the change history of a device in Bosch IoT Things.

The Thing History feature tracks modifications on devices over time:

Projects can enable the tracking in the device type configuration:

• Per information block
  
• Per defined property
  

The currently planned update will increase effectiveness and performance, incorporating the knowledge built up over three years of operating and supporting projects using it:

• Enforcement of the “Tracking activated” configuration of device type properties
• Reduction of unused fields and optimized storage usage
• Reduction of database load by uniting commands and redesigning indexes

Most of the improvements where possible without big changes on the data model or the UI. All those changes are located in the Thing History collection. You may observe it in query templates or the REST API if you use the Thing History collection. It also can affect processing pipelines, that use the Thing History collection directly.

The changes in detail

• No tracking of devices, that do not have a device type name in their thing ID or were the device type does not exist.
  Examples:
  ✔️ Thing ID namespace:devicetype_deviceid makes tracking possible.
  ❌ namespace:deviceid or namespace:nonexistingtype_deviceid cannot be tracked.
• Only information blocks and properties are actually inserted to the thing history, which explicitly are marked “to be tracked”. In the past “not defined” properties were also tracked.
• The history entries, which include all snapshots of all the child entries (device tree), do need more time to appear. This happens, because incorporating history events of related devices into the timeline of their parent is deferred. This delay allows to react better on inter-service message exchange latencies between Bosch IoT Things and Bosch IoT Insights and finally improves data quality.
• Existing history collection of free plans and projects, which have not make use of the history feature yet, are cleared.

The thing history entry structure also changes:

• Newly introduced fields:
  • validityBegin – contains the time, when the change happened in real world. I.e. entries can be backdated, if these differ.
  • hasSnapshot– replaces status, see migration instructions below
  • deviceTreeBuilt– replaces status, see migration instructions below
• Modified fields:
  • revision – converted to an array, was a single value field before.
  • change – converted to an array, was a single value field before.
  • snapshots – contains the snapshot of the current device at index position 0 now. Simplifies accessing the actual thing data of that entry.
  • createdAt – contains the time, when the change in Bosch IoT Things actually has happened technically (and the new field, validityBegin contains the time, when the change happened in real world. I.e. entries can be backdated, if these differ.
• Removed fields: trigger, status, deviceTree, user, untracked, errorInfo, snapshots.deviceType

Migration guide:

• status – replaced by hasSnapshot and deviceTreeBuilt
  • hasSnapshot – false, when the entry just includes the change received. Changes to true, when this entry has its snapshots field set with its things content. I.e., the predecessor event could be found, had its snapshot included, and this change could be applied to it. This field supports having a database index for entries in both states, because snapshots alone, which is an array field, cannot be used that way in an index. Indexes are important to optimize queries against the database.
  • deviceTreeBuilt – false, when the entry has not been processed for propagation to its parent entries. True, if the processing has happened and all the entry propagation has been done. Similar to hasSnapshot, the new field allows for improved indexing and reduction of load in the database.
• deviceTree – which device is a child of which other device is available in snapshots.features.deviceLinks.properties.parentId
• user – is available in the change.user
• snapshots.deviceType – is available in snaphots.attributes.type

In case you have any questions, please use our Customer Support System or contact us.