Plataforma | Creando notificaciones personalizadas

Índice

Objetivo

A partir de la versión 1.2, además de las notificaciones estándar del Fluig, es posible crear nuevos tipos de notificaciones personalizadas, a través de la API de Notificaciones del producto. Es posible crear aplicaciones, widgets, etc que creen y envíen notificaciones personalizadas, además de hacer este proceso a través de aplicaciones externas, utilizando la API Pública del Fluig. Este tutorial tiene el objetivo de mostrar paso a paso como crear una aplicación que crea una notificación personalizada y envía a los usuarios del tenant. Para hacer este mismo proceso a través de la API Pública del Fluig, consulte la documentación haciendo clic aquí.

Proyecto de ejemplo

Para facilitar el entendimiento y desarrollo de este tutorial, se generó un proyecto de ejemplo. En este proyecto, se implementó una aplicación que crea una notificación personalizada, simulando un aviso del RH Online: "Su holerit ya está disponible". Este proyecto es apenas un ejemplo, no se implementó ninguna integración real con el sistema RH Online. Para probar el proyecto, realizar los siguientes pasos:

1. Bajar el proyecto: Haga clic aquí o haga un clon del repositorio http://git.fluig.com/projects/SAMPLES/repos/notifications/browse (proyecto "alert-creator-sample")
2. Compilar el proyecto (es un proyecto estándar maven, para compilar, ejecutar "mvn clean install" en la raíz del proyecto)
3. Hacer deploy del archivo "/alert-creator-sample-server/target/alert-creator-sample-server.ear" en un servidor con el Fluig instalado

Entendiendo los conceptos para la creación de notificaciones personalizadas

Módulos de Notificaciones:

Los módulos de notificación son apenas agrupadores, para que las notificaciones semejantes se presenten agrupadas para el usuario. Los módulos estándar del Fluig son: Colaboración (notificaciones de apoyar, comentar, etc), Documentos (notificaciones de indicación de lectura, actualización de versión, etc), Procesos (notificaciones de movimiento de proceso, tareas atrasadas, etc) y Portal (notificaciones de alteración en el layout de páginas, etc).

Es posible crear nuevos módulos de notificaciones. En el proyecto ejemplo, se crea un nuevo módulo llamado "Notificaciones de RH".

Eventos de Notificaciones:

Antes de crear notificaciones personalizadas, es importante que quede claro el concepto de "Eventos de Notificaciones". Un evento es una representación de alguna acción que puede generar notificaciones en el Fluig. El evento contiene todas las configuraciones de las notificaciones. Por ejemplo, el evento de notificación "LIKE" posee el formato estándar de todas las notificaciones del tipo "A fulano le gusta el post 'Mira que post interesante...". A través del evento el usuario puede configurar la recepción de notificaciones. Por ejemplo: yo puedo configurar la recepción de las notificaciones del tipo "SHARE" por e-mail y SMS, las notificaciones del tipo "LIKE" apenas por la Central de Notificaciones del Fluig, y no recibir ninguna notificación del tipo "FOLLOW_REQUEST_ACCEPTED". Para configurar esta recepción, el usuario debe acceder la pantalla de configuraciones de notificaciones:

Para crear notificaciones personalizadas, es necesario crear nuevos eventos de notificaciones. En el proyecto ejemplo, se crea un nuevo evento llamado "Holerit disponible en el RH online".

Atributos de Eventos de Notificaciones:

Como se ha dicho anteriormente, un evento contiene las configuraciones de las notificaciones. Estas configuraciones son:

