Manual de integración - Colas de Mensajes
PROMO V7.0

Índice

Acerca del manual

Propósito y alcance

El presente manual tiene como finalidad la capacitación al usuario que desee integrar su aplicación de ventas con ellos servicios que expone Promo y su integración mediante colas de mensajes.
Se provee una descripción detallada de los mensajes que deben ser enviados al mismo y de cómo interpretar los mensajes de respuesta que dará ante un requerimiento.

Introducción

CONSIDERACIOENS EN EL USO DE COLAS DE MENSAJES

Actualmente las aplicaciones se disponen en la nube (SAS) y esto trajo nuevos paradigmas de soluciones de arquitectura.  Uno de ellos es el desacoplar dichas aplicaciones en pequeños componentes o bloques independientes que puedan ser más fáciles de desarrollar, implementar y a futuro mantener.  Obviamente tal arquitectura exige un mecanismo confiable y seguro de comunicación entre los mencionados bloques y sobre todo un mecanismo más flexible que la comunicación interproceso tradicional con las limitaciones que éstas imponen.

El uso de colas de mensajes nos brinda una alternativa válida para implementar la mencionada comunicación, y hasta la coordinación de dichos componentes.  Consideremos que la cola de mensajes es un arbitro que rompe el conocimiento o dependencia directa entre las partes ya que ella se ubica en medio siendo lo único que conocen y dependen consumidores y productores de mensajes.  Con ello el código de comunicación es menor en cada componente y la comunicación sigue un patrón standard como es el de Publisher-suscriber, o Listener DP, que es una solución probada y adoptada en la industria del software.

Otra ventaja en el uso de colas es que permiten implementar una comunicación asincrónica ya que como mencionamos anteriormente los productores y consumidores no interactúan entre si sino que lo hacen a través de la cola por lo cual los mensajes pueden ser enviados a la cola sin importar si existe alguien disponible escuchando los mismos o que los pueda procesar en ese mismo momento.  De igual forma un consumidor puede ir tomando o recibiendo mensajes desde la cola a su tiempo y poder de procesamiento.  De esta forma ningún componente depende directamente del otro, mejorando el flujo de datos.

De lo mencionado hasta aquí se desprende que la arquitectura es flexible respecto a su escalabilidad ya que acorde a la carga de trabajo, los nodos de la cola misma pueden escalarse, los productores pueden crecer en número y los consumidores de la misma forma, con lo cual permite crecer la capacidad del sistema de forma casi transparente.

Una gran ventaja a mencionar es que al ser la cola quien administra los datos, existe una mayor tolerancia a fallas, ya que si algún componente no se encuentra disponible es la misma cola la que realiza la persistencia de los datos y ella misma puede implementarse en un esquema de alta disponibilidad mejorando aun mas la tolerancia a errores.

CONSIDERACIONES PARTICULARES A PROMO

Promo ha incorporado de forma estándar el uso de las colas mencionadas.

En la siguiente imagen se puede observar un diagrama de arquitectura simple:

Del diagrama se desprende que Promo como productor de la información que él administra (ej: Tarjetas de fidelidad), mientras que al mismo tiempo es un consumidor de la información provista por sistemas externos (ej. Catálogo de marcas).

De esta forma se obtienen todas las ventajas mencionadas en la primer parte del documento donde se elimina la interdependencia entre sistemas, y además el balanceo de carga y escalabilidad se hacen de forma transparente ya que tanto Promo como el sistema externo puede crecer independientemente del otro.  Al mismo tiempo la comunicación entre ambos sistemas es administrada por el servidor de colas homogeneizando la misma y eliminando la relación directa y por ende la posibilidad de fallas por no encontrar un componente disponible, o no responder en el tiempo estipulado.

¿Qué es RabbitMQ?

RabbitMQ es un software de encolado de mensajes llamado broker de mensajería o gestor de colas. Dicho de forma simple, es un software donde se pueden definir colas, las aplicaciones se pueden conectar a dichas colas y transferir/leer mensajes en ellas.

¿Cómo funciona?

