Sometimes you realise that Item and Group names make little sense, or that you want those Item and Group names to follow a strict naming convention.
A typical example is when you created many items from a Thing through the UI by bulk creating new items for selected channels. Sometimes the item names make little sense or you realise that an essential part of the channel name is not conveyed in the automatically generated Item name. This can result in item naming collisions (e.g., the
OneCallAPI from the OpenWeatherMap binding doesn’t distinguish the current and forecast items, hence those names may collide. Or you have a
...Windspeed item, a
Wind_Speed item and a
...WindSpeed item that you want to refactor into a
...WindSpeed naming pattern…
If you have lots of items and groups in the item registry for which you set up InfluxDB persistence, and if you’re running openHAB 3 on a Unix-like OS, then the following instructions may be helpful.
These instructions may even lead to the creation of ‘integrated’ openHAB item and group refactorings… in a future version of openHAB.
Important warning: Please back up your system before attempting any of the following operations. They can ruin your openHAB setup and cripple your persisted data if not done carefully.
With the introduction of openHAB 3, virtually all configurations are stored in JSON format. On openhabian, these configuration database files reside in
Instead of tediously renaming by hand all items and groups, you can apply search-and-replace directly to the JSON storage.
The basic idea is: we want to change the name of an Item (or Group) from
Important warning: If you defined custom widgets that access the item registry by assembling item names (e.g., a shared item name prefix + specific suffix parts that specify the actual item, as in the OpenWeatherMap binding), then you may have to repeat your pattern search with smaller item name fragments. Failing to do so may (temporarily) break your custom widgets until you update the item and group names in the affected widgets.
- The same is true for rules. Rules created from the MainUI are also stored in the JSON storage. Rules written in Python / Jython are stored in
$OPENHAB_CONF/automation/jsr223/python/personal/. In case you rely on node-RED on openhabian, you’ll find your flows in
- If you defined your persistence strategies in
.persistfiles, then you may also want to add those to the locations (default:
- If you defined file-based sitemaps, then you may also want to add those to the locations (default:
Important warning: it is wise to stop openHAB prior to renaming the items:
$ sudo service openhab stop
Step 1. Locate the JSON storage
$ cd $OPENHAB_USERDATA/jsondb $ ls -l
The 2nd command will list all files in the JSON storage. The item registry is stored in
org.openhab.core.items.Item.json, item metadata are stored in
org.openhab.core.items.Metadata.json etc. You’ll notice that all your page layouts and custom widgets are also stored in the JSON DB. This means that you can effectively rename items throughout the JSON database when done properly.
Step 2. Log in as
Switch to the
openhab user. This way, we don’t run into file ownership and file permission problems. These can be fixed later on (
openhab-cli reset-ownership) but this adds avoidable wear to your flash memory based storage:
$ sudo -u openhab bash
Step 3. Identify all occurrences of
oldName in the JSON storage
$ grep 'oldName' *json
This command yields a list of all occurrences of
oldName in the JSON storage.
Important warning: please triple-check this list of matching results to ensure that you don’t accidentally have false positive hits (e.g., other items or groups containing “
oldName”, or other parameters not related to
Step 4. Rename the items via the command line
$ for f in *json ; do sed -i 's/oldName/newName/g' "$f" ; done
(In case you want to add your Jython rules and your node-RED flows in the substitution, you may want to add these paths in steps 3 and 4.)
With this command, we will perform inline substitution of
newName for all occurrences of the pattern
oldName in each JSON file.
Note the use of single quotes enclosing the search-and-replace pattern (
's/oldName/newName/g') and double quotes for enclosing the resulting files matching the
*jsonglob pattern (
On the UNIX command prompt, the command shell will not expand environment variables (preceded with a ‘
$’ sign) in arguments enclosed with single quotes. The opposite is true when using double quotes.
You may however decide to use double quotes on the search-and-replace pattern, e.g. if you want to iterate over a list of patterns, but in that case maybe you would rather apply multiple inline substitutions at once. How you should do this, depends on your Unix flavour. On openhabian you can use:
$ sed -i -e 'pattern1' -e 'pattern2' -e 'pattern3' "$f"
Once all items and groups you wanted renamed have been processed in the JSON storage, you may restart openHAB. If you’re still logged in as the
openhab user, then you can now log out. Then issue the following command:
$ sudo service openhab start
I strongly recommend running a log monitor (
openhab-cli showlogs) in another terminal window to check if all updates in the JSON have been properly processed.
Step 5: Access the InfluxDB database instance
Now it is time to interact with the InfluxDB command-line tool. Log in to your InfluxDB instance with credentials with sufficient privileges (e.g.,
admin) on the database where openHAB persists its state. On my setup, this database is named
$ influx -username admin -password '' password: Connected to http://localhost:8086 version 1.8.6 InfluxDB shell version: 1.8.6
Now you can interact with the InfluxDB instance. Let’s first select the database where openHAB persists its state:
> USE openhab_db Using database openhab_db
By default, openHAB persists Item and Group states in InfluxDB measurements that have exactly the same name as the persisted item or group. The measurements are case-sensitive.
You can retrieve a list of all measurements with the following command:
> SHOW MEASUREMENTS
When you have many persisted items and groups, you may want to return only measurements matching a specific name pattern. Fortunately, InfluxDB supports a (limited) set of regular expression patterns. For instance:
> SHOW MEASUREMENTS WITH MEASUREMENT =~ /OneCall.*Icon/
This pattern search will match patterns containing
OneCall followed by 0 or more unspecified characters, followed by
Icon. Note that this pattern is case-sensitive.
Step 6: Rename the persisted measurements
We can safely merge all persisted states of
oldName into the new
newName measurement with the following command:
> SELECT * INTO newName FROM oldName GROUP BY *
A summary of the number of entries merged in the new measurement will be provided. If all went well, you can now drop the old measurement:
> DROP MEASUREMENT oldName
Step 7: exit the InfluxDB client
When all measurements relating to renamed items and groups have been processed, you can exit the InfluxDB client:
If you’ve been meticulous and with some you should now have a fully functional openHAB environment with renamed items and groups as desired.