Concepts
Here we will explain some key concepts that are vital to Notification Service.
Event Type
An Event Type defines a category of notifications that a module can send out. Modules register their own Event Type via the REST API and is not tenant-specific. The event type defines what dynamic variables will be available and what their data type is. This information will later be relevant when creating subscriptions and sending events.
When defining dynamic variables, you can choose between the following data-types:
-
String
-
DateTime
-
MacmaGroup
-
Device
-
DeviceType
-
MacmaUser
-
Link
The data type here impacts how the variable is used in the subscription.
In case of default subscriptions, number of event types per module varies per application, typically 1-5 (not limited)
Subscription
The subscription represents the actual notification that gets sent and is linked to a single event type. Without a subscription, events don’t trigger notifications.
A subscription defines:
-
The event type to listen to
-
The content of a notification (e.g., subject and content of an email)
-
The recipients of a notification
-
The communication channel that is used to send the notification (email, push)
Only users with role Operator can perform CRUD-operations in the UI. Modules can create subscriptions as well.
Custom Subscription
A custom subscription is a tenant-specific entity and contains the following information:
-
Notification Type (e.g. Push or Email)
-
Subject and Content
-
Recipients
-
Filters ( for more info refer here )
-
Address to send from (for email subscriptions)
For modules using the REST API to create subscriptions, you can specify recipients by their MACMA ID.
Within the subject and content, you are able to reference dynamic variables with the following expression: {{DYNAMIC_VARIABLE_NAME}}.
Example: you have the dynamic variable ImpactedMachineName and a subscription with the content Machine {{ImpactedMachineName}} has been impacted!.When an event is received with the value Machine01 for variable ImpactedMachineName, you will get the following content: Machine Machine01 has been impacted!.
Default Subscription
Default subscriptions are registered with a tenant ID; however, it is not checked. It should not be used for filtering or applying authorization. It contains the following information:
-
A localizable title in English and German with supporting fallback to English if no translation is provided for the user’s preferred language.
-
A localizable description in English and German with supporting fallback to English if no translation is provided for the user’s preferred language
-
Filters ( for more info refer here )
-
RecipientFields to determine recipients with field names referencing dynamic variables from the event type and localizable labels. The recipient should always be a MACMA user, as the calling module cannot identify whether the email given is a MACMA user or a 3rd party user.
-
Localizable subscription templates in Markdown, which will be rendered to HTML for emails and as plain text for push notifications.
-
A default notification method (e.g., Email, Web Push).By default, all notification methods are enabled unless specified otherwise.
-
A flag indicating if the subscription is always-on (optional)
Number of default subscriptions per module will be 1-5 (not limited)
Notification-Settings
The Notification Settings page is used to fetch and display values from the default Subscription table, as well as to set and save the user’s preferred values to the Default Notification Settings table. Modules should set up default notification settings for all users in order to not having to create single ones for each user. This eliminates the need to create individual subscriptions for each user. Users can view the list of all default subscriptions that apply to them and can activate/deactivate them accordingly
Filters
For subscriptions, you can define a criteria of filters which will be evaluated when an event is received. These filters can be used to only send the notification when the criteria are met. When defining filters, you will be able to choose the dynamic variable to check, the operator and the expected value. The list of available operators depends on the data type of the dynamic variable.
Parent filters supports "And" and "Or" operators only.
The system also supports nested filter groups, allowing you to create a complex tree of filters.
Default subscription filters offer additional operators: "Changed", "Changed From", and "Changed To" for variables that support value changes. These operators consider both previous and current values. You can also use these operators when creating custom subscriptions via the REST API only and not from UI.
Example1: Filter using "Changed" operator
Given a subscription filter exists with the "Changed" operator for a dynamic variable <variable> When the value of <variable> changes from <previous_value> to <current_value> Then the filter evaluates to <result>
| Dynamic Variable | Previous Value | Current Value | Result |
|---|---|---|---|
Status |
"Open" |
"In Progress" |
true |
Priority |
"High" |
"High" |
false |
Example2: Filter using "Changed From" operator
Given a subscription filter exists with the "Changed From" operator and value <filter_value> for a dynamic variable <variable> When the value of <variable> changes from <previous_value> to <current_value> Then the filter evaluates to <result>
Examples:
| Dynamic Variable | Previous Value | Current Value | Filter Value | Result |
|---|---|---|---|---|
Status |
"Open" |
"In Progress" |
"Open" |
true |
Status |
"Pending" |
"In Progress" |
"Open" |
false |
Example3: Filter using "Changed To" operator
Given a subscription filter exists with the "Changed To" operator and value <filter_value> for a dynamic variable <variable> When the value of <variable> changes from <previous_value> to <current_value> Then the filter evaluates to <result>
Examples:
| Dynamic Variable | Previous Value | Current Value | Filter Value | Result |
|---|---|---|---|---|
Status |
"Open" |
"In Progress" |
"In Progress" |
true |
Status |
"Open" |
"Pending" |
"In Progress" |
false |
Event
An Event is used to trigger an Event Type and send out notifications based on the subscriptions. An event is referencing an event type and can provide values for the custom properties of the event types. An event is always triggered by the host module (e.g. Ticket Management).
The payload of Event contains the ID of the Event Type that it is targeting and also a list of dynamic variables with their values. For each event, the system will load all the subscriptions that are linked to the given event type and will send out a notification as defined by each subscription.