Understanding the Mail Connector
Updated in 2025.1.1
The Mail Connector is an internal Alloy Navigator tool that processes incoming email messages and converts them into Service Desk tickets or any other Alloy Navigator objects such as Purchase Orders or Approval Requests. The Main Connector can also update existing objects with responses from users and third-party tools.
If you want Alloy Navigator to convert incoming email messages into Alloy Navigator objects, you should create and configure a Mail Connector job. If you want to process multiple email accounts, you should create an individual Mail Connector job for each account.
Converting messages into objects
The Mail Connector checks for new email messages on the mail server according to the schedule you specify. You can integrate the Mail Connector with your support's email account; incoming messages may be sent as plain text or in HTML format.
The Mail Connector extracts pieces of information such as Sender, Subject, and Body from incoming email, and then uses this information to create objects and populating object fields with the extracted data. In addition, it can invoke various workflow steps on related objects and send out E-mail Notifications.
See below for an example of how an email becomes an incident.
The process of extracting information is called parsing, while the process of creating (or updating) objects is called processing.
Updating objects with data from incoming messages
When the Mail Connector processes email messages, it checks if the message is part of a thread initiated for an existing object. Such threaded messages usually contain a special MessageID Tag. This MessageID is an identification tag that Alloy Navigator automatically inserts in outgoing notifications, typically in the subject line. All threaded replies to these notifications will also contain that identification tag.
The Mail Connector can link reply emails to existing tickets even when the auto-added MessageID tag is missing. This is useful in scenarios where a CC'd user replies to an email without the tag. Such replies are correctly associated with the original ticket, preventing unnecessary new tickets.
The rule for deciding whether to update an existing object or create a new one is specified by your Mail Connector settings. See below for the default workflow for incidents and other tickets.
When the Mail Connector updates objects, it typically add new records to the object’s Activity Log, recording all replies on the communication thread. It can also replace some field values with data from the message (for example, populate some Purchase Order fields with new data). In addition, it can invoke various workflow steps on related objects and send out E-mail Notifications.
E-mail parsing, processing, and preprocessing
These three stages work together to handle incoming emails automatically.
-
Parsing is an automated process of analyzing text of email messages in accordance with a specified parsing rule and extracting specific data from the message text when it matches the rule.
-
Preprocessing is an automated process of analyzing text of email messages according to specified preprocessing rules and stripping unwanted text before processing.
-
Processing is an automated process of creating or updating Alloy Navigator objects using the extracted email information in accordance with specified processing statements. All tasks for creating and updating objects are performed through workflow Service Actions configured for the Mail Connector.
The Mail Connector is shipped with the pre-configured (canned) parsing, preprocessing, and processing rules which are sufficient for many organizations. So it may be enough to just understand how those rules work, and configure Mail Connector settings. Then you can start using the Mail Connector right away.
However, you may need to modify the default parsing and processing settings or create your own ones (see Configuring parsing rules , Configuring processing rules and Configuring preprocessing rules.
System parsing rule
Parsing rules search incoming emails and attempt to extract a reference to an existing object (ObjectRef). This helps detect if the email is a reply to a previously processed message, allowing it to be linked to the existing object and keeping the conversation consolidated.
If the identified object is inactive (such as a closed Ticket, retired Computer, or inactive Person), its ID is stored in the InactiveObjectReffield. This allows different processing rules to be applied to active and inactive objects.
The following sections explain how the system parsing rule works. You can also create additional parsing rules with custom tags to extract almost any type of information from email messages. For details on configuring parsing rules, see Configuring parsing rules.
Parsing using the MessageID tag
Alloy Navigator includes a built-in parsing rule for extracting object IDs from email messages. The Mail Connector searches each message for the MessageID string, which serves as the start parsing tag. When the tag is found, the system locates the # symbol as the end parsing tag, extracts the value between the tags, and stores it in the virtual field ObjectRef.
Parsing is case-insensitive, and leading or trailing spaces are removed. For example, both MessageID:T01234# and MESSAGEID: T01234 # result in T01234.
The start and end tags correspond to the MessageID Tag, a system tag automatically inserted into outgoing notifications, typically in the subject line. Replies to these notifications also include the tag in the subject, enabling the system to extract the object ID and link the reply to the correct object.
NOTE: For details on the MessageID Tag, see Customizing the MessageID Tag.
Handling replies without a MessageID tag
In some cases, a reply may not include a MessageID tag. This happens when a CC'd or BCC'd recipient replies to an email without the tag. To handle such situations, the Mail Connector examines the In-Reply-To and References email headers. These headers indicate that a message is a reply.
NOTE: The In-Reply-To header contains the Message-ID of the specific message being replied to, while the Referencesheader lists the Message-IDs of all messages in the conversation thread.
If these headers are present, the Mail Connector searches for the original ticket based on the information in the headers. This ensures that all replies, even without an automated MessageID tag, are correctly associated with their parent tickets.
Default processing statement
By default, the Mail Connector uses the following processing logic when creating or updating objects. Applicable object types: Incidents, Change Requests, Problems, Work Orders, Service Requests, Purchase Orders, and Approval Requests.
-
Updating existing objects
If an email is part of an object's communication thread (i.e., a reference to the original object is found), the Mail Connector updates the existing non-closed object.
-
Creating new objects
If the email is not part of an existing communication thread, the Mail Connector creates a new object.
-
Creating new Person records
If the email sender cannot be matched to an existing Person record, the Mail Connector creates a new Person record.
All tasks are performed through workflow Service Actions configured for the Mail Connector. These Actions create or update objects using the information from email messages. For example, when creating a new Incident, its Description, Requester, and Summary fields are populated with the email Body, Sender, and Subject, respectively. When updating an existing Incident, its Activity Log gets a new entry containing the comments from the email.
IMPORTANT: When the Mail Connector creates or updates objects, it extracts attachments from incoming email message and adds them to created objects or object Activities. This behavior is hard-coded and does not depend on Mail Connector settings or Service Actions. If you have put a limit on the size of attachments, this limit applies also to the attachments of the Alloy Navigator objects created or updated by the Mail Connector. For details, see Attachments.
You can use the default processing statement, modify it, or create your own ones. For details, see Configuring processing rules.