La arquitectura básica de una cola de mensajes es simple. Hay aplicaciones clientes, llamadas productores, que crean mensajes y los entregan al intermediario (la cola de mensajes). Otras aplicaciones, llamadas consumidores, se conectan a la cola y se suscriben a los mensajes que se procesarán. Un mensaje puede incluir cualquier tipo de información.

Un software puede ser un productor, consumidor, o productor y consumidor de mensajes simultáneamente. Los mensajes colocados en la cola se almacenan hasta que el consumidor los recupera y procesa.

Requisitos

En el desarrollo de este manual se asume que se posee un servidor RabbitMQ instalado, disponible y configurado.

Para mayor información dirijirse a https://www.rabbitmq.com/

Promo como Consumidor

Promo posee funcionalidad de consumidor de colas RabbitMQ a los fines de recibir información sobre catálogos desde sistemas externos (productores).

Configuración

Los parámetros de configuración que activan y definen ésta funcionalidad se encuentran en Administración→Información de Configuración.  (Palabra clave RabbitMQ en la búsqueda).

Una vez que Promo recibe información desde la cola Rabbit correspondiente, la misma será derivada al monitor de Importación y será procesada por la tarea programada denominada "Importador de Entidades".

Para dar soporte a dicha funcionalidad, se debe configurar en el menú Administración, en la sección Información de configuración, las siguientes entradas:

Acorde a la tabla anterior tendremos 2 formas excluyentes de configurar, es decir o se utiliza el parámetro de URI o se utilizan sus componentes por separado.

Tendremos entonces por ejemplo:

1) Utilizando URI:

• rabbitMQ.enabled: (true o false)

• rabbitMQ.uri:amqp://<user>:<password>@<host>:<port>/<vhost(Opcional)>

• rabbitMQ.endpointName:<nombreCola>

2) Utilizando los parámetros por separado:

• rabbitMQ.enabled:(true o false) 

• rabbitMQ.username:<user>

• rabbitMQ.password:<pass>

• rabbitMQ.host:<host>

• rabbitMQ.virtualHost:<vhost>

• rabbitMQ.port:<port>

• rabbitMQ.endpointName:<nombreCola>

En la figura siguiente se observa la pantalla de Configuración:

Una vez configurado las propiedades de las colas, el sistema intentara conectarse al servidor de RabbitMQ, de no lograr una conexión exitosa, el sistema intentara nuevamente cuando se ejecute el job de importación "JobService" (antes de realizar la llamada a la importación)

Formato de Mensajes de la Cola (Catálogos)

El formato del mensaje a recibir desde las colas sigue el siguiente patrón (JSON) general:

{
	"companyId": "<companyId>",
	"catalog": "<catalogName>",
	"params": [],
	"items": [{
			"operation": "I",
			"<fieldName>": "<name>",
			"<fieldCode>": "<code>"
		},
		{
			"operation": "U",
			"<fieldName>": "<name>",
			"<fieldCode>": "<code>"
		},
		{
			"operation": "D",
			"<fieldName>": "<name>",
			"<fieldCode>": "<code>"
		},
		{
			"operation": "I",
			"<fieldName>": "<name>",
			"<fieldCode>": "<code>"
		}
	]
}	 

Donde:

TIPOS VALIDOS DE CATÁLOGOS:

Ejemplos de carga de Catálogos

En el siguiente ejemplo se observa la inserción de 2 registros de tarjetas.

{
	"companyId": "napse",
	"catalog": "catalogCard",
	"params": [],
	"items": [
		{
		"operation": "I",
		"code": "1234000000000",
		"type": "1234",
		"validFrom": "2019-06-01",
		"validTo": "2029-06-20",
		"cvv": "987",
		"customerId": 12134,
		"amount": 300000
		},
		{
		"operation": "I",
		"code": "1234000000001",
		"type": "1234",
		"validFrom": "2019-06-01",
		"validTo": "2029-06-22",
		"cvv": "879",
		"customerId": 2222,
		"amount": 60000
		},
	]
}

En el siguiente ejemplo se observa la inserción de 2 registros de Marcas:

{
	"companyId": "napse",
	"catalog": "catalogBrand",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "coke",
			"name": "Coca-Cola Company"
		},
		{
			"operation": "I",
			"code": "pepsi",
			"name": "Pepsi"
		}
	]
}

