JRuby Scripting Official Helper Library

Setup, Configuration and Use Scripts & Rules
39

Merry Christmas!

Version 5.44.0 is out!

These changes since v5.40 add improved support for the newly enriched source information embedded in openHAB events, now available in openHAB 5.1.

Features

  • Support source in profiles by @ccutrer in #485
  • alias Item#formatted_state to display_state and transformed_state by @ccutrer in #488
  • Infer an appropriate source for commands and updates by @ccutrer in #495
  • Add convenience methods to parse the event source by @ccutrer in #496

Bug Fixes

  • Fix debug call in event_admin rspec mock by @jimtng in #480
  • Fix AbstractEvent#payload for non-JSON payloads by @ccutrer in #491
  • Fix event trigger when types are not specified by @ccutrer in #492

Full Changelog : v5.40.0…v5.44.0

Note that the current helper library is compatible with openhab 4.1 and above. Older openHAB versions (3.4 - 4.0) are supported by the helper library version v5.35.1. The correct version is automatically selected.

Intro to the New Event Source Structure

Starting with openHAB 5.1, events can now include a structured “source” field that describes where an event came from and how it was delegated along the way. Instead of a single opaque string, the source is now made up of one or more components, each representing a step in the event’s journey — for example, a rule, a binding, a UI action, or an API call. Every component can include details such as the originating bundle and the actor (like a rule UID or a thing UID), giving you a much clearer picture of what triggered the event and why.

This richer structure makes it possible to trace events more accurately, filter them by origin, and build smarter automations that react differently depending on how an event was produced.

See: Event Bus | openHAB for clarifications on the terminology and structure of the source information.

How the JRuby Helper Library Builds on This

The JRuby helper library now parses this structured source data for you and exposes a set of convenient methods to inspect, filter, and work with the individual components. Instead of manually parsing strings or digging through raw event metadata, you can directly ask questions like:

  • Which bundle sent this event?
  • Was this command triggered by a rule or by the UI?
  • Does any component in the chain match a specific bundle or actor?
  • What does the full delegation chain look like?

These helper methods make it much easier to write expressive rules that respond differently depending on the event’s origin.

JRuby helper methods for event source

The JRuby helper parses openHAB’s structured source field into a Source object so you can inspect the delegation chain without string parsing.

Overview

  • source.components — Returns an array of Component objects representing the delegation chain.
  • source.components.first — Original emitter (the component at the start of the chain).
  • source.components.last — Immediate origin (the component that most recently delegated the event).
  • source.bundle and source.actor — Convenience accessors that return components.first.bundle and components.first.actor respectively (i.e., the bundle/actor of the original emitter).

Other useful helpers

  • source.sender? — Returns true if any component matches the given bundle or actor. Accepts a single argument (bundle or actor) or keyword args bundle: and actor:.
  • source.reject — Returns a new Source with components removed.
  • source.actor_for(bundle) — Returns the actor string for the specified bundle if present (convenience for locating the actor associated with a particular bundle).
  • source.delegate(bundle, actor = nil) — Constructs a new Source by appending an additional component (useful to simulate delegation or to build a modified source chain).

Short examples

Inspect components

src = event.source
src.components.each_with_index do |comp, idx|
  logger.info "index=#{idx} actor=#{comp.actor} bundle=#{comp.bundle}"
end

Original emitter vs immediate origin

# these return the first component's values (original emitter)
logger.info "bundle=#{event.source.bundle} actor=#{event.source.actor}"

Check sender

if event.source.sender?("org.openhab.core.io.rest")
  # event came from REST/UI
end

# Suports regex
if event.source.sender?(/io\.rest|jrubyscripting/)
  # event came from either REST or a direct command/update from a jruby script
end

case event.source.bundle
when /thing/
  logger.warn "Thing event from #{event.source.actor}"
when /jrubyscripting/
  logger.warn "Script event from #{event.source.actor}"
end

Find actor for a specific bundle

actor = event.source.actor_for("org.openhab.core.thing")
logger.info "Thing UID: #{actor}" if actor

Reference: Class: OpenHAB::Core::Events::Source — openHAB JRuby

Note that the event source is available within triggered rules and Ruby profiles.

1 Like
Is Groovy the most native scripting language for OH?