Loading

Email Notifications

From ServiceNow Wiki
Jump to: navigation, search
Notifications
Knowledge.gif Get the Book

1 Overview

Use email notifications to send selected users email about specific activities in the system, such as updates to incidents or change requests. If you want to change how ServiceNow processes incoming email, see Inbound Email Actions.

Email notifications allow administrators to specify:

  • When to send the notification
  • Who receives the notification
  • What content is in the notification

Additional email notification options are available. Users can subscribe to notifications, and administrators can make some notifications mandatory. See Notifications for all the tasks required to create and send custom email when ServiceNow events occur.

Administrators also have the option of converting existing email notifications to a rich HTML format (starting with the Eureka release). This format provides several advantages, including :

  • Raw HTML content is converted into a WYSIWYG format.
  • The content can be edited in a feature-rich HTML editor.
  • Mail scripts are condensed into a single, easy-to-read line that can be reused in multiple email notifications.
  • To prevent broken links, items like images and incidents, that are linked with URLs relative to a particular instance are converted to absolute links. For example, if an incident is linked using a relative URL, the link is converted to an absolute link.
Note
Note: The rich HTML format is the default for all new email notifications starting with the Eureka release.


2 Creating Email Notifications

Creating an email notification involves performing the following steps on the Email Notification form:

  1. Identifying the notification.
  2. Specifying when to send the notification.
  3. Specifying who receives the notification.
  4. Specifying what the notification contents.

2.1 Identifying the Notification

Each notification has a set of properties that uniquely identify it.

Email notification identifying properties

Use these steps to set email notification identifying properties.

  1. Configure email properties to enable your instance to send and receive email.
  2. Navigate to System Policy > Email > Notifications.
  3. Click New.
  4. Fill in the fields at the top of the Email Notifications form, as appropriate (see table).
  5. Continue creating the notification by specifying when to send the notification.
Field Description
Name Enter a unique name for the email notification. Descriptive names help identify the purpose of the email notification. For example, Incident Opened & Unassigned.
Table Select the database table to which this notification is linked, such as Incident [incident].
Type Select the type of notification you are creating: EMAIL or Meeting Invitation.
Active Select the check box to enable the email notification.
Description Type a description for this notification

2.2 Specifying When to Send the Notification

You can define when to send a notification based on the type of triggering event. The instance can send a notification in either of these circumstances.

  • When a record is inserted or updated
  • When a specific event runs

When creating a notification based on a new or updated record, specify what additional conditions must be met to trigger the notification. You can specify these notification-specific conditions.

  • Changes: Checks to a see if a field value changes.
  • Changes from: Checks to see if a field value changes from a particular value.
  • Changes to: Checks to see if a field changes to a particular value.
Incident notification sent on insert or update

Use these steps to specify when to send a notification.

  1. Identify the notification.
  2. Fill in the fields for the When to send section of the Email Notifications form (see table).
  3. Continue creating the notification by specifying who receives the notification.
Field Description
Send when Select under what condition the notification is sent: when a record is inserted or updated or when a particular event is triggered.
Weight [Required] Set a numerical value for the sending notification's priority relative to other notifications on the same table. ServiceNow only sends the notification with the highest weight. All other notifications are moved from the Outbox to the Skipped mailbox. The default value 0 causes ServiceNow to always send the notification (assuming the conditions are met).

For example, suppose a service desk agent adds a comment to an incident and shortly thereafter closes it. By default, these actions trigger both the Incident commented and Incident Closed notifications. However, since both notifications are from the Incident table and both notify the incident caller, ServiceNow only sends the notification with the highest weight, in this case the Incident Closed notification.

Notification weights

Note: The SMTP Sender scheduled job determines how often to send email. By default, this job runs every minute.

