1 - Servicio IAdviceService

El servicio de avisos y alertas proporciona un sistema centralizado de envío de notificaciones.

1.1 - Método 'createAdvice'

Servicio para la creación de avisos vía correo electrónico. SGA enviará un correo electrónico, cuyo remitente será sga. El cuerpo de estos correos dependerán de la entidad indicada (entity_id). Además, SGA agrupa todos los correos de un mismo usuario y tipo de correo en uno solo.

La frecuencia de tiempo por la que SGA enviará correos de la aplicación integradora vendrá dada en el alta de la aplicación en SGA.

Más detalles...

1.1.1.- Signatura

ResultError createAdvice(ParamCreateAdvice paramCreateAdvice)

1.1.2 - Parámetros de invocación

Nombre	Tipo	Descripción
ParamCreateAdvice			SI
idApplication	String	Identificador de la aplicación asignado en PAU.	SI
user	String	NIF del usuario promotor/responsable de la alerta (a efectos de auditoría / estadísticas). Por compatibilidad con versiones anteriores no es obligatorio, pero deberá indicarse en nuevas integraciones ya que en un futuro podría serlo.	NO
Advice			SI
anagrama	String	Dirección de correo electrónico o NIF del usuario al que se le quiere enviar el aviso. En el caso de informarse el NIF, el usuario deberá estar dado de alta en SIU con un correo electrónico asociado.	SI
application	String (Max:50)	Código de la aplicación dada de alta en la plataforma SGA	SI
date	String	Fecha en la que se enviará el aviso en uno de los siguientes formatos: dd/MM/yy, dd/MM/yy HH:mm, dd/MM/yyyy, dd/MM/yyyy HH:mm Si no se especifica se creará con la fecha de la petición.	NO
description	String (Clob)	Descripción. Se permite el uso de HTML.	SI
subject	String (Max:25)	Asunto del aviso	SI
type	String (Max:100)	Tipo de aviso utilizado para agrupar avisos dentro de una misma categoría.	SI
entity_id	Long	Identificador de la entidad de envío, por defecto 0 (Gobierno de Aragón)	SI
mailSubject	String (Máx:200)	Asunto del correo. Si se deja en blanco, el aviso se enviará con el asunto del correo creado por defecto en base de datos	NO

1.1.3 - Parámetros de respuesta

Tipo	Descripción
ResultError	Resultado de la creación del envío.

1.1.4 - Códigos error

Descritos en la sección "Tipificación, codificación y descripción de errores"

1.1.5.- Ejemplo de invocación

// Se definen los objetos a usar
ParamCreateAdvice pca =newParamCreateAdvice();
Advice advice =newAdvice();
ResultError resultError;
 
// Se rellenan los datos del aviso
advice.setApplication(CÓDIGO_APP);
advice.setEntityId(0L);
advice.setId(3);
 
// Datos de correo
advice.setAnagrama("amartinezj@oesia.com");// Remitente, correo o NIF de usuario de SIU con correo asociado
advice.setMailSubject("Asunto del correo");// Asunto del correo enviado
advice.setDate("11/12/2018");// Fecha en la que será enviado
 
// Datos del aviso
advice.setType("Grupo del aviso");// Los avisos se agrupan y titulan en función a esto
advice.setSubject("Asunto del aviso");// Título del aviso
advice.setDescription("Descripción del aviso");// Descripción del aviso
 
// Insertamos, en los parámetros, la aviso y el usuario que la genera
pca.setoAdvice(advice);
pca.setUser("00000000T");Usuario que ha solicitado el aviso
 
// Peticion a SGA
resultError = adviceServiceWS.createAdvice(pca);
 
// Gestión de la respuesta
if("false".equals(resultError.getError())) {
System.out.println("Se ha enviado el aviso");
}else{
System.out.println("Se ha producido un error en la petición");
if(resultError.getErrorCode() !=null) {
System.out.println("Error: "+ resultError.getErrorCode() +". Mensaje: "+ resultError.getErrorMsg());
}
}

1.2 - Método 'createAdviceWithAttachment'

