Email Integration is Here, Trojita

The much anticipated mail integration functionality in xTuple Connect is now available for Beta testing.

Overview

Email integration provides a mechanism for users to import email into xTuple and have it be automatically associated with appropriate contacts and documents in the database. This solution allows users to continue using their preferred mail client and server software, but gives them control over what mail they want imported into xTuple.

The strategy to accomplish this involves two main components: The first part is a new open source email project called Trojita that is used as a tool to import mail into the xTuple database. Trojita is a lightweight open source IMAP email client that can connect to any standard IMAP server. Trojita has been enhanced for xTuple to allow users to select personal IMAP folders to export to an xTuple database that has xTuple Connect installed. The synchronization from Trojita to xTuple is performed by Trojita in the background whenever xTuple is launched.

As mail is imported it is processed by business logic in xTuple Connect that associates recognized email addresses with their respective contacts. If a matching contact is not found, one is automatically created. Additionally, Connect scans the subject and body for predefined document reference identifiers and if any are found associates the mail with those documents. An Email tab has been added to the contacts window and other documents such as Sales Order, Incident and Opportunity so that users can quickly view email associated with those records. Mail launched from xTuple includes a document reference inserted into the subject line that can later be used as a reference to associate mail imported back into xTuple with that document. This reference should continue to work as users continue to volley email back and forth from their email client using standard reply mechanisms.

Finally, email sent by Connect itself using EDI profiles, such as sales order acknowledgements and incident updates, inserts an email record into xTuple as well. Note, however, it is not necessary to run the BatchManager processing utility to otherwise take advantage of mail integration.

You can watch a webinar recording of our presentation of Mail integration here.

Diagram of xTuple Mail Integration Components

Basic Installation and Configuration

The following are the basic steps to installing and configuring Email Integration:

• Install or upgrade xTuple to version 3.6.1 or greater.
• Install or upgrade to xTuple Connect 3.6.0 or greater.
• Copy Trojita files to any local machine where a user wants to perform mail synchronization
  • The Trojita directory needs to be placed in the same directory as your xTuple ERP executable file.
• Launch the Trojita email client from xTuple and configure.
• Start the synchronization processor.

Upgrading xTuple

xTuple upgrades and release notes may be obtained from Source Forge in PostBooks downloads.

Commercial customers using xTuple Standard Edition may download upgrades from the xTuple Community home page in the Commercial Downloads section. Follow instructions provided for installation.

Upgrading xTuple Connect

xTuple Connect may be purchased from the xChange. Once purchased, downloads may be obtained form the xTuple Community home page in the Commercial Downloads section. Follow instructions provided for installation.

Copy Mail Integration files

When you uncompress the xtConnect folder downloaded from xTuple, you will find a sub folder called "trojita." Copy this sub folder so that it is in the same directory where the xTuple application resides. If you used the xTuple installer to install xTuple you should find the xTuple application in one of the following locations:

Windows:  C:\Program Files\xTuple\Client\

Macintosh: \Applications\xTuple\Client

Linux: \Opt\xTuple\Client

Linux users must rename this folder to be called "xtconnect".  

Configure Trojita

Start xTuple and navigate to User Preferences. The Trojita email client it can be launched from the Email tab by clicking on the "Start Trojita Mail Client" button.

Once Trojita opens, click on "Settings" and select the "IMAP" tab. Enter your credentials to your IMAP mail server. Click Save.

You should see your IMAP mailbox folders appear in Trojita. Right click on the folder(s) you wish to import and select "Synchronize with xTuple." The folder should then change to have an orange arrow on it indicating it is a synchronized folder. When you are finished, close the Trojita Client

Import set up can be as simple as synchronizing both your Inbox and Sent items. However, most people will not be comfortable with ALL their mail going into xTuple. A more controlled solution would be to create folders called "xTuple Inbox" and "xTuple Sent," then set up a rule in your mail client software to automatically move any messages with "xtref" in the subject to those respective folders (which mail launched from the xTuple client should have).

Once the Trojita configuration is complete check the "Synchronize Email while running application checkbox." This will make synchronization start when you start xTuple. You can click "Start Now" to start the process without having to restart xTuple. Click save and you are done with set up. You should be able to go to a contact in xTuple for which there was mail traffic in the folder you synchronized, and see mail history for that contact.

You will need to stop and restart the synchronization processor any time you change folder settings for the new settings to take affect.

Install Notes for Microsoft users

Outlook

Mail messages opened from xTuple are processed as .eml files. If you are using Outlook 2003 or Outlook 2007, then you must apply the latest updates and certain registry changes so that Outlook will recognize .eml files. More information is available here. Note that Outlook 2010 supports .eml files natively.

Exchange

Exchange 2010 has IMAP services disabled by default. Read your installation instructions on Exchange to enable IMAP service. You can also start with online resources published by Microsoft here.

Install Notes for Macintosh Mail users

You may want to enhance your Macintosh Mail application to allow you to set up rules on outbound mail. You may purchase a utility for this called "Act-On" that may be downloaded for a 30-day trial here.

Install Notes for Thunderbird users

You may want to enhance your Thunderbird client to allow you to set up message filters on outbound mail. There is a free plug-in for this called "Send Filter" that is available here.

Viewing mail from xTuple

Email integration is supported on the following documents

• Contact
• CRM Account
• Customer
• Vendor
• Employee
• Opportunity
• Project
• Quote
• Sales Order
• Transfer Order
• Purchase Order
• Return Authorization
• To Do Item
• Incident

Each of these windows has an Email tab from which you can view email associated with the document as pictured:

The plain text of the message may be viewed by clicking on a message in the list, or the entire message may be viewed by double clicking on the message which will open the message in the user's default email client.

The toolbar buttons operate as follows:

• New - Start a new message in the user's e-mail client with the To: address populated with the contact address on the document (if applicable) and an xTuple document reference in the subject.
• Print - Prints the selected email.
• Reply - Start a new message in the user's e-mail client with the To:  address populated with the From address on the selected message. Subject will be pre-pended with RE: and the xTuple document reference if it does not already exist on the subject.  Text from the body of the selected message will be added to the body of the reply message.
• Reply All - Same as reply except all addresses on the Cc column will be copied to the new message as well.
• Forward - Same as reply except prepend the subject with FW: and no addresses will be populated.
• Attach - Open an email attach dialog window that allows users to search messages by contact and associate them to the current document.
• Detach - Removes the association of the selected message from the document.

Messages launched from the email address link on the contact cluster also will include the document reference in the subject.

There will not be support to include attachments in forwarded messages forwarded from xTuple due to security risks.  If you need to forward an attachment double click on the original message to open it in your email client, then forward the message from that client.

Attach Email Dialog

When a user chooses to attach a message an interactive dialog window allows users to search for messages by contact to attach to other documents. The contact cluster will allow users to select a specific contact, while a search box will allow them to further narrow their result set. The search box will search on address fields, subject and the body fields in the database.

When a message is selected and "Ok" is clicked an association will be made between the selected message and the document.