Scripting for Email Notifications

From ServiceNow Wiki
Home > Script > Server Scripting > Scripting for Email Notifications
Jump to: navigation, search
Note
Note: This article applies to Fuji and earlier releases. For more current information, see Scripting for E-mail Notifications at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.


Notifications
Knowledge.gif Get the Book

1 Overview

Mail scripts allow for business rule-like scripting within an outbound email message. With mail scripts, you can dynamically change the email output of your system based on different criteria. Mail scripts allow you to perform simple tasks, such as displaying incident data, and complex ones, such as making advanced database queries.

Create mail scripts in System Policy > Email > Notification Email Script starting with the Eureka release. Then add a ${mail_script:script name} embedded script tag to the body of the email notification or template, replacing script name with the name of the script you created. This makes it easy to use the same scripts in multiple email notifications or templates.

Mail scripts are added directly in the Message field when creating email notifications or email templates in versions prior to Eureka.

2 Using JavaScript in Emails

To embed JavaScript in the Email Notification form, use ${mail_script:script name}, and refer to the notification script. To print text into the body of the message, use the template.print("a string") function.

JavaScript in Templates.png

2.1 Parm1 and Parm2

The event.parm1 and event.parm2 parameters that come from the originating event can also be used within the <mail_script>. To use these, enter event.parm1 or event.parm2 in the mail script.



Note
Note: This article applies to Fuji. For more current information, see Enabling Links to Records at http://docs.servicenow.com

The ServiceNow Wiki is no longer being updated. Please refer to http://docs.servicenow.com for the latest product documentation.


3 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.assigned_to=gs.getUserID()

when the condition of

current.assigned_to.nil()

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

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

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

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

4 Examples

4.1 Simple Text String

A simple text string is the most basic example of the way a mail script works. This script prints out "Incident number - INC00001".

   template.print("Incident number - " + current.number);

4.2 Summary of Requested Items

More advanced scripts, like the one below, can be found by browsing through the base system email templates.

template.print("Summary of Requested items:");  
var gr = new GlideRecord("sc_req_item");
gr.addQuery("request", current.sysapproval);
gr.query();
while(gr.next()) {
    var nicePrice = gr.price.toString();
    if (nicePrice != ) {
        nicePrice = parseFloat(nicePrice);
        nicePrice = nicePrice.toFixed(2);
    }
    template.print(gr.number + ":  " + gr.quantity + " X " + gr.cat_item.getDisplayValue() + " at $" + nicePrice + " each");
    template.print("    Options:");
    for (key in gr.variables) {
      var v = gr.variables[key];
      if(v.getGlideObject().getQuestion().getLabel() != '') {
         template.space(4);
         template.print('     ' +  v.getGlideObject().getQuestion().getLabel() + " = " + v.getDisplayValue());  
      }
    }
}

4.3 Overriding Email Fields

To dynamically change field values within an email, use the following functions within <mail_script> syntax:

...
email.setFrom(current.caller_id.email);
email.setReplyTo("joe.employee@yourcompany.com");
email.setSubject("This is the new subject line");
email.setBody("This is the new body");
...

4.4 Attachments Sent in Notifications

Using the instance_name property ensures that the notification still works when migrated between instances.

dothis();

function dothis() {
    var gr = new GlideRecord('sys_attachment');
    gr.addQuery('table_sys_id',current.sys_id);
    gr.query();
    while (gr.next()) {
        template.print('Attachment: <a href="https://' + gs.getProperty('instance_name') + '
            .service-now.com/sys_attachment.do?sys_id=' + gr.sys_id + '">' + gr.file_name + '</a>');
    }
}

4.5 Adding CC and BCC Recipients

You can specify copied and blind copied recipients by using the email object within a mail script.

    //email.addAddress(type, address, displayname);
    email.addAddress("cc", "john.copy@example.com","John Roberts");
    email.addAddress("bcc", "john.secret@example.com","John Roberts");

The following is an example script to add users from watch_list as copied recipients.

if (!current.watch_list.nil()) {
   //get watch list addresses and add to cc
   var watcherIds = current.watch_list.split(",");
 
   //get user records
   var user = new GlideRecord("sys_user");
   user.addQuery("sys_id", watcherIds);
   user.addQuery("notification", 2); //email
   user.addQuery("email", "!=", "");
   user.query();
 
   while (user.next()) {
      //add to cc list    
      email.addAddress("cc", user.email, user.getDisplayValue());
   }
}

5 Mail Script API

The following variables are available when processing mail_script scripts.

Variable Object Description
template Handles printing from the mail script to the email message.

template.print("message"); //outputs message to the email body.
template.space("number of spaces"); //outputs spaces to the email body.

email_action GlideRecord object for the email notification (sysevent_email_action).
event GlideRecord object for the event that fired the notification (sysevent).
email EmailOutbound object

Available methods:

  • addAddress(String type, String address, String displayname): type can be cc or bcc.
  • setFrom(String address): override the sender address.
  • setReplyTo(String address): override the reply to address.
  • setSubject(String subject): override the subject of the message.
  • setBody(String message): override the body of the message.

The email address that is passed by setFrom and setReplyTo needs to be in a valid form such as 'helpdesk@sn.com' or 'Display Name <helpdesk@sn.com>'. If the email address includes a 'Display Name', then that value overrides the instance's display name.

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