Entando plugin: Newsletter
Installation and configuration of the plugin jpnewsletter
The purpose of this document is to provide a complete description of the Entando Newsletter plugin whose code is jpnewsletter for the Entando platform.
This document is intended for both administrators and developers who wish to explore the capabilities of the Entando Plugin Newsletter 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 document, it is necessary to have basic knowledge of the Java platform, the servlet engine Apache Tomcat, PostgreSQL (or MySQL) DBMS and the Entando platform.
Moreover, it's necessary to have read the Plugin Pattern for the installation procedure and an explanation of the standard directory layout.
The jpnewsletter plugin enable the administrator to send contents via email to specific subscribers. Subscribers can be both registered who agreed to the service or visitors that subscribed the newsletter providing their email address.
The newsletter delivery can be scheduled or activated in any moment by the administrator.
It is worth noting that all the users of the Entando platform are eligible for the newsletter service, whatever their origin is (standard users, LDAP imported users, etc).
The content sent by the newsletter service can be associated to one or more categories or to no categories at all; registered users can subscribe the newsletter and choose the categories of interest (or none to receive the newsletter in its entirety) depending on the profile configuration created by the administrator. Is it responsibility of the administrator to create a profile with at least a boolean attribute to toggle the activation of the service.
Portal visitors (or guests), without an associated Entando user, have the option to provide their email address through a registration form. The system sends an email containing a link to confirm the registration. Such users, being unable to select the categories will receive only public contents or, in other words, those contents associated to the free group: categories are not taken into account.
Due to its nature, jpnewsletter requires as a prerequisite two plugins: Manage User Profile and Email Sender. This information is relevant only for the installations in production environments: the administrator is required to manually provide the prerequisites. For further details on those plugins consult the respective manuals.
For installations in a development environment there are no problems because Maven takes care of the prerequisites automatically; 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 document, a few Maven and Ant commands are shown: your IDE has probably the ability to execute those commands for you in background.
jpnewsletter is a pure plugin, thus it neither affects the core of the system nor the existing functionality.
This module installs three new Widgets and has four management pages in the backend; note that the Widgets have no graphical decoration.
jpnewsletter 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 tag dependencies 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-jpnewsletter</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 ID of the deployed portal.
All Entando plugins can be downloaded from the Maven Central repository, just filter by code and by version.
To install jpnewsletter in a production environment the file entando-plugin-jpnewsletter-3.2.0.war is needed; we will refer to this file as WAR package.
The WAR package might contain the dependencies of other plugins; when performing copy operations you may accidentally overwrite your previous customizations of the JSP files, so you are warmly recommended to create a backup of your installation.
The integration activity must be performed after the servlet container has been stopped.
-
install the plugins Email Sender and Manage User Profile in the production environment (consult the relative documentation for the correct procedure to follow), if they are not already present.
-
copy the content of
WEB-INF/libdirectory of the WAR package, tomyportal/WEB-INF/lib/directory. -
create the directory
myportal/WEB-INF/plugins/if it does not exist. Copy the content ofWEB-INF/plugins/directory of the WAR package, tomyportal/WEB-INF/plugins/.
Now the servlet container can be restarted.
This plugin offers many management interfaces: you have the Configure page, the Delivery Queue management, the Contents management and finally the Guest Subscribers management.
All of these menu are easily accessed via the Plugins → Newsletter menu.
The configuration page enables the administrator to:
-
specify the content type eligible for delivery (and the relative content models)
-
activate the scheduler and set the delivery time
-
associate the categories to a specific profile attribute
-
compose the HTML and plain text templates of the mail of the newsletter
-
compose the templates of the mail used for the subscription of the occasional user
(to each line of the list corresponds a section in the administration page)
In the Basic section of the page we have the following controls:
We toggle the service and we set the scheduler activity; We also choose the contents -and the relative content models - of the newsletter clicking and the Add button next the the Content Type select.
In the Categories section we establish a correspondence between the categories of the contents of the newsletter and the attributes of the user profile
In the image above you see the category News is tied to the profile attribute News of the user profile. The users with the News attribute set to true will receive all the contents sharing this category; in a similar manner users with the Sport attribute set to true will receive the sport news.
Please consider that if the “sport” category is a child of the “news” in the category tree, the users who have the attribute News set to true will also receive the sport news.
You may appreciate that this is the exact situation depicted in the figure above where the Category field shows clearly that “Sport” is a child of the “News” category.
You add new category-attribute binding using the Add button and remove a single element from the list clicking in the remove icon.
Is an administrator responsibility to provide correct user profiles for the newsletter service: at least one boolean attribute must be given to enable users to receive all the newsletter regardless of the category settings (in fact the association between categories and profile attributes is entirely optional). The attribute used to subscribe the newsletter is declared in another section which will be shown later in this chapter.
In the Messages section we setup all the templates - both plain text and HTML – of the newsletter. Please note that you enable the HTML delivery by checking the I want to send HTML format checkbox before the HTML templates textarea fields.
The administrator chooses the Sender to deliver emails among those defined in the system through the jpmail plugin management pages.
In the Subscription section you control how the users subscribe the newsletter service.
By users we intend Entando system user who have a profile associated. Visitors (or guests) are the occasional users of the portal who didn't registered themselves.
For registered users the administrator chooses which attribute is used for the eMail and the boolean attribute for the newsletter Subscription.
The guest visitors subscription process happens this way: the users submit their own email addresses in a specific portal page then, upon receiving a automatic message, confirm the subscription clicking on the provided link: from that moment on users will receive the newsletter.
In every newsletter received is present a footer with a link that allows the user to unsubscribe with a simple click: users are required to confirm the operation.
The unsubscribe link is present only in the newsletter sent to guest visitors.
For the process described above to work is necessary to configure properly the following parameters located in the Guest part of the section; this part is divided in two sub-sections namely Subscription and Cancellation where the settings for the different phases of the process are placed.
For Subscription:
-
Confirm page is the page where is placed the Widget Newsletter – Subscription Confirm where the visitors receive confirmation of their subscription.
-
Link validity is the validity of the link provided with the confirmation mail, expressed in days.
-
Plain Text and HTML are the templates used for the confirmation mail. Within the template the token {subscribeLink} is expanded with the link generated by the plugin.
For Cancellation:
-
Confirm page is the page where the user lands to confirm the removal operation; in other words this is the page where the Widget Newsletter - Unsubscription is placed.
-
Plain Text – Footer and HTML – Footer are the templates of the footer inserted in the newsletter (again, for the guest visitors only): the token {unsubscribeLink} will be expanded with the link generated by the system.
In the Plugins → Newsletter → Contents the administrator decides which contents will be included in the next delivery
Using the Search button it is possible to restrict the number of contents available for delivery: by default this management page displays all the contents of the types defined in the Configure page. In the image above we chose those contents which have the world “option” in their body / title and which weren't previously sent and are not already present in the delivery queue.
The contents are added to the newsletter simply selecting the relative checkbox and pressing the Add to the next Newsletter button; if no content is put in the delivery queue the newsletter won't be sent!
It is worth noting that the search result returned may be enriched with additional columns specified in the Add to the table of result section, as shown in the next picture:
As a side note, It is always possible to add new contents in the delivery queue even when the service is not active.
The delivery queue page gives a comprehensive view of what will be sent in the next newsletter run.
The administrator can remove anytime contents from the delivery list anytime by clicking on the removal icon.
The Send Now button, present only if the service is active, will start immediately the delivery when pressed.
The immediate delivery request does not affect the scheduler in any way.
Guest Subscribers management page is accessed form the Plugins → newsletter → Guest Subscribers.
This page gives a list of the visitors who have subscribed the newsletter service. The administrator can delete those users anytime from the list so removing them from the receivers: the removal, carried out by clicking on the remove icon, is permanent and cannot be undone.
Though by default all the users will be listed, you may refine the search by mail address and the status of the user; Active are those users who confirmed their subscription, Not Active haven't confirmed yet while All applies the filter regardless of the status.
The guest status is also indicated by the sun or the moon icon in the column labeled A in the relative list entry.
The administrator must choose the page where the Widget Newsletter - Subscription is placed. The following screenshot is taken from the PortalExample 3.2.0 demo and actually images may differ; please remember that the Widgets of the package have no graphical decoration at all
As explained earlier, the administrator must configure in the Plugins → Newsletter → Configure the pages where the guest visitors receive confirmation of the subscription or removal processes.
After clicking in the confirmation link received in the mail the user receives confirmation from the Newsletter – Subscription Confirmation Widget
Clicking on the removal link of the newsletter received, the user lands where the Widget Newsletter – Unsubscription is placed:
