• Glen (Xapity)

Part 1: SCSM Email Notifications and Subscriptions


Email notifications are a very useful feature in Service Manager, but as with most things there are a tips and tricks to using them.

Email Notifications in Service Manager are made up of the following components:

  • Notification Templates - the content of the message, based on a work item class

  • Subscriptions - the trigger point to send the Notification template to a set of hard coded recipients or related recipients

  • Notification Channel - the SMTP connection used to send the emails

This post is Part 1 of a two part series on Email Notifications and Subscriptions.

  • Part 1: Notification Templates

  • Part 2: Subscriptions and Notification Channels

Notification Template Design


Notification Template - HTML To control the formatting of the Notification template I generally use the HTML option. My HTML skills are not great, so I don't do much more than basic HTML formatting - bold or italic text, line breaks, tables, and styles.

The major problem with HTML is the lack of line break support in fields like Description. So if this is a must, try it with the HTML option off, but usually the benefits of HTML text formatting are worth it.

If Outlook is your email client, you should test the templates look and feel as Outlook sometimes renders HTML in unexpected ways.

The example Notification HTML below, is a notification template example from Xapity Teams to notify Team members when an Incident was created. In this example I have used a table to present the basic information about the incident, as I think it helps to structure the data for the analyst.

I have used a Style block at the top of the template to define the basic settings for the table. And then a simple introduction sentence, followed by the table of data.

Example Notification HTML:

<style > H3 {FONT-SIZE:14pt;FONT-WEIGHT:bold;text-align:left;FONT-FAMILY: Verdana, Arial, Helvetica, sans-serif; } body {vertical-align:top;text-align:left;FONT-FAMILY: Verdana, Arial, Helvetica, sans-serif;} TH {FONT-WEIGHT:bold;text-align:left;FONT-FAMILY: Verdana, Arial, Helvetica, sans-serif; } TR {vertical-align:top;text-align:left;FONT-FAMILY: Verdana, Arial, Helvetica, sans-serif;} PRE {vertical-align:top;text-align:left;FONT-FAMILY: Verdana, Arial, Helvetica, sans-serif;} </style> The following Incident has been created: <br> <BR> <table > <TR> <TH>Incident: </TH> <TH> [$Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/Id$] - $Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/Title$ </TH> </TR> <TR> <TH>Support Group: </TH> <TD> $Context/Property[Type='CustomSystem_WorkItem_Incident_Library!System.WorkItem.Incident']/TierQueue$</TD> </TR> <TR> <TH>Affected User:</TH> <TD> $Context/Path[Relationship='CustomSystem_WorkItem_Library!System.WorkItemAffectedUser' TypeConstraint='System!System.User']$?$DisplayName$?</TD> </TR> <TR> <TH>Assigned To:</TH> <TD> $Context/Path[Relationship='CustomSystem_WorkItem_Library!System.WorkItemAssignedToUser' TypeConstraint='System!System.User']$?$DisplayName$?</TD> </TR> <TR> <TH>Priority: </TH> <TD> $Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem.TroubleTicket']/Priority$</TD> </TR> <TR> <TH>Status: </TH> <TD> $Context/Property[Type='CustomSystem_WorkItem_Incident_Library!System.WorkItem.Incident']/Status$</TD> </TR> <TR> <TH>Classification: </TH> <TD>$Context/Property[Type='CustomSystem_WorkItem_Incident_Library!System.WorkItem.Incident']/Classification$</TD> </TR> <TR> <TH>Created Date:</TH> <TD>$Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/CreatedDate$</TD> </TR> <TR> <TH>Description: </TH> <TD><PRE>$Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/Description$</PRE></TD> </TR> </TABLE> <BR> This e-mail was generated by Xapity Teams Notifications. <BR>

Large Text fields I like to put the large fields, like Description, at the bottom of the table or page. As the size of the data can vary and can sometimes be quite large it seems to be distracting to put this at the top or middle of the email.

Multi-Line fields <Pre> Tags Also large fields tend to be multi-line fields and this presents a challenge, as by default the line breaks are not honored in the HTML format. To get around this, I have used the <PRE> tag on the description property. This will preserve the line breaks, but comes at the cost of using a different font from then rest of the email. This seems like a reasonable trade off. With better HTML skills you might be able to solve this.

Subject Line and the Exchange Connector [ID] If you are using the Exchange Connector then the subject line of any notification should have the [ID] on it. This allows the email to be uploaded to the work item if a reply or forward is sent to a monitored mailbox, rather than a new job being created.

Email Output of Example Notification HTML:


Tagging the Email Adding a tag at the bottom of the email indicating which template was used can be extremely useful when troubleshooting. When the analysts start complaining about the number of emails they are receiving, ie SCSM is spamming them, you can at least identify which templates are being used. From this, you can then work out which subscriptions are sending the emails.

In larger organisations the number of templates and subscriptions can get quite large and managing them can be challenging. It is likely that some templates will be copies with only slight variations and this can make tracking down the template\subscription combination a real hassle.

My recommendation is to use a clear naming standard for templates and subscriptions. And to tag the email with the template used to create it.

HTML Links Obviously using HTML formatting allows you to put HTML links in the email. These can be do support pages or can even be links to images that you want to add to the email.

