In this article, I want to discuss how new rule templates for the Sage CRM Advanced E-mail Manager can be created and which SDK resources are available to developers.

I have written previously about the Advanced E-mail Manager and these articles are worth looking at again as they provide a useful set of background information about what features the Mail Manager provide and the possibilities this opens up for working inbound communications of all types.

About the Advanced E-mail Manager (Mail Manager)

The mail manager processes emails that come into the monitored accounts. Each monitored account is associated with a Script Template. The association is done in the administration screens.

Administration -> E-mail and Documents -> E-mail Management Server Options

The scripts that are shown available in the Template field are automatically drawn from a folder on the server.

C:\Program Files (x86)\Sage\CRM\Services\CustomPages\Scripts

The script files are written in JavaScript. There are several resources available for you to use when working with the Advanced E-mail Manager scripts.

There are dedicated snippets for the Advanced E-mail Manager for the simple Text Editor program Textpad

Textpad Snippet Files

There are also snippets available for the Visual Studio installed as part of the SDK.

The specialist E-mail Manager code snippets can be combined with the standard JavaScript snippets that can be used with either the classic ASP pages or with internal scripts like Validate or Table Level Scripts.

Sage CRM adds several script files as examples when it is installed. These provide very good patterns for any script that you may wish to create. An easy way of experimenting with the script files is to create a copy of a template like 'support.js'.

But the SDK resources do allow you to start assembling your own template script file quite easily.

Script files have a common structure.

• Comments
• Initialise Variables
• General Event Functions
  • BeforeMainAction
  • AfterMainAction
• Main Functions (referenced in Config screen)
  • N.B. MainAction is a reserved word. Do not call any function 'MainAction' as this is internally replaced with a function called from the configuration screen.
• Utility Functions

The JavaScript of these templates is processed by 'eWareEmailManager.exe' which runs as a service. It is processed externally from the main eware.dll and uses CRM's registered COM objects with some particular object available to it.

The Comments area is an important reminder that certain objects are automatically passed into the scripting environment as the template loads and is processed.

These objects are

• UserQuery
• PersonQuery
• CompanyQuery
• eWare
• MsgHandler
• eMail

An email being processed will have come from 'someone' and that 'someone' may be in the system and needs to be identified by the sender's email address.

The first three objects are 'QueryObjects' passed into the process that have carried searches using the SQL shown below

UserQuery

[code language="sql"]
SELECT * FROM vUsers WHERE
user_emailaddress = FromAddress
OR
user_mobileemail = FromAddress
[/code]

PersonQuery

[code language="sql"]
SELECT * FROM vEmail, vPerson WHERE email_personid
= pers_personid AND emai_emailaddress = FromAddress
[/code]

CompanyQuery

[code language="sql"]
SELECT * FROM vEmail, vCompany WHERE
emai_companyid = comp_companyid AND
emai_emailaddress = FromAddress
[/code]

You will note that Leads are not automatically scanned by the Mail Manager but the fourth object passed into the template scope is the eWare object.

The eWare object is more normally referenced as the CRM object and provides access to all the general API objects. The eWare or CRM object could then be used to search for the email address in the Lead table or if it was associated with any custom entity that may have been added to the system e.g. project. Through the use of the QueryObject it could also check the email address in external systems such as an ERP database.

All COM API interactions have to be done as a CRM user. This is part of system security. See the article "An Overview of System Security". The eWare or CRM object will have used the credentials provided in the Administration screen. This will typically be a user with Administration rights.

The MsgHandler allows for Debugging control and the eMail object represents the interface to the email and provides ways of accessing the recipients' list and any attachments. The same object can be used by the template script to both processes an inbound email but also to formulate an outbound email response.

Note: The email object is not available for either internal scripts like Table Scripts or ASP pages.

There are some other objects passed to the script. In the Administration screen shown above the administrator can configure

• Default Ruleset Assigned User
• Default Ruleset Assigned team

and

• Default Ruleset Action

The log files for the eWareEmailManager.exe service can be found here

C:\Program Files (x86)\Sage\CRM\Services\Logs

These would show how the additional objects are passed

**********RulesScript is...********
if (bCond)
{
AssignedUser = 4;
AssignedChannel = 1;
SalesEnquiry();
}
**********End of RulesScript.****

There will be another article that discusses how the Sage CRM Advanced E-mail Manager can be configured to use different functions within templates to allow the processing of emails according to business requirements.

Where alternative functions are specified then the additional object passed look like this

**********RulesScript is...********
if ((!CompanyQuery.EOF) && (CompanyQuery("comp_type")=="Customer")
)
{
AssignedUser = 4;
AssignedChannel = 1;
CreateRepeatSale();
bCond=false;
}

if (bCond)
{
AssignedUser = 4;
AssignedChannel = 1;
SalesEnquiry();
}
**********End of RulesScript.****

The comments section of a Template, therefore, acts as a good reminder of the objects that are passed to the process. The template script also needs to declare global variables that will facilitate the passing of data between the different functions within the template.

In the examples above we can see that a function called 'SalesEnquiry' is called. This is an example of a main action function.

The main action function defines the key behaviour invoked by the template. Typically this will further reference helper functions that do standardised tasks such as filing an email or providing the auto-response.

The Email Object

The email object is automatically passed to the template script and is globally available to all functions. It has properties and methods to allow the inbound email to be parsed.

Properties

• Body - String (read/write)
• IsHTML - Boolean (read/write)
• Subject - String; (read/write)
• Priority - Integer (read/write)
• Recipients - AddressList Object
• SenderName - String (read/write)
• SenderAddress - String
• DeliveryTime - Date
• Attachments - AttachmentList Object
• BCC - AddressList Object
• CC - AddressList Object

Methods

• Send()
• AddFile('physical path')
• Clear()
• Header("named header")

Code Example

In have attached an example template script file to this article which can be referenced to see how the object is used.

The example also discusses the way in which the email's addresslist and mail addresses can be parsed.

AddressList

Properties

• Items(index)
• Count - Integer(readonly)

Methods

• AddAddress(Address, Name)

MailAddress

Properties

• Name - String (read/write)
• Address - String (read/write)

AttachmentList

Properties

• Items(index)
• Count - Integer(readonly)
• LibraryPath - String

Attachment

Properties

• Name - String (read/write)
• Extension - String (read only)

Methods

• Save(Name, Path)
• SaveAs(Name, Path)