Servicio para la creación de avisos vía correo electrónico y documentos adjuntos al correo. El integrador deberá de informar de estos documentos a través de código CCSV, con lo que la aplicación integradora también debe estar integrada con la aplicación CCSV - Servicio de Almacenamiento y Verificación de Documentos Electrónicos.

SGA enviará un correo electrónico, cuyo remitente será sga. El cuerpo de estos correos dependerán de la entidad indicada (entity_id). Además, SGA agrupa todos los correos de un mismo usuario y tipo de correo en uno solo. La frecuencia de tiempo por la que SGA enviará correos de la aplicación integradora vendrá dada en el alta de la aplicación en SGA.

Más detalles...

1.2.1 - Signatura

ResultErrorAdviceSMS createAdviceSMS(ParamCreateAdviceSMS paramCreateAdviceSMS)

1.2.2 - Parámetros de invocación

Nombre	Tipo	Longitud máxima	Descripción	Obligatorio
ParamCreateAdviceSMS				Sí
idApplication	String	-	Identificador de la aplicación asignada en PAU.	Sí
user	String	-	NIF del usuario promotor/responsable de la alerta (a efectos de auditoría / estadísticas). Por compatibilidad con versiones anteriores no es obligatorio, pero deberá indicarse en nuevas integraciones ya que en un futuro podría serlo.	No
AdviceSMS				Sí
anagrama	String	30	Dirección de correo electrónico o NIF del usuario al que se le quiere enviar el aviso. En el caso de informarse el NIF, el usuario deberá estar dado de alta en SIU con un correo electrónico asociado.	Sí (si se usa canal MAIL o canal AMBOS)
application	String	50	Código de la aplicación dada de alta en la plataforma SGA	Sí (si se usa canal MAIL o canal AMBOS)
date	String	-	Fecha en la que se enviará el aviso en uno de los siguientes formatos: dd/MM/yy dd/MM/yy HH:mm dd/MM/yyyy dd/MM/yyyy HH:mm Si no se especifica se creará con la fecha de la petición.	No
description	String	-	Descripción. Se permite el uso de HTML.	Sí (si se usa canal MAIL o canal AMBOS)
subject	String	25	Asunto del aviso	Sí (si se usa canal MAIL o canal AMBOS)
type	String	100	Tipo de aviso utilizado para agrupar avisos dentro de una misma categoría	Sí
entityId	Long		Identificador de la entidad de envío, por defecto 0 (Gobierno de Aragón)	No
mailSubject	String	200	Asunto del correo. Si se deja en blanco, el aviso se enviará con el asunto del correo creado por defecto en base de datos	No
phoneNumber	String	9	Número de teléfono al que se enviará el SMS	Sí (si se usa canal SMS o canal AMBOS)
textSMS	String	160	Texto del SMS	Sí (si se usa canal SMS o canal AMBOS)
requestType	String	-	Tipo de canal por el cual se desea mandar el aviso: MAIL, SMS, AMBOS.	Sí (se debe indicar siempre el tipo de canal)

1.2.3 - Parámetros de respuesta

En la respuesta se devuelve siempre un objeto ResultErrorAdviceSMS.

Nombre	Tipo	Descripción
error	String	Este campo siempre será rellenado con uno de los siguientes valores: 0 → No ha habido ningún error 1 → Indica que ha habido un error en el canal MAIL 2 → Indica que ha habido un error en el canal SMS 3 → Indica que ha habido un error en ambos canales
mailErrorCode	String	Este campo solamente se rellena si el campo "error" es 1 o 3
mailErrorMsg	String	Este campo solamente se rellena si el campo "error" es 1 o 3
smsErrorCode	String	Este campo solamente se rellena si el campo "error" es 2 o 3
smsErrorMsg	String	Este campo solamente se rellena si el campo "error" es 2 o 3

Ejemplos de utilización según el tipo de canal invocado:

