Entando plugin: Action Logger
Installation and configuration of the plugin jpactionlogger
The purpose of this guide is to provide a complete description of the Action Logger Plugin whose code is jpactionlogger for the Entando platform.
This guide is intended for both administrators and developers who wish to explore the capabilities of the Entando Plugin Action Logger 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, 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 Action logger plugin tracks the backoffice operations (Struts² actions). To accomplish this the plugin offers a Struts2 interceptor which, inserted in the XML definition of the action to be monitored, tracks all the invocations of that function. For each logged action are recorded the date and time, the namespace, the user and the value of the parameters involved; the administrator can also prevent some parameters (e.g. password) from being traced.
This plugin does not have a configuration interface, because the only configuration is done adding the interceptor to the XML definition of the action that we want to trace; the only interface added enables the administrator to consult the summary of the recorded actions.
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 commands for you in background.
jpactionlogger is a pure plugin, thus it neither affects the core of the system nor the existing functionality.
jpactionlogger directories are organized following the Maven Standard Directory Layout as shown in the Plugin Pattern.
It is worth noticing 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-jpactionlogger</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 jpactionlogger in a production environment the file entando-plugin-jpactionlogger-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.
-
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.
To configure jpactionlogger you are required to locate the Struts² file which declares the actions to trace.
The first step is to open the Struts² file containing the actions to modify and add the declaration of the new interceptor inside the package declaration:
<interceptors>
<interceptor name="jpactionlogger_actionLogger"
class="com.agiletec.plugins.jpactionlogger.
apsadmin.system.ActionLoggerInterceptor" />
</interceptors>and then insert the following reference
</interceptor-ref><interceptor-ref name="jpactionlogger_actionLogger" />inside the definition of the desired action.
Lets say that we want to monitor the actions involved in the creation of a new user, namely new and save, excluding the password from being recorded. A correct Struts² action file which overwrites the one of the core, would be the following:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE struts PUBLIC
"-//Apache Software Foundation//DTD Struts Configuration 2.1//EN"
"http://struts.apache.org/dtds/struts-2.1.dtd">
<struts>
<package name="core_do/UserMonitor" namespace="/do/User" extends="entando-default">
<interceptors>
<interceptor name="jpactionlogger_actionLogger"
class="com.agiletec.plugins.jpactionlogger.apsadmin.system.ActionLoggerInterceptor" />
</interceptors>
<action name="new" class="userAction" method="newUser">
<result type="tiles">admin.User.entry</result>
<interceptor-ref name="entandoDefaultStack">
<param name="requestAuth.requiredPermission">superuser</param>
</interceptor-ref>
<!-- we have no parameters -->
<interceptor-ref name="jpactionlogger_actionLogger" />
</action>
<action name="save" class="userAction" method="save">
<result name="input" type="tiles">admin.User.entry</result>
<result type="redirectAction">list</result>
<interceptor-ref name="entandoValidationStack">
<param name="requestAuth.requiredPermission">superuser</param>
</interceptor-ref>
<!-- we don't want to track the passwords! -->
<interceptor-ref name="jpactionlogger_actionLogger">
<param name="excludeParams">password</param>
</interceptor-ref>
</action>
</package>
</struts>Please note that when the interceptor is inserted in a stack the correct declaration that prevents a parameter from being recorded is the following:
<interceptor-ref name="jpactionlogger_actionLogger">
<param name="jpactionlogger_actionLogger.excludeParams">password</param>
</interceptor-ref>This approach is slightly different from the example file; multiple excluded parameters are separated by a comma in both cases.
Create a new user whose name and password are “Matteo” and “mypassword”, respectively. Access interface from Plugins → Action Logger: you are presented with all the actions tracked.
Action Logger behaved as expected: we see that the “admin” created a new user named “Matteo”. The careful reader might have noticed that though the “password” parameter was not recorded, the password used for confirmation is clearly displayed, and this is not what we intended: adding the exclusion for the “passwordConfirm” parameter solves the problem:
The correct configuration of the parameters to be excluded is shown below:
<!-- we don't want to track the password! -->
<interceptor-ref name="jpactionlogger_actionLogger">
<param name="excludeParams">password,passwordConfirm</param>
</interceptor-ref>