Aqui se observa un ejemplo de insertar un registro de Categoría:

{
	"companyId": "napse",
	"catalog": "catalogCategory",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "lineaBlanca",
			"name": "Linea Blanca",
            "familyCode":"Elect" 
		} 
	]
}

{
	"companyId": "napse",
	"catalog": "catalogChannel",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "web",
			"name": "WEB" 
		} ,{
			"operation": "I",
			"code": "POS",
			"name": "POINT OF SALE" 
		} 
	]
}

{
	"companyId": "napse",
	"catalog": "catalogCreditCampaignCode",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "campg1",
			"name": "Campania 1" 
		}   
	]
}

{
	"companyId": "napse",
	"catalog": "catalogCustomer",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "abc29789456",
			"name": "Jose Luis",
			"lastName": "Martinez", 
			"email":"[email protected]",
		   	"identificationType":"DNI",
            "identifier":"29789456"
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogCustomerType",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "vip",
			"name": "VIP CLIENT" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogIdType",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "DNI",
			"name": "DOCUMENTO NACIONAL DE IDENTIDAD" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogDepartment",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "elec",
			"name": "Electronica" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogEventTransaction",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "blFriday",
			"name": "Black Friday" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogEventTransactionType",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "bf2019",
			"name": "Black Friday 2019" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogExtendWarranty",
	"params": [],
	"items": [{
		"operation": "I",
		"code": "sonyArg",
		"category": "lineaBlanca",
		"creditProduct": "40 por ciento",
		"profileCustomers": "vip",
		"store": "dot",
		"skuWarranty": "WAUKH78EX6A144617",
		"yearsWarranty": "2 años",
		"initDate": ,
		"endDate": ,
		"endPrice": 13999
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogFamily",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "coc",
			"name": "Cocina" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogFormat",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "dig",
			"name": "Digital" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogInfoFinancial",
	"params": [],
	"items": [{
			"operation": "I",
			"code": "buss",
			"name": "Financial Bus" 
		}  
	]
}

{
	"companyId": "napse",
	"catalog": "catalogItem",
	"params": [],
	"items": [{
		"operation": "I",
		"code": "997551470-7",
		"name": "Disco sdd 256",
		"unitprice": 5000,
		"level1": "depart1",
		"level2": "family1",
		"level3": "category1",
		"level4": "subcategory1",
		"supplier": "tecno",
		"brand": "WesternDigital",
		"detail": "WesternDigital 512 gb",
		"detail2": "WesternDigital 512 gb sdd",
 		"<CodeFieldDynamic>":"<value>"
	}]
}

Ejemplo de CatalogItem con dos campos dinámicos, por ejemplo si se tienen dos campos dinámicos con el código sublinea y otro color, el ejemplo seria el siguiente
Productos con campos Dinámicos

{
	"companyId": "napse",
    "catalog": "catalogItem",
    "params": [],
    "items": [{
        "operation": "I",
        "code": "997551470-7",
        "name": "Disco sdd 256",
        "unitprice": 5000,
        "level1": "depart1",
        "level2": "family1",
        "level3": "category1",
        "level4": "subcategory1",
        "supplier": "tecno",
        "brand": "WesternDigital",
        "detail": "WesternDigital 512 gb",
        "detail2": "WesternDigital 512 gb sdd",
        "sublinea":"miSublinea",
        "color": "azul"
    }]
}

{
	"companyId": "napse",
	"catalog": "catalogPaymentBank",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "credit18",
		"name": "18 cuotas sin interes"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogPaymentCode",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "paymentCode1",
		"name": "payment code 1"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogPaymentPrefix",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "perfix1",
		"name": "perfix1"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogPaymentType",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "tarjeta",
		"name": "tarjeta de credito"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogProfileCode",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "abc1",
		"name": "clientes abc1"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogPaymentType",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "tarjeta",
		"name": "tarjeta de credito"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogStoreChain",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "chain1",
		"name": "chain1"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogStore",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "dot",
		"name": "tienda dot bs as"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogSubCategory",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "peqElec",
		"name": "Pequeños Electrodomesticos",
        "categoryCode": "ELECT"
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogSubZone",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "conurb",
		"name": "conurbano bsas" 
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogSupplier",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "sony",
		"name": "sony corporation" 
	}]
}

