When performing Service Manager implementations, a near-universal request from clients is to have a notification email triggered upon a work item’s assignment changing. As a Service Manager admin, you may or may not already be aware that this functionality is present within Service Manager, however, is unable to be created from within the GUI as of the 2012 release. Instead, it requires a number of changes to a notification subscription which can only be exacted via directly editing the notification subscription’s XML. There are a number of blog posts out there on the internet already about how to go about making the necessary changes, however one thing each of these has in common is that the solutions are very much environment-specific, requiring the lookup of the appropriate notification template GUID, unique to each environment, in order to work.
My co-worker and I decided that we wanted to find a way to present an all-in-one management pack which could be imported into any environment without any need for looking up a GUID and editing XML. With a bit of experimentation, we were successful. I’m writing this blog post in order to make our management pack available for others as well as detailing what was needed in order to make this a true all-in-one solution. Additionally, the majority of the other blogs about relationship-type notification subscriptions, as of the time of this writing, contain outdated XML code from the Service Manager 2010 release. This post will also show the 2012 workflow XML with the updated notification assembly. Let’s dive in!
To begin with, there are a few considerations from Service Manager’s architecture that we had to keep in mind. Mainly, that for a true all-in-one solution, any notification templates used by our subscriptions would also need to be included. Since notification templates will naturally need to remain editable, and unsealed management packs are unable to be referenced, this meant our notification templates would need to be stored within the same management pack as our subscriptions. So the first step was to create a new management pack in the console and create notification templates for each of the planned subscriptions.
Next, “dummy” subscriptions were created via the Create Notification Subscription Wizard. Since the plan was to convert them into relationship-type subscriptions via XML anyway, the criteria were left blank. A notification template and a target relationship user were required to be selected in order to save the subscription, though they would be changed in the XML also. The real reason to create the subscription first in the console was simply to establish the XML framework (as well as providing a source for screenshots). Once we’d made “dummy” subscriptions for each of our planned subscriptions, the MP was exported.
The XML generated by the Notification Subscription wizard for our Incident Assigned To User subscription looked like this:
Original Subscription
There are two main components to a notification subscription – the Data Source and the Write Action. The Data Source element defines the subscription’s trigger – the matching criteria for which the CMDB is monitored in order to trigger the Write Action. The Write Action is the action performed by the workflow. It is a Windows Workflow Foundation XML which passes parameters from Service Manager into the defined assembly file which is what puts together the components and sends the email to the selected recipient(s).
By default, all notification subscriptions created in the console are what is known as an Instance Subscription. This type of subscription monitors the CMDB for any cases where an instance (individual object) of the selected class (in this case, the Incident class, identified by its GUID) matches the selected criteria. When a match is found, it triggers the Write Action. The limitation to Instance Subscriptions is that they look purely at property values and changes made to property values; they do not look at the relationships to related objects. As such, while a property value change on a related object can be used to trigger an instance subscription, the change of one related object to another (even with different property values) does not trigger the Instance Subscription.
Here is where the other subscription type, the Relationship Subscription, comes into play. The element was removed and replaced with the following code:
Relationship Subscription
A Relationship Subscription is unaware of object properties, such as “Username”, “ID”, “Status”, etc. Instead, what it looks for is a change in the related object on a given relationship class. Specifically, when a new object is added via the targeted relationship. There are three elements to a Relationship Subscription:
• RelType = The relationship class which the subscription should monitor.
• SourceType = The specific class (or child class) which is the Source defined in the relationship.
• TargetType = The specific class (or child class) which is the Target defined in the relationship.
In this example, we’re looking at the Assigned To User relationship, known internally as “System.WorkItemAssignedToUser”. Here’s what the relationship definition looks like in the System.WorkItem.Library management pack:
Work Item Assigned To User Relationship
As you can see, the Source is “System.WorkItem” and the Target is “System.User”. Because the Incident class (“System.WorkItem.Incident”) descends from the Work Item class in the Service Manager data model, it also inherits the “System.WorkItemAssignedToUser” relationship. As such, we can use the Incident class as the Source within our Relationship Subscription to limit this subscription and have it only trigger when the relationship changes between the Incident and User classes.
(For those who are unfamiliar with management pack XML, the “WorkItem!”, “CoreIncident!”, and “System!” components are aliases which define in which separate management pack the specified element is defined. Each of these referenced management packs and their aliases is defined in the top section of the management pack, under “References”.)
The same structure can be used to create a Relationship Subscription for any relationship in the program, even custom relationships. Simply enter the appropriate RelType, SourceType, and TargetType entries for the desired relationship and classes, just as we’ve done in the example here.
Because the Relationship Subscription code pulls information based upon class names rather than GUIDs, the code for a given relationship is the same regardless of the Service Manager environment. The Write Action, however, is where environment-specific customizations usually need to be done in order to define which notification template the workflow should use when sending an email. Here is a close-up on the default Write Action configuration in Service Manager 2012:
Write Action (GUID)
There are several components to the Write Action:
• AssemblyName = Lists the DLL which contains the Windows Workflow being triggered.
• WorkflowTypeName = The name of the specific workflow being triggered.
• WorkflowParameters = Used to define the workflow’s inputs and set data values for those inputs.
In Service Manager 2012, the workflow used for Notification Subscriptions is called “Microsoft.EnterpriseManagement.Notifications.Workflows.SendNotificationsActivity”, and it can be found in the Microsoft.EnterpriseManagement.Notifications.Workflows.dll.
There are five parameters which Service Manager passes into the workflow engine for this type of workflow. The first three, “SubscriptionID”, “DataItems”, and “InstanceIds”, are populated dynamically by the data source. This is done via the $Data and $MPElement variables. These are able to dynamically enter data based on the given trigger and their usage is explained on TechNet here: http://msdn.microsoft.com/en-us/library/hh964966.aspx.
The final parameter, “PrimaryUserRelationships”, is also dynamically populated via the undocumented $Context variable and lists the target user relationship to use when selecting which user to notify via email.
The fourth parameter, however, called “TemplateIds”, lists the GUID of the notification template to use when formatting the email. Because content in unsealed management packs is given a randomly generated GUID upon creation or import, this value will be unique in every separate Service Manager implementation. This is why the general instruction for configuring relationship subscriptions is to simply look up the GUID of the appropriate notification template in your environment and update the XML appropriately.
As stated above, our desire was to create a management pack containing these relationship subscriptions which would require zero XML editing in order to accelerate deployment. As such, the “TemplateIds”’s use of a GUID poses two problems for us – first, because the GUID will be different everywhere, it is impossible to enter a GUID and have the management pack be imported into a new environment without updating XML. Second, because our notification templates are located within the same management pack as our subscriptions, they won’t even have GUIDs assigned to them yet and thus there is no way to look up the appropriate GUID for the job.
This “problem” can be resolved by use of the same variable notation used above – the $MPElement variable. Because our notification templates are located in the same management pack, we have no issues with referencing them. Instead, all we need to do is enter the appropriate $MPElement variable referencing our notification template’s element ID. The result is this:
Write Action (MP Element)
Note that under “TemplateIds”, the GUID has been replaced with “$MPElement [Name=’NotificationTemplate.IncidentAssignedToUser’]$”. This is the name of the notification template as found further down the same management pack. Here’s what the template looks like:
Notification Template
With the $MPElement entry and the local notification template, this can now be imported into any Service Manager 2012 environment and work immediately without any XML editing. The final, complete code for the relationship subscription looks like this:
Finished RelSub
We went ahead and configured separate relationship subscriptions and notification templates within our management pack for the following relationship changes:
• Incident Affected User
• Incident Assigned To User
• Incident Primary Owner
• Service Request Affected User
• Service Request Assigned To User
• Change Request Assigned To User
• Release Record Assigned To User
• Problem Assigned To User
• Activity Assigned To User
Each subscription is configured to be disabled upon import, ensuring that no notifications are inadvertently sent while notification templates are being customized or due to relationship changes for which the client does not desire notifications. The management pack is unsealed so that notification templates can be customized however is appropriate for the client, though the basic information is included within each template for a quick get-up-and-go project.
Next Steps
Review our case studies and engagements where we helped companies just like yours solve a variety of business needs.
About Oakwood
Since 1981, Oakwood has been helping companies of all sizes, across all industries, solve their business problems. We bring world-class consultants to architect, design and deploy technology solutions to move your company forward. Our proven approach guarantees better business outcomes. With flexible engagement options, your project is delivered on-time and on budget. 11,000 satisfied clients can’t be wrong.
