Email Notifications

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

Contents

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 instead.

Email notifications allow administrators to specify:

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

Users can choose whether to receive email notifications by setting a preference on their User record.

If the Subscription Based Notifications plugin is active, additional email notification options are available. Users can subscribe to notifications and administrators may make some notifications mandatory. See Email Notifications for all the tasks required to create and send custom emails when ServiceNow events occur.

2 Enhancements

2.1 Calgary

The following enhancement is available as of the Calgary release:

  • Email notifications no longer support the email.setFieldsInCurrent() method.

2.2 Berlin

The following enhancements are available as of the Berlin release:

3 Creating an Email Notification

Creating an email notification requires:

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

3.1 Identifying the Notification

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

  • Name
  • Table
  • Description
  • Type
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. Enter values for the Email Notification form. As of Berlin, enter these fields.
    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. For example, Incident [incident].
    Description Enter an optional description for the notification.
    Type (Visibile from the Advanced view) Select whether the notification is an email or a meeting invitation.
    Active Select the check box (true) to enable email notification.
  5. Continue creating the notification by specifying when to send the notification.

3.2 Specifying When to Send the Notification

As of the Berlin release administrators can choose when to send a notification based on the type of triggering event. Note that on instances with a large number of events, there may be a slight delay in processing the email event. The instance can send a notification in either one of these circumstances.

  • When a record is inserted or updated (available as of Berlin)
  • When a specific event runs

When creating a notification based on a new or updated record, you can specify what additional conditions must be met in order to trigger the notification. These Changes conditions do not work with notifications generated from events. As of Berlin, 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. Enter values for the Email Notification form. As of Berlin, enter these fields.
    Field Description
    Send when Select whether the email notification runs when a record is inserted or updated or if the notification runs when a particular event is triggered.
    Weight Set the sending priority of the notification in relation to other notifications on the same table. When there are multiple notifications in the Outbox that are from the same notification table and addressed to the same recipients, ServiceNow uses the weight to determine which notification to send. ServiceNow only sends the notification with the highest weight. All other notifications are moved from the Outbox to the Skipped mailbox.

    Set a numerical value from 0 to the maximum field size for the weight. The default value 0 causes ServiceNow to always send the notification (assuming the conditions are met). This field cannot be empty.

    For example, suppose a service desk agent adds a comment to an incident and then shortly thereafter closes it. Normally, 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 Select the conditions under which this notification is sent. For example, you might select Priority > greater than > 3 - Moderate.
    Inserted Select the check box (true) to enable email notification when a record is inserted. This field is only visible when the Send when field has the value Record inserted or updated.
    Updated Select the check box (true) to enable email notification when a record is updated. This field is only visible when the Send when field has the value Record inserted or updated.
    Event name Select the event that triggers this notification. This field is only visible when the Send when field has the value Event is fired.
  3. Continue creating the notification by specifying who receives the notification.

3.2.1 Optional: Specifying Advanced Conditions

By default, the Advanced condition field is hidden from the Email Notification form. Personalize the form to add the field if you want to add a script-based condition. Use an advanced condition to send a notification based on the current email record, changing field values, or system properties. Your advanced condition script must set a global answer variable to true in order to send the notification.

The advanced condition script has access to 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 field

3.3 Specifying Who Receives the Notification

You can send notifications to the following users and groups.

  • 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 (Berlin release).