Invocamos por el canal MAIL → El campo "error" será 0 (si todo ha ido bien) o 1 (si se ha producido un error). Si es 1, pasaremos a obtener mailErrorCode y mailErrorMsg.
Invocamos por el canal SMS → El campo "error" será 0 (si todo ha ido bien) o 2 (si se ha producido un error). Si es 2, pasaremos a obtener smsErrorCode y smsErrorMsg.
Invocamos por el canal AMBOS → El campo "error" será 0 (si todo ha ido bien) o 1 (si se ha producido un error con el MAIL) o 2 (si se ha producido un error con el SMS) o 3 (si ha fallado tanto el MAIL como el SMS)
- Si es 1 → Obtener mailErrorCode y mailErrorMsg
- Si es 2 → Obtener smsErrorCode y smsErrorMsg
- Si es 3 → Obtener mailErrorCode, mailErrorMsg, smsErrorCode y smsErrorMsg

1.2.4 - Códigos de error

Descritos en la sección "Tipificación, codificación y descripción de errores"

Invocación por canal MAIL

ParamCreateAdviceSMS paramCreateAdviceSMS = new ParamCreateAdviceSMS();
paramCreateAdviceSMS.setIdApplication("SGA");
         
AdviceSMS adviceSMS = new AdviceSMS();
adviceSMS.setAnagrama("correo@gmail.com");
adviceSMS.setApplication("SGA");
adviceSMS.setDate("18/12/19"); // si no se pone, la fecha será la de la petición
adviceSMS.setDescription("Correo de prueba");
adviceSMS.setEntityId(0L); //si no se pone, será 0 por defecto
adviceSMS.setMailSubject("Prueba createAdviceSMS");
adviceSMS.setSubject("Prueba");
adviceSMS.setType("SGA");
adviceSMS.setRequestType(AdviceSMS.RequestType.MAIL.toString());
         
paramCreateAdviceSMS.setAdviceSMS(adviceSMS);
         
ResultErrorAdviceSMS resultErrorAdviceSMS = adviceServiceWS.createAdviceSMS(paramCreateAdviceSMS);
         
if(resultErrorAdviceSMS.getError().equals(ResultErrorAdviceSMS.NO_ERROR)) {
    System.out.println("Proceso por canal MAIL realizado correctamente");
} else {
    System.out.println("Error al realizar el proceso por canal MAIL");
    System.out.println("Código Error: " + resultErrorAdviceSMS.getMailErrorCode());
    System.out.println("Mensaje Error: " + resultErrorAdviceSMS.getMailErrorMsg());
}

Invocación por canal SMS

ParamCreateAdviceSMS paramCreateAdviceSMS = new ParamCreateAdviceSMS();
paramCreateAdviceSMS.setIdApplication("SGA");
         
AdviceSMS adviceSMS = new AdviceSMS();
adviceSMS.setPhoneNumber("611223344");
adviceSMS.setTextSMS("SMS de prueba");
adviceSMS.setRequestType(AdviceSMS.RequestType.SMS.toString());
         
paramCreateAdviceSMS.setAdviceSMS(adviceSMS);
         
ResultErrorAdviceSMS resultErrorAdviceSMS = adviceServiceWS.createAdviceSMS(paramCreateAdviceSMS);
         
if(resultErrorAdviceSMS.getError().equals(ResultErrorAdviceSMS.NO_ERROR)) {
    System.out.println("Proceso por canal SMS realizado correctamente");
} else {
    System.out.println("Error al realizar el proceso por canal SMS");
    System.out.println("Código Error: " + resultErrorAdviceSMS.getSmsErrorCode());
    System.out.println("Mensaje Error: " + resultErrorAdviceSMS.getSmsErrorMsg());
}

Invocación por canal AMBOS

ParamCreateAdviceSMS paramCreateAdviceSMS = new ParamCreateAdviceSMS();
paramCreateAdviceSMS.setIdApplication("SGA");
                 
AdviceSMS adviceSMS = new AdviceSMS();
adviceSMS.setAnagrama("correo@gmail.com");
adviceSMS.setApplication("SGA");
adviceSMS.setDate("18/12/19"); // si no se pone, la fecha será la de la petición
adviceSMS.setDescription("Correo de prueba");
adviceSMS.setEntityId(0L); //si no se pone, será 0 por defecto
adviceSMS.setMailSubject("Prueba createAdviceSMS");
adviceSMS.setSubject("Prueba");
adviceSMS.setType("SGA");
adviceSMS.setPhoneNumber("611223344");
adviceSMS.setTextSMS("SMS de prueba");
adviceSMS.setRequestType(AdviceSMS.RequestType.AMBOS.toString());
                 
