[OH3] Rule and map file name requirements

After migrating from OH2.x to OH3 I ran into issues with my rule and map files. Obviously, there are specific file name restrictions in OH3, which did not exist in previous versions.

My rule files were named like this:

  • home.light.rules
  • home.weather.rules
  • home.sonoff.rules
  • home.<…>.rules

It seems like the name before the first dot (home) is used as namespace, while the rest of the file name is ignored. This leads to rules being overwritten. In the OH UI/Settings/rules section you could only see a subset of the rules, named “home-<rule#>”. However it seems like for each rule file, the rules started with the same name, thus overwriting rules from other files.

Map files have kind of a similar problem. In my OH2.x config I had map files without the .map extension (I know, this is not quite nice naming, but it worked). Now with OH3, map files seem to require the .map extension. Otherwise you would get errors like this:

[rg.apache.cxf.jaxrs.utils.JAXRSUtils] - Problem with writing the data, class org.openhab.core.io.rest.Stream2JSONInputStream, ContentType: application/json

Are there any other changes with regards to file name requirements? Might be worth documenting for beginners.


It’s not really clear exactly what you are describing but it has always been required that each rule must have a unique name regardless of which files they are defined in and regardless of the file’s name. If it worked for you in the past, it only worked because you found some bug that apparently got fixed. The name of the file has never really had any impact on the stuff defined inside it, so long as it ends in .rules.

Well, the docs already state:

  • <RULE_NAME> - Each rule must have a unique name (given within quotes). It is recommended that you choose a name that has meaning when spoken.

For the map transformation, that might be something good to add to the docs. There is a link at the bottom of the page that will take you to where you can update the docs in a way that you think will be more clear.

I think it has always been assumed that the map files require the .map extension. All of the examples certainly included it. And it would make sense to explicitly state it.

There very well may be. but I doubt anyone has a list to produce a document.

I think the issue is that filenames with multiple dots
are not handled as expected.
I don’t think docs have ever encouraged this form,but haven’t prohibited it either.

I see no reason why an issue shouldn’t be filed on that. There really is no reason why it shouldn’t be able to handle the dots in the file name.

I think the issue is that filenames with multiple dots
are not handled as expected.

Yes, this is exactly what I meant. Thanks for clarifying.