opEvents releases after 1.1.0 include a facility to define your own templates for email notifications (ie. emails as part of an event action or because of an escalation).
The setup is very simple and requires basically just two steps:
- deciding on what information to present and in what order, and
- associating a contact with a particular template.
Defining custom email templates
The configuration file
install/EventEmails.nmis contains the definitions of all email templates. As shipped it includes one special template named
default, which is chosen for all email contacts without a template association, and one example for a very concise report. You can of course modify these existing templates or define your own. Here are these two example templates:
The syntactic rules for templates are simple but flexible:
- An email template consists of two named lists of items to include, one for the mail subject and one for the body.
- The template lists define what order you want the items to be shown.
- Entries like
macro.HIJ) are treated specially, but only if they are isolated separate items.
For example, the text entry "The lazy fox likes node.group" is not special because here
node.groupis part of a longer bit of text.
- All non-special plain text items are included as-is, ie. for generating static header or footer text.
- You can write your texts either single- our double-quoted; within double-quoted strings all the standard backslash escapes work - e.g. "\t" for a tab character).
As these are all perl strings, the "@", "$" and "%" characters are special: within double-quoted strings you'll need to prefix those with a backslash. No such problems arise when you use single-quoted strings, but then no backslash escapes whatsoever are recognized in single-quoted strings.
- Newlines are NOT created automatically. You have to include "\n" for that (within your double-quoted strings, or as separate item) whereever you want a line break.
- The line breaks in the actual template definition are not relevant.
- All special entries, of the form
event.XYZare replaced by the node or event property
If the property is structured, with sub-elements (e.g.
event.script), then these are shown on separate lines and indented with a tab character.
The common node properties are documented here, and the event properties are listed on this page.
- From opEvents 2.2 onwards, special entries of the form
macro.XYZare replaced by the value of the macro named
XYZ(which are defined in the
opCommon.nmisconfiguration file, in the section
- The entry
link.eventcontextis replaced by a hyperlink to the event context page.
- The entry
link.nodecontextcreates a hyperlink to the node context page.
Both of these hyperlink generators rely on the setting
opCommon.nmisto set an appropriate schema and hostname for the hyperlink. if this setting is missing you'll see
http://localhost/in the created hyperlinks.
- Entries of the form
node.*are translated into a list of all "standard summary" node properties, which are defined in
For this summary, the property name is shown first, followed by a colon and a space, the property value, and a newline; repeated for each property. There is a trailing newline.
- The form
event.*works similarly, but for event properties and is not restricted to a default set. It also creates a trailing newline.
- Both special forms
event.*are disabled in the subject template, because that must contain just a single line of text. You also must not create multiple lines of text in the subject template (using "\n").
Associating an email contact with a template
The configuration file
Contacts.nmis contains the list of (email) contacts, and needs to be adjusted if you want templates other than
default to be used. The example file as shipped shows where the email template is set:
Simply change the value after
EmailTemplate to the name of your desired template. If opEvents cannot find the named template, or if no
EmailTemplate setting is present, then the
default template will be used. If that template doesn't exist or work, then you will receive your emails formatted with a hardcoded fallback template that includes a warning notice at the top.