Email Notifications How-To

Hey All,

Since we haven't had any LEM discussions yet, I thought I'd post a quick how-to on setting up custom notifications. There's a couple of really common use cases for going beyond the out of the box Log & Event Manager users and email templates:

1. You've got more than one user and you'd like to be notified about different things.
2. You'd like to change the appearance of the notification emails to include more (or less!) information.
   
3. You've got someone who needs notifications, but doesn't need to view real-time data (for example, a helpdesk user).
4. You've got an automated system that you use to triage alerts/incidents (for example, a trouble ticketing system).

First of all, you'll want to set up users for anyone who needs to receive notifications. We see a lot of common ways this is done:

1. If you've got people who need to access the Log & Event Manager Console, you can create an admin, auditor, or monitor user - just be sure to associate an email address with their user.
   
2. If you've got an external system (i.e. for trouble ticketing/incident handling) or person who doesn't need to access the Console, you can create a contact user - again, be sure to associate an email address.
3. If you want to be sure you're notifying everyone in your IT organisation of the same thing at the same time, you can associate a distribution list email address with any of the above types of users.

To set up users, go to Build > Users. Click the + button on the top right, then fill in the information at the bottom - if you're creating a Contact user, you don't need to enter a password. Add email addresses to the user by clicking the + button under "Contact Information" and click the nearby Save button. When you're done, click the bottom-most Save button.

Whew, now that we've got the boring stuff out of the way, let's talk templates. Email templates let you customize the appearance of email notifications when they are triggered as responses in your Rules. An email template is actually two components:

1. Static text that lets you customize the appearance of the email.
   
2. Dynamic text (parameters) that is filled in from the original event that triggered the rule to fire.

For example, if I'm creating an Account Lockout template that will notify me when someone's account gets locked out (or automatically file a trouble ticket so the Helpdesk can take care of it), I'll want to fill in some static text that describes the event (say, "Account Locked!") and then use the dynamic text to describe the account that got filled out from the original event (say, the username and computer or domain controller they were locked out on). Generally, I create templates that are specific to a "type" of event  that I'm looking for - that keeps me from having one email template per  rule, which can get out of hand. For example, I have one template for "Account Modification" that can be used to tell me when a user is added/removed from a group, their password is reset, or other details are changed. There's no limit to the number you can have, so do whatever works for you.

To create a new email template, go to Build > Groups. Click the + button at the top, and choose Email Template.

1. First, provide a Name for your template - remember this, you'll use it in rules to reference the template.
   
2. To create dynamic text (parameters) for your rule, type in a name, then click the + button underneath the Parameters box to add it to the list; repeat for all the parameters you want to add. Each one of these is kind of like a variable that will "hold" your data and place it in the right location in the email. For my Account Lockout template, I used Time (always handy to have a timestamp), Account (for the user that was locked), DC (so I knew where they were originally locked), and Machine (so I know what Windows thinks was the source of the original logon failures, in case I need to do further investigating). 
3. Type how you'd like the Subject to appear in the Subject box. If you'd like to specify static text, just type it in. To add a parameter, you can either type in the name as it appears in the parameters list (with the dollar sign), or you can drag from the parameters list into where you want it to appear in the subject. Yes, you really CAN use your dynamic text (parameters) here! That means I could  have a subject that included the user's account name, source, or any  other text from the originating event. In my case, I chose a fixed subject line and just typed "Account Lockout" in the Subject box (that way Outlook groups them all together for me in conversation view).
   
4. Type how you'd like the body of the message to appear in the Message box. Again, if you'd like to specify static text, just type it in. To add a parameter, you can either type in the name as it appears in the parameters list (with the dollar sign), or you can drag from the parameters list into where you want it to appear in the subject. In my case, I kept it simple, and went with: Account $Account locked out at $Time on DC $DC from computer $Machine. If your email is going to be consumed by a trouble ticketing system, make sure the format of your email matches whatever your ticketing system is expecting, some are more flexible than others.
   
