Javier Arroyo
Kilo Guru

This article is about discarding OOTB notification architecture in favor a more maintainable approach that frees developers from ball of mud code, while delegating email branding to the appropriate team. The strategy is to separate html, css and JavaScript. Notification email content (html and css) become sys_ui_messages, while mail_scripts a mediator to logic in script includes. Email content is then controlled through JSON valued sys_properties.

With the following strategy, once the creative team has come up with the templates. It takes the span of time needed to open a sys_ui_message and paste the contents inside. In practice, I rebranded 200+ email notifications three times in less than 10 minutes. More importantly, an admin can do the same during the same time span.

 

First, lets look at how OOTB email notifications are constructed.

Examples of OOTB Email Notification Scripts

incident_body_header

(function runMailScript(current, template, email, email_action, event) {
	template.print('<p><font size="6" color="#808080" face="helvetica">');
	template.print('${number} - ${short_description}');
	template.print('</font></p>');
})(current, template, email, email_action, event);

incident_take_me_to_the_incident

(function runMailScript(current, template, email, email_action, event) {
	var link = current.getLink();
		if (email_action.name != "Incident Resolved") {
		template.print('<p><font size="3" color="#808080" face="helvetica">');
		template.print(gs.getMessage('You can view all the details of the incident by following the link below:'));
		template.print('</font></p>');
	}
	else {
		template.print('<p><font size="3" color="#808080" face="helvetica">');
		template.print(gs.getMessage('If you feel the issue is not resolved, please click the following link and reopen your incident:'));
		template.print('</font></p>');
	}
	template.print('<font face="helvetica">');
	
	var backgroundColor = 'background-color: #278efc;';
	var border = 'border: 1px solid #0368d4;';
	var color = 'color: #ffffff;';
	var fontSize = 'font-size: 16px;';
	var fontFamily = 'font-family: Helvetica, Arial, sans-serif;';
	var textDecoration = 'text-decoration: none; border-radius: 3px;';
	var webKitBorder = '-webkit-border-radius: 3px;';
	var mozBorder = '-moz-border-radius: 3px;';
	var display = 'display: inline-block;';
	var padding = 'padding: 5px;';
	
	if (email_action.name == "Incident Survey") {
		color = 'color: #343d47;';
		backgroundColor = 'background-color: #e6e8ea;';
		border = 'border: 1px solid #bdc0c4;';
	}
	template.print('<a href="' + link + '"');
	template.print('style="' + backgroundColor + border + color + fontSize + fontFamily + textDecoration + webKitBorder + mozBorder + display + padding);
	template.print('">');
	template.print(gs.getMessage('Take me to the Incident'));
	template.print('</a>');
	template.print('</font>');
	template.print('<br><br>');
	template.print('<p><font size="3" color="#808080" face="helvetica">');
	template.print('Thank you.');
	template.print('</font></p>');
})(current, template, email, email_action, event);

 

incident_comments

(function runMailScript(current, template, email, email_action, event) {
	template.print('<p><font size="4" color="#999999" face="helvetica"><strong>');
	template.print(gs.getMessage('Comments:'));
	template.print('</strong></font></p>');
	template.print('<p><font size="3" color="#808080" face="helvetica">' + gs.getMessage('${comments}') + '</font></p>');
})(current, template, email, email_action, event);

 

The three scripts above tied to Notification Incident Commented for ITIL return the image below:

find_real_file.png

 

Now lets consider the effort required to rebrand 200+ notifications. Say, that only the font needed to be changed for ALL outbound emails, or, that Change Management only required a different branding. How long would it take a developer to delve through that OOTB code and put together a new branding? I can tell you that I've worked in systems with hundreds and hundreds of emails with an estimated effort of 3+ months to reconstruct emails following SNow OOTB practices. This, as we should all be familiar, are common requirements by corporate.  Email notifications to various audiences are bound to corporate mandates.

 

A More Manageable Approach 

Create email content in a sys_ui_message for each Object (Incident, Change, Requested Item, Catalog Task, etc). Hand HTML and CSS to the creative team

1a. create the sys_ui_message to host email content:

