Tuesday, September 27, 2011

Branding SharePoint Server 2010 E-mail Alerts

My organization relies heavily on SharePoint discussion boards and the SharePoint discussion board alert system. Our clients use the alerts too. So, I was asked to brand them.

There are a couple of options when branding SharePoint alerts.
  1. Change the XSLT that is used to generate the alert (ugh! I hate XSLT)
  2. Write an OnNotification method for a class that implements IAlertNotifyHandler
I chose option 2 for our organization. This post will show the before and after as well as a high level explanation of the technical details.

Before and After
Here is what an alert for a discussion board looks like out of the box (see annotations for numbered boxes below the image)

  1. "Connect to this Discussion Board" is Outlook functionality that allows the user to monitor posts and updates to SharePoint Lists. It shows read and unread items. Discussions can be replied to without ever going to the SharePoint site, which can be handy if you spend a lot of time in Outlook.
  2. "Modify my alert settings" links the user to their alert settings for the site. It basically takes you to [Site]/_layouts/mysubs.aspx
  3. "View [Item Subject] links the user to the item's view form. If it is a message (message is a SharePoint content type that acts like a list item. A single message is a reply to a discussion post), it takes you to the message's view form. If it is a discussion (discussion is a SharePoint content type that acts like a folder. It contains the original post of a new discussion), it takes you to the discussion's view form.
  4. "View [Discussion Board Name]" takes you to the default view of the discussion board (usually a list of discussions).
Here is what it looked like after I implemented option 2 for our organization (I had to blur a lot out...sorry):

There are a few notable differences between the before and after:
  1. "Connect to this Discussion Board" is gone. We specifically don't want our external users to be able to connect to the discussion board. In fact, we prefer it if they don't know that it is SharePoint.
  2. I added a logo to the top left corner of the e-mail body.
  3. "View [Item Subject]" now says "View or Reply to [Item Subject]" and instead of taking you to the item form it takes you to the default message view for the discussion, which is usually either the threaded or the flat view.
  4. Obviously I change the color scheme a bit to be consistent with our logo and branding and I removed all of the fields except the body and indented the body a bit. I also changed the wording of the title a bit and made it (what I think) is a bit cleaner and more user friendly.
Note that this is a very simple design with logo, link to reply, and color/CSS changes. You obviously have a lot of flexibility to make this look how you want.

Technical Details
I am going to give a high level of the important technical details here, but I will probably have to go into more detail in future blog posts as there is quite a bit under the surface.

You should create a solution package that will put a dll into the GAC. The solution package should contain a class that implements IAlertNotifyHandler and has a method called OnNotification. You should use this method to create the new alert format. It should look something like this:

The beginning of the class looks like this:

The end of the class looks like this:

Notice that I add a linked resource for the logo and use the SmtpClient.Send method to send the mail. All the work to create the build variable that contains the html for the e-mail is in the class.

Once you create your class and deploy it to the GAC, there is more work to do:

Create a copy of this file: Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\XML\alerttemplates.xml. This file contains the alert templates for each of the different lists, document libraries, etc. You can find the schema here: http://msdn.microsoft.com/en-us/library/bb802961.aspx. Note that there is a separate file for SMS. I specifically didn't bother to update that file since we don't use it and it is disabled, but you will need to update that file as well, if you want to change your SMS.

Once you have a copy, you need to add the NotificationHandlerAssembly and NotificationClassName Properties in the newly copied file for alert template you would like to override with your new design. For example, I was changing the discussion board alerts. So, I found the section in the XML that pertained to discussion boards, then I added the appropriate entries in the properties section. You can find an example of the entries here: http://msdn.microsoft.com/en-us/library/ff407215.aspx. These entries should point to your new assembly and class.

Once that is done, you need to tell SharePoint to use the new alerttemplates file that you just created. You do that with this command: http://technet.microsoft.com/en-us/library/dd278299(office.12).aspx

Then iisreset and restart the timer service.

I would be happy to go into more technical details if someone has questions. Just post a comment!

Happy SharePointing!