Email Templates

• 1. Overview
• 2. Installation
  • 2.1. From the Marketplace
  • 2.2. By Coordinates
• 3. Usage
  • 3.1. Creating Email Templates
  • 3.1.1. Creating Email Template From Report
  • 3.1.2. Creating Email Template From Designer
  • 3.1.3. Setting attachments
  • 3.2. Setting Groups
  • 3.3. Custom Blocks
  • 3.4. Sending Emails
• 4. Email Templates API
  • 4.1 Email Templates Builder
• 5. Predefined Roles
• Release notes

1. Overview

The add-on enables creating and configuring outbound email templates containing a constant body and variable parameters. A template is created in the visual HTML designer or by using reports. The add-on provides a visual HTML editor with the extensive set of HTML elements.

Sending emails from templates can be set as a reaction to different events in your application. You can preset recipients, configure parameters and upload attachment files to be sent with emails.

Key features:

• Visual HTML templates builder based on GrapesJS JavaScript library.
• HTML reports as a base for outbound emails body.
• Downloading/uploading HTML code of a template.
• User interface for configuring and managing templates.

See sample application using this add-on. See webinar on the CUBA Platform channel.

2. Installation

The add-on can be added to your project in one of the ways described below. Installation from the Marketplace is the simplest way. The last version of the add-on compatible with the used version of the platform will be installed. Also, you can install the add-on by coordinates choosing the required version of the add-on from the table.

In case you want to install the add-on by manual editing or by building from sources see the complete add-ons installation guide in CUBA Platform documentation.

2.1. From the Marketplace

1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.

2. Go to CUBA -> Marketplace in the main menu.

   

3. Find the Email Templates add-on there.

   

4. Click Install and apply the changes. The addon corresponding to the used platform version will be installed.

2.2. By Сoordinates

1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.

2. Go to CUBA -> Marketplace in the main menu.

3. Click the icon in the upper-right corner.

   

4. Paste the add-on coordinates in the corresponding field as follows:

   com.haulmont.addon.emailtemplates:yet-global:<add-on version>

   where <add-on version> is compatible with the used version of the CUBA platform.

   Platform Version	Component Version
   7.2.x	1.4.2
   7.1.X	1.3.1
   7.0.X	1.1.3
   6.10.X	1.0.3

5. Click Install and apply the changes. The add-on will be installed to your project.

3. Usage

You can use the following component features.

3.1. Creating email templates

The component enables you to create, edit and remove email templates.

To open Email template browser press Email templates in the Administration menu.

There are two ways to create email template: from report and from designer.

3.1.1. Creating Email Template From Report

The following parameters are available for editing:

• the Name field;
• the Code field;
• the Group drop-down;
• the Use subject from report checkbox;
• the Subject field (if Use subject from report unchecked);
• the From field;
• the To field;
• the Cc field;
• the Bcc field;
• the Report template to generate body lookup field.

If the report type is a report with an entity you can set entity for a template. In addition, you can set report parameters.

If the report type is a report with entities you can set entities for a template. In addition, you can set report parameters.

3.1.2. Creating Email Template From Designer

The following parameters are available for editing:

• the Name field;
• the Code field;
• the Group drop-down;
• the Subject field;
• the From field;
• the To field;
• the Cc field;
• the Bcc field.

The screen contains the following elements:

• the Import HTML button;
• the HTML code button;
• the View HTML button;
• the Export Report button;
• the HTML Editor.

This type of creating template provides the ability to use HTML editor. You can design a template with different elements and set every element, using Setting panel.

See more information about using the editor in README for GrapesJs HTML editor.

To add parameters and value formats go to the Parameters and Formats tab.

To create parameters automatically from template use Create from template button in the Parameters section.

See the complete parameter guide in CUBA Platform. Report Generator | External Report Parameters.

See the complete value format guide in CUBA Platform. Report Generator | Field Value Formats.

3.1.3. Setting attachments

You can add or remove attachments on the Attachments tab for both types of templates: from report and from designer. You can attach a report or a file.

You can set the following parameters for a report attachment:

• File name - a report attachment name for an addressee;
• an entity or entities for a report;
• parameters from a report.

3.2. Setting Groups

To open group browser click Groups in the Email templates browser. The screen enables you to create, edit or remove email template groups.

To create or edit the group enter the name of the group.

After setting groups, you can specify a group for a template.

3.3. Custom Blocks

The add-on enables creating custom blocks. Go Administration -> Email templates and click the Blocks button.

To create a new block click the Create button and in the Template Block editor screen you can move predefined HTML elements and change them on the canvas. Or you can see and set HTML code on the HTML tab.

You can put the created custom block to the predefined groups or create your own. Go Administration -> Email templates and click the Blocks button and then Groups button.

Your created custom HTML elements will appear in the Email template editing screen while creating an email template from designer.

3.4. Sending Emails

To send an email select a template in the list and click Send.

The following parameters are available for editing:

• the Subject field;
• the From field;
• the To field;
• the Cc field;
• the Bcc field.

The To field is required. You can select entity or entities for the report and set report parameter.

4. Email Templates API

A developer can use the following methods from EmailTemplatesAPI:

1. To create EmailInfo from a template that may contain the same reports with different parameter values:

   EmailInfo generateEmail(EmailTemplate emailTemplate, List<ReportWithParams> params)

2. To create EmailInfo by parameters map for all included reports:

   EmailInfo generateEmail(EmailTemplate emailTemplate, Map<String, Object> params)

3. To check that the report input parameter did not change its parameter type:

   void checkParameterTypeChanged(ReportInputParameter inputParameter, ParameterValue parameterValue)

The EmailTemplate entity contains subject, body, and attachments. It also contains from, to, cc, bcc addresses.

The ReportWithParams is a wrapper class that represents a report and a map of parameters for that report.

The ParameterValue is a class that provides a string representation of the parameter with alias and type.

The ReportInputParameter is a class of Reporting component.

The EmailInfo is a class of CUBA EmailService.

4.1. Email Templates Builder

Email templates API contains builder that can create and fill EmailTemplate entity.

EmailTemplateBuilderImpl is an implementation of EmailTemplateBuilder that provides intermediate methods for setting and adding email template properties. It also contains terminal methods that can build EmailTemplate, generate or send EmailInfo.

A copy of the specified EmailTemplate is created in the constructor. Every intermediate method fills the created copy.

    public EmailTemplateBuilderImpl(EmailTemplate emailTemplate) {
        this.emailTemplate = cloneTemplate(emailTemplate);
    }

The build() method creates the copy from the copy inside builder. It is necessary to save a state of the existed entity or builder.

Example of using the builder:

    EmailTemplate newTemplate = emailTemplatesAPI.buildFromTemplate(emailTemplate)
            .setSubject("Test subject")
            .setTo("address@haulmont.com")
            .setBodyParameter("entity", someEntity)
            .setAttachmentParameters(reportsWithParams)
            .build();

5. Predefined Roles

• email-templates-admin - grants access to all Email templates screens and entities.
• email-templates-can-send-templates - allows user to send created email templates as emails.