paramCreateAdviceSMS.setAdviceSMS(adviceSMS);
                 
ResultErrorAdviceSMS resultErrorAdviceSMS = adviceServiceWS.createAdviceSMS(paramCreateAdviceSMS);
                 
if(resultErrorAdviceSMS.getError().equals(ResultErrorAdviceSMS.NO_ERROR)) {
    System.out.println("Proceso por canal AMBOS realizado correctamente");
} else if (resultErrorAdviceSMS.getError().equals(ResultErrorAdviceSMS.MAIL_ERROR)) {
    System.out.println("Error al realizar el proceso MAIL por canal AMBOS");
    System.out.println("Código Error: " + resultErrorAdviceSMS.getMailErrorCode());
    System.out.println("Mensaje Error: " + resultErrorAdviceSMS.getMailErrorMsg());
} else if (resultErrorAdviceSMS.getError().equals(ResultErrorAdviceSMS.SMS_ERROR)) {
    System.out.println("Error al realizar el proceso SMS por canal AMBOS");
    System.out.println("Código Error: " + resultErrorAdviceSMS.getSmsErrorCode());
    System.out.println("Mensaje Error: " + resultErrorAdviceSMS.getSmsErrorMsg());
} else {
    System.out.println("Error al realizar el proceso MAIL y el proceso SMS por canal AMBOS");
    System.out.println("Código Error MAIL: " + resultErrorAdviceSMS.getMailErrorCode());
    System.out.println("Mensaje Error MAIL: " + resultErrorAdviceSMS.getMailErrorMsg());
    System.out.println("Código Error SMS: " + resultErrorAdviceSMS.getSmsErrorCode());
    System.out.println("Mensaje Error SMS: " + resultErrorAdviceSMS.getSmsErrorMsg());
}

2. - Servicio IEventsService

El servicio de gestión de eventos proporciona un sistema centralizado de envío de notificaciones entre aplicaciones a fin de disminuir el tráfico innecesario entre ellas y aumentar el control sobre el flujo de información.

2.1.- Método 'sendNotification'

Este método es utilizado por las aplicaciones emisoras de eventos para enviar sus eventos a las aplicaciones suscritas por medio de sga. Un evento es un listado genérico de datos, por lo que cada aplicación deberá de informar y explicar a los receptores los datos que envía en los eventos.

Más datos...

2.1.1 - Signatura

ResultError sendNotification(ParamCreateEvent paramCreateEvent)

2.1.2 - Parámetros de invocación

Nombre	Tipo	Descripción
ParamCreateEvent		Encapsula los datos del evento que se quiere enviar y opcionalmente la aplicación destinataria
event	Event	Información del evento que se desea enviar.
appTo	String	Identificador de la aplicación destinataria del evento. Si no se especifica se enviará a todas las aplicaciones que estén suscritas.
Event
appCode	String	Identificador de la aplicación origen del evento.
method	String	Nombre del método origen del evento.
data	Map<String, String>	Datos a enviar en forma de pares clave-valor.

2.1.3 - Parámetros de respuesta

Tipo	Descripción
ResultError	Resultado de la creación del envío.

2.2.4.- Códigos error

Descritos en la sección "Tipificación, codificación y descripción de errores"

2.2.5.- Ejemplo de invocación

// DATOS - Evento
String identificadorAppOrigen = "SNT"; // (Obligatorio) Identificación de la app origen del evento
String method = "enviarNotificacion"; // (Obligatorio) Nombre del método origen del evento
// Se rellenan los datos del evento
Map<String, String> dataMap = new LinkedHashMap<String, String>();
dataMap.put("id", "test");
Event event = new Event(identificadorAppOrigen, method, dataMap);
 
// DATOS - ParamCreateEvent
String identificadorAppDestinataria = "PFI"; // (No obligatorio) Identificación de la app destinataria del evento
ParamCreateEvent paramCreateEvent = new ParamCreateEvent(event, identificadorAppDestinataria);
 