• Requerido: Indica si el usuario puede dejar de recibir las notificaciones relacionadas con el evento. Si el evento se requiere, el usuario deberá obligatoriamente recibir las notificaciones referentes a él. Un ejemplo de notificación obligatoria es la solicitud de participación en una comunidad. Obligatoriamente el moderador de la comunidad debe recibir todos los pedidos de participación.
• Agrupados: Indica si las notificaciones de aquel evento se agrupan por objeto. En el caso que la notificación sea agrupada, el sistema exhibirá así: "Fulano, Beltrano, Ciclano y 5 personas más apoyaron el post 'Post del Fulano de Tal...'". En el caso que la notificación no sea agrupada, el sistema generará una notificación nueva para cada vez que una acción sea generada sobre un objeto. OBS: Notificaciones agrupadas no pueden tener acciones asociadas.
• Puede eliminarse: Indica si la notificación puede ser eliminada por el usuario. En el caso que no pueda, el sistema no dejará que el usuario elimine la notificación, hasta que se ejecute alguna de las acciones puestas a disposición.
• Elimina después de ejecutar una acción: Si se configura de esta forma, después de realizar alguna acción, el sistema excluirá automáticamente la notificación. En el caso contrario, el sistema exhibirá la notificación con un mensaje informando la acción ya ejecutada. Por ejemplo: "Fulano quiere seguirlo. (Usted ya aceptó esta requisición)". El sistema entonces permitirá que el usuario remueva aquella notificación.
• Apenas para administradores: Indica si aquel tipo de notificación es exclusivo para administradores del tenant.

Notificaciones:

Las notificaciones se deben crear obligatoriamente con un evento asociado. De esta forma la Central de Notificaciones podrá hacer la gestión de creación, envío y exhibición de la notificación. Las notificaciones creadas contienen algunos objetos asociados, que son:

• Usuarios que enviaron la notificación: Una notificación puede ter ninguno, uno o varios usuarios que la enviaron. En la creación de la notificación se puede informar ninguno o un usuario que está enviando. En el caso que la notificación sea agrupada, la Central de Notificaciones hará el agrupamiento automáticamente.
• Objeto asociado: Una notificación puede tener o no un objeto asociado. El objeto puede ser un post, un documento, o cualquier objeto existente dentro o fuera del sistema. En la creación de la notificación puede ser informado o no un objeto asociado.
• Lugar donde se generó: Una notificación puede contener o no la información desde donde esta se generó. Un lugar puede ser una comunidad, un proceso, o cualquier lugar existente dentro o fuera del sistema. En la creación de la notificación puede ser informado o no un lugar asociado.
• Acciones: Son las acciones colocadas a disposición por una notificación. Verifique a seguir una documentación detallada.
• Metadatos: Son datos del tipo clave-valor que pueden ser asociados a la notificación. Ellos pueden ser utilizados por aplicaciones personalizadas de envío de notificaciones.

Acciones de Notificaciones:

Una notificación puede colocar a disposición una o más acciones. Estas acciones son informadas en el momento de la creación de la notificación. Las acciones son individuales por notificación, no siendo asociadas al evento relacionado con ella. Las acciones poseen los siguientes atributos:

• Tipo de integración: Indica el tipo de integración que será utilizado para ejecutar aquella acción. Actualmente el Fluig soporta tres tipos de integración:
  
  1. JMS: Al ejecutar aquella acción el sistema disparará un mensaje JMS con los datos de la acción. El mensaje JMS disparado es del tipo "EXECUTE_ALERT_ACTION_EVENT". Cabe al desarrollador implementar una rutina que se conecte al tópico "TOTVSTechIntegrationListenerTopic", escuche estos mensajes y ejecute efectivamente las acciones.
  2. HTTP: Al ejecutar aquella acción, el sistema hará una llamada HTTP a una URL registrada en el momento de la creación de la notificación. Los métodos HTTP soportados actualmente son GET y POST. Cabe al desarrollador colocar a disposición un servicio que responda en aquella URL y ejecute efectivamente la acción.
  3. NONE: Al ejecutar aquella acción el sistema la marcará como ejecutada, pero no realizará ninguna acción.
• Tipo: Existen actualmente dos tipos de acción.
  
  1. MAIN: Es la acción principal. El sistema exhibirá en la Central de Notificaciones esta acción como acción de destaque.
  2. DEFAULT: Es una acción estándar. El sistema exhibirá como acción común, sin destaque.

Utilizando la API de Notificaciones para crear eventos personalizados

Existen dos formas de utilización de la API de Notificaciones del Fluig: a través del módulo "foundation-alert-api", interno al Fluig, y a través de la API Pública. Este tutorial muestra un ejemplo utilizando-si el módulo "foundation-alert-api". Para obtener más informaciones sobre la API Pública, haga clic aquí.

