Upgrade to 7.0 [ Mandatory ]
This guide outlines the process for upgrading your ThingsHub installation to version 7.0
Following the Upgrade Path
For a seamless upgrade, consult the Upgrade thingsHub document to determine the exact sequence required for your current version. Look for "mandatory" in the page title to identify essential steps in the upgrade path. These mandatory upgrades ensure compatibility and prepare your system for the final upgrade to 7.0.x.
What's New?
Before upgrading, be sure to do the following:
Review the What's New page for details on new features and functionalities introduced in version 7.0.x. Additionally, the Breaking Changes page highlights any significant changes that might impact your existing setup.
The Pre Upgrade Migration & Post Upgrade Migration will guide you through the essential migrations that need to be done before and after the upgrade to thingsHub 7.
Upgrading from Previous Versions
Direct upgrades to thingsHub 7.0 can be done if you are using any thingsHub version 6.0.latest+.
If you're using an older version, an upgrade to version 6.0.latest is recommended before you upgrade to thingsHub 7.0.x.
Before You Begin
Make sure to read the What's New for the release 7.0.x.
Checkout the Breaking Changes page to see if this version has any major breaking changes.
Make sure the thingsHub Installation to be upgraded is in the version 6.0.latest+.
Make sure all the Prerequisites have been setup.
Make sure you go thoroughly through the mentioned Migration Guides. These are mandatory.
Prerequisites
This section lists all the new prerequisites that need to be setup before doing the upgrade.
Business Objects Configuration:
ThingsHub 7.0 introduces Business Objects, which represent key data entities that reflect various aspects of your business operations. This allows users to create and manage custom fields for Assets.
Please ensure you understand the Business Objects concept before upgrading, as it affects how Assets are managed. Refer to the Business Objects documentation for detailed information.
API Compatibility:
Starting with version 7.0.x, all v3/assets and v3/tracked-assets endpoints have been deprecated and replaced with unified v4/assets endpoints. Ensure that any existing integrations or custom applications are prepared for this change.
Determine which version to upgrade to
This section shows how you can list all the available patch versions available for this thingsHub version i.e. 7.0. You can select the patch version you want to upgrade your thingsHub Installation to. We recommend using the latest available patch version to not miss out on any bug fixes and security patches.
#!/bin/bash
helm3 repo add smartmakers http://helm.smartmakers.de
helm3 repo update
helm3 search repo smartmakers/th-tenant --version 7.0 --versions
Pre Upgrade Migration
ThingsHub operators upgrading to thingsHub 7.0.x must complete pre-upgrade preparations to ensure compatibility with the new Business Objects and unified Assets inventory. Please consult the following preparation steps:
API Integration Assessment:
Review all existing API integrations using v3/assets endpoints
Identify usage of v3/tracked-assets endpoints
Document current asset import processes using v3/assets-import
Prepare for migration to v4/assets endpoints
For detailed information about all breaking changes in version 7.0, please refer to the Breaking Changes documentation.
Update Tenant Configuration
This section outlines all the changes that you need to make and that are available in the tenant configuration file. These changes encompass incremental changes required from thingsHub 6.0.x.
For thingsHub 7.0, there are no tenant configuration changes required. Your existing tenant configuration from version 6.0.x will continue to work without modifications.
Backup Databases
Before applying the upgrade, back up all your data from both the time-series database and the relational database. This section explains how you can backup and restore your databases.
Postgres
#!/bin/bash
# backup:
pg_dump -U <your-user> -h <address-to-your-db> -p <port> --database <your-database> --no-owner --format=t --verbose >sql.dmp
# restore:
pg_restore -d <database> -h <address-to-your-db> -p <port> -U <your-user> --no-owner --role=<your-user> sql.dmpInfluxDB
Make sure that influxdb is port-forwarded to port 8086 in the system where you're running the shell commands.
#!/bin/bash
# backup:
influxd backup -portable -db things_hub ./influxdata/
# restore:
influxd restore -portable -db things_hub ./influxdata/If you have set up any other backing-up mechanisms in your infrastructure, you can leverage that as well for the backups in place of the one mentioned above.
Apply the Upgrade
After setting up everything, we can proceed to upgrade the thingsHub Installation.
#!/bin/bash
helm3 repo update
helm3 upgrade <your-thingshub-installation> --namespace <your-thingshub-namespace> smartmakers/th-tenant --version 7.0.0 -f <tenant_configuration.yaml> --atomicPost Upgrade Steps
API Integration Updates
After completing the upgrade, all API integrations must be updated to use the new v4 endpoints:
Assets CRUD Operations: Update from v3/assets to v4/assets endpoints
Assets Listing: Update query parameters (query → search, remove sort_by/sort_dir)
Asset Import: Update from v3/assets-import to v4/assets-import
Asset Binding: Update from v3/tracked-assets to v4/assets/{id}/bind and v4/assets/{id}/unbind
Business Objects Setup: Configure custom fields as required for your business operations.
Post Upgrade Testing
We recommend doing smoke testing on your thingsHub Installation after the upgrade to ensure that the system is functioning smoothly.
Based on your use case, we recommend verifying the functionality of assets management, custom fields via Business Objects, v4 API integrations, asset import/export using v4/assets-import, asset binding/unbinding, incoming device data flow, external integrations, asset dashboards, and tracked asset position updates as part of your upgrade to ThingsHub 7.0.