Conditions Use the condition builder to select the conditions under which this notification is sent. For example, you might select Priority > greater than > 3 - Moderate to send the notification only for High and Critical priority incidents.
Inserted Select the check box to enable email notification when a record is inserted. This field is visible only when the Send when field has been set to Record inserted or updated.
Updated Select the check box to enable email notification when a record is updated. This field is visible only when the Send when field has been set to Record inserted or updated.
Event name Select the event that triggers this notification. This field is visible only when the Send when field has been set to Event is fired.

2.2.1 Optional: Specifying Advanced Conditions

Use an advanced condition to send a notification based on the current email record, changing field values, or system properties. The advanced condition script must return true or set a global answer variable to true in order to send the notification.

You can add a script-based condition in the Advanced condition field by personalizing the Email Notification form and adding the field. You can access the field in the Advanced view without personalizing the form starting with the Eureka release.

The advanced condition script uses the following global variables:

  • current: contains the current record from the table to which the notification is linked.
  • event: contains the event that triggered the notification.
Note
Note: The Advanced condition field is evaluated in addition to other conditions you set on the notification. Both the Condition and Advanced condition must evaluate to true in order to send the notification.


Advanced condition.png

2.3 Specifying Who Receives the Notification

You can send notifications to:

  • A static list of users and groups determined when the notification is created.
  • A variable list of users and groups determined by entries in a particular task record.
Sample recipients of an incident email notification

ServiceNow recommends limiting the recipient list of any notification to 1000 users. By default, if a notification has more than 100 intended recipients, ServiceNow automatically creates multiple notification messages with up to 100 recipients each. If you want to change the recipient limit, set the system property glide.email.smtp.max_recipients.

Use these steps to specify who receives the notification.

  1. Identify the notification.
  2. Specify when to send the notification.
  3. Fill in the fields for the Who will receive section of the Email Notifications form (see table).
    Additional fields are available in Advanced view; however, these are needed only under rare circumstances.
  4. Continue creating the notification by specifying the notification contents.
Field Description
Users/groups in fields Select users or groups from reference fields and Glide lists of the notification record's table. For example, if a notification uses the Incident [incident] table, then you can select users or groups from incident fields like Opened by and Assignment group. This list of users or groups is variable and depends upon the values of the associated task record.

Note: You can dot-walk to values in reference fields by clicking the plus sign in the field selector and then selecting the related field.

Users Select the users you want to receive the email notification. You can search for users with the reference lookup icon or manually add their email addresses. This list of users is static.
Groups Select the groups you want to receive the email notification. You can search for groups with the reference lookup icon or by manually entering the group name. This list of groups is static.

2.4 Specifying the Notification Contents

The administrator controls the formatting of the notification content with the built-in WYSIWYG HTML editor (starting with the Eureka release). If you are modifying a notification that was created prior to the Eureka release, you can edit the notification in its current form or convert the content to rich HTML formatting, which can be maintained with the HTML editor. If you are using an older version, see the previous version information.

Note
Note: As a best practice, use the same format type for all notifications. This ensures that all notifications have a consistent look and feel.


Although there are no required content elements, you can use one or more of the following options to specify the email notification contents:

Note
Note: Additional fields are available in Advanced view; however, these are needed only under rare circumstances.

Email notification what v2.png

Fill in these fields to specify the content of an email notification (starting with the Eureka release).

Field Description
Email template If you want to re-use existing content, select an email template to add content to the email notification.
Subject Enter the subject line for the email message. The subject can include variables from the Select variables column.
Message HTML Enter the content of the email notification message. The message can include variables from the Select variables column. Variables map to column names available from the notification table, its parent tables, and reference tables. Use variables to include values from a record in the table such as an incident's short description or comments and work notes. The Message HTML field is visible only if you set the content type to HTML and plain text or HTML only.

Note: If you want to include a link to the record that triggered the notification, see Enabling Links to ServiceNow Records.

SMS alternate Enter the notification message to send to an SMS device. The SMS alternate message is limited to 140 characters.


3 Converting Email Notifications to Rich HTML

