Entando plugin: Email Sender
Installation and configuration of the plugin jpmail
The purpose of this guide is to provide a complete description of the Entando Email Sender Plugin whose code is jpmail for the Entando framework.
This guide is intended for both administrators and developers who wish to explore the capabilities of the Entando Plugin Mail and are considering a possible integration into a running production environment or in a Development Environment.
In order to take maximum advantage from the present guide, it is necessary to have basic knowledge of the Java platform, Java Servlet containers, PostgreSQL (or MySQL) DBMS and the Entando Framework.
Moreover, it's necessary to have read the Plugin Pattern guide for the installation procedure and an explanation of the standard directory layout.
The Email Sender plugin provides the basic email functionality to your Entando installation, so that it's possible to send emails both in plain text or HTML, with or without attachments. This service is the first prerequisite for all those plugins requiring email delivery.
Though the plugin installation is not difficult at all, we are going to modify the system tables, so a backup of your database is highly recommended. Furthermore, you may be required to customize the scripts to your needs before installation.
For the purpose of the current guide, a few Maven and Ant commands are shown: your IDE has probably the ability to execute those command for you in background.
The Email Sender plugin is a pure plugin because its installation neither modifies nor alters any system functionality.
jpmail directories are organized following the Maven Standard Directory Layout as shown in the Plugin Pattern
It is worth noting that the plugin installation is greatly changed from the previous releases (thank you, Maven!).
As always when it comes down to install new things, stop your servlet container before moving on.
Open the pom.xml of your project: locate the <dependencies> tag toward the end of the file, after the <build> tag; if the dependencies tag doesn't exist just create a new one just after the closure of the build tag.
Add the following snippet inside the dependencies:
<dependency>
<groupId>org.entando.entando.plugins</groupId>
<artifactId>entando-plugin-jpmail</artifactId>
<version>${entando.version}</version><!-- version. Don't remove this comment. -->
<type>war</type>
</dependency>You are done! You can verify the correct installation of the plugin going to the administration area and checking for the new item in the Plugins menu.
From now we will use the name myportal when referring to your deployed Entando application or, in other words, to the artifact name of the portal.
All Entando plugins can be downloaded from the [Maven Central repository] (http://search.maven.org/#search|ga|1|entando-plugin), just filter by code and by version.
To install jpmail in a production environment the file entando-plugin-jpmail-3.2.0.war is needed; we will refer to this file as WAR package.
The integration activity must be performed after the servlet container has been stopped.
-
copy the content of
WEB-INF/libdirectory of the WAR package, tomyportal/WEB-INF/lib/directory. -
make sure that the directory
myportal/WEB-INF/pluginsexists, otherwise create it. Copy the content ofWEB-INF/plugins/directory of the WAR package, tomyportal/WEB-INF/plugins/.
Now the servlet container can be restarted.
This plugin can be easily configured from the administration interface: basically we have to set up the network configuration and create at least one sender profile. it is worth noting that by sender profile we do not mean the users profile functionality as offered by the User Profile (entando-plugin-jpuserprofile) plugin: we will discuss later about that in the senders management paragraph.
From the left menu panel of the administration area: Plugins → eMail Configuration → Smtp Server
You are presented with the network administration panel, with a number of default values.
The General Settings section is pretty straightforward: two checkbox toggle the activation and the debug mode as shown in the figure below
Enabling the debug mode is warmly recommended to fix all the problems that might arise from mail sending.
Disabling the mail service will obviously prevent the system to send any email, resulting in an error of those services that need that functionality.
In the Connection section you must specify the SMTP Host, Port, type of the Security and the Timeout. The port and the timeout get respectively the values of 25 and and 10000 msecs if left blank.
In the Authentication section you specify the Username and the Password if the smtp server requires it. Please remember that the password is saved in clear text in the email configuration item jpmail_config in the sysconfig table of your Port database.
From the left panel click on Plugins → eMail Configuration → Senders to access the management area. The idea behind is rather simple: we insert here all the email addresses that the system will use to send email. All these email addresses are uniquely identified by a code that can be exposed to those services that require email functionality (e.g. the Newsletter service).
The insertion, edit and removal operations are carried, respectively, clicking on the New Sender link, on the email address and on the Remove button.
Insertion of a new email address
Editing an existing sender
You are not allowed to change the Code to avoid affecting the services referencing the address currently on edit.
Deletion of a sender
Clicking on the removal icon you will be asked for confirmation:
Depending on the implementation of the service that relies on the email plugin, you might be prevented from deleting a sender that is currently in use.