Note: if you use HTML links to images the recipient must be able to access these links for them to display - this can be a problem if the emails go externally and the links were internal.

HTML Links for Review Activity Approval or Manual Activity Completion With the Exchange Connector to monitor a mailbox it is possible to use the notification email to allow approvers and activity implementer's to approve or mark activities as complete via email.

Essentially this is just another HTML link in the email, but it opens up a new email with the reply to address already prefilled and the basic approval text, keyword and most importantly the subject Line ID tag prefilled.

One simple click and the RA is approved or rejected via email. Getting managers to approve stuff is hard enough, without making them use the console to do it. Email is what they use daily and are familiar with.

The example here is for a Review Activity approval, but by changing the keywords to [Complete] it could be used for a Manual Activity notification. Remember insert the ID references rather than rely on copying the HTML.

Example HTML in template:

Please click <A HREF="mailto:SYS-SCSM_Workflow@Xapity.Lab?subject=[$Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/Id$] Approved&body=[Approved] This Review Activity has been approved.">Approve</A> to confirm your approval of the Activity.<BR> <BR> Please click <A HREF="mailto:SYS-SCSM_Workflow@Xapity.Lab?subject=[$Context/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem']/Id$] Rejected&body=[Rejected] - Reject Reason: ">Reject</A> to reject the Activity Please provide details or a reason for the rejection.<BR> <BR>

Example Email:


Copy Template Content to another MP It is very common to copy the contents of the template to another template as a starting point. If they are in stored in the same management pack this will not be a problem and all the inserted properties will work correctly.

However, if they are in different management pack, then some or all the inserted properties will break. This is because the reference alias's in the new management pack do not match or are not present. When a property is inserted into the template, the management pack XML is updated along with the reference alias for that property.

If your email has not substituted the property data and just has the HTML string, re-insert the properties that are not working . Thisn will add the correct reference alias in the management pack or edit the management pack XML file to add the required references directly.

Data from Parent work Item when Using a Activity Template

This is a very common problem and is caused by the Notification Template being based on a specific work item class. The common example is a Review Activity or Manual Activity where you can only get data from the actual Activity itself and not the parent Change or Service Request. There are a number of ways to get around this and which is appropriate will depend on each individual use case.

The most common solutions are: • Use SeedRole = 'Target' • Copy Data from the Parent to the Activity Use SeedRole = 'Target' to get to the Parent Work Item

This blog post from Travis Wright is still relevant: Using Data Properties From the Parent Work Items in Activity Email Templates. It allows you to go one level up from the activity and pull data down for generic work item properties.

This is another good blog post from Antoni Hanus that also explains how to use this method. This blog goes into more detail on how to reference other properties (not just generic work item ones) and how to traverse to another relationship or level eg to get the Affected User on the Change or Service Request: Include Details from Parent Work Items in Notifications

This is an example of the HTML to add to the notification template:

$Context/Path[Relationship='CustomSystem_WorkItem_Activity_Library!System.WorkItemContainsActivity' SeedRole='Target' TypeConstraint='CustomSystem_WorkItem_Library!System.WorkItem']/Property[Type='CustomSystem_WorkItem_Library!System.WorkItem'

Copy Data from Parent to the Activity

Another way to deal with the lack of data in the Activity is to copy the data from the parent to the Activity. This usually means collecting the data from the Parent and then adding it to the Description field on the Activity.

Usually there is no need to replicate the properties from the parent to the activity, we just want a summary of the parent details so copying to the description field is good enough. The email notification template can then use the Activity Description field to display the information from the parent item.

Again, there a few ways to achieve this: • Custom PowerShell workflow that runs when the Parent goes In Progress and copies data to the activities- refer to this blog post by Gabriel Taylor on SCSM Workflow - Populate Work Item Data to Child Activities for an example • Xapity PowerShell Activity that copies data to the activities - easier to control when it triggers compared to a custom workflow. See the blog post PowerShell for SCSM: Copy Parent Description to Child Activities • Orchestrator runbooks

Attachments

Unfortunately Service Manager does not support attachments in email notifications. To meet this requirement and to make triggering notifications easier we developed Xapity Notification Activity.

Xapity Notification Activity will allow you to add attachments to an email notifications and combined with Xapity PowerShell Activity will allow you to add attachments from the parent Change or Service Request to the email.

For an examole and more details see our blog post: PowerShell for SCSM: Copy parent Attachments to Child Activity

Testing Email Templates

After doing all this work to get the template just right, you want to make sure that it looks good and has the correct data. Creating a subscription to do this can be a bit of a hassle, so check out Anton Gritsenko's Email Template Tester. This is a great way to check your templates as you are developing them.

Continued in Part 2: SCSM Email Subscriptions.


Xapity Notification Activity

Enables Email Notifications to be sent directly from any System Center Service Manager (SCSM) workflow. With the Xapity Notification Activity, email notifications can have attachments, external and related recipients and can use Notification Templates


See more product videos

Xapity - Innovative Software for SCSM - Discover our Products

#SCSM #Email #NotificationActivity #Templates

© 2018 Xapity PTY LTD ABN: 81 611 883 482

  • White RSS Icon
  • White YouTube Icon
  • White Vimeo Icon
  • Facebook Clean
  • Twitter Clean