By default, new email notifications are created in the rich HTML format starting with the Eureka release. Administrators can convert notification content that was created in a pre-Eureka version to rich HTML so it can be edited in the WYSIWYG editor. This is an optional step. Skip this process if you prefer to maintain email notifications in their current format.

  1. Navigate to System Policy > Email > Notifications.
  2. On the Email Notifications list screen, click the name of the email notification you want to convert.
  3. Click the What it will contain tab.
    Unconverted.png
  4. Click Switch to Rich HTML Editor.
    Any raw HTML in the Message field is rendered as WYSIWYG text. Additionally, any mail scripts in the body are automatically saved to the Email Script [sys_script_email] table and are replaced in the notification body with an embedded script tag. This makes the notification body easier to read.
    Converted.png
Note
Note: The letter "P" at the bottom of the screen shows the location of your cursor within the Message field. In this case, the cursor is in a line containing an HTML <p> tag.
Note
Note: For email notifications that were created in the Eureka release or that were already converted, the Switch to Rich HTML Editor button is not displayed.


4 Working with Mail Scripts

When you convert an email notification that was created in a version prior to Eureka to rich HTML, mail scripts are automatically moved to the Email Script [sys_script_email] table and an embedded script tag with the name of the script is automatically inserted into the body of the notification.

When creating new email notifications in the Eureka release, it is a best practice to write mail scripts using System Policy > Email > Notification Email Scripts. When the scripts are completed, add a ${mail_script:script name} embedded script tag to the email notification body. This makes it easy to use the same scripts in multiple email notifications. All you need to copy and paste from one notification to the next is the embedded script tag.

If you manually enter a mail script—any text bounded by <mail_script> and </mail_script>—in the body of a new or converted email notification or template, and then attempt to save the record, a message asks whether the mail script should be converted.

Invalid Mail Script.png

In many cases, an unconverted mail script fails to run from inside the HTML editor. If you select Yes, the script is added to the Email Script [sys_script_email] table and is automatically replaced in the body with an embedded script tag.

You can view the mail scripts in their original form by opening the email notification and clicking the Show Notification Scripts related link.

4.1 Handling Line Breaks

Rich HTML provides additional control over line breaks in your email notifications and templates. To accommodate this, a Newlines to HTML check box is available in the Email Script form to ensure that <mail_script> scripts work the same after an upgrade to Eureka.

Newlines to HTML.png

Selecting the Newlines to HTML check box indicates that the method for handling line breaks in earlier versions carries forward for email notifications and templates used in Eureka. When an email notification or template is converted to rich HTML, the Newlines to HTML check box is automatically selected.

For new mail scripts written in Eureka, it is a best practice to add correct HTML line breaks to template.print() statements.

If an email notification or template to rich HTML is not converted to rich HTML, newlines are automatically wrapped with <div> tags, the same as versions prior to Eureka. The old mail scripts still work; however, the administrator does not enjoy the benefits of working in the rich HTML format, and does not have as much control over exact HTML formatting.

4.1.1 Best Practice

When writing new scripts, it is best to insert explicit HTML line breaks and clear the Newlines to HTML check box so that no HTML tags are injected when email notifications are generated. The same approach is recommended for existing notifications and templates. That is, a best practice would be to replace template.print("\n") JavaScript function calls with template.print("<br />"). This gives you better control over the HTML formatting of your email notifications.

4.2 Handling Line Breaks in Versions Prior to Eureka

When emails are generated in versions prior to Eureka, the template.print() JavaScript function automatically injects HTML <div> tags whenever newline (\n) characters are present in scripts.

For example:

<mail_script>
template.print("line 1\n"); // Note that \n is Javascript's notation for a newline character
template.print("line 2\n");
</mail_script>

When an event triggers an email notification, every line in the script that ends with a newline character is wrapped with <div> tags, which is the way HTML introduces a line break.

For example:

<div>line 1</div>
<div>line 2</div>