Use these steps to specify who receives the notification.

  1. Identify the notification.
  2. Specify when to send the notification.
  3. Enter values for the Email Notification form. As of Berlin, enter these fields.
    Field Description
    Users/groups in fields Click the lock icon to 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 such as the Opened by or Assignment group fields. 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 selecting the plus sign from the field selector and then selecting the related field.

    Click the plus sign to show the fields from a related reference field.

    Click the related field to add a dot-walk reference.


    Users Click the lock icon to select the users to receive the email notification. You can search for users with the reference icon or manually add users name by their email address. This list of users is static.
    Groups Click the lock icon to select the groups to receive the email notification. You can search for groups with the reference icon or by group name. This list of groups is static.
    Send to event creator (Visibile from the Advanced view) Select this check box (true) to send the notification to the person who performed the action that started the notification process if the person is also specified in one of the Users/groups in fields, Users, or Groups fields. If the event creator is not specified in one of these fields, then the event creator does not receive a notification regardless of the value of the Send to event creator field.
    Event parm 1 contains recipient (Visibile from the Advanced view) Select this check box (true) if the event parameter 1 contains the email recipient. This field is only visible when the Send when field has the value Event is fired.
    Event parm 2 contains recipient (Visibile from the Advanced view) Select this check box (true) if the event parameter 2 contains the email recipient. This field is only visible when the Send when field has the value Event is fired.
    Subscribable Select this check box to allow users to subscribe to specific notifications defined as subscribable.
    Warning
    Warning: Do not check this field for any other type of notification. See Subscribable Notifications for details.
  4. Continue creating the notification by specifying what content the notification contains.

3.4 Specifying What Content the Notification Contains

There are no required content elements of an email notification, however, you can specify one or more of the following content options in your email notifications.


Sample email notification content using an email template

Use these steps to specify the content of an email notification.

  1. Identify the notification.
  2. Specify when to send the notification.
  3. Specify who receives the notification.
  4. Enter values for the Email Notification form. As of Berlin, enter these fields.
    Field Description
    Importance Set the importance of the email message to low or high.
    Content type (Visibile from the Advanced view) Select between HTML and plain text or Plain text only. By default, HTML is enabled.
    Include attachments Select this check box (true) to send all attachments from the triggering record as email attachments.
    Omit watermark (Visibile from the Advanced view) 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.
    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 Enter the content of the email message. The message can include variables from the Select variables column as well as HTML code if you set the content type to HTML and plain text. 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.

    Notes:

    SMS alternate Enter the notification message to send to an SMS device. The SMS alternate message is limited is 140 characters.
    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.
  5. Continue creating the notification by specifying what content the notification contains.

4 Adding HTML Markup

When the email format is multipart/mixed, you can add HTML markup to the body of the message. For example, this HTML markup:

This message will have <b>these words</b> in Bold!  

Results in the following message text:

This message will have these words in Bold!

4.1 Adding Images

HTML email can include images stored on either the instance or accesible from a network address.

To use an image stored on the instance:.

  1. Upload the image to your instance. See Storing Images in the Database for instructions on uploading images.
  2. Navigate to System Policy > Email > Notifications.
  3. Select the email notification to which you want to add an image.
  4. Edit the Message field, and add an image link to the uploaded file. The image link uses this format:
    <img src="https://instance_name.service-now.com/image_name.gifx"></img>
  5. Click Update.

To use an image from a network address:

  1. Navigate to System Policy > Email > Notifications.
  2. Select the email notification to which you want to add an image.
  3. Edit the Message field, and add an image link to the uploaded file. The image link uses this format:
    <img src="http://example.domain.com/image_name.png"></img>
  4. Click Update.

5 Attaching Documents

You can include all attachments from the source record with the notification. For example, if an incident updates 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 checkbox for the Include attachments field. Note that emails, including attachments, cannot excede 26 MB. This size includes MIME encoding which increases total attachment size by approximately 137%.

5.1 Attaching Documents with Scripting

You can also 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="http://[INSTANCE_NAME].service-now.com/sys_attachment.do?sys_id='
+ gr.sys_id + '">' + gr.file_name + '</a>\n');

6 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.

6.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.

6.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

6.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

7 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.

The generation of watermarks is hardcoded into the system, but you can configure email notifications to use a different prefix instead of MSG, hide watermarks globally, or omit watermarks from individual emails. Any custom prefix you select must begin with MSG. It is important to note that inbound email actions might not work properly if watermarks are omitted from email notifications. Without a watermark, inbound emails 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: Email clients that use the plain text version of the email still show the watermark.


7.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 emails. This cannot be done on a per-email basis.

7.2 Omitting Watermarks on Individual Emails