{
	"companyId": "napse",
	"catalog": "catalogZone",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "bsnorte",
		"name": "zona norte bsas" 
	}]
}

{
	"companyId": "napse",
	"catalog": "catalog<Dynamic>",
	"params": [],
	"items": [{
		"operation": "I", 
		"code": "code",
		"name": "name" 
	}]
}

Catálogos Asociados a Campos Dinámicos

La definición de los denominados campos dinámicos permite asociar los mismos con un catálogo.  Este catálogo puede ser también administrado vía colas.

Ejemplo de carga de catalogo DINÁMICO.

Pasos 

1. Ir al menú Administración en la opción Atributo de elementos, allí se creara el campo dinámico el cual tendrá que definirse como tipo AUTOCOMPLETADO POR CATALOGO. 
   
   
   
   
   
2. Una vez creado el nuevo atributo, desde el Productor de RabbitMQ, ya se podrá enviar los datos asociados al nuevo catalogo
   
   
   
   
   
3. Para poder acceder al resultado de la importación se tendrá que ver ir  en el menú SOPORTE la opción Monitor de Importación.

 4. En Administración, Importación de catálogos se podrán ver los datos ingresados.

5. En la promoción se podrá seleccionar los datos ingresados.

6 .Para que el motor pueda evaluar la promoción se deberá distribuir el atributo creado en el paso (Dicha distribución precisa que se reinicie el motor).

7. Distribuir el mapa con la promoción para poder evaluar la misma.

Promo como Productor

Promo permite el envío de información mediante colas RabbitMQ (función productor).  Por defecto esta información es enviada cada 30 minutos (proceso background) al servidor de colas.

Configuración del Producer

Para dar soporte a dicha funcionalidad, se debe configurar en el menú Administración, en el sub-menú Información de configuración, las siguientes entradas:

Nuevamente la configuración via URI es excluyente a la configuración por parámetros separados.  Entonces tendremos dos configuraciones:

Configuración mediante URI:

• rabbitMQ.producer.enabled: (true o false)

• rabbitMQ.producer.uri:amqp://<user>:<password>@<host>:<port>/<vhost(Opcional)>

• rabbitMQ.promotion.endpointName:<nombreCola para posteo de promociones>

• rabbitMQ.limitstatus.endpointName:<nombreCola para posteo del status de limites>
  

• rabbitMQ.cardhistory.endpointName: <Nombre de la cola de RabbitMQ para el posteo de datos de tipo CardHistory>
  

• rabbitMQ.enginestatus.endpointName:<nombreCola para posteo del status del motor y consola>
  

Segunda o configuración por parámetros:

• rabbitMQ.producer.enabled:(true o false) 

• rabbitMQ.producer.username:<user>

• rabbitMQ.producer.password:<pass>

• rabbitMQ.producer.host:<host>

• rabbitMQ.producer.virtualHost:<vhost>

• rabbitMQ.producer.port:<port>

• rabbitMQ.promotion.endpointName:<nombreCola para posteo de promociones>

• rabbitMQ.limitstatus.endpointName:<nombreCola para posteo del status de limites>

• rabbitMQ.cardhistory.endpointName: <nombreCola para posteo del CardHistory>
  

• rabbitMQ.enginestatus.endpointName:<nombreCola para posteo del status del motor y consola>
  

RabbitMQ – Historial de Tarjetas

La cola de mensaje disponibles para el envío del historial de tarjetas:

• rabbitMQ.cardhistory.endpointName  >>  Nombre de la cola de RabbitMQ para el posteo de datos del historial de tarjetas.

Ejemplo del Json que se envía:

{
 "_id": "603d02251082e8369081744b",
 "amount": "0",
 "amountPrev": "0",
 "card": {
 "code": "9900000000000000",
 "status": "ENABLED",
 "type": "987"
 },
 "cardAction": "ACTIVATION",
 "companyId": "napse",
 "createdAt": "2021-03-01T15:03:01Z",
 "customerCode": null,
 "date": "2021-03-01T15:03:01Z",
 "reason": null,
 "reasonName": null,
 "storeCode": null,
 "terminalCode": null
}