5 Editing the HTML of an Email Notification

For added control over the content of a converted email notification, can edit the underlying HTML.

  1. With the converted email notification displayed in the Message text field, click the HTML button in the rich HTML editor.
    HTML source editor.png
  2. Make the needed changes to the HTML.
  3. Click Update.

6 Adding Images to Email Notifications

Images can be inserted into email notifications that were created in the Eureka release or that were converted to rich format using the HTML editor. The images can be stored in the image library in your instance, or they can be inserted as attachments.

7 Attaching Documents to a Notification

You can include all attachments from the source record with the notification. For example, if an incident update generates a notification, you can include all attachments from the incident record with the notification. To include all attachments from the source record, select the check box for the Include attachments field. Note that email messages, including attachments, cannot exceed the maximum email size. This size includes MIME encoding, which increases total attachment size by approximately 37%.

7.1 Attaching Documents with Scripting

Using scripting, you can attach documents by linking to them, or you can attach various types of reports by specifying their IDs in the system.

7.1.1 Linking to an Attachment

You can add attachments to a notification by linking to the attachment record in the message of the notification. Linking to attachment records in this fashion requires using email notification scripting. For example:

template.print('Attachment: <a href="/sys_attachment.do?sys_id=' + gr.sys_id + '">' + gr.file_name + '</a>\n');

7.1.2 Attaching Reports Using the Sys ID

You can also attach various types of reports, including gauges, dashboards, and charts, to a notification. The scripts to attach these reports take the following syntax:

${report:X:Y}

where:

X is the type of report you want to attach (reportID, gaugeID, dashboardID, or chartID).
Y is the sys ID of the report, gauge, dashboard, or chart to be attached.

For example:

  • ${report:reportID:<abc123>}
  • ${report:gaugeID:<abc123>}
  • ${report:dashboardID:<abc123>}
  • ${report:chartID:<abc123>}

8 Enabling Links to ServiceNow Records

Adding the special ${URI} parameter to an outbound email body or template creates a link to a specific ServiceNow record. When a user clicks on the word LINK, the instance prompts the user to log in if not already logged in, and then redirects the user to the record specified in the URI.

Link displayed by ${URI} parameter

The ${URI} parameter has an extension called the ${URI+} format to specify additional arguments in the email link, such as sysparm terms, in addition to the automatically created URI. For example:

${URI+&sysparm_scriptlet=current.assigned_to=gs.getUserID()
&sysparm_scriptlet_condition=current.assigned_to.nil()
&sysparm_view=incident_active}

This example executes the JavaScript:

current.asigned_to=gs.getUserID()

when the condition of

current.assigned_to.nil()

is satisfied. Additionally, the script sets the view to incident_active.

8.1 Changing the Link Text

To show the display value of the record as the link text instead of the word LINK, use the ${URI_REF} parameter instead of the ${URI} parameter.

Link displayed by ${URI_REF} parameter

For example, if the URL displays an incident record, the link text is the incident number, which is the display value for incidents. If the URL displays a user record, then the link text is the user name.

8.2 Linking to Related Records

A notification can link to a related record by specifying a reference field in front of the ${URI} or ${URI_REF} parameters. Format the related record link as follows:

  • ${<reference field that contains the related record you want to display>.URI}
  • ${<reference field that contains the related record you want to display>.URI_REF}

For example:

Related Record to Provide Link to Notification record table Reference Field Samples
Related task record to be approved from an approval notification Approval [sysapproval_approver] Approval for [sysapproval]
  • ${sysapproval.URI}
  • ${sysapproval.URI_REF}
Related problem record in an incident notification Incident Problem [problem_id]
  • ${problem_id.URI}
  • ${problem_id.URI_REF}

For example, the following notification template produces the email links in the picture below:

Click here to view Incident: ${URI_REF}
Click here to view Related Problem: ${problem_id.URI_REF}
Example related record links

8.3 Linking to Content Pages

You can create links to content management pages using the following format:

${CMS_URI+<site>/<page>}

For example, to link the email recipient to a page called Incident in the content site ESS, with the current incident as the target document, use the following format:

${CMS_URI+ess/incident_detail}

The resulting email URL has this format:

https://<instance name>.service-now.com/ess/incident_detail.do?sysparm_document_key=incident,46e18c0fa9fe19810066a0083f76bd56

9 Working with Watermarks

By default, ServiceNow generates a watermark label at the bottom of each notification email to allow matching incoming email to existing records. The watermark always includes "Ref:" and a customizable prefix (default MSG), followed by the autonumbered identifier of the source record (such as incident, problem, or change request). For example, Ref:MSG3846157.

Watermarks are always generated, but you can configure them to:

  • Have custom prefix characters after MSG
  • Be hidden globally
  • Be omitted from individual email messages

Any custom prefix you select must begin with MSG. Inbound email actions might not work properly if watermarks are omitted from email notifications. Without a watermark, inbound email messages cannot be associated with the accumulated comments related to the original incident, and each subsequent notification that is sent is treated as a new incident.

Note
Note:
  • Do not use colons (:) in custom watermark prefixes. Colons are a reserved character and may cause the watermark to be ignored.
  • Email clients that use the plain text version of the email still show the watermark.


9.1 Hiding Watermarks Globally

Rather than omitting watermarks, it is possible to hide watermarks on a global basis using HTML markup.

  1. Navigate to sys_properties.list in the Application Navigator.
  2. Create a new property named glide.email.watermark.visible and set it to false.

This ensures that all watermarks are hidden on all email messages. This cannot be done on a per-email basis.

9.2 Omitting Watermarks on Individual Email Notifications

When incoming email does not contain a watermark, either because it has been omitted or hidden, ServiceNow searches the subject line and message body for an incident number. ServiceNow attempts to match any incident number it finds to an existing incident. If there is a matching incident number, ServiceNow updates the incident with the values in the incoming email.

To omit watermarks on a per-email basis:

  1. Navigate to System Policy > Email > Notifications.
  2. Select the email notification to update.
  3. Click the Advanced View related link.
  4. In the What it will contain section, select the Omit watermark check box.
  5. [Optional] If you want response email messages to generate new incidents, remove the record number ${number} variable from the Subject and Message HTML fields.

9.3 Creating Custom Watermark Prefixes

By default, email notifications use the watermark prefix MSG. Any email notifications that are forwarded from one instance to another might be indistinguishable because they use the same watermark. To avoid unintentionally triggering events in the wrong instance, ServiceNow recommends creating a unique watermark prefix for each instance.

To create a unique watermark prefix for an instance:

  1. Navigate to System Definition > Number Maintenance.
  2. Open the sys_watermark record.
  3. Make the Prefix unique for this instance.

    Watermark Prefix.png

  4. Click Update.

10 Specifying Alternative Outbound Email Addresses

By default, ServiceNow sends all outbound email notifications from the default email address of the instance. For organizations that need to send email messages from specific email addresses, such as from multiple service desks, or they want to send notifications in different languages, the platform supports the configuration of multiple outbound addresses.

To create a notification for a different outbound email address:

  1. Navigate to System Policy > Email > Notifications.
  2. Select an existing notification record for the desired event, such as Incident Closed.
  3. Create a copy of this notification for each outbound email address.
  4. Open one of the notification copies, and click the Advanced view related link.
  5. In the What it will contain section, add an email address to the From field that is different from the default instance address.
  6. Add a different email address than the From address to the Reply to field if you want replies to this notification to go to a different address.
    The system checks the From field for an address. If this field is empty, then the system uses the default address for the instance. If the Reply to field is empty, then all replies are sent to the address from which the notification was sent. If the Reply to field contains an email address, then the system sends all replies to the notification to this address.
  7. Create mutually-exclusive conditions for notifications of the same type, so only the desired notification is sent when the event is fired.
    For example, if the Company is a certain value, then the notification comes from a unique email address entered in the From field.
  8. Click Update.

