Developing Email Notifications for Metrics
Developing Email Notifications for Metrics
Developing Email notifications includes the following steps:
- Step 1: Optionally, Define Notification Categories for Templates
- Step 2: Define Notification Messages
- Step 3: Define Notification Templates
- Step 4: Assign metrics to notification templates
Step 1: Optionally, Define Notification Categories for Templates
Optionally, the first step in developing a notification system for metrics is to develop custom categorizations for your templates. Defining categories facilitates selection of the appropriate template, and finding notifications. You create categories depending on the template you are defining and how you want to track them. For example, you can organize template by importance, by trigger type, or recipient type.
Accessing the form:
You use the following view file to define categories:
- Navigator Path: System / Add-In Manager / Define Notification Categories for Metrics.
-
File:
ab-def-notifycat-metrics.axvw
From this view, the only Notification Categories visible will be those for the Application ID (notifycat.activity_id) = ‘AbSystemAdministration” (Archibus System Administration), and any new notification categories you define are assigned to this application ID..
To define a category, you enter a Notification Category (the unique identifier) and Category Description.
Step 2: Define Notification Messages
The next step in developing notifications is to use the Define Notification Messages task to define subject-line and body message content for notification templates. Performance Analysts can then select this text to be included in notification templates.
You use the following view file / task to define the notification message:
- Navigator Path: System / Add-In Manager / Define Notification Messages for Metrics
-
File:
ab-def-notify-msgs-metrics.axvw
To define notification subject lines:
In the Edit Messages pane, enter the following required information:
Message Purpose |
Ensure that Subject Line is selected. Using this selection indicates that you are defining a subject line. |
Message Code |
Enter a unique identifier for this subject line. Do NOT include spaces in your entry. For example, enter REMINDER_SUBJECT to define a subject line for a reminder notification. |
Description |
Enter a description of how the subject line is used. For example, enter "Subject Line for reminder template." |
Message |
Enter the subject line for the email notification. Use the syntax ${table.field} as a placeholder for specific field values. For example, enter “Event ${activity_log.action_title} is scheduled to begin on ${activity_log.date_scheduled}”. This entry includes the syntax for entering a placeholder for the Event Title and its Date Schedule. See Configuring Email Messages for information on creating messages. |
Customized? |
Use this field to keep track of any standard messages that you have changed from the default message value. |
Is Rich Message Format? |
If you are referencing database fields in the message, you must set the Is Rich Text field to Yes. Messages can be created using the new Rich Message format. The format utilizes Freemarker (http://freemarker.sourceforge.net ) software, and the messages entered are templates that use parameters that the system will fill in at runtime. See the topic Workplace Services / Service Desk / System Integrator / Service Desk Steps / Configuring Email Messages in User Help. |
Message ( Language ) |
If you are localizing the application, there are Message boxes for the different languages. |
To define notification body messages:
Message Purpose |
Ensure the Message Body is selected. Using this selection indicates that you are defining the message content. |
Message Code | Enter a unique identifier for this body message. Do NOT include spaces in your entry. For example, enter "REMIND_UPCOMING_EVENT" |
Description | Enter a description of how this message is used that helps you identify it. For example, enter “Default email body text for reminders of upcoming events.” |
Message |
Enter the body text for the email notification. Use the syntax ${table.field} as a placeholder for specific field values. You can use either ${afm_metrics_definitions.metric_name} or ${afm_metrics_Trend_values.metric_name} For notifications that are sent for other granularities then 'all' (all = entire portfolio), for example 'by Building', for greater clarity, you can include the granularity value in the message. For example: “"${afm_metric_trend_values.metric_value} EH&S Requirements deadlines are approaching for building ${afm_metric_trend_values.collect_by_value}, on date ${afm_metric_trend_values.date_collected}. Please be alerted as this is considered a critical number of requirement deadlines. For more information, please access your Environmental Manager Home Page: http://localhost:8080/archibus/” This entry includes the syntax for entering a placeholder for metric details. See Workplace Services / Service Desk / System Integrator / Service Desk Steps / Configuring Email Messages in the User Help for information on creating messages. |
Customized? |
Use this field to keep track of any standard messages that you have changed from the default message value. |
Is Rich Message Format? |
If you are referencing database fields in the message, you must set the Is Rich Text field to Yes. Messages can be created using the new Rich Message format. The format utilizes Freemarker ( (http://freemarker.sourceforge.net ) software, and the messages entered are templates that use parameters that the system will fill in at runtime. See the topic Workplace Services / Service Desk / System Integrator / Service Desk Steps / Configuring Email Messages in the User Help. |
Step 3: Define Notification Templates
The third step in developing a notification system is to set up notification templates. Notification templates specify the message content, recipients, the triggering conditions that cause the email to be sent, and the number of recurrences for the notification.
Tip:
Multiple metrics - one template
. You might want to set up templates that can be used for multiple metrics, that is if the same message, recipients, recurrence, and triggering conditions apply to more than one metric, these metrics can be assigned to the same template.
For example, you might want safety managers to receive email notifications when the high warning limits have been breached for medical monitoring (Medical Monitoring Requirement: Deadline Approaching), personal protective equipment renewal (Personal Protective Equipment: Renewal Date Approaching), or safety training (Training Requirement Deadline: Nearing). In this case, these three metrics could be assigned to the same template, as they use the same triggering conditions and recurrence pattern.
Tip: One metric - multiple templates
. In some cases, you might need to examine different triggering conditions for the same metric. Since each template has only one triggering condition, doing so would require more than one template for the same metric.
For example, an Energy Manager might need to know if energy consumption has exceeded a targeted limit. The metric is Energy Consumption and the triggering condition in this case would be >= Report Limit Target.
The Energy Manager might also want to be notified if the energy consumption is above the critical limit defined for the energy consumption metric. In this case, you would define another notification template for the Energy Consumption metric, this time using the triggering condition >= Report Limit High Critical.
Accessing the form
You use the following view file / task to define the notification template:
- Navigator: System Administration / Add-In Manager / Manage Notification Templates for Metrics
-
File:
ab-notify-template-metrics.axvw
From the Select Notification Template tab, click Select in the row for the template, and the Define Notification Template form appears.
Configuring Dynamic Email Recipients
In addition to hard-coding recipients into the email notification template, you can specify dynamic recipients based on a field in the notification's trigger table.
For example, in Compliance Management, you might want the notification to go to the Responsible Person, and this person might differ by requirement. By using the following syntax in the recipient's list, the application finds the email for the requirement's Responsible Person and sends it to that person.
(FreeMarker): ${activity_log.manager.em.email}
Using this syntax, when the Responsible Person changes, you do not need to update the email address in the notification template - only in the user's record.
Any recipient in the list without an '@' sign is considered to be a recipient in the aforementioned syntax. Examples for Compliance Management:
- activity_log.manager.em.email
- activity_log.contact_id.contact.email
- activity_log.vn_id.vn.email
Valid separtors are ";" and ";"
For example, if you add
${activity_log.contact_id.contact.email}; ${activity_log.manager.em.email}
in the Recipients Email Addresses field both persons will be notified , but if the two fields are separated by ‘,’ only the first person will be notified.
If the entry contains only a single period (.), then it is considered to be the field name of a text field in the event table containing an email address:
activity_log.option1
Using the form
The following describes the data you can enter when defining the template.
Label | Table | Column | Required? | Description |
---|---|---|---|---|
Notification Template Code | notify_templates | template_id | Yes | Primary key: Unique identifier for the template |
Notification Category | notify_templates | notify_cat | No | The category for the template, if you want to associate the template with a category. This facilitates searching for specific templates. |
Template Description | notify_templates | description | No |
Describe the purpose of this template, for example, “Notify if the Monthly Energy Consumption is Above Target” For better identification, it is best to include in the description a reference to the scope of the notification, or the Metric Name- for example: "Daily Warning: EH&S Requirements Deadlines Approaching (High Warning Limit Notification)" |
Define Notification Message | ||||
Notification Subject Line | notify_templates | notify_subject | No |
Select a predefined subject, or enter a custom one. You defined subject lines in step 2 of this Help topic. In the messages table, the messages specifically for metrics are associated with the Primary Application (messages.activity_id) = ‘AbSystemAdmin” and Referenced By (messages.referenced_by) = ‘METRICS’. |
Notification Subject ID | notify_templates | notify_subject_id | No | |
Notification Body ID | notify_templates | notify_message_id | Yes |
Select a message body that has been defined for metrics. You defined messages in step 2 of this Help topic. In the messages table, the messages specifically for metrics are associated with the Primary Application (messages.activity_id) = ‘AbSystemAdmin” and Referenced By (messages.referenced_by) = ‘METRICS’. |
Define recipients | ||||
Recipients Email Addresses | notify_templates | notify_recipients | Yes |
Specify the employees or group of recipients who should receive the notification message This is entered as a comma or semicolon-separated list of email addresses. You can select from the list of employees or manually enter an email address. You can also have the application dynamically select the recipient by using the following format to specify the role that should receive the notification. (FreeMarker): ${activity_log.manager.em.email} |
Define notification condition and trigger | ||||
Notification Trigger Date Field | notify_templates | trigger_date_field | Yes |
This is a read-only field that describes the date on which the Manager receives the notifications, if the notification condition is met. The email notification is triggered on the metric’s collection date (‘afm_metric_trend_values.metric_date). This date is determined by the recurrence pattern set when defining the metric (afm_metric_definitions.recurring_rule). |
Notify If Metric Values Is | notify_templates | trigger_condition_to | Yes |
From the list, select the status and condition that triggers this notification to be sent. If the metric value for the Collection Date meets the value defined for the condition, then the notification is sent. The values for these conditions are part of the metric definition.
|
Resend Notification Every Days(s) |
notify_templates | notify_recurrence | No |
If you want notifications to be sent again after the first notification is sent, enter the number of days between these subsequent notifications. This entry depends on the business priority for the metric, and how often the metric is collected:
|
Maximum Notifications to Send | notify_templates | total_recurrence | No |
Enter the maximum number of notification to be sent. Notifications are sent until the Event Status changes, or until the maximum number of notifications has been sent, whichever occurs first. If you do not enter a maximum number, notifications are sent until the Event Status changes. |
Granularities | notify_templates | metric_collect_group_by | No |
Select the granularities (afm_gran_defs.collect_group_by) for which you want the notification to be sent. Multiple granularities are allowed separated by the delimiter (,), The same notification conditions may be valid for multiple granularities, as long as those granularities are assigned to the targeted metric. For example, an Energy Manager might want to be notified when monthly energy consumption is above a specified target. A granularity of 'All' would notify the manager when all buildings (all data stored in the database for this metric) are over this target; a granularity of 'by building' would notify the manager when any building was over the target limit. |
Step 4: Assign metrics to notification templates
Now that you have defined notification templates, you need to assign the metrics to the templates. You assign the metrics for which your organization's managers need to receive email notification with the triggering condition and granularity as described in the template. For example, a Compliance Manager might need to receive a weekly notification when the number of compliance regulations due this week has reached the High Warning level defined for the metric. In this case, you would assign the metric Regulatory Actions: Due This Week (risk_alert_Regulations_crit_weekly) to a template that has a Notification Trigger of >= Report Limit High Warning.
When you assign more than one metric to a notification:
- the notification is sent if the value for any of the assigned metrics matches the triggering condition.
- The trigger date occurs every time one of the associated metrics is collected.
To assign metrics to template:
You assign metrics using the Manage Notification Templates task.
-
From the Select Notification Template tab, select the check box for one or more notification templates, and click Assign Selected.
The Select Available Metrics form appears. This list shows metrics that are not already assigned to the selected notification templates.
- From this list of metrics, you select the check boxes for the metrics you want to assign, and click Save.