View Source Runbox.Scenario.OutputAction.Notification (runbox v20.0.0)

Parameters for output action Notification.

The resulting output action sends a notification.

Summary

Types

t()

Notification

Types

@type t() :: %Runbox.Scenario.OutputAction.Notification{
  actors: [
    Runbox.Scenario.OutputAction.Notification.AssetActor.t()
    | Runbox.Scenario.OutputAction.Notification.IncidentActor.t()
  ],
  aqls: map(),
  attachments: [map()] | nil,
  data: map(),
  direct_subscriptions: [map()] | nil,
  email_reply_to: map() | nil,
  metadata: map(),
  primary_actor:
    Runbox.Scenario.OutputAction.Notification.AssetActor.t()
    | Runbox.Scenario.OutputAction.Notification.IncidentActor.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 attribute notifications. The type 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_actor - the primary actor of this notification, optional. The reference to 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. Use Runbox.Scenario.OutputAction.Notification.AssetActor and Runbox.Scenario.OutputAction.Notification.IncidentActor to reference the entities.

  • :actors - list of related entities/actors, optional. The notification will be sent only to those recipients who have the right to see the specified entities. These can be Assets (Runbox.Scenario.OutputAction.Notification.AssetActor) or Incidents (Runbox.Scenario.OutputAction.Notification.IncidentActor).

  • 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 (menu NOTIFICATIONS / Notification groups / Metadata Filter). Metadata should adhere to the format specified in Runbox.Scenario.Manifest.t/0 attribute notifications.

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 the priv/notifications/[scenario_id]/templates/[notification_type] directory or in deployment/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 (menu NOTIFICATIONS / 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 the email_reply_to attribute is defined, the appropriate Reply-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 the reply_to parameter of the config.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 the data 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 an AQL 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 the AQL 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 the AQL 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.Ecto.Model.Asset{
      type: "/assets/server_room",
      id: "Z10",
      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"] %>