10.1 Specifying An Outbound Email Address for a Particular Language

You can specify a different email address for each language your instance supports.

  1. Create or copy a notification record for the desired event.
  2. In the What will it contain section, enter a new email address in the From field.
  3. Create the Subject and Message content in the desired language.
  4. In the When to send section, create a condition as follows:
    a. In the list of Condition fields, select Show Related Fields from the bottom of the choice list.
    b. From the choice list of Related Fields, select the field that identifies the recipient.
    For example, select .Caller-->User fields to send the notification to the user who called in an incident, or .Assigned to-->User fields to send the notification to the user to whom an incident is assigned.
    c. From the choice list of user fields, select Language.
    d. Select the is operator.
    e. Complete the condition by selecting the language of the desired user.
  5. Click Update.
    All notifications for that event originate from the specified email address and go out in the language of the recipient.

11 Specifying the Time Zone

The date and time stamp of a notification uses the system time zone and not the time zone of any recipient. The property glide.email.append.timezone in System Properties > Email controls whether to append the time zone. If true, the system time zone of the instance is appended to any dates or date/times in outbound email messages (for example, 2010-07-02 04:01:14 PST).

12 Setting the Date Field for a Calendar Invitation Notification

You can specify what field provides the date information in calendar invitation notifications by changing the mappings of the dtstart and dtend variables in the iCalendar invitation transformation map.

  1. Navigate to System Imports > Maps.
  2. Open the icalendar.change_request map.
  3. In the Field Maps related list, click either the end_date or start_date mapped field to change the mapping for dtstart or dtend, as needed.
  4. Change the Database Field to the ServiceNow field you want to use to set the start date or end date.
  5. Click Update.

13 Troubleshooting Email Notifications

For a list of common email notification errors and their solutions, see this ServiceNow Knowledge Base article: KB0535129.

14 Configuring the Platform for Incoming Email

To configure the platform to create ServiceNow records and perform other tasks from incoming email, see Inbound email actions.

15 Advanced View Fields

Field Description
Email Notifications - Who will receive
Send to event creator Select this check box to send the notification to the person who performed the action that started the notification process if the person is also specified in the Users/groups in fields, Users, or Groups field. If the event creator is not specified in one of these fields, the event creator does not receive a notification regardless of the setting in this field.
Event parm 1 contains recipient Select this check box if the event parameter 1 contains one or more email recipients (in a comma separated list). This field is visible only when the Send when field is set to Event is fired.
Event parm 2 contains recipient Select this check box if the event parameter 2 contains one or more email recipients (in a comma separated list). This field is visible only when the Send when field is set to Event is fired.
Subscribable Select this check box to allow users to subscribe to notifications defined as subscribable.
Warning
Warning: Do not select this check box for any other type of notification. See Subscribable Notifications for details.
Email Notifications - What it will contain
Importance Set the importance of the email message to low or high.
Content type Select the content type for the email notification:
  • HTML and plain text
  • HTML only
  • Plain text only

By default, HTML only is enabled.

Include attachments Select this check box to send all attachments from the triggering record as email attachments.
Omit watermark Use this check box to apply or remove the watermark attached to each email. ServiceNow does not recommend removing the watermark as a reply to an email without a watermark creates a new incident rather than updating the incident the original email referred to. For more information, and an alternative way to hide watermarks, see: Watermarks.
Message Text Enter the notification message to send in plain text. This field is visible only if you set the content type to HTML and plain text or Plain text only.
From Enter the email address you want the email notification to use in the From field. For example, helpdesk@yourcompany.com.
Reply to Enter the email address you want people to use when replying to the email notification. For example, helpdesk@yourcompany.com.
Was this article helpful?
Yes, I found what I needed
No, I need more assistance
Views
Personal tools