Para la creación de una aplicación interna al Fluig que utilice la API de Notificaciones, es necesario crear un proyecto Java (estándar maven) y adicionar el siguiente tramo de código en el archivo "pom.xml":

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

Registrando módulos de Notificaciones:

Para la creación de un nuevo módulo de notificaciones, es necesario realizar una llamada al método "registerModule", de la interfaz "com.totvs.technology.foundation.alert.service.AlertModuleService". Un ejemplo de llamada de este método sigue a continuación:

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

	public void registerModule() {
		
		/*
		 * Crea un nuevo módulo de notificaciones. Los módulos estándar del Fluig son:
		 * 1. DOCUMENT
		 * 2. PROCESSES
		 * 3. PORTAL
		 * 4. COLABORATION
		 * 
		 * En el caso que el nuevo evento de notificaciones se encaje en uno de estos módulos, 
		 * no es necesario crear uno nuevo.
		 */
		final AlertModuleVO myModule = alertModuleService.registerModule(
				"RH_MODULE", "Notificaciones del RH", myTenantId);
				
	}
}

Los parámetros para ejecución del método son:

1. moduleKey: Clave única de identificación del módulo
2. descripción: Es la descripción del módulo. Puede ser un texto plano o una clave para traducción. Para que la traducción funcione, la clave debe estar previamente registrada en el servicio I18n, en el bundle "foundation_alert".
3. tenantId: Id del tenant para cuál módulo se está creando.

Registrando eventos de Notificaciones:

Para la creación de un nuevo evento de notificaciones, es necesario realizar una llamada al método "createEvent", de la interface "com.totvs.technology.foundation.alert.service.AlertEventService". Un ejemplo de llamada de este método sigue a continuación:

@Singleton(mappedName = "MyEventRegister", name = "MyEventRegister")
public class EventRegister {
	
	@EJB(lookup = AlertModuleService.JNDI_REMOTE_NAME)
	private AlertEventService alertEventService;
	
	public void registerEvent() {
				
		alertEventService.createEvent(
				"MY_EVENT",
				Boolean.FALSE,
				"Mi evento personalizado",
				"creó",
				"crearon",
				"/myapp/myimg.jpg",
				myModule.getId(),
				Boolean.TRUE,
				Boolean.TRUE,
				Boolean.FALSE,
				Boolean.FALSE,
				tenantId:
		
	}
}

Los parámetros para ejecución del método son:

1. eventKey - String única que representa el evento en el Fluig.
2. required - Indica si se requiere el evento. En el caso que sea, el usuario no conseguirá configurar para no recibir notificaciones del evento.
3. descriptionKey - Descripción del evento. Puede ser un texto plano o una clave para obtener descripción traducida en el I18n. En el caso que quiera utilizar la traducción, la clave debe estar previamente registrada en el I18n, en el bundle "foundation_alert".
4. singleDescriptionKey - Descripción de la acción realizada por un usuario. Puede ser un texto plano o una clave para obtener descripción traducida en el I18n. En el caso que quiera utilizar la traducción, la clave debe estar previamente registrada en el I18n, en el bundle "foundation_alert".
5. groupDescriptionKey - Descripción de la acción realizada por por varios usuarios. Puede ser un texto plano o una clave para obtener la descripción traducida en el I18n. En el caso que quiera utilizar la traducción, la clave debe estar previamente registrada en el I18n, en el bundle "foundation_alert".
6. eventIcon - Ícono que representa el evento (opcional). Este ícono se exhibirá por el sistema en notificaciones que no tengan un usuario que la envió. En el caso que tenga un usuario "enviador", el sistema exhibirá la foto de este usuario. En el caso que haya más de un usuario "enviador", el sistema mostrará la foto del último usuario que envío la notificación.
7. moduleId - Módulo al cual pertenece este evento
8. grouped - Indica si la notificación puede ser agrupada por acción y objeto.
9. canRemove - Indica si la notificación se puede eliminar.
10. removeAfterExecAction - Indica si la notificación se elimina después de que se ejecuta una acción.
11. onlyAdmin - Indica si el evento es válido solamente para usuarios administradores.
12. tenantId - Tenant para el cual el evento se está registrando.

@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);
				
	}
}