Working with Email Inboxes

Use this feature to create a business object, such as an incident, from an email. After an incident or other business object record is created (or updated), the application attaches the email to the record (in the Activity History tab) and moves the email from the inbox folder to the archived folder.

If a user exists or is created, the application adds the associated email to the employee record for the user.

About Creating Incidents from Emails

The default Service Manager application comes with one inbox, which is based on the Incident business object. When you send an email to this inbox, the email listener processes the incoming message and creates an incident.

About Creating Other Business Object Types from Emails

You can create additional inboxes for other business objects. To process emails from other business objects, you must create an inbox for each business object. You must define a template for each business object so that users can submit emails in the correct format.

We recommend that you create new inboxes for other business objects after you modify the default inbox.

About Updating a Service Request via Email

You cannot create service request records from incoming emails; however, you can update service request records from incoming emails.

The corresponding field names and field values in the record are updated from the email and the email is attached to the record under the Activity History tab.

If the email body does not contain valid field names and field values, then an attempt is made to search for the service request from the service request ID is in the subject line; then the email is attached to the record in the Activity History tab.

If Service Manager cannot locate the service request record, the application creates a new incident and attaches the email to the record.

Accessing the Default Email Inbox

Service Manager always has a default inbox configured to create incidents. Therefore, you do not need to configure an inbox for creating incidents, but can instead just update the default inbox if you need to make changes.

The default email inbox is used to create incidents in Service Manager from email. Follow the steps here to access it.

1.Log into the Service Manager Application.

2.Open the Email Config workspace. If there is only one email server, the application automatically opens it. If there is more than one, click the default record link under the Mail Host column.

3.From the Inbox tab at the bottom of the page, click the default record link under the Address column. The application opens the Inbox Configuration workspace.

Creating an Inbox

1.Log into the Service Manager Application.

2.Open the Email Config workspace.

3.From the Inbox tab at the bottom of the page, click New. The application displays the New Inbox workspace.

4.Enter information into the fields.

Parameter Description
Incoming Server Connection
Enable Email Listener Turns on the email listener to catch emails and create a business object.
Address The email address that users send emails to. An example is [email protected]
Host

The host name or group that handles emails from the email address. An example is pop.emailsvr.com.

This field is not applicable for the Microsoft Graph option because this protocol does not require any host addresses.

Port

(Only shown if you select POP3 or IMAP4 for the Protocol field.)

The corresponding port number for the selected protocol. The default email port for POP3 is port 110 and the default port for IMAP4 is port 143.

Protocol

The protocol used to retrieve emails. The options are as follows:

Exchange Web Services

IMAP4

Microsoft Graph

POP3

Authentication

The authentication method for incoming messages. See About Authentication Types.

User Name The user name required to access the inbox on the email server. Usually the same as the address.

Client Login URL

(Only shown if you select Exchange Web Services as the Mail Protocol and Authentication as AuthLogin.)

The endpoint URL. For example, https://login.microsoftonline.com/. This can be obtained from the Azure Active Directory where you have registered an application.

Client Resource URL

(Only shown if you select Exchange Web Services as the Mail Protocol and Authentication as AuthLogin.)

The value to be used is - https://outlook.office365.com

Client Tenant ID

(Only shown if you select Exchange Web Services or Microsoft Graph as the Mail Protocol and Authentication as AuthLogin.)

The directory (tenant) ID. This can be obtained from the Azure Active Directory where you have registered an application.

Client ID

(Only shown if you select Exchange Web Services or Microsoft Graph as the Mail Protocol and Authentication as AuthLogin.)

The application ID. This can be obtained from the Azure Active Directory where you have registered an application.

Client Secret Key

(Only shown if you select Exchange Web Services or Microsoft Graph as the Mail Protocol and Authentication as AuthLogin.)

The secret login key. This can be obtained from the Azure Active Directory where you have registered an application.

Password

(Only shown if you select POP3 or IMAP4 as the Mail Protocol or Exchange Web Services as the Mail Protocol with Authentication as Plain.)

The password required to access the inbox in the email server.

Use SSL/TLS

