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 Neurons for ITSM 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 Neurons for ITSM cannot locate the service request record, the application creates a new incident and attaches the email to the record.
Accessing the Default Email Inbox
Neurons for ITSM 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 Neurons for ITSM from email. Follow the steps here to access it.
1.Log in to Neurons for ITSM.
2.Open the Email Config workspace. If there is only one email server, the application automatically opens it. If there is more than one email server, select the default record link under the Mail Host column.
3.From the Inbox tab at the bottom of the page, select the default record link under the Address column. The application opens the Inbox Configuration workspace.
Creating an Inbox
1.Log in to Neurons for ITSM.
2.Open the Email Config workspace.
3.From the Inbox tab at the bottom of the page, select New. The application displays the New Inbox workspace.
4.Enter information into the fields.
Parameter | Description |
Email Listener Settings |
|
Name |
Enter a unique name up to a maximum of 50 characters. This name must be unique for every email monitor, even if using the same address or account across multiple monitors. If you leave this field blank it is auto-filled with the email address in the Address field for the incoming server connection. This may result in the name not being unique and may result in an error message, therefore it is recommended that you do not leave this field blank. |
Description |
Enter a description for the email listener (optional). |
Enable Email Listener |
Select this checkbox to enable the email listener to identify emails and create a business object. |
Incoming Server Connection | |
Address | The email address that users send emails to. For example, [email protected]. |
Host |
The host name or group that handles emails from the email address. For example, 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 •Google Services Account •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 for the 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 for the 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 for the 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 for the 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 for the 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 for the Protocol, or Exchange Web Services for the Protocol with Authentication as Plain. The password required to access the inbox in the email server. |
Use SSL/TLS |
Only shown if you select IMAP4 or POP3 for the Protocol. Enables SSL and TLS security for incoming messages. |
Incoming Server Settings | |
Inbox Name |
Only shown if you select Exchange Web Services, Google Service Account, IMAP4, or Microsoft Graph for the Protocol. A folder 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 the Move to Folder option for Action To Perform On Processing Success (see below), Not applicable and not shown for the POP3 protocol. The folder for storing archived or successfully processed emails. Note: Even though this field is called Archive Mailbox Name, this is not actually a mailbox, it is 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. |
Action To Perform On Processing Success |
Only shown if you select Exchange Web Services, Google Services Account, IMAP4 or Microsoft Graph for Protocol. The action to perform on an incoming email if it is processed successfully. Select from the drop-down list:
If Move to Folder is selected with Google Service Account as the configured protocol, the email is not moved to the archive folder. Instead the "Inbox" label is removed from the email. The email is no longer visible in your inbox, but can be viewed in "All Mail". For more information on label use with Gmail, see Organize your inbox in the Google Help Center.
When the Move to folder or Delete options are selected, be aware that all emails currently in the Inbox are read and processed, regardless of their read/unread status. When the Mark as read option is selected, only emails with unread status are processed, after which they are marked as read. |
Action To Perform On Processing Error |
Only shown if you select Exchange Web Services, Google Services Account, IMAP4 or Microsoft Graph for Protocol, The action to perform on an incoming email if an error occurs during processing. Select from the drop-down list:
If Move to Folder is selected with Google Service Account as the configured protocol, the email is not moved to the archive folder. Instead the "Inbox" label is removed from the email. The email is no longer visible in your inbox, but can be viewed in "All Mail". For more information on label use with Gmail, see Organize your inbox in the Google Help Center.
|
Error Mailbox Folder |
Only shown if you select Exchange Web Services,, Google Service Account, IMAP4 or Microsoft Graph for Protocol, and also select Move to folder in the Action to Perform On Processing Error field. The folder for storing emails that have failed to process. |
Test Connection |
Tests the connection between Neurons for ITSM and the protocol service you have selected. Last Test Result: Displays the result of the previous connection test, including a time stamp, with date/time the test was run. It will include any failed message received. See 'Test Connection' in Configuring the Outgoing and Incoming Email Servers for more information. |
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. Advanced Monitoring: When the email is received, a business object is created, or (if found) an existing business object is updated in accordance with the action defined for the monitor item. 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). |
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. 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. |
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. 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 a data import connection 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 select 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. You can check either this option or the 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 Method 1. Does one of the following:
Note: If you create a task for an external contact, there must be a value for the LoginID field in the External Contact workspace, see Working with External Contacts. 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 Method 1. Does one of the following:
|
Create record without creating Employee or External Contact |
Only shown if you check Method 1. Does one of the following:
|
Contact Type |
Only shown if you check 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. |
Contact Field Name |
Only shown if you check Method 1 and then select Create record by creating or linking the Employee or External Contact. The field used to link the selected contact business object. This field defaults to the primary email of the contact if left blank. Note: This is the internal field name, not the display name. |
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 an existing business object, or if the business object does not exist, creates a new business object and links the record to it. You can check either this option or the 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. Method 2 is hidden if you select Advanced Monitoring or ExportEmailAsXml in the Email Processor drop-down list. |
Create record by creating or linking the Custom Business Object |
Only shown if you check Method 2. Does one of the following:
|
Create record when the Custom Business Object exists |
Only shown if you check Method 2. Does one of the following:
|
Relationship to Custom Business Object |
Only shown if you check 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 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 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.Select 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.
•If you selected Advanced Monitoring from the Email Processor field, configure the fields on the Monitor Items tab, See Using the Monitor Items Tab.
The following table lists the authentication types for each protocol based on the email component type that you selected for the Email Configuration workspace [either Basic (Default) or Advanced]. See Configuring the Outgoing and Incoming Email Servers for information about the email component types.
Protocol | Basic (Default) | Advanced |
---|---|---|
Exchange Web Services |
Plain Password is not required for Exchange Web Services users. The login is based on client credentials (OAuth). |
AuthLogin |
Google Service Account |
AuthLogin |
- |
IMAP4 |
AuthLogin CramMD5 NTML Plain |
AuthLogin CramMD5 NTML Plain None Regular DigestMD5 Msn GssAPI Auto |
Microsoft Graph |
AuthLogin Password is not required for Microsoft Graph users. The login is based on client credentials (OAuth). |
- |
POP3 |
APOP AuthLogin CramMD5 NTML Plain |
DigestMD5 GssAPI Msn CramMD5 AuthLogin APOP Plain NTLM Regular Auto None |
The following table describes the Simple Authentication and Security Layer (SASL) authentication types:
Authentication Type | Description |
---|---|
None |
No authentication. Sometimes used with SMTP when the server allows relay for anonymous senders. |
Regular |
Standard authentication. Passwords are transmitted as clear text. Not supported by SMTP servers. |
APOP |
Secure APOP authentication. Supported by many POP3 servers but cannot be used with other servers like SMTP because APOP is POP3-specific. Disabled when FIPS mode is enabled. |
AuthLogin |
SASL LOGIN authentication. Not secure but widely supported. Passwords are transmitted as Base64 strings. Note for IMAP users: This is the AUTHENTICATE LOGIN command, not the LOGIN command (which corresponds to the Regular authentication type). |
Plain |
SASL PLAIN authentication. Not secure but widely supported. Passwords are transmitted as Base64 strings. |
CramMD5 |
Secure SASL CRAM-MD5 authentication. Might not be supported by particular server implementations. Disabled when FIPS mode is enabled. |
DigestMD5 |
Secure SASL DIGEST-MD5 authentication. Might not be supported by particular server implementations. Disabled when FIPS mode is enabled. |
NTLM |
Secure SASL NTLM authentication. Also known as Secure Password Authentication (SPA). In a Microsoft Windows domain environment such as Active Directory, you can also use NTLM to authenticate the current Microsoft Windows user. In this case, you should pass a null reference (or "Nothing" in Visual Basic) for the accountName and password values. Might not be supported by particular server implementations. |
Msn |
Secure SASL MSN authentication. Equivalent to NTLM. Not widely supported. |
GssAPI |
Secure SASL GSSAPI authentication (through Kerberos or NTLM). Like SASL NTLM, supports Integrated Windows Authentication mode. The internal implementation (Kerberos or NTLM) is selected depending on if the value of the targetName field of the Login method is an empty string (or for SMTP, the TargetName field). An empty string denotes NTLM, and all other values (including a null reference) denote Kerberos. The underlying implementation downgrades to NTLM from Kerberos if the targetName field is not empty but not valid (denotes non-existent SPN). |
Auto |
Tells the email service to automatically select the best supported authentication method and downgrade to insecure methods if the server does not support secure methods. |
The Field Mapping tab only appears if you check Method 2 (for Custom BO).
If you create a new business object, you can map certain fields to appear in an email.
1.After performing the tasks in Creating an Inbox, select the Field Mapping tab.
2.Select New Tenant Email Mailbox Mapping. The application displays the Tenant Email Mailbox Mapping workspace.
3.Enter the field to map.
Field | Description |
---|---|
Map Field | The name of the field to map, such as PrimaryEmail. |
Map Value | The field value, such as @From: |
Field Mapping Values
Map Field |
Map Value |
FRS_Knowledge Type |
Document |
Title |
@Subject |
Details |
@Body |
Collection |
IT Knowledge |
Category |
Mobile |
Keywords |
@From |
Status |
Draft |
Tokens for Field Values
Tokens for Field Values |
|
@From |
The email address from which the mapping occurs. |
@To[N] |
The email address for the nth value to which the mapping occurs. Indexing starts from 1, so the first email recipient is addressed as @to[1]. If the index is missing, then just the @to is used or the first recipient is less than 1 (or, @to[0]). |
@CC[N] |
The carbon copy email address for the nth value to which the mapping occurs. |
@FirstName |
The first name associated with the email from which the mapping occurs. |
@LastName |
The last name associated with the email from which the mapping occurs. |
@Subject |
The subject of the email. |
@Body |
The body of the email. |
4.Select Save.
The Status Mapping tab only appears if you select Incident from the Email Processor field.
1.After performing the tasks in Creating an Inbox, select the Status Mapping tab.
2.Select New Tenant Email Status Mapping. The application displays the Tenant Email Status Mapping workspace.
3.Enter information.
Field | Description |
---|---|
Current Status | The current status that triggers the quick action. |
Quick Action | The name of the quick action to execute. |
Enabled | Enables this status mapping record. If not checked, the default status handling logic is in effect. |
4.Select Save.
The Monitor Items tab only appears if you select Advanced Monitoring from the Email Processor field.
1.Select New Inbox Monitor Item. The application displays the New Inbox Monitor Item workspace.
2.Enter the monitor item information.
Field/Parameter | Description |
---|---|
Name | Enter a name for the monitor item. This must be a unique name up to a maximum of 50 characters. |
Description | Enter a description for the monitor item. The description can contain up to a maximum of 255 characters. |
Execution Order | Enter a number in this numerical field to determine the monitor item execution order. For example, if you enter "2", the monitor item executes if the preceding monitor item with execution order "1" fails. |
Business Object |
Enter the business object that the monitor item applies to (example: Incident). |
ID Existing Record | |
Attempt to find existing record |
Select this check box before selecting any options for identifying existing records. The following options are available when this option is selected:
|
Look for conversation ID |
Neurons for ITSM identifies an existing record from the Conversation ID in an email message. |
Try to match based on subject |
Neurons for ITSM identifies an existing record based on the subject line of an email message. The following and option is available when this option is selected:
|
Ignore short subjects |
Neurons for ITSM ignores subject lines that are less than 10 characters. |
Ignore closed records |
Neurons for ITSM ignores records that have been closed. |
Search subject for ID |
Neurons for ITSM identifies an existing record from a Record ID in the subject of an email message. This is useful receiving messages from automated systems, or if email senders use a template that always includes the Record ID in the subject. |
Search subject details |
Neurons for ITSM identifies an existing record in the subject line of an email message based on the criteria selected in this drop-down, which are described below:
|
Search body for ID |
Neurons for ITSM identifies an existing record from a Record ID in the body of an email message. |
Search body details |
Neurons for ITSM identifies an existing record in the body of an email message based on the criteria selected in this drop-down list, which are described below:
|
Conditions |
|
Only if existing record found |
Associated actions executed only if an existing record is found (using the options and criteria defined in the ID Existing Record section above). |
Only if contact found |
Associated actions are executed only if a contact is identified. |
Action condition email property |
Select a part of the email message from the drop-down list (example: Subject and body combined) to search. Some property options seem similar but produce different results when searching for matched values. For example, if you select the From property, validation is performed against a concatenation of the user's name and email address (e.g. "(Henri Bryce) [email protected]"). If you want the validation to run against a name or email address only, choose From (just name) or From (just address). You can enter up to four different action conditions for your search. All action conditions you enter must be true for the action to execute (example: If you specify four conditions, then all four conditions must evaluate to true for the action to execute). See the List of available email property action condition operators and their descriptions in the table below. |
Action condition operator |
Select an operator from the drop-down list. See the List of available action condition operators and their descriptions in the table below. |
Action condition criteria |
Provide a keyword or phrase, date/time, etc. |
Actions |
|
Action Business Object |
Enter the Business Object the Action is associated with. This is usually the same Business Object that the monitor item applies to (as entered in the Business Object field above). If you leave this field blank the monitor item looks for the named Action associated with the Business Object as entered in the Business Object field above. If it fails to find the Action the monitor item does nothing. |
Action Name |
This is the Action the monitor item executes on the monitor item conditions being met. You can display a list of available Actions, see Using Quick Actions. If the Action you want the monitor item to execute is not available, you can create a new Action, see Using Quick Actions. |
3.Select Save.
List of available email property action condition operators
Each email property returns a specific value type used to evaluate the condition, this can be plain text, HTML, number, etc. The returned values are subsequently evaluated to determine if true or false according to the evaluating condition (example: Greater than, Less than, Equals, Ends with, etc). Consideration should be given to the evaluating condition operator used for the query so that it is compatible with, and can be used to correctly evaluate the value returned by the selected email property (see List of available action condition operators below). Example: If you use "Ends with" and the email property selected returns HTML, then you may get an unexpected result as the returned content ends with an HTML tag. For this example it is advised that you use the"Contains" operator to return the expected result.
Property | Description |
---|---|
Attachment Count | Search by evaluating the number of attachments in the email. Returns the number of attachments present. |
Body (HTML) | Search the body of the email when in HTML format. Returns HTML. |
Body (plain text) | Search the body of the email when in plain text format. Returns plain text. |
CC | Search the CC list. |
Date/time received | Search the date/time the email was received. |
Date/time sent | Search the date/time the email was sent. |
Entire message |
Search the entire email message. Returns HTML. |
Entire message (subject first) | Search the entire email message, but search the subject line first. Returns HTML. |
FirstCC | Search the first entry in the CC list. |
FirstCCAddress | Search the first address entry in the CC list. |
FirstCCName | Search the first name entry in the CC list. |
From | Search the From list. |
From (just address) | Search the From list using address only. |
From (just name) | Search the From list using name only. |
Has Attachments |
Search the email for attachments and return "true" if attachments are found. |
HasCCLine |
Search the CC list and return "true" if there is an entry. |
Priority |
Search the priority value associated with the email. |
Raw subject (no FWD:, RE:, etc.) |
Search the subject line ignoring the prefix. |
Subject |
Search the subject line only. |
Subject and body combined |
Search both the subject line and the email body. |
To |
Search the To line. |
To - first entry |
Search and evaluate the first entry in the To line. |
To - first entry (just address) |
Search and evaluate the first entry in the To line using only the address. |
To - first entry (just name) |
Search and evaluate the first entry in the To line using only the name. |
List of available action condition operators
Operator | Description |
---|---|
Begins with | Finds email items that begin with the value in the criteria field. |
Contains | Does an SQL Server Full-Text search to find email items that contain the text in the the criteria field. |
Does not contain | Finds email items that do not contain the text in the criteria field. |
Empty |
Finds all email items where the field value is empty. |
Ends with |
Finds email items that end with the value in the criteria field. |
Equals |
Finds email items where value in field equals value in the criteria field. |
Greater or equal |
Finds all email items where the value is greater than or equal to the value in the criteria field. |
Greater than |
Finds all email items where the value is greater than the value in the criteria field. |
Less or equal |
Finds all email items where the value is less than or equal to the value in the criteria field. |
Less than |
Finds all email items where the value is less than the value in the criteria field. |
Like |
Finds email items where the value matches the value and its wildcard in the criteria field. For example, Jo% will find Joe, John, etc. |
Not empty |
Finds all email items where the field value is not empty. |
Not equal |
Finds email items where value in field does not equal the value in the criteria field. |
Not like |
Finds all email items that do not match a value and its wildcard. |
Modifying an Inbox
You can modify the settings for all inboxes, including the default inbox.
1.Log in to Neurons for ITSM.
2.Open the Inbox workspace. The application displays the list of inboxes.
3.Select 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.Select 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 in to Neurons for ITSM.
2.Open the Email Config workspace,
3.Select the record link under the Mail Host column.
4.From the Inbox tab, select the address to delete.
5.Select Delete.
6.Select Yes at the confirmation prompt.