Inbound email processing

The system determines which inbound actions to run by comparing the inbound email type and inbound action conditions to the incoming email message. Certain properties are available to set the reply and forwarding prefixes in the email subject lines that your instance recognizes when processing inbound emails.

The system follows this processing flow to determine whether to run an inbound action.

Figure 1. Inbound action processing work flow
The system only runs an inbound action when:
  • The incoming email type matches the inbound action Type.
  • If present, the watermark or record number refers to a record in the Target table.
  • The inbound action Conditions evaluates to true.

If any of these criteria are not met, the system skips the current inbound action and evaluates the next active inbound action. The system processes inbound actions from the lowest to highest Order value. If the inbound action has Stop processing enabled, then the system updates the State of the email record to Processed after running the inbound action Script.

The following video shows how an inbound action condition prevents an incident from being created.

Prefixes recognized in email subject lines

Email reply prefixes
When no watermark is present or the In-Reply-To email header is present, the instance recognizes email containing a prefix from the glide.email.reply_subject_prefix property as reply email. You can use this property to set non-standard reply prefixes in your email system.
Property Description
glide.email.reply_subject_prefix Specifies the list of prefixes (comma-separated) in the subject line that identify an email reply.
  • Type: string
  • Default value: re:,aw:,r:
  • Location: Add to the System Properties [sys_properties] table
Note: Prefixes are case insensitive.
Email forward prefixes
Emails with certain prefixes trigger the forward type of inbound email action. The instance recognizes any email whose subject line contains a prefix from the glide.email.reply_subject_prefix property as forwarded email. Emails with these prefixes trigger inbound email actions of the type forward. Use this property to set non-standard forward prefixes in your email system or you want email forwards to behave like replies.
Property Description
glide.email.forward_subject_prefix Specifies the list of prefixes (comma-separated) in the subject line that identify a forwarded email.
  • Type: string
  • Default value: fw:,fwd:
  • Location: Add to the System Properties [sys_properties] table
Note: Prefixes are case insensitive.
Email forwards as replies
Properties are available to force inbound actions to process forwarded mail as replied mail. These properties control the subject prefix that the inbound actions use.
Property Value needed
glide.email.reply_subject_prefix re:,Re:,RE:,aw:,r:,fw:,fwd:,Fwd:,FWD:
glide.email.forward_subject_prefix [any text that is not a forward prefix]
These properties cause the Update Incident inbound action to process all forwarded and replied-to mail.
Note: The glide.email.forward_subject_prefix property must contain some text so that the forwarded email can be processed as a Reply. It can be any text except a forward prefix (that is, fw:,fwd:,Fwd:,FWD:).

Matching a sender email address to a user

The instance matches a senders email address to an active user in the User [sys_user] table using inbound actions.

Note: The Email Automatic User Creation plugin must be active.

When processing an email, the instance sets the current user to the user whose email address matches email.from. Inbound actions can then reference that current user. For example, the base system inbound action Create Incident sets the caller_id of the incident to the value returned by gs.getUserID().

If multiple users have the same email address, the instance first searches for an active user with the email address. The instance does not match inactive users.

Note: Each user record must have a unique email address so that the instance can reliably match the email to the correct user.
If a unique email address for each user is not possible, assign a shared email address to only one active user so that the instance always matches incoming email from that address to the active user.

Matching watermarks in the Subject line or Body

The following examples illustrate how the instance matches randomized watermarks in an email subject line or body.

Note: For instances upgraded from a release before Jakarta, the system can recognize both randomized and non-randomized watermarks during a watermark transition period. For details, see the Notifications upgrade information .
Table 1. Examples of matching watermarks in the Subject line or body
Subject Line or Body Contents Matching Results
Ref:MSG0000008_ aLJc130zDhCVuh3spXmt The instance recognizes this string as a watermark and searches the Email Watermarks [sys_watermarks] table for a record with the number MSG0000008_ aLJc130zDhCVuh3spXmt. If this watermark exists, the instance matches the email to the associated record. If this watermark does not exist, the system processes inbound email messages as described in Criteria for matching email to inbound actions.
Ref:MSGWTR0000008_wfLLz42IxCgUvG2JlYnh The instance recognizes this string as a watermark and searches the Email Watermarks [sys_watermarks] table for a record with the number MSGWTR0000008_wfLLz42IxCgUvG2JlYnh. If this watermark exists, the instance matches the email to the associated record. If this watermark does not exist, the system processes inbound email messages as described in Criteria for matching email to inbound actions.