If watermarks must be omitted on a per-email basis, select the Advanced View from the Email Notification form, and select the Omit Watermark checkbox.

  1. Navigate to System Policy > Email > Notifications.
  2. Select the email notification to update.
  3. Click the Advanced View link.
  4. Select the Omit watermark checkbox in each email notification record in which you want to suppress the watermark.
  5. [Optional] If you want response emails to generate new incidents, remove the ${number} variable from the notification record's Subject and Message fields.
Note
Note: When incoming email does not contain a watermark, 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. If you want email replies to generate new incidents instead, remove the ${number} variable from the original notification so the reply does not contain an incident number. This behavior only applies to emails that reply to or forward an email generated by ServiceNow.


7.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. It should be noted, however, that this should be done very early in the development process. If the system already has lots of incidents, the watermark table may be populated with obsolete watermark prefixes that do not match properly.

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.
    Note: All watermark prefixes must begin with the string MSG. Add a unique string to the end of the MSG prefix.

    Watermark_Prefix.png‎

  4. Click Update.

8 Specifying Alternate 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 emails 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. In addition, you can define a different email address for responses than the address from which the notification was sent.

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. For example, Incident Closed.
  3. Create a clone of this notification for each outbound email address.
  4. Add an email address to the From field that is different from the default instance address.
  5. 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 platform checks the From field for an address. If this field is empty, then the platform 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 platform sends all replies to the notification to this address.
  6. Create mutually-exclusive conditions for notifications of the same type, so only the desired one will send 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.
  7. Submit the record.

8.1 Specifying An Outbound Email Address for a Particular Language

You can specify a different email address for each language your instance supports. To configure notifications for different languages for multiple outgoing email addresses:

  1. Create or clone a notification record for the desired event.
  2. Enter a new email address in the From field.
  3. Create the Subject and Message content in the desired language.
  4. Create a condition as follows:
    a. In the list of Condition fields, select Show Related Fields from the bottom of the drop-down list.
    b. From the drop-down 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 drop-down list of user fields, select Language.
    d. Select the operator is.
    e. Complete the condition by selecting the language of the desired user.
  5. Submit the record.
    All notifications for that event will originate from the specified email address and go out in the language of the recipient.

9 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).

10 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 set the start date or end date.
  5. Click Update.

11 Troubleshooting Email Notifications

Here is a list of common email notification errors and their solutions.

Error or Symptom Solution
A specific user is not receiving email notifications Your notification preferences might be set to Disable instead of Enable. Check your notification preferences.
  1. Click Self Service > My Profile.
  2. Verify that the Notification field is set to Enable.
Check your profile's notification preferences

Closing a new incident does not generate an Incident Opened notification The Incident Opened email notification has a condition of active is true. This means that it will only send out the notification if the new incident is active. When using the Close Incident button to submit a new incident, the incident is considered inactive and the notification does not go out. You can create a custom email notification to cover this use case if desired.
Notification fails with the error SMTPSender: no recipients, email send ignored. This error occurs when an email notification is generated but has no valid recipients based on its notification definition. For instance, an email that would be sent to the 'assigned_to' user from an incident can't send because the incident is not assigned to anyone. Review who receives the email notification and make sure there is at least one valid user for the email notification.
Some users receive email notifications but other users do not receive email notifications There are two possible reasons why users may not receive email notifications.
  • The user chose not to receive email notifications. There is a flag in the user record that specifies the notification method. Go to the user record (User Administration > Users) and display the user that is not getting email. Check the choice list in the Notification field. If this user is not getting email, the choice is probably set to Disable. Use the drop down to select the Enable option. Note that changing choice list values can cause all notifications to fail. Do not modify these choice values.
  • The user is the event creator. By default, ServiceNow does not send an email to the person who caused the email action. For example, if you assign an incident to yourself, the system does not notify you that the incident has been assigned to you. If you are testing the system, you might want an email delivered to check your configuration. This default behavior can be changed so that the event creator does receive emails. Select System Policy > Email > Email Notifications and open up the notification of interest. Select the check box for Send to event creator and add yourself to the list of notified users to ensure that you receive notifications.

12 What Do I Do Next?

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

Was this article helpful?
Yes, I found what I needed
No, I need more assistance
Views
Personal tools