View Source Runbox.Scenario.OutputAction.Notification (runbox v18.0.0)
Parameters for output action Notification.
The resulting output action sends a notification.
Summary
Types
@type t() :: %Runbox.Scenario.OutputAction.Notification{ aqls: map(), attachments: [map()] | nil, data: map(), direct_subscriptions: [map()] | nil, email_reply_to: map() | nil, ids: [String.t()], metadata: map(), primary_asset: String.t() | nil, priority: :low | :medium | :high | String.t(), type: String.t() | atom() }
Notification
Structure Notification defines the possible attributes of notifications. Different types of notifications are distinguished by the use of different attributes and their specific values. The specific use of the Notification structure in the source code defines the pattern according to which the final notifications of a given type will be generated.
Final notifications are sent to recipients according to the rules defined
in Notification Groups or in direct_subsctriptions
attribute of the Notification
structure desribed below.
Example
%Notification{
type: "technician_entry",
data: %{
"room_id" => %{type: "/assets", id: "server_room"},
"technician_id" => %{type: "/assets/cardholder", id: "j_adams"}
},
priority: :medium
direct_subscriptions: [
%{
"channels" => ["smtp"],
"templates" => ["operator"],
"user" => %{"email" => "operator@acme.com"}
}
],
email_reply_to: %{
"Technical support" => "technician@acme.com"
},
aqls: %{
"asset" => %{
"aql" => "FROM '/assets/server_room' SELECT ["name"]",
"primary" => true
}
},
}
Notification Attributes
:type
- string. Type of the notification.The scenario manifest defines notification types and some additional metadata about each type. See details in
Runbox.Scenario.Manifest.t/0
attributenotifications
. Thetype
identifier is used, along with other criteria, to find the template through which the notification will be transformed into the final notification intended for sending to a specific communication channel.:data
- map. A map of data that can be used within the notification template. Keys of the map are used to reference the data.
Example
# Definition of the data attribute
%{
"room_id" => %{type: "/assets", id: "server_room"},
"technician_id" => %{type: "/assets/cardholder", id: "j_adams}"
},
# Usage of the data attribute in the template
<%= inspect(data["technician_id"]) %>
:primary_asset
- string, optional. The ID of the asset or incident to which the notification relates. If a primary asset is included in the notification then the notification is not sent to recipients who do not have permission to see the primary asset.:ids
- list of asset IDs, optional. The notification will be sent only to those recipients who have the right to see specified assets.priority
- optional, atom. Possible value are:low
,:medium
,:high
. Defaults to:medium
. Only applicable to some channels. Attribute is not used for prioritization of email notifications.:metadata
- map, optional. Additional metadata which can be used to filter recipients. Metadata filter can be set in the User UI (menuNOTIFICATIONS / Notification groups / Metadata Filter
). Metadata should adhere to the format specified inRunbox.Scenario.Manifest.t/0
attributenotifications
.
Example
# metadata attribute
%{"report_for" => "C-Level"}
:direct_subscriptions
- list of maps, optional. Direct subscriptions provide a way to bypass routing system defined through notification groups and send notifications to the specific recipients directly. It is even possible to send notifications to recipients who do not have an Altworx account.Each member of the list is a map with the following structure:
"user"
- is a map that with keys:"email"
- the value is a string containing email address."notification"
- optional. The value is a map with key:"language"
- optional. String containing language of the notification template.
Type of the channel determines which keys are used.
"templates"
- list of template types that will be used to generate the final notification. Templates itselves are located either in thepriv/notifications/[scenario_id]/templates/[notification_type]
directory or indeployment/scenario_notification_overrides/[scenario_id]/templates/[notification_type]
directory."channels"
- list of channel ids through which notifications will be sent. Channels are defined in the Altworx Admin UI (menuNOTIFICATIONS / CHANNELS
).
Example
# Direct_subscriptions attribute
[
%{
"channels" => ["smtp"],
"templates" => ["operator"],
"user" => %{
"email" => "operator@acme.com",
"notification" => %{"language" => "en"}
}
}
]
:attachments
- list of maps, optional. Attachments that will be attached to the notification. Each map has the following keys::data
- binary. Content of the attachment.:filename
- string. Name of the file.:content_type
- string, optional. MIME type of the data.:type
- whether the attachment is to be inlined in the template (:inline
) or not (:attachment
, this is the default).
Example
# Definition of the attachments attribute
%{
data: "greeting",
content_type: "text/plain",
filename: "greeting.txt",
type: :attachment
}
:email_reply_to
- map, optional. If theemail_reply_to
attribute is defined, the appropriateReply-To
headers will be inserted into the email protocol. The recipient of the notification will see the information as the email addresses to which his possible reply will be sent.If the attribute
email_reply_to
is not specified the value defined in thereply_to
parameter of theconfig.ini
configuration file stored in the deployment directory is used.Keys are the names of the recipients of the reply. Values are their email addreses.
Example
# Definition of the email_reply_to attribute
%{
"Call Centrum" => "info@acme.com"
}
:aqls
- map of AQL defintions, optional.AQL
enables to add more context to the final notification.AQL
also allows to simplify the scenario code. For example, if you need to insert the name of an asset that the notification references into the text of the notification, you can either manage that name yourself in scenario state or you can fetch the name using AQL.Without
AQL
the scenario has to maintain the asset name in the scenario state, handle messages that change the asset name coming from the input topics and pass the name to the template via thedata
attribute. All of this is usually unrelated to the scenario logic and only serves to create a better text of the notification.Using
AQL
, developer passes anAQL
query to the notification. This query uses an asset ID to retrieve the current asset name from the reality network at the time the final notification is created. The scenario usually needs the asset ID for its own purposes, so it is probably stored in the scenario state anyway.The keys of the
aqls
are the string identifiers under which theAQL
query results are available inside the notification template. The values are maps providing more information about the query. Each map has the following keys:aql
- string. Contains theAQL
query.primary
- boolean atom:true
- notifications will be sent only to those recipients who have read permission to all the assets returned by the query.false
- permissions are not evaluated.
Example
# Definition of the aqls attribute
%{
"asset" => %{
"aql" => "FROM '/assets/server_room' SELECT ["name"]",
"primary" => false
}
}
# Value passed to the notification template after above AQL queries are executed:
%{
"asset" => [
%AssetMap.DAO.Entity.Asset{
id: "/assets/server_room",
attributes: %{"name" => "022-000033/AGPP"}
}
]
}
# The name of the technician can be obtained inside the notification template
# with the following command
<%= List.first(aqls["asset"]).attributes["name"] %>