Matching record numbers in the Subject line or Body

The following examples illustrate how the instance matches record numbers in the subject line of an email to an existing record when no watermark is present.

Table 2. Examples of matching record numbers in the Subject line
Subject line contents Matching results
RE: Example INC0005574 The instance recognizes this subject line as a reply and recognizes the INC prefix as belonging to the Incident table. The instance searches the Incident table for an existing record INC0005574. If this incident exists, the email is associated with this incident. If this incident record does not exist, the instance uses the inbound action for new emails to create an incident and associates the new incident with the email.

RE: Example "INC0005574"

RE: Example *INC0005574

The instance recognizes this subject line as a reply but does not recognize the "INC prefix as belonging to the Incident table because of the quotation mark. The same error occurs for any character other than a space before the record number. The instance instead uses the inbound action for new emails to create an incident and associates the new incident with the email.

RE: "Example INC0005574"

RE: Example INC0005574*

The instance recognizes this subject line as a reply and recognizes the INC prefix as belonging to the Incident table. The instance searches the Incident table for an existing record INC0005574", which it cannot find because of the quotation mark. The same error occurs for any character other than a space at the end of the record number. The instance instead uses the inbound action for new emails to create an incident and associates the new incident with the email.
RE: CHG0008593 and INC000576 The instance recognizes this subject line as a reply and recognizes one, but not both, of the number prefixes. There is no way to predict which prefix the instance matches first. Whichever prefix it matches, it searches the corresponding table for a matching record. If the record exists, the email is associated with the table. If the record does not exist, the instance uses the inbound action for new emails to create an incident and associates the new incident with the email.
Note: The instance does not support processing email with multiple numbers in the subject line because there is no way to predict which record the instance matches first. For this reason, do not include more than one $number variable in your notifications.
FW: Example INC0005574 The instance recognizes this subject line as a forward because of the FW: prefix. It uses the inbound action for forwarded emails to create an incident and associates the new incident with the email.
Example INC0005574 The instance recognizes this subject as a new email because it does not contain a matching reply or forward prefix. It uses the inbound action for new emails to create an incident and associates the new incident with the email.

Criteria for matching email to inbound actions

The system matches incoming email to the conditions of the active inbound actions.

The default inbound actions create or update task record under these conditions.

Figure 2. Default matching criteria
Work flow for matching email to the default inbound actions

If you customize or deactivate the default inbound actions, the system checks the conditions of the active inbound actions. If the system cannot find an inbound action with matching conditions, it sets the state to Processed.

Figure 3. Custom matching criteria
Work flow for matching email to custom inbound actions
Table 3. Inbound action type criteria
Inbound email action type Required matching criteria Name of default action (Incident table) Result of default action
Forward The email contains the following conditions:
  1. A subject starting with a recognized forward prefix (even if a watermark or an In-Reply-To header is present).
  2. From <user email> appears anywhere in the email body.
Create Incident (Forwarded) Create new record
Reply The email contains one of the following conditions and the table specified in the email matches the table of the inbound action:
  1. A valid watermark that matches an existing record.
  2. An In-Reply-To email header (when no watermark is present) that matches an existing record.
  3. A subject line starting with a recognized reply prefix (when neither a watermark nor an In-Reply-To header is present) and a valid record number that matches an existing record.
Update Incident (BP) Update existing record
New The email does not meet the conditions for either a reply or forward type inbound email action Create Incident Create new record

If more than one inbound action is available for a particular type, the instance uses the Table field to match the email to a particular table. If there is also more than one action for the inbound action's table, the instance uses the Order field to determine the order in which the actions run.

Example assignment of tasks via email

Name:value pairs in an email template can set field values in a record.

For example, the change.itil.approve.role email template lists several fields in the outbound notification.
Figure 4. The Email Template form
Notice the line in the template that shows Priority:${sysapproval.priority}. When replying to this email, the approver can change the value of the Priority field directly from the email. For example, the approver could set the priority to 4- Low:
Priority: 4

