Tutorial: how to extend social email notifications

The email notification feature will help you to avoid missing things that happen in your organization. These emails will help you to keep track of activities and events in your social intranet.

There are two types of email notification: notification emails for each event and a digest email that collects all notifications during a certain period and is sent once per day or per week.

By default, eXo Platform supports a large of number of events like: new user, connection request, space invitation, space join request, mention, comment on activity, like on activity, post on my stream and post in my spaces.

In some cases, you might want to add other notifications or customize existing notifications based on a dedicated event. In this tutorial, you will see how to add a new notification, ‘One of my connections has posted a message’, by implementing your own eXo social notification plugin.

Sample Notification Extension

This extension will send an email notification when a connection posts an activity on their activity stream.

This new notification should also appear in the settings. Just like the others, users can choose whether they want to receive this kind of notification or not.

Prerequisites

The extension requires Platform 4.1.x. I’ve already tested it on Platform 4.1-M1 and 4.1-M2.
This tutorial involves developing your own extension, so it is good if you understand eXo Platform Extensions.

Creating your extension project

Creating your extension called custom-notification-extension requires two packages:

custom-notification-config.jar is where you declare the extension webapp as a dependency of the portal container. This means that under custom-notification-extension.jar you need to create /conf/configuration.xml with the following content:

<object-param>
	<name>addDependencies</name>
	<object type="org.exoplatform.container.definition.PortalContainerDefinitionChange$AddDependencies">
 <!-- The name of the portal container -->
		<field name="dependencies">
			<collection type="java.util.ArrayList">
				<value>
					<string>custom-notification-extension</string>
				</value>
			</collection>
		</field>
	</object>
</object-param>

custom-notification-extension.war contains resources and configurations. The webapps are loaded in the order defined in the list of dependencies in the PortalContainerDefinition.

In /conf/configuration.xml you need to register two external component plugins:

<external-component-plugins>
	<target-component>org.exoplatform.social.core.manager.ActivityManager</target-component>
	<component-plugin>
		<name>ActivityNotificationImpl</name>
		<set-method>addActivityEventListener</set-method>
		<type>org.exoplatform.custom.notification.impl.ActivityNotificationImpl</type>
	</component-plugin>
</external-component-plugins>

* When an activity is created (this event is addActivityEventListener) then org.exoplatform.custom.notification.impl.ActivityNotificationImpl will be triggered. In this class, we will implement sending an email notification (see the details in the next section):

<external-component-plugins>
	<target-component>org.exoplatform.commons.api.notification.service.setting.PluginContainer</target-component>
	<component-plugin>
		<name>notification.plugins</name>
		<set-method>add</set-method>
		<type>org.exoplatform.custom.notification.plugin.ActivityConnectionPlugin</type>
		<description>Initial information for plugin.</description>
		<init-params>
			<object-param>
				<name>template.ActivityConnectionPlugin</name>
				<description>The template of ActivityConnectionPlugin</description>
				<object type="org.exoplatform.commons.api.notification.plugin.config.PluginConfig">
					<field name="pluginId">
						<string>ActivityConnectionPlugin</string>
					</field>
					<field name="resourceBundleKey">
						<string>UINotification.label.ActivityConnectionPlugin</string>
					</field>
					<field name="order">
						<string>5</string>
					</field>
					<field name="defaultConfig">
						<collection type="java.util.ArrayList">
							<value><string>Instantly</string></value>
							<!--value><string>Daily</string></value→
							<!--value><string>Weekly</string></value-->
						</collection>
					</field>
					<field name="groupId">
						<string>connections</string>
					</field>
					<field name="templateConfig">
						<object type="org.exoplatform.commons.api.notification.plugin.config.TemplateConfig">
							<field name="bundlePath">
								<string>locale.notification.template.Notification</string>
							</field>
							<field name="templatePath">
								<string>war:/notification/templates/ActivityConnectionPlugin.gtmpl</string>
							</field>
						</object>
        			</field>
				</object>
			</object-param>
		</init-params>
	</component-plugin>
