How to use images in Mail Operation

by Ombretta Malinverno
2,168 views Published on Nov 27, 2017
Applies to: 7.2 or higher
Table of contents

Introduction

The Mail Operation permits users to send personalized emails to each destination address. The email body can be dynamically computed, replacing placeholders in the defined templates with the real content. The email body can also contains images. There are two different cases:

  1. The email body contains a static image.
  2. The email body contains a placeholder to include an image that changes according to the instances.

 

At runtime, the process to retrieve the resource of the image is:

  1. The resource is searched as a public resource located in the application directory.
  2. The resource is searched as a BLOB, which can be located outside the application directory, such as in a protected uploaded file or in the database.
  3. If no resource has been found, the received HTML email shows the missing image icon instead of the real image.

 

In this article you learn how to include static and dynamic images in the body of your emails.

How to use static images

Suppose you want to send an email to a user when he registers; the email body can contain your company logo as a header, which means that the image is predefined and is the same for all emails. The model representing this feature can be something like the one shown in the following figure:

Follow the procedure to configure the Mail Operation:

  1. Add a Placeholder for each piece of dynamic information you want to add to the email body

    Move to the Outline View, right-click on the Mail Operation, and select the Add > Placeholder option. The name of each placeholder is used in the email body to indicate where they must be replaced. The value of the placeholder is not specified, because it must not have a default value.
    In this example, the modeled placeholders are the following:

  • "Username". The username submitted by the user.
  • "Password". The password generated when the user is created.

  1. Configure an SMTP Server that delivers messages. Move to the Property View of the Mail Operation, press on the Select button next to the SMTP Server property and click on the Create new SMTP Server.. link. Refer to the procedure in the "Looping & Branching" online lesson to set the properties of the SMTP Server.
  2. Set the email format. Choose the "HTML" option in the Format property. 
  3. Create a Body Template File. Press on the Browse button next the Body Template File property to create a new template file. Give a name to the file (e.g., "StaticImages.mt") and press OK to confirm. The file is automatically associated to the Mail Operation, and its content will be used as the email body.

The template for the email can be as follows:

<html> 
  <body>
    <div>
      <img src="upload/webratio-logo.png"/>
    </div>
 
    <div>
      Dear Customer,
    </div>

    <div>
      Your subscription was accepted.
      Your access information are:
    </div>
 
    <div>
      <b>Username</b>: $$Username$$
    </div>
 
    <div>
      <b>Password</b>: $$Password$$
    </div>
 
    <div>
      Visit our <a href="http://www.webratio.com">web site</a> to know the WebRatio world.
    </div>
  </body>
</html>

The placeholders are inserted in the email body with the notation $$placeholderName$$.

The proposed template produces as result an email, as in following the image:

The image is added to the email as <img src="{path-to-image}"/> where the {path-to-image} can be:

  1. The relative path identifying a style image resource (e.g., Resources/webratio-logo.png).
  2. The relative path identifying an uploaded public image (e.g., upload/ent1/1/webratio-logo.png) in the case of the upload directory is contained in the Web application deploy directory. In the example this option is used.
  3. The relative path identifying an uploaded protected image (e.g., ent1/1/webratio-logo.png) in cases in which the upload directory is contained outside the Web application deploy directory.

How to use dynamic images

Suppose you want to keep your customers up to date about your new products. Each time you add a product, an email is sent to the customers with some product details (name, description and photo).

The model is shown in the following image:

Follow the procedure to configure the Mail Operation:

  1. Add a Placeholder for each dynamic information you want to add to the email body. Move to the Outline View, right-click on the Mail Operation, and select the Add > Placeholder option.

    The name of each placeholder is used in the email body to indicate where they must be replaced. The value of the placeholder is not specified because it must not have a default value.
    In this example, the placeholders are the following:

  • "Code". The code of the product.
  • "Name". The name of the product.
  • "Description". The description of the product.
  • "Price". The price of the product.
  • "Image". The uploaded image that represents the product.

  1. Set an SMTP Server that delivers messages. Move to the Property View of the Mail Operation, press on the Select button next to the SMTP Server property, and click on the Create new SMTP Server.. link. Refer to the procedure in the "Looping & Branching" online lesson to set the properties of the SMTP Server.
  2. Set the email format. Choose the "HTML" option in the Format property.
  3. Create a Body Template File. Use the Browse button next the Body Template File property to create the template file. Give a name to the file (e.g., "DynamicImages.mt") and press OK to confirm. The file is associated to the Mail Operation and its content will be used as the email body.

The template for the email can be as follows:

<html>
  <body>
    <div>
      Dear Customer,
    </div><br/>
 
    <div>
      There is a new product for you:
    </div><br/>
 
    <div>
      <b>Code</b>:  $$Code$$
    </div>
 
    <div>
      <b>Name</b>:  $$Name$$
    </div>
 
    <div>
      <b>Description</b>:  $$Description$$
    </div>
 
    <div>
      <b>Price</b>:  $$Price$$
    </div>
 
    <div>
      <b>Image</b>:  <img src="$$Image$$"/>
    </div>
  </body>
</html>

The placeholders are inserted in the email body with the notation $$placeholderName$$ .

The template produces, as result email as shown in the following image:

The image, that is a BLOB attribute of the Product entity, is added to the email as <img src="$$Image$$"/>, and the placeholder $$Image$$ will be replaced with the image path.

How to use the sample project

You can use the attached "MailImagesSample.zip" sample project to see the proposed examples in action.

Follow these steps to use the project:

  1. Import the sample project in WebRatio Platform; you can learn how to do this by watching the "Organize the Workspace" online lesson.
  2. Set the properties of the SMTP Server, connected to the Mail Component used in the project. You can refer to this procedure in the "Looping & Branching" online lesson.
  3. Change, in the "Init" action definition, the values passed to the "Create User" operation for inserting an existing email. In this way, you can test the send of the email.
  4. Generate the project with the Generate and Run on Cloud command if you have a WebRatio Community Platform version; otherwise, use the Generate and Run command.
  5. Visit http://localhost:8080/AcmeMailOperationProject/page1.do or http://freeXXXXX-freeapp.eu.webratio.net/page1.do with any browser and test the application.