Adding the macro handler to the email template

Introduction

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).

Bpm’online enables to implement a custom logic of adding values that is returned by the macro handler. During the processing of the macro the bpm’online 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

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

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

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