// Petición a SGA
ResultError resultError = eventsServiceWS.sendNotification(paramCreateEvent);
 
// Gestión de la respuesta
if ("true".equals(resultError.getError())) {
    // gestión del error
    System.out.println("Se ha producido un error en la petición");
    if (resultError.getErrorCode() != null) {
        System.out.println("Error: " + resultError.getErrorCode() + ". Mensaje: " + resultError.getErrorMsg());
    }
}

ANEXO 1: Recepción de eventos

Para la recepción de los eventos a los que se haya suscrito, debe implementar un servicio rest, accesible por SGA, que implemente la interfaz NotificationManager

Interfaz NotificationManager

/**
 * Interfaz REST común para las aplicaciones que integren el sistema de eventos
 *
 */
public interface NotificationManager{
     
    @PUT
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    Map<Long, Boolean> processNotification(RestEvent eventData);
 
}

El objeto RestEvent contiene información sobre la aplicación y el método origen del evento. Además contiene un objeto tipo Map donde cada entrada tiene como clave un id único y como valor el mapa de los datos del evento propiamente dichos.

El servicio tiene que devolver un mapa donde la clave sea ese id único y el valor el resultado de procesar los datos asociados (true → procesado con éxito; false → se ha producido algún error).

ANEXO 2: Clases comunes a los servicios

A continuación enumeramos los tipos de datos utilizados para el intercambio de información con el sistema.

Ver clases comunes,,,

A2.1. - Objeto ParamBase

Contiene información del usuario y la aplicación que ejecutan el método del servicio web.

Nombre

Tipo

Obligatorio

Descripción

idApplication

String

Sí

Identificador de la aplicación asignado en PAU.

user

String

No

NIF del usuario promotor/responsable de la alerta (a efectos de auditoría / estadísticas).

Por compatibilidad con versiones anteriores no es obligatorio, pero deberá indicarse en nuevas integraciones ya que en un futuro podría serlo.

A2.2.- Objeto Advice

Contiene el aviso o alerta a guardar.

Nombre	Tipo	Obligatorio	Descripción
anagrama	String	Sí	Dirección de correo electrónico o NIF del usuario al que se le quiere enviar el aviso. En el caso de informarse el NIF, el usuario deberá estar dado de alta en SIU con un correo electrónico asociado.
application	String (Max:50)	Sí	Código de la aplicación dada de alta en la plataforma SGA
date	String	No	Fecha en la que se enviará el aviso en uno de los siguientes formatos: dd/MM/yy, dd/MM/yy HH:mm, dd/MM/yyyy, dd/MM/yyyy HH:mm Si no se especifica se creará con la fecha de la petición.
description	String (Clob)	Sí	Descripción. Se permite el uso de HTML.
subject	String (Max:25)	Sí	Asunto del aviso
type	String (Max:100)	Sí	Tipo de aviso utilizado para agrupar avisos dentro de una misma categoría.
entity_id	Long	No	Identificador de la entidad de envío, por defecto 0 (Gobierno de Aragón)
mailSubject	String (Máx:200)	No	Asunto del correo. Si se deja en blanco, el aviso se enviará con el asunto del correo creado por defecto en base de datos.

Nota: Actualmente el aviso se envía en formato HTML, con lo que se puede hacer uso de HTML para mejorar la presentación (negrita, hiperenlaces, …). No obstante hay que tener en cuenta que en un mismo correo lleva información de varias aplicaciones, con lo que un mal uso de esta funcionalidad puede afectar a la percepción final que obtenga el usuario afectando a los avisos de todas las
aplicaciones.

A2.3 - Objeto Event

Contiene aplicación y método origen del evento y los datos a comunicar.

Nombre	Tipo	Obligatorio	Descripción
appCode	String	Sí	Identificador de la aplicación origen del evento.
method	String	Sí	Nombre del método origen del evento.
data	Map<String, String>	Sí	Datos a enviar en forma de pares clave-valor.

A2.4.- Objeto ResultError

Encapsula los parámetros de salida del resultado de la operación.

Nombre