Detalle de los campos:

Fecha de creacion de la tarjeta de fidelidad.

RabbitMQ – Estado de los limites

La cola de mensaje disponibles para el envío de estado de los limites es:

• rabbitMQ.limitstatus.endpointName  >> Nombre de la cola de RabbitMQ para el posteo de datos de tipo LimitStatus (informara movimientos de todos los tipos de limites)

Ejemplo del Json que se envía:

{
                "_id": "603a36021082e83690816fe0",
                "promotionId": "603a2fa81082e83690816f81",
                "benefitId": "603a2fce1082e83690816f88",
                "promotionCode": null,
                "promotionName": "limite general",
                "limitId": "603a2fca1082e83690816f87",
                "scope": "RETAILER",
                "period": "UNDEFINED",
                "maxValue": 10.0,
                "customerId": "-",
                "storeId": "-",
                "numberDays": 0,
                "nextReset": "2021-02-27T03:00:00Z",
                "lastReset": "2021-02-27T03:00:00Z",
                "companyId": "napse",
                "limitTypeCode": "benefiedProductCount",
                "description": null,
                "lastUpdate": "2021-02-27T12:07:30Z",
                "active": true,
                "currentValue": 1.0
}

Detalle de los campos:

Tipo de limite a contabilizar (CUSTOMER, STORE, RETAILER).

Código del tipo de limite (benefitAmount, benefiedProductCount, benefitApplicationCount).

RabbitMQ – Estado de Motor y Consola

La cola de mensaje disponibles para el envío de estado de de motor y consola es:

• rabbitMQ.enginestatus.endpointName  >> Nombre de la cola de RabbitMQ para el posteo del status de motor y consola.

Configuración

El Job por defecto se ejecutará cada 5 minutos, pudiendo modificar el tiempo de ejecución desde Administración ->Tareas programadas.

Configuración del archivo promoplus.properties

Para identificar a la consola se deberán configurar los siguientes parámetros : promo.general.id y promo.general.name. Si estos parámetros se encuentran vacíos o no se definen, se utilizará en los procesos en ambos parámetros la ip.

Ejemplo del Json que se envía de RabbitMQ

{
    "engineId": "5",
    "engineName": "CONSOLE_5",
    "processDate": "16/03/2021 11:33",
    "startDate": "2021-03-12T03:00:00Z",
    "endDate": "2021-04-20T02:59:00Z",
    "keyMap": "napse",
    "mapVersion": "2",
    "stores": "napse",
    "statusMQ": "ONLINE",
    "timestamp": "16/03/2021 11:35"
    "isConsole":"false"
}

El Json de RabbitMQ, contendrá el siguiente formato:

Mensajes: Cache de Promociones

Cuando es ejecutado el proceso que evalúa y genera el cache de Promociones de Promo, se generan una serie de mensajes a la cola Rabbit con el siguiente formato general. 

Cada inicio de lote recibirá un primer mensaje del estilo:

{ 
   "promotionCode" : "0", 
   "promotionName" : "init promoCache lot number 1596140494623", 
   "SKU" : "0",
   "img": null
}

Luego cada promoción asociada al producto llevará el siguiente formato:

{ 
   "promotionCode" : "p003", 
   "promotionName" : "Promo03", 
   "SKU" : "2734",
   "img": “http://myserverPromo:8080/assets/images/promonavidad.jpg”
}

Gestión de Errores

En el caso de existir registros de posteos a server RabbitMQ con ERROR, se mostrara un aviso (banner) en la cabecera de Promo, indicando de forma general la incidencia.

1. Banner con detalle de la incidencia. 
   - Para conocer el detalle de la incidencia, presione Ver mas detalle.
   
   
   
   
2. Lista de procesos de exportación fallidos.
   - En el campo Descripción: se podrá visualizar la causa del error
   - Una vez corregido error que ocasiona el fallo en el posteo de los mensajes al server RabbitMQ, deberá presionar el botón Reprocesar
   
   
   
   
   
3. Si el procesamiento de los fallos relacionados al posteo de datos vía RabbitMQ es exitoso, la grilla deberá quedar sin registros por Reprocesar.