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, nil) (defaults to: nil) —

    The email address 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) 


128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/openhab/core/actions/notification.rb', line 128

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
    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.



157
158
159
 
# File 'lib/openhab/core/actions/notification.rb', line 157

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, nil) (defaults to: nil) —

    The email address to send to. If nil, the message will be broadcasted.

  • 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.

See Also:



69
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
 
# File 'lib/openhab/core/actions/notification.rb', line 69

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
    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)

  # @!deprecated OH 4.1
  if Core.version >= Core::V4_2
    buttons ||= []
    buttons = buttons.map { |title, action| "#{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)
  end

  NotificationAction.__send__(*args)
end