Yaml rules and rule templates documentation#2737
Conversation
✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
I can't find any documentation for the different triggers, conditions and actions. It would have been nice to be able to link directly to the documentation for the specific type, but as I can't find them, I can't do that. I'm not going to make documentation for all of those in this PR. Is it really the case that they aren't documented? |
Do you mean something like https://next.openhab.org/docs/configuration/jsr223.html#triggertype-objects or are you looking for different documentation. That's the only rules language neutral set of docs I'm aware of. Indeed they are not super user friendly. In general each rules language ends up documenting these all separately (e.g. https://next.openhab.org/docs/configuration/rules-dsl.html#rule-triggers, https://next.openhab.org/addons/automation/jsscripting/#jsrule, etc.). Non one has really documented the UI rules stuff before now as the UI does an OK job of being self documenting. But with the new YAML format this is probably a gap in the docs that needs to be filled. |
rkoshak
left a comment
rkoshak
left a comment
There was a problem hiding this comment.
I at least have all the information I would need to write a rule or rule template with what's here. I intend to watch this with interest and will try to apply them by converting some of my rule tempaltes to YAML in the coming days.
Yes, that's spot on. That seems to only cover triggers though, not conditions and actions. I think that when I tried to search, I searched for "condition codes", not "trigger codes", which is why I found nothing. I imagined that they should all be there somewhere. It's a bit strange that these are placed under JSR223, since they apply system-wide and aren't really affiliated specifically with JSR223, but I guess that's where the need arose? Ideally, I think they should all be documented like that, for all module types, in a "neutral place" that more specialized documentation can then link to. It seems that there's no way to link to a specific type, which I would have preferred from the table of types - but I'll have to find a way to reference that "table" for triggers. |
I've linked to the various sections of the DSL documentation, but it's not really a good fit. Not everything is covered in the DSL documentation, and the names of the properties aren't mentioned at all, since you use the DSL syntax to set them, not the names of the properties. Even if each language document things individually, I think that a "core documentation" of the basic functionality of the module and the name and syntax of the parameters/properties would be helpful. Otherwise, those will just have to be repeated "everywhere", and the chance that they are maintained are even slimmer. |
Probably because of history. All the triggers were originally documented in the Rules DSL docs. Then when JSR223 was documented there needed to be a lower level set of information (audience was primarily automation add-on developers I think) so they got documented there. And then each individualindividual automation add-on documetns how they expose the JSR223 stuff. Since conditions and the non-script actions were only supported in MainUI until very recently, I think they never got documented at all anywhere else.
I agree. I'm not sure the best place though, JSR223 has served as that place up until now. |
|
I just found that when serializing to YAML, the order of modules is either random, or "condition-action-trigger". That needs to be looked at later. I also noticed that there seems to be a regression when creating a new rule from scratch in YAML view, the UID is overwritten by the autogenerated one. I know that this worked previously during development, so some other change must have clobbered it. |
|
I'm not as concerned about that, though the order there would be nice if the order were consistent across the boardtoo. I'm more concerned that the examples in the docs maintain the same order. I wouldn't hold up this PR by a change to the serialization. |
I didn't intend to. I just noted some things I discovered while tinkering. The order of serialization will have to be changed post 5.2.0, but it's probably not very hard to fix, and I think it would be better if they appeared in a more "logical" order than "condition-action-trigger". |
|
What is "holding up" this PR at the moment is rather that I've gotten the idea that I should use local AI for proofreading/consistency checks into my head, and I have a problem to admit defeat and just give up. The tools (the VS code extensions primarily) are mostly completely useless and broken, and the ability to do these things are mostly theoretical, even if the local model seems to handle the tasks reasonably, I can't find any extensions that can actually manage the formatting/data exchange correctly, so they end up completely breaking the document. I must soon accept that I'm beating a dead horse, and just get on with it, relying on humans to catch my mistakes instead 😉 |
Looking at the documentation, I think "Concepts -> Rules" would be where it would fit the best. Despite the section being called concepts, the documentation goes into some considerable details about triggers, conditions and actions - but I must say that I find it somewhat confusing and incomplete. Still, judging by the content found there, I'd say that's where it would fit. More ideally, I think I could have been under "Configuration Guide -> Rules" (doesn't exist, but could/should, just like it does for Things and Items). It would "fit" better to do that kind of details there, but I think that would also mean that a lot of the details from the "Concepts" section should also be moved there, and "Concepts" should only describe the overarching structure. That would mean a somewhat larger refactoring/restructuring though, so it's probably not viable to do short-term. |
|
I've had some luck with Open Web UI as the interface to my local LLMs. It presents an OpenAI compatable API so anything that can connect to OpenAI can use my local LLMs instead. That opens up a whole range of capabilities. You can also add in stuff like websearch, MCP and the like. I don't know if that can help at all but it's made it a lot easier for me to integrate local LLMs into various services. I haven't tried VSCode yet (maybe not ever) though. |
The needs vary depending on what you want to do, the reason I'm so "insistent" on VS Code (or one of its alternatives like VSCodium or Eclipse Theia) is that I primarily want it for "review"/improvement suggestions for documents I write myself. To make that useful, there has to be some integration with the editor. I guess that if you want the model to generate content, integration might not be that important, but as I see it, AI generated content is mostly "slop" and not of much interest to me, except for filling in boilerplate code that I can use as a starting point. Which leads back to why I keep focusing on VS Code. I know that there are Eclipse plugins available too, but I haven't looked at them at all for two reasons:
VS Code is where I mess with all the stuff I don't really know that well, so that's where it's most useful. |
|
I gave OpenWebUI a try, but it wasn't easy to even get to where I could configure the Ollama connection. Once I finally did, I get "communications problems" similar to what I've seen from some of the VS Code extensions. I don't get what this is about, but there clearly is some fundamental issue with communication protocols that means that the JSON they are supposed to be exchanging ends up in the chat: 
edit: Something changed without me doing anything, and it actually started replying sensibly to questions. Since it's very slow, I don't have much more to say other than it seems to be working. |
Nadahar
force-pushed
the
yaml-rules
branch
5 times, most recently
from
40133f8 to
a250477
Compare
|
I've added brand-new sections for standard triggers, conditions and actions under "Concepts -> Rules". I don't really feel that it fits under concepts, it's too specific for that, but it's the only place I could find to "integrate it" without rewriting a whole lot. The rule concept description seems very dated as well, there are things that are plain wrong there (like that "some rule engines" supports conditions), and other things that just don't describe the current situation very well IMO. If the rest of the rules documentation is refactored/restructured in the future, these pages could be moved to a more suitable location, but I think it's better to have them here, somewhat misplaced, than to not have them at all. I'll update the YAML documentation to reference these new pages for rule modules, so that each type can have explicit documentation. @rkoshak Can you see what you think about what I've done under "Concepts -> Rules"? |
|
This has been quite some extra work, that I wasn't really prepared for, so I might have been a bit "fast and loose" at times, so there's the potential for some "human slop" in there. I've used a local LLM to review it, but there might still be things that should be rephrased or changed in there. |
Nadahar
force-pushed
the
yaml-rules
branch
2 times, most recently
from
9ded7f5 to
b960b89
Compare
|
When working with this, I come across some "challenges" that I can't fix. Among them are configuration parameter Configuration parameter Overall, I'd say that the documentation for configuration description parameters and their use is weak, and it should be improved and put in a dedicated location, outside add-on development documentation. |
Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
…actions Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
|
@florian-h05 @lolodomo @rkoshak This is now ready for review, and should be a part of the 5.2.0 documentation. It's been quite a lot of work, and I've pushed myself quite a lot to get it done. I know that it's a lot to review, and I know that it's not the job of either of you, but I can't quite think of anybody else that can do it. The upside is that we can easily correct mistakes later, without waiting for a new release. |
|
This pull request has been mentioned on openHAB Community. There might be relevant details there: https://community.openhab.org/t/help-making-a-javascript-example/169675/12 |
There was a problem hiding this comment.
Pull request overview
Adds documentation pages to bring YAML rules and rule templates in line with other YAML-definition docs, and expands the rules concepts documentation with dedicated “standard triggers/conditions/actions” reference pages. Updates navigation (YAML index + sidebar) to surface the new content.
Changes:
- Add new YAML documentation pages for
rulesandruleTemplates, including examples. - Add new “Standard Triggers / Conditions / Actions” concept pages and link them from the rules concept page.
- Update YAML index page and VuePress sidebar to include the new pages.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 18 comments.
Show a summary per file
| File | Description |
|---|---|
| configuration/yaml/ruletemplates.md | New documentation for YAML rule templates, syntax and examples. |
| configuration/yaml/rules.md | New documentation for YAML rules, including standard module type references. |
| configuration/yaml/index.md | Adds rules / ruleTemplates to the YAML index navigation and examples. |
| concepts/standard-triggers.md | New reference page describing standard trigger types and parameters. |
| concepts/standard-conditions.md | New reference page describing standard condition types and parameters. |
| concepts/standard-actions.md | New reference page describing standard action types and parameters. |
| concepts/rules.md | Enhances rules concept docs with links to the new standard trigger/condition/action pages. |
| .vuepress/docs-sidebar.js | Updates sidebar structure to include the new rules children and YAML pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
|
I have read everything except ruletemplates.md. Will try to finish today. |
Signed-off-by: Ravi Nadahar <nadahar@rediffmail.com>
|
@lolodomo Let me know when you are finished reading it - I'll then hava a swift look and merge it. |
Finished and no additional comment. You can merge. |
| | `label` | ☐ | The trigger label. | | ||
| | `description` | ☐ | The trigger description. | | ||
| | `type` | ☑ | The trigger type, which must be a valid/existing trigger type. This is what decides how the trigger works, what mechanism is in use, and which configuration properties must be present. | | ||
| | `config` | ▧ | A key-value map of the trigger's configuration. See the trigger type documentation for which keys exist, are mandatory, and what their values should be. | |
There was a problem hiding this comment.
What does this checkbox signal?
From how it looks in the preview, I think Y / N entries might be "clearer" when skimming through.
There was a problem hiding this comment.
It means "both", "neither" or "conditionally true" I guess. In this case it's because it depends on type. Some trigger types (most it fact) requires at least one configuration parameter to work, but some can do without (because of defaults mostly as far as I can remember for triggers). Some conditions, like "holiday condition", have no configuration at all.
I was looking for a checkbox with a filled square inside, which is the "standard" that I guess everybody will recognize from using UIs, but it seems that it doesn't exist in Unicode, and this one was the closest thing.
There was a problem hiding this comment.
@florian-h05 I'm not really sure what you're suggesting here, I don't think Y/N/Maybe would be better, I think it's much easier to "read" a checkbox, and I doubt that "unclear meaning" of ▧ will cause much of an issue, since the description text spells out that it depends on circumstances.
What is important is to get this in a part of the 5.2.0 documentation, especially since I've linked to it in my suggestion in the blog post.
|
Let's try to merge that before documentation for OH 5.2 is freezed. |
I'm working on creating corresponding sections for rules and rule templates that exist for other YAML definitions.