Work with emails basics

Guide
Medium

Junk case custom filtering 

Creatio users can filter unwanted cases by creating a list of email addresses and domains for automatic spam detection. Incoming cases from these domains or addresses are either not registered at all or have the “Canceled” status (the default status value is set in the Junk Case Default Status system setting).

Junk filter enables email header analysis based on certain flags, e.g. Auto-Submitted. Emails with those flags are either not registered or register with the pre-defined initial status, set in system settings.

To analyze email addresses and domains, simply add the required value to the Blacklist of email addresses and domains for case registration lookup. The emails will be marked as blacklisted during the analysis when you populate the lookup with values (their type is set automatically).

Email analysis is done through the Email header properties management lookup. Follow these steps to add a new analysis property:

  1. Add a new class that implements the IHeaderPropertyHandler interface. This interface contains a single Check() method that returns a value of bool type. Check the property value and return the result during the Check() method implementation. If the method returns true, the system creates the case using the standard mechanism, if false, the system treats the email as blacklisted.
  2. Add an [Email header properties management] lookup value. Specify the property name used for analysis in the Name column. Specify the class name (added in the previous paragraph) in the handler column.

Working with email threads 

The mechanism for creating email threads is available in Creatio since version 7.10.0. The main purpose of this mechanism is to improve the email interface. Use this mechanism to easily find email connections, e.g. by copying the connections of the previous email.

The thread construction mechanism is based on the In-Reply-To email header data. According to generally accepted agreements, this header should contain the Message-ID email identifier. The Creatio application retrieves these headers from the synchronized Email service (IMAP / Exchange).

The mechanism can be divided into two logical parts – creating threads and populating activity connection fields.

Creating email threads 

The EmailMessageData detail contains 3 fields:

  • MessageId – a string of 500 characters in length;
  • InReplyTo – a string of 500 characters in length;
  • ParentMessageId – a lookup field that references the EmailMessageData detail.

The MessageId and InReplyTo fields are populated with the corresponding message header values during synchronization.

The ParentMessageId field is populated with the following values:

  1. The EmailMessageData table searches for records where MessageId is identical to InReplyTo. The first found record is set as the current ParentMessageId.
  2. The ParentMessageId field is populated with the current Id value in all EmailMessageData records if the InReplyTo field of these records is identical to the MessageId field.

Email thread connections are updated for every email.

Copying previous email connections in a thread 

Spreading activity connections across the thread upon adding an email. The Case field is used in this case.

A parent record with the activity that includes the populated Contact field is searched for the current EmailMessageData record. The Case field values from this activity will be spread across the thread. Starting with the found EmailMessageData record, all child EmailMessageData records are found and their Case field value is updated.

A thread with 3 emails:

ActivityId Title CaseId EmailMessageId EmailMessageParentId
28BD6D59-B9D7-4FF9-89F5-FEE1DD003912 Re: relation NULL 66812FBF-411B-4FE0-94C9-1E70FBBEB2D3 F05B529D-C98C-4E26-BE00-21F8721AEF58
DC0A40D4-700A-40EB-B394-90E0376C3B5D Re: relation 1C6E18E3-48B1-495E-8EF9-ACA35DB9DE0B F05B529D-C98C-4E26-BE00-21F8721AEF58 E1A0120E-B7C0-4261-9DE0-C63341BF1E0B
D7A9B82C-ED46-437C-980A-B2650D4FF3DA relation 906909E8-4D64-47FD-AF92-B65B0826AEC3 E1A0120E-B7C0-4261-9DE0-C63341BF1E0B NULL

Another email is received in the thread:

