Concepts

In a helpdesk solution it is common that a customer or user gets back with more information regarding an already existing helpdesk ticket. Because of this updating existing records or adding more information to existing records is supported. Mail Gateway however needs to know how to associate an incoming message with a record that already exists in the database. This is done by scanning the message for a known signature, for example a ticket number in a known format enclosed in brackets. If the number can be extracted from the message a database lookup is performed against a given field and if a unique match is returned that matching record is updated.

A common method to enable lookups is by appending the unique reference number (e.g. ticket number, key) by embedding a field code in the subject line of outgoing messages sent by Mail Gateway.

Read more about lookups in the configuration reference.

To provide a dynamic experience Mail Gateway supports field codes in several places in the configuration. A field code is a placeholder for information that for example depends on the contents of an incoming message. A common scenario is that the subject line of the incoming message is to be imported into a specific field of record in the Lime CRM database. This is achieved by specifying that the field code %%SUBJECT%% is to be used as data source for that particular field. Field codes can also be used in outgoing message templates so that the content of those messages can be dynamic.

The following field codes are available for use:

Mail Gateway can be configured to automatically respond to incoming messages. What is sent back to the sender of the original message is defined through templates. For each account two different templates can be configured, one that is used when a message import leads to the creation of a new record and another that is used when an existing record is updated. This makes it possible to send a message saying “We have registered your helpdesk ticket and assigned it ticket number ABC123” in the first case and another saying “Thank you for providing more information regarding your ticket having number ABC123”.

Templates can be in either HTML or .msg format, where HTML is strongly recommended since there are less issues with plain text files. It is possible to use field codes in templates, thereby making it possible to use dynamic content in outgoing messages, as “ABC123” in the example above. Using field codes in message templates is a bit different than in other places. Example:

Dear Sir/Madam,
We have received your email and will start working on solving your problem as soon as possible.
Your case has been assigned ticket number HELPDESK.HELPDESKNO, please refer to this number if contacting >us regarding this case in the future.

A field code in message templates consists of the name of the table (helpdesk in this example) followed by a dot and the name of the field (helpdeskno above), enclosed in %%. Note that the field used must have its direction attribute set to Out for it to be available for use like this. Refer to the configuration reference for more information.

When using HTML templates it is possible to embed images in outgoing messages. The image file to be embedded needs to be located in the same folder as the template and the appropriate HTML markup needs to be present in the template file, for example:

<img src="image.png" />

Contains options for how Mail Gateway should attempt to associate company and/or person records with the sender of an incoming message. Matches on email, you must set a link-field with label “Email” for Mail Gateway to match against that field.

account

Mail Gateway will automatically try to look up company and person records matching the sender of an incoming message when the field codes %%COMPANY%% and %%PERSON%% are used. Optionally, looking up coworkers is also supported by using the %%COWORKER%% field code. This information can be used when populating a database record so that relations are set automatically. Mail Gateway uses database metadata such as relations, table and field labels to try to identify the matching company and person records. The following search order is used if not explicitly specified in the configuration:

1. If a person has already been found using exact address matching as described below, use the company associated with that person.
2. Match the sender's full email address with the company email address.
3. Match the domain name in the sender's address with the company email address.
4. Match the domain name in the sender's address with the domain name of the company's web site.
5. Search for persons in the database having the same domain name in their email address as in the sender's address and only one result is returned, use that company.

1. Match the sender's email address exactly.

Mail Gateway has a built in filter chain that each incoming message is run through before being processed. Typical uses of message filter is for example:

• Ignoring messages sent from a specific domain if those messages should be processed manually.
• Deleting messages having a spam level header above a certain level.

The outcome of the filtering process can be one of the following:

None

Do not run any more filters and continue processing the message as usual.

NextFilter

Proceed with the next filter in the chain.

Ignore

Mark the message with the ignore flag which means that Mail Gateway will never look at it again (unless reset using the Mailbox Reset tool). No more filters are run.

Delete

Delete the message and do not run any more filters.

DontReply

Suppress any replies to this message.

Mail Gateway can be configured to handle email attachments in three ways:

• Discard attachments. Usually as a security measure by configuring the removeAttachments attribute of the security element in the configuration file.
• Embedded attachments. Original attachments are embedded in the .msg or .eml file containing the original message and saved as a document in Lime CRM.
• Extracted attachments. Original attachments are extracted from the incoming message and are stored as individual documents in Lime CRM.

The extract individual attachments, use a subtable configuration similar to this:

<subtable relationField="document" attachmentTemplate="true">
  <fields>
    <field name="description" contents="%%ATTACHMENTNAME%%" />
    <field name="document" contents="%%ATTACHMENTFILE%%" />
  </fields>              
</subtable>

The attachmentTemplate attribute instructs Mail Gateway to create a new record for every attachment in the original message and map the fields according to the elements in the fields element collection.

If an error somehow occurs when Mail Gateway is importing an incoming message different action is taken depending on the error handling configuration.

The default behavior (the saveFailedToDisk attribute set to false) is to try again up to the number of times specified in the configuration. If the message still has not been possible to import, the message will be left in the mailbox and ignored by Mail Gateway for all future (unless the ignore flag is reset using the Mailbox Reset tool).

If the saveFailedToDisk attribute is set to true messages will after the specified number of attempts be saved to disk in the folder specified in the configuration and deleted from the mailbox.