Email user matching

When the instance receives an email message, the system searches for an existing user record with the same email address as the sender.

Table 4. Matching email to existing users
Value of email.from Variable Matching User ID Email Address Name
michael.tossi@company.com michael.tossi@company.com michael.tossi@company.com Michael Tossi
"Michael Tossi" <michael.tossi@company.com> michael.tossi@company.com michael.tossi@company.com Michael Tossi
"Tossi, Michael" <michael.tossi@company.com> michael.tossi@company.com michael.tossi@company.com Michael Tossi
"Tossi" <mtossi@company.com> mtossi@company.com mtossi@company.com Tossi
Note: This functionality requires that you activate the Email Automatic User Creation plugin.

Inbound Email Action scripts no longer support the gs.createUser() method. Use either the automatically-generated email variables or the gs.GetUserID() method instead.

User impersonations and inbound actions

When the instance receives an email, it can take a variety of actions by impersonating the sender.

If the sender of an incoming email matches an existing user, the instance impersonates the matching user to complete any inbound email actions. If the sender does not match an existing user, the instance impersonates the Guest user to complete any inbound email actions. If the impersonated user is locked out , the inbound email action fails.

Note: If inbound email comes from an untrusted domain, the instance impersonates the Guest user unless you explicitly prevent users from untrusted domains from triggering inbound actions.

Setting field values from the email body

Values in an inbound email can set field values in a task record.

Any name:value pair in an inbound email body gets parsed into a variable/value pair in the inbound email script. The name:value pair must be on its own line. Note that most email clients limit the number of characters allowed per line and may truncate excessively long name:value pairs.

To populate a reference field, use setDisplayValue() instead. See Redirecting Emails for an example of using setDisplayValue() in an inbound email action.

Note: The action always generates a lowercase variable name. Also, this functionality does not work on reference fields.
For example, if an email body contains this line:
Foo:bar
The inbound email script creates the variable email.body.foo with the value of bar. You can use these variables to create conditions such as:
if(email.body.foo!=undefined){
   current.[field]=email.body.foo;}
In this example, the script sets the value of [field] to the value bar.

Redirecting email to the instance POP3 account

You can have other mailboxes forward email to the instance's POP3 account.

By default, the POP Reader scheduled job checks for new email every two minutes. It connects to the mail server and account specified in email properties. The POP Reader downloads any email waiting on the mail server and creates email.read events. After the instance processes the events, the inbound email actions run.

The POP Reader shows the number of emails processed during the reader's last run. The message shows the number of emails the reader processed or 0 processed if no emails were available. The reader resets the status each time it runs.

While it is not possible to specify more than one POP3 account for the instance, you can forward other mailboxes to the designated POP3 account. This script can be added to the Create Incident inbound email action to differentiate the content based on the original recipient, and then set an assignment_group value.

if(email.direct.indexOf('facilities@anycorp.com')>-1)
current.assignment_group.setDisplayValue('Facilities Management');

Integrate inbound events

This example illustrates how to create a notification from an inbound JSON request.

Before you begin

Role required: admin

About this task

When complete, you will be able to:

  • Send a JSON request to the imp_notification web service import set with the JSON processor
  • Create a new import set in the imp_notification table in the instance using data from the JSON request

The following example steps assume you have your own demonstration instance.

Procedure

  1. Activate the JSON Web Service plugin.
  2. Install the RESTClient Firefox plugin.
  3. Open the RESTClient.
  4. Create the following JSON request.
    • Method: POST
    • URL: http://<instance name>.service-now.com/imp_notification.do?JSON
    • Headers: Authorization: Basic
    • Body:
      {"sysparm_action":"insert","message":"this is an event","uuid":"abc"}
    The REST JSON request
  5. Click Send.
  6. Navigate to Response > Response Body (Raw).
  7. Verify that the instance sends back a response with a sys_id.
    The REST response
  8. Login to your development instance.
  9. In Navigation filter, enter imp_notification.list.
  10. Verify that the import set table has an event matching your JSON request.
    REST import set table