ActivityId Title CaseId EmailMessageId EmailMessageParentId
6623B052-73AD-4AE5-AE61-A6F9BCD930A0 Re: relation NULL 60C00B01-D0BF-40F6-923E-1830E433AEA1 66812FBF-411B-4FE0-94C9-1E70FBBEB2D3
28BD6D59-B9D7-4FF9-89F5-FEE1DD003912 Re: relation NULL 66812FBF-411B-4FE0-94C9-1E70FBBEB2D3 F05B529D-C98C-4E26-BE00-21F8721AEF58
DC0A40D4-700A-40EB-B394-90E0376C3B5D Re: relation 1C6E18E3-48B1-495E-8EF9-ACA35DB9DE0B F05B529D-C98C-4E26-BE00-21F8721AEF58 E1A0120E-B7C0-4261-9DE0-C63341BF1E0B
D7A9B82C-ED46-437C-980A-B2650D4FF3DA relation 906909E8-4D64-47FD-AF92-B65B0826AEC3 E1A0120E-B7C0-4261-9DE0-C63341BF1E0B NULL

Starting with the record in which EmailMessageId is "60C00B01-D0BF-40F6-923E-1830E433AEA1", a record with the populated CaseId column is searched (does not contain NULL). This is a record where EmailMessageId = "F05B529D-C98C-4E26-BE00-21F8721AEF58", and CaseId = "1C6E18E3-48B1-495E-8EF9-ACA35DB9DE0B".

Now, starting with the record in which EmailMessageId is "F05B529D-C98C-4E26-BE00-21F8721AEF58", Creatio updates the value of the CaseId field for the connected records throughout the thread.

ActivityId Title CaseId EmailMessageId EmailMessageParentId
6623B052-73AD-4AE5-AE61-A6F9BCD930A0 Re: relation 1C6E18E3-48B1-495E-8EF9-ACA35DB9DE0B 60C00B01-D0BF-40F6-923E-1830E433AEA1 66812FBF-411B-4FE0-94C9-1E70FBBEB2D3
28BD6D59-B9D7-4FF9-89F5-FEE1DD003912 Re: relation 1C6E18E3-48B1-495E-8EF9-ACA35DB9DE0B 66812FBF-411B-4FE0-94C9-1E70FBBEB2D3 F05B529D-C98C-4E26-BE00-21F8721AEF58
DC0A40D4-700A-40EB-B394-90E0376C3B5D Re: relation 1C6E18E3-48B1-495E-8EF9-ACA35DB9DE0B F05B529D-C98C-4E26-BE00-21F8721AEF58 E1A0120E-B7C0-4261-9DE0-C63341BF1E0B
D7A9B82C-ED46-437C-980A-B2650D4FF3DA relation 906909E8-4D64-47FD-AF92-B65B0826AEC3 E1A0120E-B7C0-4261-9DE0-C63341BF1E0B NULL

Note.

Mail servers sometimes send out letters in the wrong sequence, disregarding the way they were written in the thread

(e.g. during synchronization, emails are received first from the inbox and then from the outbox). This complicates the mechanism. Building a thread for the emails that were not received consistently is impossible during synchronization. In that case, a thread can be built once the synchronization is complete. If certain mailbox folders are not loaded, or if the conversation was interrupted by other participants, the thread search logic may not work. However, the thread can be built when all emails are downloaded from the inbox in most cases.

 

Recommendations for adding a custom search process for all thread connections after downloading an email 

Use the following guidelines to start working on a new email after thread formation:

  1. The Id field of the synchronization session appears in the EmailMessageData table (the values are unique for all synchronization processes). This field is populated only for synchronized emails.
  2. A record is added to the new FinishedSyncSession table if at least one email was received during synchronization.
  3. Certain processes that responded to the signal of saving activities now respond to the (Inserted) insertion signal of the FinishedSyncSession object. Emails from EmailMessageData are selected based on the synchronization session Id. The MailboxSyncSettings field of the EmailMessageData object can be used to select Email messages from the service box.

Macro handler in the email template 

The email templates can be used for communication with a service team. They are available in the Email templates lookup. More information about email templates setup can be found in the “Automatic emailing setup”.