(Only shown if you select SMTP as the Mail Protocol or Exchange Web Services as the Mail Protocol with Authentication as Plain.)

Enables SSL and TLS security for incoming messages.

Incoming Server Settings
Inbox Name (Only shown if you select Exchange Web Services, Microsoft Graph, or IMAP4 for the Protocol field.) A directory for incoming emails. When the application processes an email, it creates or updates the business object record. If the email is incorrectly configured, the application moves it from the inbox folder to the archive folder.
Archive Mailbox Name

(Only shown if you select Exchange Web Services, Microsoft Graph, or IMAP4 in the Protocol field.)

The directory for storing archived or processed emails.

Note:  Even though this field is called Archive Mailbox Name, this is not actually a mailbox, but is instead a folder.

Ignore CC and BCC Emails Ignores emails addressed to this inbox when the email address is only in the CC or BCC fields. The application does not process these emails.
Default Domain

A default domain. The application may not correctly process incoming emails without a domain. Use the default domain to construct a valid address, enabling emails to process as normal, including creating incident records.

Include Source Mailbox Name (Only shown if you select Incident for the Email Processor field.) Includes the name of the source mailbox in the From field of the email. When checked, the CreatedBy field in an incident stores the processing mailbox name (such as Email [email protected]; If unchecked, the CreatedBy field has the value email listener. This enables you to determine which mailbox generated the incident.
Test Connection

(Only shown if you select Exchange Web Services or Microsoft Graph for the Mail Protocol field or if you select Advanced for the Email Component Type field on the Email Configuration workspace.

See Configuring the Outgoing and Incoming Email Servers for more information.) Tests the Microsoft Exchange web services connection and displays the highest priority result of the most recent test.

Record Creation
Email Processor

The business object created from the incoming email.

Incident: When the email is received, an incident record is created. This option is the default setting.

Problem: When the email is received, a problem record is created.

Other: You can select another business object. See Creating an Inbox that Creates a Generic Business Object.

Export Email as XML: When the email is received, it is exported as an XML file. See Using XSLT to Process Incoming Emails in XML Format.

Name (Only shown if you select Other for the Email Processor field.) The type of business object that the application creates when it receives the email.
Unique Key (Only shown if you select Other for the Email Processor field.) The value that identifies this business object. Match the value you enter in this field with the Display field value for the business object on the Object Details tab (found in the Configuration Console in the Business Objects workspace for the particular business object). For example, the default unique key for change is ChangeNumber and the default unique key for knowledge is KnowledgeNumber.
Record Marker

(Only shown if you select Problem or Other for the Email Processor field.)

A valid marker value that separates multiple record information within an email. For example, if you enter # as a record marker, information in the email body preceding the # sign creates one record and information after the # sign creates another record. When inserted in a message body, this record marker (for example, a # sign) allows multiple records to be created from the body of a single message. See the note below.

Field Value Separator

(Only shown if you select Problem or Other for the Email Processor field.) A character that separates the field name from the field value. For example, if you enter $ as a field separator value, Summary$summary_field_information populates the Summary field with the field information.

Do not add white spaces before the field value separator.

Create Email When No Target BO (Only shown if you select Other for the Email Processor field.) Check this option to send an email if the application cannot find the target business object.
Create Incident On Error

Creates an incident when an error occurs in generating the record from an email (regardless of the business object specified). The application displays the fields in the Incident and Task Creation section if you select this option.

Note: The application only creates an incident upon error for cases other than create incident. That is, it creates an incident when there is an error updating an incident, or when there is an error creating or updating any other business object.

Data Import Connection (Only shown if you select Export Email as XML for the Email Processor field.) Specifies the data import connection to use. Select one from the drop-down list. The list is populated based on the list of data import connections that are created using the Data Integration Wizard. See Setting Up a Data Import Connection for information about data import connections.
Compress Message (Only shown if you select Export Email as XML for the Email Processor field.) If checked, supports Unicode characters in the email message body.
Incident and Task Creation (This section only appears if you check Create Incident On Error or if you select Incident from the Email Processor field)
Incident or Task Owner Team The team to which incidents generated from email errors are assigned.
Create New Task for Every Email Creates a task record for the incident record. This task record appears in the Tasks tab of the incident record.
New Task Subject The default subject line for every task email.
Sender / BO Identification and Matching
Method 1 (for Employee / External Contact / None) Creates a record and links it to an existing user (either employee or external contact), or creates a record and a new user and links the record to the new user.

 

Note: You can check either this option or the Use Method 2 (for Custom BO) option, but not both. Use Method 1 if you are linking to either an employee or external contact. Use Method 2 if you are linking to any other business object.

Create record by creating or linking the Employee or External Contact

(Only shown if you check Use Method 1.) Does one of the following:

If the user (either employee or external contact) is already in the application, creates a record and links it to the user.

If the user (either employee or external contact) is not in the application, creates a record and a new user and links the record to the new user.

Note: If you create a task for an external contact, there must be a value for the LoginID field in the External Contact workspace. When you configure the email listener to create a new external contact, the application uses the default value of the LoginID field as the primary email address. We recommend that you create a business rule that ensures that this field is populated.

Create record only when the Employee or External Contact exists

(Only shown if you check Use Method 1.) Does one of the following:

If the user (either employee or external contact) is already in the application, creates a record and links it to the user.

If the user (either employee or external contact) is not in the application, does not create a record or a new user.

Create record without creating Employee or External Contact

(Only shown if you check Use Method 1.) Does one of the following:

If the user (either employee or external contact) is already in the application, creates a record and links it to the user.

If the user (either employee or external contact) is not in the application, creates a record and links it to the default user called Internal Services.

Contact Type (Only shown if you check Use Method 1 and then select Create record by creating or linking the Employee or External Contact.) The contact type. Can be either Employee or External Contact.  
Method 2 (for Custom Business Object) (Only shown if you select Incident, Problem, or Other for the Email Processor field.) Creates a record and links it to either an existing business object, or if the business object does not exist, creates a new business object and links the record to it.

 

NOTE: You can check either this option or the Use Method 1 (for Employee / External Contact / None) option, but not both. Use Method 1 if you are linking to either an employee or external contact. Use Method 2 if you are linking to any other business object.

Create record by creating or linking the Custom Business Object

(Only shown if you check Use Method 2.) Does one of the following:

If the business object already exists, creates a record and links it to the business object.

If the business object does not exist, creates a record and creates a new business object, and links the record to the new business object.

Create record when the Custom Business Object exists

(Only shown if you check Use Method 2.) Does one of the following:

If the business object already exists, creates a record and links it to the business object.

If the business object does not exist, does not create a record or a new business object.

Relationship to Custom Business Object (Only shown if you check Use Method 2.) The name of the relationship between the target business object (the value in the Email Processor field) and the new business object.  
Match the email address "from" value to the related object field value (Only shown if you check Use Method 2.) You can either enter a value in this field or in the related object field value field, but not in both. See Example: Creating or Linking Business Objects via Email for more information.
related object field value (Only shown if you check Use Method 2.) You can either enter a value in this field or in the Match the email address "from" value to the related object field value field, but not in both. See Example: Creating or Linking Business Objects via Email for more information.

5.Click Save.

6.Do one of the following:

If you selected Problem, Other, or Export Email as XML from the Email Processor field, configure the fields on the Field Mapping tab. See Using the Field Mapping Tab.

If you selected Incident from the Email Processor field, configure the fields on the Status Mapping tab. See Using the Status Mapping Tab.

Modifying an Inbox

You can modify the settings for all inboxes, including the default inbox.

1.Log into the Service Manager Application.

2.Open the Inbox workspace. The application displays the list of inboxes.

3.Click the inbox to modify. The application displays the Inbox Configuration workspace.

4.Edit the fields as needed. For more information on each field, see Creating an Inbox.

5.Click Save.

Deleting an Inbox

Be cautious when deleting the default inbox, as it might lead to permanent loss of all the emails in the application.

1.Log into the Service Manager Application.

2.Open the Email Config workspace,

3.Click the record link under the Mail Host column.

4.From the Inbox tab, select the address to delete.

5.Click Delete.

6.Click Yes at the confirmation prompt.