Index

Objective

Starting with version 1.2, in addition to the default Fluig notifications, new types of custom notifications may be created through the Notifications API of a product. It is possible to create applications, widgets, etc., that create and send custom notifications. This process may also be conducted through external applications, using the Public API of Fluig. This tutorial aims to show step-by-step instructions on how to create an application that creates a custom notification and sends it to tenant users. In order to conduct the same process through the Public API of Fluig, check the documentation by clicking here.

Sample project

To facilitate the understanding and development of this tutorial, a sample project was generated. In this project, an application that creates a custom notification was implemented, simulating an Online HR notification: "Your pay stub is now available". This project is only an example, no real integration was implemented with the Online HR system. To test the project, follow these steps:

• Download the project: Click here or clone the repository http://git.fluig.com/projects/SAMPLES/repos/notifications/browse ("alert-creator-sample" project)

• Compile the project (it is a default maven project, to compile, execute "mvn clean install" in the project root)

• Deploy the file "/alert-creator-sample-server/target/alert-creator-sample-server.ear" in a server where Fluig is installed

Once these steps are executed, the system should generate a new type of notification. You can verify that the event was created correctly via the notifications settings screen. A new grouping named "HR Notifications" should be displayed, with the same notification as shown in the image below:

In an environment with a large number of users, a small delay may take place between the application deploy and creation o the event in the settings screen.

• After the application is installed, the system will send a fake notification every two minutes, telling the user that his/her pay stub is available in Online HR, as shown in the image below:

We recommend reading this entire material, even if the developer uses the sample project as basis. This tutorial presents key concepts for one to work correctly with notifications within Fluig.

Understanding the concepts for creating custom notifications

Notification Modules:

The notification modules are simply groupers, so that similar notifications can be presented to the user as a bundle. The default modules in Fluig are: Collaboration (support, comments, etc), Documents (reading recommendations, version updates, etc), Processes (process handling, late fees, etc) and Portal (changes in page layouts, etc).

New notification modules may be created. In the sample project, a new module named "HR Notifications" is created.

Notification Events:

Before creating custom notifications, it is important to have a clear understanding of the "Notification Events" concept. An event is a representation of any action that may generate notifications in Fluig. The event contains all notification settings. For example, the notification event "LIKE" has the default format for all notifications such as "Someone likes your post 'Check this out...'". The user can change the settings for receiving notifications through the event. For example: I can change the settings for "SHARE" notifications by e-mail and SMS, the "LIKE" notifications only through the Notifications Central of Fluig, and did not receive any "FOLLOW_REQUEST_ACCEPTED" notification. To configure this receipt, the user must access the notifications setting screen:

To create custom notifications, new notification events must be created. In the sample projct, a new event is created, named "Pay stub available in Online HR".

Atributos de Eventos de Notificações

As previously mentioned, an event contains the notification settings. These settings are:

• Required Indicates whether the user may no longer receive notifications related to the event. If the event is required, the user must receive the notification related to him/her. One example of mandatory notification is the request to join a community. The community moderator must receive all join requests.
• Grouped: Indicates whether notifications for that event are grouped by object. If the notification is grouped, the system will display it as follows: "[User name], [User name] and [User name] and 5 other people liked the post 'Post by [User name]...'". If the notification is not grouped, the system will generate a new notification every time that an action is generated for an object. NOTE: Grouped notifications cannot have associated actions.
• May be removed: Indicates whether the notification may be removed by the user. If it can not, the system will not allow the user remove the notification until one of the actions available is executed.
• Remove after executing an action: If this configuration is selected, the system will automatically delete the notification after an action is executed. Otherwise, the system will display the notification with a message that the action has already been executed. For example: "[User name] wants to follow you. (You accepted this request)". The system will then allow the user to remove this notification.
• For administrators only: Indicates whether this notification type is exclusive for tenant administrators.

Notifications:

Notifications must be created with an associated event. This way, the Notifications Central will be able to manage the creation, as well as the sending and display of the notification. The notifications created contain some objects associated, which are:

• Users that sent the notification: The notification may have none, one or multiple users sending it. When the notification is created, it may inform none or one user who sent it. If the notification is grouped, the Notifications Central will group automatically.
• Associated object: A notification may or may not have an associated object. The object may be a post, a document or any object within or outside the system. When the notification is created, it may or may not inform an associated object.
• Place where it was generated: A notification may or may not contain information about where it was generated. A place may be a community, a process or any place within or outside the system. When the notification is created, it may or may not inform an associated place.
• Actions: These are the actions that a notification produces. A detailed documentation is shown below.
• Metadata: These are key-value data that may be associated with the notification. They may be used by customized notification sending applications.

Notification Actions:

A notification may produce one or more actions. These actions are informed when the notification is being created. The actions are individual per notification, and are not associated to the event associated to it. The actions have the following attributes:

• Integration type: Indicates the type of integration that will be used to execute that action. Fluig currently supports three types of integration:
  
  1. JMS: When executing that action, the system will fire a JMS message with information on the action. The JMS message fired is of the type "EXECUTE_ALERT_ACTION_EVENT". It is the responsibility of the developer to implement a routine that connects to the topic "TOTVSTechIntegrationListenerTopic", listens to these messages and effectively executes the actions.
  2. HTTP: When executing that action, the system will make an HTTP call to a URL registered when creating the notification. The HTTP methods currently supported are GET and POST. The developer is responsible for providing a service that responds in that URL and effectively executes the action.
  3. NONE: When executing that action, the system will mark it as executed, but will not take action.
• Type: There are currently two types of action.
  
  1. MAIN: This is the main action. The system will display this action in the Notification Central as a featured action.
  2. DEFAULT: This is a default action. The system will display it as a common action, undistinguished.

Using the Notifications API to create custom events

There are two ways for using the Notifications API of Fluig: through the "foundation-alert-api" module, internal to Fluig, and through the Public API. This tutorial shows an example, using the "foundation-alert-api" module. For more information on Public API, click here.

To create an internal application in Fluig that uses the Notifications API, you must create a Java project (maven default) and add the following snippet in the "pom.xml" file:

<dependency>
    <groupId>com.fluig</groupId>
    <artifactId>foundation-alert-api</artifactId> 
    <version>1.2.0</version>
    <scope>compile</scope>
</dependency>

Registering Notification modules:

To create a new notification module, a call must be made to the "registerModule" method, of the "com.totvs.technology.foundation.alert.service.AlertModuleService" interface. A sample call for this method is shown below:

@Singleton(mappedName = "MyModuleRegister", name = "MyModuleRegister")
public class ModuleRegister {
	@EJB(lookup = AlertModuleService.JNDI_REMOTE_NAME)
	private AlertModuleService alertModuleService;

	public void registerModule() {
		
		/*
		 * Creates a new Notifications module. The default modules in Fluig are:
		 * 1. DOCUMENT
		 * 2. PROCESSES
		 * 3. PORTAL
		 * 4. COLLABORATION
		 * 
		 * If the new notifications event fits into one of these modules, 
		 * a new one does not have to be created.
		 */
		final AlertModuleVO myModule = alertModuleService.registerModule(
				"RH_MODULE", "Notificações do RH", myTenantId);
				
	}
}

The parameters for executing the method are:

1. moduleKey: Unique identification key for the module
2. description: This is the description of the module. It may be a plain text or a key for translation. For the translation to work, the key must be previously registered in the service I18n, in the bundle "foundation_alert".
3. tenantId: Id of tenant for whom the module is being created.

Registering Notification events:

To create a new notification event, a call must be made to the "createModule" method, of the "com.totvs.technology.foundation.alert.service.AlertEventService" interface. A sample call for this method is shown below:

@Singleton(mappedName = "MyEventRegister", name = "MyEventRegister")
public class EventRegister {
	
	@EJB(lookup = AlertEventService.JNDI_REMOTE_NAME)
	private AlertEventService alertEventService;
	
	public void registerEvent() {
				
		alertEventService.createEvent(
				"MY_EVENT",
				Boolean.FALSE,
				"Meu evento customizado",
				"criou",
				"criaram",
				"/myapp/myimg.jpg",
				myModule.getId(),
				Boolean.TRUE,
				Boolean.TRUE,
				Boolean.FALSE,
				Boolean.FALSE,
				tenantId);
		
	}
}

The parameters for executing the method are:

1. eventKey - Unique string that represents the event in Fluig.
2. required - Indicates whether the event is required. If it is, the user will not be able to change the settings to not receive event notifications.
3. descriptionKey - Description of event. It may be a plain text or a key to obtain a description translated in I18n. If you would like to use the translation, the key must be previously registered in I18n, in the bundle "foundation_alert".
4. singleDescriptionKey - Description of the action taken by a user. It may be a plain text or a key to obtain a description translated in I18n. If you would like to use the translation, the key must be previously registered in I18n, in the bundle "foundation_alert".
5. groupDescriptionKey - Description of the action taken by multiple users. It may be a plain text or a key to obtain the description translated in I18n. If you would like to use the translation, the key must be previously registered in I18n, in the bundle "foundation_alert".
6. eventIcon - Icon that represents the event (optional) This icon appears in the system in notifications that do not have a user who sent it. If it has a "sender" user, the system will show a picture of that user. If there is more than one "sender" user, the system will show a picture of the last user who sent the notification.
7. moduleId - Module to which the event belongs
8. grouped - Indicates whether the notification may be grouped by action or by object.
9. canRemove - Indicates whether the notification may be removed.
10. removeAfterExecAction - Indicates whether the notification is removed after an action is executed.
11. onlyAdmin - Indicates whether the event is valid for administrator users.
12. tenantId - Tenant for whom the event is being registered.

@Stateless(name = "AlertCreator", mappedName = "AlertCreator")
public class AlertCreator {
	
	@EJB(lookup = AlertService.JNDI_REMOTE_NAME)
	private AlertService alertService;
	
	public void sendHoleritAlert() {
		
		alertService.sendAlert("MY_EVENT", loginUserThatSendsTheNotification, loginUserThatIsGoingToReceiveTheNotification, objectAttached, placeWhereTheEventOccurs, actions, metadata);
				
	}
}