Entando plugin: User Registration
Installation and configuration of the plugin jpuserreg
The purpose of this document is to provide a complete description of the Entando User Registration plugin whose code is jpuserreg for the Entando platform.
This document is intended for both administrators and developers who wish to explore the capabilities of the Entando Plugin User Registration 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 and the documentation relative to the eventual dependencies of the present plugin; such dependencies will be declared in the next chapters.
The User Registration plugin let users register themselves to the portal and later to sign in. This is accomplished with a number of Widgets: Login Form - With registration management, User Activation, User Reactivation, User Recover, User Registration, User Registration - With profile choice and User Suspension. As for the administration area, you need to configure mail templates and a few other options that will be shown later.
The registration procedure requires the insertion of fields name, surname, language and email. When user provides required data, he receives an email with a link with a ticket valid for account activation. By ticket we mean a special code -called token- provided in form of a HTTP link which lets users interact with the registration system for a fixed amount of time.
Clicking on the link provided the user accesses to a page to finalize the registration procedure. During this procedure the user have to set the password. Upon completion the user has an account to access reserved area on portal.
The reactivation process allows the user to recover the password (if lost) or to reactivate an account, previously deactivated, redefining the password.
The password recovery procedure requires the user to provide the username or the email address from his/her profile on the portal. If the data provided are correct the user receives an email containing a link with a new ticket to update the password of the account.
Due to its nature, jpuserreg 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 command for you in background.
jpuserreg is a pure plugin, thus it neither affects the core of the system nor the existing functionality.
The module presents a set of interfaces for the Front-End. These interfaces do not contain any graphical element. In this way it's possible to decorate them as you prefer.
jpuserreg 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-jpuserreg</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 jpuserreg in a production environment the file entando-plugin-jpuserreg-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 contents of the folder
WEB-INF/libof the WAR package supplied in the foldermyPortal/WEB-INF/lib/in production. -
create the directory
myportal/WEB-INF/plugins/. Copy the contents of the folderWEB-INF/plugins/of the WAR package in the foldermyPortal/WEB-INF/plugins/in production. -
copy the content of the directory
resources/pluginsof the WAR package intomyportal/resources/plugins/within the servlet container.
Now the servlet container can be restarted.
In a nutshell, to configure this plugin you have to create a profile type (or reuse one of your choice) and then configure the Widgets accordingly. You have a number of administrative decisions to take and some email templates to prepare too, and this is just shown below.
From the left panel of the of the administration area Plugin → User Registration → Configure.
Let's watch closely to the various administration sections:
In Info you set the Token Validity or, in other words, the time in which the receiver has to confirm the registration before the expiration of the token itself; Sender allows to select the email address used by the system to notify the users.
In Groups and Roles we assign the new users to a specific group(s) and role(s).
In user Activation and Reactivation we insert the email templates -one for each language of the portal - used for the various notifications (we show only the Activation section because they are identical).
When composing the templates (as you may have noticed in the picture above) you have a small set of keywords surrounded by braces: {name}, {surname} and {link}.
{name} and {surname} are substituted with the name and the last name of the registering user, while {link} will be expanded with the HTTP link used to confirm the registration.
For a newly created profile, to be considered as a possible candidate for the user registration process, it must contain an attribute with the role jpuserprofile:mail assigned to it. The name of the attribute is not really important because what triggers the user registration plugin later in the Widget configuration, is uniquely the role of the attribute. So if you want to reuse an existing profile make sure that condition above is met.
In the image below we have assigned the correct role jpuserprofile:mail to an attribute named email from the entity management of the User Profile plugin (please refer to the jpuserprofile documentation for further information). However we don't discuss about the configuration of the profile entities because it works in the same way of the content management.
To conclude the configuration process you have to place the Widgets, shown in the picture below, in the pages of choice; the list of all the system Widgets can be accessed from the left menu → Widgets in the administration area.
Login form - with registration management: it displays a sign in form with a link to edit the profile of the current logged user.
User Activation: this is where the user lands after having clicked on the verification token received in the mail.
User Registration: let the user start the registration process.
User Registration - with profile choice: the same as above, with the difference that users can choose their profile type among those made available.
User suspension: let users suspend their own account.
User Recover: let the user retrieve access credentials by providing the correct username or email address.
User reactivation: this is where the user lands after having clicked on the verification token received by mail.
Now it's time to configure the page and select the frame where to place the Widgets. Then you have to configure the User Registration Widget:
As you can see this Widget was configured so that the new registered users will have a profile of type City dweller. Please remember that in the Profile Type select will be listed only those profiles that have an attribute configured with the role jpuserprofile:mail.
The configuration process ends with all the Widgets placed in their respective pages; to test this plugin make sure in advance to have a properly configured and working jpmail plugin.