Notification Templates

June 2019

Notification Templates

Summary

This summary briefly explains how to create custom notification templates in ControlUp for use with Incident Triggers. All steps are performed from a ControlUp Console. More detailed information about creating notification templates and assigning them to Incident Triggers can be found in the rest of this guide.

Step 1.
In the Trigger Settings window, select Templates. The Template Settings dialog box opens, and lists the currently defined notification templates (see Creating a New Template).

Step 2.
Select an existing template to use as the basis for the custom template, and then select Duplicate. A copy of the existing template opens.

Step 3.
Under Template Name, enter a name for the custom template.

Step 4.
Modify the Subject and Body fields as required.
Note: To see a list of variables that can be used in these fields, select variables.

Step 5.
Select OK. The template is created.
Note: For information about assigning the template to an Incident Trigger, see Assigning a Template to a Trigger.

Overview

Notification templates are used by ControlUp to create follow-up notifications when Incident Triggers are activated. They are used either to create e-mail notifications or to insert a log entry in the Windows Event Log, and can be assigned to the following types of triggers:

  • Send an e-mail alert
  • Record an event in the application log
  • Send an e-mail alert via a local SMTP server
  • Run an action

Templates can include both text and variables; the variables are replaced by specific information about the trigger in the actual notification text. The message body may also include other text, before and/or after the template text, that is predefined by ControlUp and cannot be modified or removed (e.g., “This is an automated alert...”).

In older versions of ControlUp, templates were all predefined by ControlUp. Beginning with ControlUp v7.4, you can also create custom templates. Thus, you can add additional information to a notification or create a notification whose text is in French.

Predefined templates cannot be edited or deleted, but they can be duplicated, and the duplicates can be modified or deleted. This is, in fact, how all custom templates are created – by making a duplicate of an existing template and modifying it.

Using Variables in a Template

Variables that can be used in notification templates have the form $(…), where the name of the variable is in the parentheses. For example: $(ObjectName) is a variable whose name is ObjectName, and it is used to insert the name of the object whose behavior generated the trigger into a notification. Variables can be included anywhere in the subject line or the body of a template. For example, the template body could include this line:

The $(ObjectName)object has been disconnected from monitoring.

In the actual notification, it would then say something like:

The my-pc.domain.com object has been disconnected from monitoring.

Not all variables are relevant to all triggers. For example, if the trigger is related to computer stress, no process is directly connected to it, so the $(ProcessName) variable is not defined. A complete list of supported variables, including descriptions of each variable and the contexts in which it is defined, is available from the link below. This list is presented as a spreadsheet in which the first four columns define and explain the variable, and the remaining columns show the contexts in which the variable is defined.

Note: Variable names are not case-sensitive.

List of variables: Link

2.png

Variable list ( mceclip4.pngin a column indicates the variable is defined in the context of that column)

Multi-Counter Variable

In addition to the variables described above, another type of variable exists. This variable, ListOfColumns, is a special variable that is invoked multiple times in multi-counter incidents – once for each counter involved. The variable is only for use with Stress Level or Advanced triggers, because these are the only triggers that can include multiple conditions.

