openxava / documentation / Email data changes notifications (new in v5.9)

Since v5.9 the user can follow any module just by clicking on an icon on the right top corner:

After clicking on it any change done by other users on the data of that module will be notified via email to him. He can click on any moment on the same button to unsubscribe. In order to work the user need to have a valid email defined in his account (XavaPro or Liferay) or well to use a valid email as user name (also available with plain OpenXava in naviox-users.properties). Subscribing to a module is not available for modules with @Tab with baseCondition for security reasons.
Moreover, when a user creates a new record, all the changes in that invididual record by other users are emailed to him.
In each message the user has links to remove his subscription.
The changes notified are: creation of new records, modification, deletion of records, adding comment to discusion, adding/removing images from gallery, adding/removing attached files and modification of collections.
In the case of modification the email message informs about the properties modified with the old and new values.
Configure
This feature is disable by default. In order to active it you have to follow the next steps.

Adding the subscription entity to persistence.xml

In the persistence.xml of your project add the org.openxava.util.impl.EmailSubscription entity:

<persistence-unit name="default">
    <provider> ... </provider>
    <non-jta-data-source> ... </non-jta-data-source>
    <class> ... </class>
    <class>org.openxava.util.impl.EmailSubscription</class>
    <properties>
        ...
    </properties>
</persistence-unit>
 
<persistence-unit name="junit">
    <provider> ... </provider>
    <non-jta-data-source> ... </non-jta-data-source>
    <class> ... </class>
    <class>org.openxava.util.impl.EmailSubscription</class>
    <properties>
        ...
    </properties>
</persistence-unit>
 

We include it in junit persistence unit too, to be recognized by updateSchema Ant target.

Creating subscription table

You have to create the next table in your database:

CREATE TABLE OXEMAILSUBSCRIPTIONS (
 module VARCHAR(80) NOT NULL,
 email VARCHAR(50) NOT NULL,
 PRIMARY KEY (module, email)
);
CREATE INDEX UK_mo4jh7y2lwcbl9twwxjn2733e
 ON OXEMAILSUBSCRIPTIONS (module);

Maybe you'll need to adapt the above sentence to your own database dialect.
If you create the tables from JPA entities (using updateSchema Ant target or with hibernate.hbm2ddl.auto to update in persistence.xml) this step is not needed.

Email settings in xava.properties

If you don't have the email setting in xava.properties already configured you have to do it. For example:

smtpHost=smtp.gmail.com
smtpPort=587
smtpUserId=myoxapps@gmail.com
smtpUserPassword=openxava
smtpHostTrusted=true
smtpStartTLSEnable=true

Don't use the above data as is, you have to put your own email account settings.

Defining the access tracker provider in xava.properties

Finally add the next entry to the xava.properties of your project:

accessTrackerProvidersClasses=org.openxava.util.EmailNotificationsAccessTrackerProvider

If in any moment you want to disable the email notifications feature just remove or comment the above line.

Programmatic use

You can subscribe and unsubscribe users for modules or entities using the utility class EmailNotifications from org.openxava.util package.
By default, all the changes made via MapFacade are notified, however if your create your own code to modify data via JPA, JDBC, etc. and want that your user would be notified by email use the class AccessTracker from org.openxava.util package.