Introduction

Email templates are pre-formatted and/or pre-written email messages. For example, customer service specialists often use email templates to automate routine communications with the customers. Bpm’online stores email templates in the [Email templates] lookup (e.g. the “Case resolution notification” email template is used to notify customers that their case has been resolved). Learn more about email templates in the Automatic emailing setup article.

Pre-configured macros are used in email message templates to fill them with certain object column values (e.g. to personalize emails with titles or phone numbers of contacts).

Bpm'online enables you to implement a custom logic of populating values, which returns a macro handler. In this case, the system executes the algorithm implemented by the developer instead of the base logic during the processing of macros.

The @Invoke tag points to a specialized class handler. Specify the class name of the IMacrosInvokable interface that includes the GetMacrosValue() method, separated by dots. This method must return a string that will substitute the macro string.

To implement a custom macro handler:

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

Case description

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

Case implementation algorithm

1. Creating a class that implements the IMacrosInvokable interface

To create a new class that implements the IMacrosInvokable interface, add the [Source Code] schema to the package used for development. To do this, go to the [Configuration] section of the system designer, select a custom package and on the [Schemas] tab, execute the menu command [Add] -> [User Task] (Fig.1). As a result, the source code designer window will open for further schema configuration.

Fig. 1. Adding a new [Source code] schema

Populate the following required values for the created object schema:

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

Add the following source code on the [Source Code] tab of the schema designer:

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

Publish the created schema.

2. Registering a macro in the EmailTemplateMacros table

To register a macro in the EmailTemplateMacros table, execute the following SQL query:

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

3. Adding a macro handler in the email template

After registering the macro, you can start using it in email templates. To do this, you must change one or more records in the [Email templates] lookup (Fig. 2).

Fig. 2. The [Email templates] lookup

For example, modify the [Case resolution notification] record to edit the email used to notify customers that their case has been resolved. If you add the [#@Invoke.UsrTestStringGenerator#] macro to the template (Fig. 3), the "Test” value will substitute the macro when the email is sent to the client.

Fig. 3. A macro in the email template