The ListOfColumns variable has a special syntax, in which you can include the text and variables you would like to see for each counter involved in the incident. All of the text must be placed within the variable’s parentheses, after a colon and between quotation marks (e.g., $(ListOfColumns: "my text…”)). In addition, certain variables exist only for use with the ListOfColumns variable:

$(Column)

$(ColumnSeverityLevel)

$(ColumnTimestamp)

$(ColumnUTCTimestamp)

$(ColumnCrossedThreshold)

$(ColumnValueBefore)

$(ColumnValueAfter)

 

 

Note: The variables in this category are also marked as such in the variable list. 3.png $(ListOfColumns) variables in the variable list

The following is a sample of template text that uses the ListOfColumns variable:

$(ListOfColumns:"          Column: $(Column)
Value changed from $(ColumnValueBefore) to $(ColumnValueAfter)
On ($(Timezone)): $(ColumnTimestamp)
Threshold crossed: $(ColumnCrossedThreshold)
")

If two columns – CPU and Name – were involved in this incident, the output of this code in the notification would look like this:

Column: CPU 
Value changed from 13% to 25%
On (UTC +3 Jerusalem Standard Time): 13/05/2019 16:19:27
Threshold crossed: 20%

Column: Name
Value changed from CPUSTRES.EXE to CPUSTRES.EXE
On (UTC +3 Jerusalem Standard Time): 13/05/2019 16:19:27
Threshold crossed: CPU*

Creating a New Template

Each template has three components:

  • Template Name: The name of the template that identifies it in the list of available templates
  • Subject: The title that will appear in the notification – in an e-mail, this is the subject line; in a log entry, this is the first line
  • Body: The text of the notification

The Subject and Body fields of the template can include variables.

In order to create a new template, you begin by duplicating an existing template, and then modifying it. You can select any existing template to duplicate. If you create a new template by selecting Add, the ControlUp Advanced Trigger template is duplicated.

11.pngTo create a new template:

  1. In a ControlUp Console, in the My Organization screen, in either the Home or the Settings ribbon bar, select Triggers. The Settings window opens with the Trigger Settings tab displayed.

4.png

Settings window with Trigger Settings tab displayed

  1. Select Templates. The Template Settings dialog box opens, and lists the currently defined notification templates. Predefined ControlUp templates are identified by a mceclip1.png icon, while user-defined templates are identified by a mceclip0.png icon. Only user-defined templates can be edited; ControlUp templates are not editable.

5.png

Template Settings dialog box showing the list of currently defined templates

  1. Select an existing template to use as the basis for the custom template in one of the following ways:
    • Select Add. The Edit Template window opens a copy of the ControlUp Advanced Trigger template.
    • Select an existing template, and then select Duplicate. The Edit Template window opens a copy of the selected template.

6.png

Edit Template window

  1. Under Template Name, enter a name for the custom template.
  2. Modify the Subject and Body fields as required.

Note: To open the list of variables that can be used in these fields (see above), select variables.

7.png

Template edited

  1. When you are finished creating the template, select OK. The Edit Template dialog box closes, and the template is added to the list of available templates in the Template Settings dialog box.

Assigning a Template to a Trigger

Once you have created a template, you can assign it to any trigger. This is done in the trigger’s settings.

Note: For the Run an action follow-up action, if you choose to send an e-mail notification, you must ensure that the trigger also has the Send an e-mail alert or the Send an e-mail alert using a local SMTP server follow-up actions configured. This is because the recipients of the Run an action e-mail notification are not specified in the Run an action settings – rather, they are copied from the settings of the Send an e-mail and the Send an e-mail alert using a local SMTP server follow-up-actions.
When the trigger is activated, the Send an e-mail and the Send an e-mail alert using a local SMTP server follow-up actions are implemented immediately; the Run an action notifications are sent to the same recipients, but after the Run an action follow-up action is completed (successfully or not).
If no Send an e-mail and no Send an e-mail alert using a local SMTP server follow-up-actions are defined along with a Run an action follow-up action, no notification e-mails are sent for the trigger.

11.pngTo assign a template to a trigger:

  1. In the Settings window, in the Trigger Settings window, do one of the following:
    • Select Add Trigger to create a new Incident Trigger.
    • Select an existing Incident Trigger, and then select Edit to edit an existing trigger.

The trigger-configuration wizard opens.

  1. Define or modify the trigger settings as required until you get to the Follow-up Action screen.
  2. In the Follow-up Action screen, under Type, select the type of follow-up action. Template assignment is supported in any of the following follow-up action types:
  • Send an e-mail alert
  • Record an event in the Application Log
  • Send an e-mail alert using a local SMTP server
  • Run an action

8.png

Selecting a follow-up action

  1. Under Template, select the template to use for the notification.
    Note: Depending on the follow-up action you chose, the fields in this screen will vary, but a Template field is included for all follow-up actions that handle notifications.
  1. If you are configuring a Run an action follow-up action, in addition to configuring the settings for the Run an action follow-up action, as you just did, you must also configure a Send an e-mail alert and/or a Send an e-mail alert using a local SMTP server follow-up action.

    To do this, repeat steps 3-4 above: This time, select Send an e-mail alert or Send an e-mail alert using a local SMTP server. Configure all of the settings. Under Template, you can select any template that is appropriate for the e-mail notification; it does not have to be the same template that you selected in the Run an action settings (Two e-mails will be sent to each recipient whenever the trigger is activated – the one that is selected here, and the one that is selected in the Run an action settings). When you are finished, both follow-up actions should appear in the list:

9.png

Both Run an action and Send an e-mail alert configured for a trigger

  1. Configure the rest of the settings for the trigger as necessary, and then, select Finish. The trigger is configured and the notification will be generated whenever the trigger’s conditions are met.

Troubleshooting

  1. A variable appears in a notification instead of the value of the variable.
    The variable does not exist. This is most likely caused by a typo in the template, in the name of the variable. Check the variable list above to ensure the variable name is correct.
  1. A blank space appears in a notification instead of the value of the variable.
    The variable name is defined, but it has no value when this type of trigger is activated. This occurs when you include a variable in a template that is not defined in the context of the incident. Check the variable list above to ensure all variables included in the template are defined in the context of the incident (look green cells with ‘v’ in the variable list).
Powered by Zendesk