For example, the Case closure notification template is used to notify the user that the case has been closed. A number of pre-set macros can be used to display the values of some system object columns in the emails (for example contact's title or job).

Creatio enables to implement a custom logic of adding values that is returned by the macro handler. During the processing of the macro the Creatio will execute the algorithm implemented by the developer instead of the basic logic.

The @Invoke tag points on the specific handler of a class. After that, the name of the class that implements the IMacrosInvokable interface with the GetMacrosValue() method should be specified after “.”. This method will return the string that replaces the macro string.

To implement custom macro handler:

  1. Create class that implements the IMacrosInvokable interface.
  2. Register a macro in the EmailTemplateMacros table by specifying the ParentId (base template with the @Invoke tag) and the ColumnPath (class name).
  3. Add a macro to the email template
Add a email filtering property
Medium

Case description 

Add a new No-reply property for case analysis. If the property is found in the email header and its value is anything other than “No”, treat the case as blacklisted.

Case implementation algorithm 

1. Add a new class that implements the IHeaderPropertyHandler interface. 

Add a “Source code” schema in a custom package (e.g. Custom). In this schema, define a class that implements the IHeaderPropertyHandler interface, e.g.:

namespace Terrasoft.Configuration
{
    using System;
    public class NoreplyHandler: IHeaderPropertyHandler
    {
        public bool Check(object value) {
            return string.Equals(value.ToString(), "No", StringComparison.OrdinalIgnoreCase);
        }
    }
}

Save and publish the new schema.

The IHeaderPropertyHandler interface is defined in the JunkFilter package, so it must be added to the custom package dependency.

2. Adding a lookup value 

Add the No-reply property to the Email header properties management lookup. Select the NoreplyHandler class (created in the previous paragraph) as the handler class (handler property).

After receiving an email with a No-reply header flag and a value that is anything other than “No”, the following options are possible:

  • the case is not created if the [Create Cases From Junk Emails] system setting value is false;
  • the case is created with the [Junk Case Default Status] system setting status if the [Create Cases From Junk Emails] system setting value is true.
Add the macro handler to the email template
Advanced

The example is relevant to Service Creatio products.

Case description 

Add the email macro handler that will return the “Test” string.

Source code 

You can download the package with case implementation using the following link.

Case implementation algorithm 

1. Creating the class which implements the IMacrosInvokable interface. 

To create class implementing the IMacrosInvokable interface, add the Source Code schema to the development package. For this, execute the Add – Source Code menu command on the Schemas tab in the Configuration section (Fig.1).

Fig. 1. Adding the Source Code schema
scr_add_source_code.png

For the selected schema specify:

  • [Title] – “Text string generator”.
  • [Name] – “UsrTestStringGenerator”.

Source code of the schema:

namespace Terrasoft.Configuration
{
    using System;
    using Terrasoft.Core;
    // The class of the macro handler for the Email template.
    public class UsrTestStringGenerator : IMacrosInvokable
    {
        // A user connection.
        public UserConnection UserConnection {
            get;
            set;
        }
        // A method that returns an substitution value.
        public string GetMacrosValue(object arguments) {
            return "Test";
        }
    }
}

Publish the schema.

2. Macro registration in the EmailTemplateMacros table 

To register macro in the EmailTemplateMacros, execute the following SQL request:

INSERT INTO EmailTemplateMacros(Name, Parentid, ColumnPath)
VALUES (
    'UsrTestStringGenerator',
    (SELECT TOP 1 Id
    FROM EmailTemplateMacros
    WHERE Name = '@Invoke'),
    'Terrasoft.Configuration.UsrTestStringGenerator'
)

3. Adding a macro to the email template 

After registering the macro you can use it in the email templates. For this, modify one or several records of the Email templates lookup (Fig. 2).

Fig. 2. The Email templates lookup
scr_lookup.png

For example to modify the content of the emails sent at case resolution you need to change the Case resolution notification record. If you add the #@Invoke.UsrTestStringGenerator# macro to the template (Fig. 3), the “Test” value will be displayed instead of the macro in the email sent to the customer.

Fig. 3. Macro in the email template
scr_template.png