5. Click the big Save at the bottom to save all that work.

Still with me? Good. Let's go use that fancy new template over in our rules. Head over to Build>Rules and create a rule for your template by clicking the + button and building out your rule logic, OR if you're following my Account Lockout example, you can clone our out of the box NATO5 rule by navigating to NATO5 Rules > Change Management > Windows/Active Directory > Users.To clone, select the User Account Lockout (Updated) rule and go to the left side/rule's Gear and click Clone; select a folder from your Custom Rules folder and click OK. When you clone, the rule automatically opens for you - handy!

To associate your template with the rule, you'll need to add or edit a Send Email Message Action.

1. To create a new Send Email Message Action (if you have more than one specified, multiple email messages will be sent), navigate to Actions in the list on the left, and drag Send Email Message into the orange Actions box on the right side. If you make a mistake, or decide you want to clear out the actions and start over, no worries! Hover over any action and click the upper right hand X. Didn't mean to do that? No worries, again! Click the Undo button to bring it back.
2. In either case - editing an existing Send Email Message Action or starting with a new one - select your new template from the Email Template dropdown (if you forgot the name, you can always go back to Build>Groups real quick and dig it up - the rule will still be waiting for you with no lost work when you come back to Build>Rules).
   
3. Click on the Users dropdown and check the box next to the users you want to be notified about this event. (If you forgot those, don't stress - head back to Build>Users and take a peek. The rule will still be waiting.) 
4. Here's where it gets fun. You'll see the dynamic text (parameters) you specified in the Email Template over here in the Send Email Message action. You can fill them out with the fields from the rule by dragging and dropping the fields from the Alerts/Alert Groups area, just like building a rule. In my Account Lockout example, I'm using the UserDisable alert, so I'll go over to Alerts and type in UserDisable in to the search box (because I'm pretty lazy) and click on it to select, or navigate to GenericAlert>AuditAlert>AuthAudit>UserAuthAudit>UserDisable (now you know why I'm so lazy, say that 3 times fast). Drag over the DetectionTime field into the Time variable, the SourceMachine field into the Machine variable, the DestinationMachine into the DC variable, and the DestinationAccount field into the Account variable. 
5. Make sure your rule is enabled by checking the Enable checkbox. You can also use the Test checkbox/mode if you're not sure how your rule will behave - you'll see InternalTestRule alerts in the Console to let you know it was triggered and what it would have done. I'm feeling pretty confident, so I'm going to leave Test mode off, check Enable, and don't forget to click Save.
6. Don't forget this step! You'll see that the Activate Rules button is enabled in the top right corner. We let you batch up all your rules changes in case you want to make multiple changes before changing the running state of the manager. So, be sure to click Activate Rules to tell the Console to send your changes to the manager and enable them. 

At this point, your rule is active, your template's all set up, and you're ready to go. Next time your rule fires, you should have an email (well, someone should!) that matches the format you've specified above.

Common gotchas:

1. How do I know the rule is being triggered? Check your Console for InternalRuleFired alerts, either by using nDepth or a filter. Those alerts will show you what rule was triggered and when. 
2. Rule not being triggered when it should be? Check your rule logic, but also check your timestamps. Your appliance or virtual appliance host layer might need to be configured for NTP. By default, rules won't fire when incoming data drifts more than 5 minutes from the appliance's clock.
3. Rule being triggered but emails aren't being sent? Make sure you've got the Email Active Response connector configured on your manager appliance by going to Manage > Appliances, then clicking the leftmost Gear icon, going to Tools, then System Tools and Email Active Response.  Click Gear>New to create a new tool, or click Gear>Stop and Gear>Edit to edit the configuration if you see a mistake. Always click Save and Gear>Start to start/restart the tool. If you typed in a test email address, you can click Test after starting to send a test mesage.

This is a topic we cover in our Rules and Actions training session (in more depth), but it's not something you do every day which makes it super easy to forget until you really need it. :)