</external-component-plugins>

* This configuration will register a plugin called ActivityConnectionPlugin with some important parameters:

defaultConfig: Instantly – sends email notifications right away; daily and weekly are used for digest emails.
groupId: general, connections, spaces, activity – This is the group for your custom notification in Notification Settings (you could also create a new group).
templateConfig: bundlePath – points to the resource bundle file and templatePath is the template for the email notification’s content.

Implementing your own eXo social notification plugin

ActivityNotificationImpl.java is extended from ActivityListenerPlugin.java. In this class we override the saveActivity method:

public void saveActivity(ActivityLifeCycleEvent event) {
	ExoSocialActivity activity = event.getSource();    
	NotificationContext ctx = NotificationContextImpl.cloneInstance().append(ACTIVITY, activity);

	ctx.getNotificationExecutor().with(ctx.makeCommand(NotificationKey.key(ActivityConnectionPlugin.ID)))
                                 .execute(ctx);
}

The main class you need to implement is ActivityConnectionPlugin. This is extended from AbstractNotificationPlugin with some important methods:

1. makeNotification creates a NotificationInfo object, which is used to build a message for sending a notification instantly and store it in the database for building a digest message.
2. makeMessage makes the MessageInfo from the given NotificationInfo that is kept inside NotificationContext, which is sent immediately when a user is active.
3. makeDigest makes the digest message from the given NotificationInfo that is kept inside NotificationContext.
4. isValid validates the conditions for sending an email notification. If it returns false then a message is not sent.
For this example, we make sure that if a poster posts on their activity stream then an email is sent. If they post on somebody else’s activity stream or in a space, then an email is not sent.

* Edit email content

custom-notification-extension/webapp/WEB-INF/notification/template/ActivityConnectionPlugin.gtmpl

* Edit resource bundle

custom-notification-extension/resources/locale/notification/template/Notification_en.properties

If you want to add more languages, simply clone this file and change _en to a required language, then create a translation for it.

You can download the source code here.

Deployment

* Build a project using: mvn clean install

* Copy the custom-notification-extension.war file to the ${PLF_TOMCAT}/webapps directory.

* Copy the custom-notification-config-xxx.jar file to the ${PLF_TOMCAT}/lib directory.

* Start your tomcat using: ./start_eXo.sh

Now in your Notification Settings you should see the new notification ‘One of my connections has posted a message’ under Connections.

Test it to see whether you receive an email notification when one of your connections posts an activity on their activity stream. You should receive an email like this:

Congratulations on your first simple customized social email notification! Now you can implement any customizations you might need.

Going further

Of course, customizations can do more than this sample customized social notification. You can register any event to send email notifications, like user login, logout, posting to the wiki, uploading or creating documents, calendar events, tasks…

Just do it. If you have any questions, don’t hesitate to post them on the Support Forums.

References

+ Email Notification Specification: https://community.exoplatform.com/portal/intranet/wiki/

+ Managing Email Notifications: https://docs.exoplatform.org

+ Creating your Extension Project: https://docs-old.exoplatform.org/public/index.jsp?topic=%2FPLF40%2FPLFDevGuide.eXoPlatformExtensions.CreatingExtensionProject.html

Join the eXo tribe by registering for the community and get updates, tutorials, support, and access to the Platform and add-on downloads!

Make the most out of eXo Platform 4

Register to the next webinar and get a complete overview of what you can do with eXo Platform 4. Reserve your seat now!

Brahim Jaouane

I am a Digital Marketing specialist specialized in SEO at eXo Platform. Passionate about new technologies and Digital Marketing. With 10 years' experience, I support companies in their digital communication strategies and implement the tools necessary for their success. My approach combines the use of different traffic acquisition levers and an optimization of the user experience to convert visitors into customers. After various digital experiences in communication agencies as well as in B2B company, I have a wide range of skills and I am able to manage the digital marketing strategy of small and medium-sized companies.