<br /><br />
<table class="bodyContent">
    
         <tr class="alt">
            <td colspan="4"><p />
                <div>
                    <span>${sys_class_name} ${URI_REF}</span>
                </div>
            </td>
        </tr>
        <tr class="alt">
            <td class="cellName"> Number: </td>
            <td> ${number}</td>
    
            <td class="cellName"> Reporting Method </td>
            <td> ${u_reporting_method} </td>
        </tr>
    
        <tr>
            <td class="cellName"> Requested By: </td>
            <td> ${caller_id} </td>
    
            <td class="cellName"> Affected End User: </td>
            <td> ${u_affected_end_user} </td>
        </tr>
    
        <tr class="alt">
            <td class="cellName"> Opened: </td>
            <td> ${sys_created_on} </td>
    
            <td class="cellName"> Phone Number: </td>
            <td> ${caller_id.phone} </td>
        </tr>
    
        <tr>
                <td class="cellName"> Opened By: </td>
                <td> ${opened_by}</td>
        
                <td class="cellName"> Location:</td>
                <td> ${location} </td>
            </tr>

        <tr class="alt">
            <td class="cellName"> Category:
                <br />Subcategory:</td>
            <td> ${category}
                <br /> ${subcategory}</td>
    
            <td class="cellName"> State: </td>
            <td> ${state}</td>
        </tr>
    
        <tr>
            <td class="cellName"> Configuration Item: </td>
            <td> ${cmdb_ci} </td>
    
            <td class="cellName"> Assignment Group: </td>
            <td> ${assignment_group} </td>
        </tr>
    
        <tr class="alt">
            <td class="cellName"> Parent Incident: </td>
            <td> ${parent_incident}</td>
    
            <td class="cellName"> Impact:</td>
            <td> ${impact} </td>
        </tr>

        <tr>
                <td class="cellName"> Urgency: </td>
                <td> ${urgency} </td>
        
                <td class="cellName"> Priority: </td>
                <td> ${priority} </td>
            </tr>
                   

        <tr class="alt">        

            <td class="cellName"> Short Description: </td>
            <td colspan="3"> ${short_description} </td>
        </tr>
    
        <tr>
            <td class="cellName"> Description: </td>
            <td colspan="3"> ${description}</td>
        </tr>
    
        </tbody>
    </table>

1b. Notification Theme also as a sys_ui_message

find_real_file.png

3. create configuration in sys_properties

find_real_file.png

4. Create Email Notification Script to call from ALL notifications to ITIL

find_real_file.png

5. Create Script Includes:
I will not show what our Script Includes does but here is a psudo-code

      if sys_property hasOwnProperty sys_class_name
           fetch sys_ui_message 
      else 
           return default template sys_ui_message

 

 

2. Add mail script to Template

find_real_file.png

 

The above strategy produces the following email for Incident

find_real_file.png

For Change Request

find_real_file.png

Approval Notifications

find_real_file.png

 

 Requested Item Approval

find_real_file.png

With the above strategy, all outbound emails are controlled by 1 script include, 3 email notification scripts (approval, ess, and itl), 2 CSS ui_sys_messages, and as many sys_ui_messages as there are tables which to "configure". (We use incident, request, requested item, catalog task, change request, change task, problem, problem task, knowledge, sysapproval_approver.  Not mentioned above is that Layouts are used also, and the CSS is auto adjusted whenever themes are changed by the creative team.

The success and maintenance ease of the strategy drove the requirement to expose the same look and feel each Catalog Item. All catalog items now look precisely as they look to the requester, even approval notifications look the same. The beauty really, mobile users are very pleased as well.

 

Note that dynamic content within the emails such as tables, or displaying field specific messages such as comments, work notes, assigned to, unassigned, etc is driven through configuration. As an example, the approval email includes a table of approvers. and all comments or work noted emails also display those contents accordingly. 

 

Outside of above mentions... Introduction of new objects or emails don't require any JavaScript code regardless of content requirements (One table, many tables, div, just text). Contents can use a default look and feel, or require registering the sys_class_name to the sys_properties causes the template provided by the team.  This is the same for tables in scoped applications.

For example, the introduction of a new custom table with its 10+ notifications into the branded email rotation took exactly the amount of time needed to agree on a look and feel for the object.

 

There are other various methods of achieving the same, such as introducing tables to drive the functionality... choose what fits you best.

<TL;DR>

In this article we saw that emails can be configured in a method that allows non-developers to brand email content. This was achieved by separating HTML, CSS and JavaScript from email scripts and introducing ui messages, and properties. Because notification content is cleanly separated, re-branding hundreds of emails becomes a trivial task. As example, I rebranded 200+ emails three times in 10 minutes. The amount of time taken to copy and paste templates into sys_ui_messages.

Comments
John Caruso
Kilo Guru

Please get hired by ServiceNow and fix the OOB mudball once and for all. 😉

Version history
Last update:
‎11-10-2018 02:25 PM
Updated by: