Customizing HTML email notifications

This chapter describes the most typical scenarios of customizing HTML email notifications. Instead of using the out-of-box set of email notifications and templates, your organization is likely to have its own email templates and include its own fields in email messages. For example, a company may include its company logo and follow its own color schemes in email messages.

In most scenarios, you only need to make some minor changes to an out-of-box HTML template, such as changing the formatting of the message body and including some additional fields in the email message. Therefore, you can use the out-of-box HTML template as a basis and create your own HTML templates by copying from that out-of-box template.

Create your own HTML templates

To create a custom HTML template, follow these steps:

1. Click Tailoring > Notifications > HTML Templates.

2. Search for and select an existing HTML template as the base of the new template.

   Example: SM Add

3. On the General tab, specify a name for the new template in the Name field.

4. Change the Mail Title field if necessary.

5. In the Language field, select a language for the template.

6. Describe the template in the Comment text box.

7. The Module and Test Record fields combined determine which record is passed in for preview. Select a module in the Module field and specify the id of the record in the Test Record field.

   Note The module name is designed to be a general name, it may include multiple tables or refer to nonexistent table. Therefore, not all previews are supported currently.

8. In the text box on the Expressions tab, edit the JavaScript code that evaluates the variables that you include in the email message.

   Note To post certain field values of the record that is passed in, you can add these fields directly in the HTML Source, such as $RECORD.incident_id. However, if you want to add variables computed based on record fields, you must evaluate these variables using JavaScript code on the Expressions tab and then post the variables in the HTML Source.

   Only the following simple data types are supported:

   • String
   • Date/Time
   • Logical
   • Number

9. The HTML Source tab displays an HTML editor where you can design the message body of your HTML template. You can click Source to toggle between the normal view and the source code view. To reference a variable or expression in the message, enclose your variable or expression in braces, such as {$RECORD.title}.

10. To generate a preview using the Module and Test Record fields that you specified in step 7, click the Preview tab.

11. Click Add to create the new template.

Localize a template

To create a language version of an HTML template, follow these steps:

1. Click Tailoring > Notifications > HTML Templates.

2. Use search or advanced search to find the template that you want to localize.

3. On the General tab, select a language in the Language field for the localized template.

4. Keep the name in the Name field as is, because HTML template records with the same name are considered language versions of one template.

5. In the Mail Title field, replace the original text with the appropriate translation and make sure all the variables are in the correct positions.

6. On the HTML Source tab, replace the original text with the appropriate translation.

7. Click the Preview tab to verify that your localized version works as expected.

8. Click Add to create the localized template.

Link an HTML template to a notification

To link an HTML template to a notification, follow these steps:

1. Click Tailoring > Notifications > Notifications.

2. Search for the notification record to which you want to link the HTML template.

3. On the Message tab, locate the message with an Msg Class of HTMLTemplate and an id Msg No. of 1.

4. In the Arguments field, replace the second argument of the jscall function with the name of the template that you want to use for this notification.

5. On the Email/Mail Subject Line tab, locate the message with an Msg Class of HTMLTemplate and an id Msg No. of 1.

6. In the Arguments field, replace the second argument of the jscall function with the name of the template that you want to use for this notification.

7. Click Save to save the changes.

Add commonly used elements in templates

This section describes how to add certain elements that you are likely to include in your email message.

Images

To post images in the message, you must store the images in a location that your email recipients can access and add image tags referencing the corresponding URLs.

Web URL

It is a common practice to include a Web URL in the email message pointing to the corresponding record so that the recipient can follow the link to view the record in a Service Manager web client. You can reference the web_url variable that is defined in the expressions of the out-of-box templates.

You can keep one of the following statements and comment out the other one, depending on whether the email message is sent to an ESS user or a regular Web-tier user.

For ESS users:

var web_url = lib.urlCreator.getURLFromQuery(file_name,record_query,record_title);

For regular Web-tier users:

var web_url = lib.urlCreator.getESSURLFromQuery(file_name,record_query,record_title);