Skip to main content
Matrix42 Self-Service Help Center

Designing Emails

Overview

The article explains the overall principals of Email Designer, namely how the Email Designer is used for authoring Emails, how the System stores and process the designed Email, and how the Emails templates delivered out of the box could be customized.

Description

To design the Email template which will be used further for generating emails, the Solution Builder uses Email Descriptor object. The Email Descriptor defines list of input parameters the final generated email depends on, and which forms the default Data Model fro the Email Designer. Once the Descriptor is created, you can use action "Customize" to start Email Designer for authoring the Email Subject and Body. 

Email Designer, in general, is a special mode of Layout Designer  adopted for designing Emails, and the same designing experience of Email Engine  is identical to designing any other Layouts in the Solution Builder(e.g. Preview).  All the artifacts, like Toolbox with range of Controls, Designing canvas and Data Model is present. The Data Model could be easily extended by incorporating Additional Data Sources, the Data Model properties also can be dragged & dropped to canvas. But, as far as, the way how the Email generated is absolutely different from the way other Layouts are built, as it is built on Server Back-End, whereas others are composed on Client browser, the Email Designer has some peculiarities.  

Designing Canvas

The Canvas of the E-mail Designer is enclosed into the rich text editor which you can use to create and format the body of the Email template. Simply type and, optionally, format the text of the email’s body using the rich text editor, then drag the desired controls and/or Data Model property from the Toolbox or Data Model and drop them into desired locations. In case the property is dropped in a new paragraph, the Designer automatically inserts or suggests one of the available Control which fits to the Property data type. But, when the Property is dropped in existing paragraph with text, the Designer inserts a placeholder, exactly in a point the property has been dropped. The placeholder has the following pattern {model:property path}, and could be added to Body or Subject automatically on drop, or typed manually. Here the example of placeholder usage

Your ticket {model:Parameters.Incident.SPSActivityClassBase.TicketNumber} has been closed

Localization

Email Engine on generating Emails analyzes the preferable language of the recipients, and creates mail in appropriate languages, if the localization of the Email Template is present. The localization of the Email Template can be easily done inline in Email Designer, when you authoring the Email. The Email Designer automatically creates necessary Localization Strings when you defines text on canvas or Subject, which could be localized either by switching the Email Designer canvas to another language or using Localization String Editor.

To see how the Email looks like for different languages use the Language switcher on top of the Canvas. It immediately adopts the WYSIWYG designer to use selected language, and allows in a single glance to identify which strings missing translations, and provide the right text for the selected language directly in designer.

EmailLanguageSwitch.png


Another alternative for Localizing Emails available in Email Designer is using Localization String Editor, which could accessible on clicking the yellow flag on the begging each paragraph with text. In contrary to Language switcher option, this Flag is available only after save of the Email Designer. 

As well as in ordinary Layout Designer the Solution Builder allows to use already present Localization strings (from Data Model or Global strings) for setting properties of the controls.

Data Model

All the data required to be used in Email Template need to be declared in Data Model. On the first run of the Email Designer the Data Model already keeps data which have been specified as parameter on Email Descriptor definition. For the parameters of simple types (e.g. String, Integer, DateTime) the Data Model has an appropriate property with the same name and type. Whereas for parameters of some Schema type (Data Definition or Configuration Item), the Data Model automatically fill the Data Model with the full structure of the referenced Schema type, so the Configuration Item or Data Definition attributes can be immediately used.

The Data Model for Emails has some restrictions in compare to other Layout Templates. As far the Email created on Server, the usage of Javascript expressions are disabled in Email Designer, what means, missing the possibility to define Calculated properties in Data Model. Instead of them, for building dynamically complex strings the Email Designer provides the light way, which allows to use simple placeholder format for building additional Data Sources filters.

EmailDesignerFilter.png

Just like for any other widget, such as a Dialog, users can  incorporate additional data to Data Model, by "Add Data Source" to the Data Model. The Implementation options for a new Data Source are limited to Configuration Items and Data Definitions (for performance reason, the System does not allow to add Web Service Data Source). 

Toolbox

Due to absolutely different way the Emails are generated compare to ordinary Layouts (Dialog, Preview), the  Email Designer provides a new set of Controls, which nohow intersect with Controls in Layout Designer. 

 

 

  • Was this article helpful?