openHAB

Class: OpenHAB::Core::Actions::Notification

Inherits:
Object
  • Object
show all
Defined in:
lib/openhab/core/actions/notification.rb

Overview

Provides methods for openHAB Cloud Notification Actions.

Class Method Summary collapse

Class Method Details

.hide(email: nil, id: nil, tag: nil) ⇒ void

This method returns an undefined value.

Hide a notification by ID or tag.

Either the id or tag parameter must be provided. When both are provided, two calls will be made to the NotificationAction:

  • Notifications matching the id will be hidden, and
  • Notifications matching the tag will be hidden, independently from the given tag.

Parameters:

  • email (String, <String>, nil) (defaults to: nil) —

    The email address(es) to hide notifications for. If nil, hide broadcast notifications.

  • id (String, nil) (defaults to: nil) —

    hide notifications associated with the given reference ID.

  • tag (String, nil) (defaults to: nil) —

    hide notifications associated with the given tag.

Raises:

  • (ArgumentError) 


140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/openhab/core/actions/notification.rb', line 140

def hide(email: nil, id: nil, tag: nil)
  unless Actions.const_defined?(:NotificationAction)
    raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
  end

  raise ArgumentError, "Either id or tag must be provided." unless id || tag

  args = []
  if email.is_a?(Enumerable)
    email.each do |e|
      hide(email: e, id:, tag:)
    end
    return
  elsif email
    args.push(email)
    notification = :notification
  else
    notification = :broadcast_notification
  end

  NotificationAction.__send__(:"hide_#{notification}_by_reference_id", *args, id) if id
  NotificationAction.__send__(:"hide_#{notification}_by_tag", *args, tag) if tag
end

.log(msg, icon: nil, tag: nil) ⇒ void

This method returns an undefined value.

Sends a log notification.

Log notifications do not trigger a notification on the device.

Parameters:

  • msg (String) —

    The message to send.

  • icon (String, Symbol, nil) (defaults to: nil) —

    The icon name

  • tag (String, Symbol, nil) (defaults to: nil) —

    a name to group the type or severity of the notification.



174
175
176
 
# File 'lib/openhab/core/actions/notification.rb', line 174

def log(msg, icon: nil, tag: nil)
  NotificationAction.send_log_notification(msg.to_s, icon&.to_s, tag&.to_s)
end

.send(msg, email: nil, icon: nil, tag: nil, severity: nil, id: nil, title: nil, on_click: nil, attachment: nil, buttons: nil) ⇒ void

Note:

The parameters title, id, on_click, attachment, and buttons were added in openHAB 4.2.

This method returns an undefined value.

Send a notification using openHAB Cloud Notification Action.

Examples:

Send a broadcast notification via openHAB Cloud

rule "Send an alert" do
  changed Alarm_Triggered, to: ON
  run { Notification.send "Red Alert!" }
end

Provide action buttons in a notification

rule "Doorbell" do
  changed Doorbell, to: ON
  run do
    Notification.send "Someone pressed the doorbell!",
      title: "Doorbell",
      attachment: "http://myserver.local/cameras/frontdoor.jpg",
      buttons: {
        "Show Camera" => "ui:/basicui/app?w=0001&sitemap=cameras",
        "Unlock Door" => "command:FrontDoor_Lock:OFF"
      }
  end
end

Parameters:

  • msg (String) —

    The message to send.

  • email (String, <String>, nil) (defaults to: nil) —

    The email address(es) to send to. If nil, the message will be broadcast.

  • icon (String, Symbol, nil) (defaults to: nil) —

    The icon name (as described in Items).

  • tag (String, Symbol, nil) (defaults to: nil) —

    a name to group the type or severity of the notification.

  • severity (String, Symbol, nil) (defaults to: nil) —

    Deprecated - an alias for tag for backwards compatibility.

  • title (String, nil) (defaults to: nil) —

    The title of the notification. When nil, it defaults to openHAB inside the Android and iOS apps.

  • id (String, nil) (defaults to: nil) —

    An optional reference ID which can then be used to hide or update the notification. Subsequent notifications using the same reference ID will update/overwrite the existing notification with the same ID.

  • on_click (String, nil) (defaults to: nil) —

    The action to be performed when the user clicks on the notification. Specified using the action syntax.

  • attachment (String, Item, nil) (defaults to: nil) —

    The URL of the media attachment to be displayed with the notification. This can either be a fully qualified URL, prefixed with http:// or https:// and reachable by the client device, a relative path on the user's openHAB instance starting with /, or an image item.

  • buttons (Array<String>, Hash<String, String>, nil) (defaults to: nil) —

    Buttons to include in the notification.

    • In array form, each element is specified as Title=$action, where $action follows the action syntax.
    • In hash form, the keys are the button titles and the values are the actions.

    The maximum number of buttons is 3.

Raises:

  • (ArgumentError)

See Also:



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/openhab/core/actions/notification.rb', line 70

def send(
  msg,
  email: nil,
  icon: nil,
  tag: nil,
  severity: nil,
  id: nil,
  title: nil,
  on_click: nil,
  attachment: nil,
  buttons: nil
)
  unless Actions.const_defined?(:NotificationAction)
    raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
  end

  args = []
  if email.is_a?(Enumerable)
    email.each do |e|
      send(msg,
           email: e,
           icon:,
           tag:,
           severity:,
           id:,
           title:,
           on_click:,
           attachment:,
           buttons:)
    end
    return
  elsif email
    args.push(:send_notification, email)
  else
    args.push(:send_broadcast_notification)
  end
  tag ||= severity
  args.push(msg.to_s, icon&.to_s, tag&.to_s)

  buttons ||= []
  buttons = buttons.map { |button_title, action| "#{button_title}=#{action}" } if buttons.is_a?(Hash)
  raise ArgumentError, "buttons must contain (0..3) elements." unless (0..3).cover?(buttons.size)

  attachment = "item:#{attachment.name}" if attachment.is_a?(Item) && attachment.image_item?

  args.push(title&.to_s,
            id&.to_s,
            on_click&.to_s,
            attachment&.to_s,
            buttons[0]&.to_s,
            buttons[1]&.to_s,
            buttons[2]&.to_s)

  NotificationAction.__send__(*args)
end