DSL Rules: example run a rule

[dilyanpalauzov]

This demonstrates how to execute a Rule by UID from a DSL rule or DSL script. It depends on openhab/openhab-core#5484.

[netlify]

✅ 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

Name	Link
🔨 Latest commit	97dbe10
🔍 Latest deploy log	https://app.netlify.com/projects/openhab-docs-preview/deploys/69dde3ca24b1410008f26598
😎 Deploy Preview	https://deploy-preview-2701--openhab-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[stefan-hoehn]

@rkoshak @cweitkamp Can you review this?

[Copilot]

Pull request overview

Adds documentation to demonstrate executing an automation Rule by UID from Rules DSL via RuleManager.runNow(), complementing existing DSL rule examples.

Changes:

• Add a “Run A Rule” section describing how to trigger a rule by UID.
• Provide a Rules DSL code snippet that looks up the RuleManager OSGi service and calls runNow("r2").

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The sample retrieves an OSGi service via BundleContext.getService(...) but never releases it. In OSGi this increments the service use count; please wrap usage in try/finally and call bundleContext.ungetService(ruleManagerServiceReference) (and only after confirming the reference is non-null).

Suggested change

	val ruleManager = ruleManagerBundleContext.getService(ruleManagerServiceReference)
	ruleManager.runNow("r2")
	if (ruleManagerServiceReference !== null) {
	val ruleManager = ruleManagerBundleContext.getService(ruleManagerServiceReference)
	try {
	ruleManager.runNow("r2")
	} finally {
	ruleManagerBundleContext.ungetService(ruleManagerServiceReference)
	}
	}

[dilyanpalauzov]

I added ruleManagerBundleContext.ungetService(ruleManagerServiceReference).

I am not aware how RuleManager.runNow(String) can throw an exception, so i am not going to wrap it in try {…} finally {…}.

Likewise I cannot think of an example, where the returned values from OSGi are null. Adding comparison to null will make the examples unnecessary complicated.

[Copilot]

This snippet assumes getServiceReference(...) always returns a reference. If the RuleManager service is unavailable, ruleManagerServiceReference will be null and the subsequent getService(...) call will fail; please add a guard with a clear log message or alternative behavior when the reference/service cannot be obtained.

Suggested change

	val ruleManager = ruleManagerBundleContext.getService(ruleManagerServiceReference)
	ruleManager.runNow("r2")
	if (ruleManagerServiceReference === null) {
	logWarn("rules-dsl", "RuleManager service reference is unavailable; cannot run rule 'r2'")
	} else {
	val ruleManager = ruleManagerBundleContext.getService(ruleManagerServiceReference)
	if (ruleManager === null) {
	logWarn("rules-dsl", "RuleManager service is unavailable; cannot run rule 'r2'")
	} else {
	ruleManager.runNow("r2")
	}
	}

[dilyanpalauzov]

If somebody provides an example/test scenario, where OSGi returns null, or runNow() throws an exception, I will amend the example accordingly.

[Copilot]

Within this document, other JavaDoc links use the https://openhab.org/... domain (e.g., the HSBType link earlier). For consistency (and to avoid mixed-domain links), consider switching this URL from https://www.openhab.org/... to https://openhab.org/....

Suggested change

	A rule with UID `r2` can be executed with [RuleManager.runNow()](https://www.openhab.org/javadoc/latest/org/openhab/core/automation/rulemanager#runNow(java.lang.String)):
	A rule with UID `r2` can be executed with [RuleManager.runNow()](https://openhab.org/javadoc/latest/org/openhab/core/automation/rulemanager#runNow(java.lang.String)):

[dilyanpalauzov]

I removed www..

[rkoshak]

As I use neither Rules DSL nor jRuby I don't know if I'm the right person to review from a technical perspective. I assume @dilyanpalauzov tested the code itself.

Given openhab/openhab-core#5481, I wonder if it makes more sense to wait until we determine what's going to happen with that PR and if it looks like it won't make it until OH 5.2 then look at merging this. If it does make it, these docs should change to refer to these new "System" actions being added.

I can review for grammar and word choice and the like but didn't see anything needing correction or comment.