Developing Email Notifications for Metrics

Developing Email notifications includes the following steps:

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}

See Configuring Dynamic Email Recipients .

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.

  • >= Report Limit High Critical
  • <= Report Limit Low Warning
  • <= Report Limit Low Critical
  • <= Report Limit Low Warning OR >= Report Limit High Warning
  • <= Report Limit Low Critical OR >= Report Limit High Critical
  • <= Report Limit Target
  • >= Report Limit Target

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:

  • Leave this field blank if you want the notification to be sent only once, the first time the triggering conditions are met.
  • When entering this field, you need to consider how often the metric is collected. For example, if the metrics are collected on a daily basis, there would be no need to make an entry here.
  • If the metric is especially critical (such as the number of regulations due this week), and the metric is calculated on a less than daily basis, you might want to send the message additional times during the week.
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.

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

  2. From this list of metrics, you select the check boxes for the metrics you want to assign, and click Save.