Tipo

Descripción

error

String

Devuelve “false” si todo ha sido correcto.

Devuelve “true” si se ha producido algún error.

errorCode

String

Devuelve un código de error en función de lo sucedido cuando error=true.

errorMsg

String

Descripción del error si se ha producido.

A2.5.- Objeto ParamCreateAdvice (extiende ParamBase)

Contiene el aviso o alerta a guardar.

Nombre	Tipo	Obligatorio	Descripción
	ParamBase
oAdvice	Advice	Sí	Información de la alerta que se desea crear.

A2.6.- Objeto ParamCreateAdviceWithAttachment (extiende ParamBase)

Contiene el aviso o alerta con adjuntos a guardar.

Nombre	Tipo	Obligatorio	Descripción
	ParamBase
advice	Advice	Sí	Información de la alerta que se desea crear.
attachments	List<String>	Sí	Códigos CSV de los adjuntos.

A2.7.- Objeto ParamCreateEvent

Contiene información del evento y su aplicación destinataria.

Nombre	Tipo	Obligatorio	Descripción
event	Event	Sí	Información del evento que se desea enviar.
appTo	String	No	Identificador de la aplicación destinataria del evento. Si no se especifica se enviará a todas las aplicaciones que estén suscritas.

ANEXO 3: Códigos de error de los servicios

Ver códigos de error...

Código	Descripción
0001	Error genérico
0101	Error de validación del aviso
0102	No se pudo recuperar el correo del usuario
0103	Error en el formato de la fecha
0104	Error de validación de la aplicación, no esta dada de alta
0105	Error de validación de la entidad, no esta dada de alta
0106	Error de formato en el correo del usuario
0107	Error al enviar notificación
0108	La aplicación destino no está suscrita al método.
0109	El campo mailSubject debe tener una longitud máxima de 200 caracteres
0110	El campo anagrama es obligatorio
0111	El campo anagrama debe tener una longitud maxima de 30 caracteres
0112	El campo application es obligatorio
0113	El campo application debe tener una longitud maxima de 50 caracteres
0114	El campo description es obligatorio
0115	El campo subject es obligatorio
0116	El campo subject debe tener una longitud maxima de 25 caracteres
0117	El campo type es obligatorio
0118	El campo type debe tener una longitud maxima de 100 caracteres
0119	El campo oAdvice es obligatorio
0120	Error al conectar al servidor
0121	El campo textSMS es obligatorio
0122	El campo textSMS debe tener una longitud maxima de 160 caracteres
0123	El campo phoneNumber es obligatorio
0124	El campo phoneNumber debe tener 9 dígitos
0125	El campo phoneNumber debe ser numérico
0126	El campo adviceSMS es obligatorio
0127	El campo requestType es obligatorio
0128	El campo requestType solamente admite los siguientes valores: [MAIL, SMS, AMBOS]

4.- Servicios SGA

1 - Servicio IAdviceService

1.1 - Método 'createAdvice'

1.1.1.- Signatura

1.1.2 - Parámetros de invocación

1.1.3 - Parámetros de respuesta

1.1.4 - Códigos error

1.1.5.- Ejemplo de invocación

1.2 - Método 'createAdviceWithAttachment'

1.2.1 - Signatura

1.2.2 - Parámetros de invocación

1.2.3 - Parámetros de respuesta

1.2.4 - Códigos de error

2. - Servicio IEventsService

2.1.- Método 'sendNotification'

2.1.1 - Signatura

2.1.2 - Parámetros de invocación

2.1.3 - Parámetros de respuesta

2.2.4.- Códigos error

2.2.5.- Ejemplo de invocación

ANEXO 1: Recepción de eventos

ANEXO 2: Clases comunes a los servicios

A2.1. - Objeto ParamBase

A2.2.- Objeto Advice

A2.3 - Objeto Event

A2.4.- Objeto ResultError

A2.5.- Objeto ParamCreateAdvice (extiende ParamBase)

A2.6.- Objeto ParamCreateAdviceWithAttachment (extiende ParamBase)

A2.7.- Objeto ParamCreateEvent

ANEXO 3: Códigos de error de los servicios