Manual de integração - Filas de mensagens 
PROMO V7.0

Índice

Sobre o Manual

Propósito e Escopo

O objetivo deste manual é treinar o usuário que deseja integrar seu aplicativo de vendas com os serviços expostos pelo Promo e sua integração através de filas de mensagens.
Uma descrição detalhada das mensagens que devem ser enviadas e como interpretar as mensagens de resposta que serão dadas a uma solicitação requerida. 

Introdução

Considerações no uso de Filas de Mensagens 

Atualmente as aplicações estão disponíveis na nuvem (SAS) e isso trouxe novos paradigmas de soluções arquitetônicas. Uma delas é desvincular essas aplicações em pequenos componentes ou blocos independentes que possam ser mais fáceis de desenvolver, implementar e manter no futuro. Obviamente, tal arquitetura requer um mecanismo de comunicação confiável e seguro entre os blocos acima mencionados e, acima de tudo, um mecanismo mais flexível do que a comunicação interprocesso tradicional com as limitações que impõem.

O uso de filas de mensagens nos dá uma alternativa válida para implementar a comunicação acima mencionada, e até mesmo a coordenação desses componentes. Considere que a fila de mensagens é um árbitro que quebra o conhecimento ou a dependência direta entre as partes, uma vez que está localizada no meio sendo a única coisa que consumidores e produtores de mensagens conhecem e dependem. Com isso, o código de comunicação é menor em cada componente e a comunicação segue um padrão Standard, como Publisher-subscriber, ou Listener DP, que é uma solução comprovada e adotada na indústria de software.

Outra vantagem no uso das filas é que elas permitem implementar uma comunicação assíncrona, já que como mencionado acima os produtores e consumidores não interagem entre si, mas o fazem através da fila para que as mensagens possam ser enviadas para a fila independentemente de haver alguém disponível ouvindo-os ou quem possa processá-los naquele momento. Da mesma forma, um consumidor pode pegar ou receber mensagens da fila em seu momento e poder de processamento. Dessa forma, nenhum componente depende diretamente do outro, melhorando o fluxo de dados.

Pelo que foi mencionado até agora, segue-se que a arquitetura é flexível em relação à sua escalabilidade, uma vez que, de acordo com a carga de trabalho, os nós da fila em si podem ser dimensionados, os produtores podem crescer em número e os consumidores da mesma forma, o que permite aumentar a capacidade do sistema de forma quase transparente.

Uma grande vantagem a mencionar é que sendo a fila que gerencia os dados, há uma maior tolerância às falhas, já que se algum componente não está disponível é a mesma fila que realiza a persistência dos dados e pode ser implementado em um esquema de alta disponibilidade melhorando ainda mais a tolerância a falhas.

Considerações Particulares do Promo 

O Promo incorporou o uso das filas acima mencionadas como padrão.

Na imagem a seguir, você pode ver um diagrama de arquitetura simples:

O diagrama mostra o Promo como produtor das informações que gerencia (por exemplo, cartões de fidelidade), ao mesmo tempo em que é consumidor das informações fornecidas por sistemas externos (por exemplo, catálogo de marca).

Dessa forma, todas as vantagens mencionadas na primeira parte do documento são obtidas onde a interdependência entre os sistemas é eliminada, e também o balanceamento de carga e escalabilidade são feitos de forma transparente, uma vez que tanto o Promo quanto o sistema externo podem crescer independentemente do outro. Ao mesmo tempo, a comunicação entre ambos os sistemas é gerenciada pelo servidor de fila, homogeneizando-o e eliminando o relacionamento direto e, portanto, a possibilidade de falhas por não encontrar um componente disponível, ou não responder no tempo estipulado.

O que é RabbitMQ?

RabbitMQ é um software de colagem de mensagens chamado corretor de mensagens ou gerente de fila. Simplificando, é um software onde as filas podem ser definidas, os aplicativos podem se conectar a essas filas e transferir/ler mensagens nelas.

Como Funciona?

A arquitetura básica de uma fila de mensagens é simples. Existem aplicativos de clientes, chamados produtores, que criam mensagens e as entregam ao intermediário (a fila de mensagens). Outros aplicativos, chamados de consumidores, se conectam à fila e assinam as mensagens a serem processadas. Uma mensagem pode incluir qualquer tipo de informação.

Um software pode ser um produtor, consumidor ou produtor e consumidor de mensagens simultaneamente. As mensagens colocadas na fila são armazenadas até que o consumidor as recupere e as processe.

Requisitos

No desenvolvimento deste manual presume-se que você tenha um servidor RabbitMQ instalado, disponível e configurado.

Para mais informações, entre em contato com https://www.rabbitmq.com/

Promo como Consumidor

O Promo tem a funcionalidade do consumidor da fila RabbitMQ com o objetivo de receber informações sobre catálogos de sistemas externos (produtores).

Configuração

Os parâmetros de configuração que permitem e definem essa funcionalidade estão localizados em Informações de Configuração de Administração→. (RabbitMQ palavra-chave na pesquisa).

Uma vez que o Promo recebe informações da fila Rabbit correspondente, ele será encaminhado para o monitor de importação e processado pela tarefa agendada chamada "Importador de Entidades".

Para suportar essa funcionalidade, as seguintes entradas devem ser configuradas no menu Administração, na seção Informações de Configuração:

De acordo com a tabela anterior teremos 2 maneiras exclusivas de configurar, ou seja, ou o parâmetro URI é usado ou seus componentes são usados separadamente.

Teremos, então, por exemplo:

1) Utilizando URI:

• rabbitMQ.enabled: (true o false)

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

• rabbitMQ.endpointName:<nombreCola>

2) Utilizando separadamente os parâmetros:

• rabbitMQ.enabled:(true o false) 

• rabbitMQ.username:<user>

• rabbitMQ.password:<pass>

• rabbitMQ.host:<host>

• rabbitMQ.virtualHost:<vhost>

• rabbitMQ.port:<port>

• rabbitMQ.endpointName:<nombreCola>

A figura a seguir mostra a tela Configurações:

Uma vez configuradas as propriedades da fila, o sistema tentará se conectar ao servidor RabbitMQ, se uma conexão bem sucedida não for alcançada, o sistema tentará novamente quando o trabalho de importação "JobService" for executado (antes de fazer a chamada de importação)

Formato de Mensagem de Fila (Catálogos)

O formato da mensagem a ser recebida das filas segue o seguinte padrão geral (JSON):

{
	"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>"
		}
	]
}	 

Onde:

TIPOS DE CATÁLOGOS VÁLIDOS:

Exemplos Carga de Catálogos

O exemplo a seguir mostra a inserção de 2 registros de cartão.

{
	"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
		},
	]
}

O exemplo a seguir mostra a inserção 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 está um exemplo de inserção de um registro de categoria:

{
	"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>"
	}]
}

Exemplo do CatalogItem com dois campos dinâmicos, por exemplo, se você tiver dois campos dinâmicos com o código sublinhado e outra cor, o exemplo seriam os seguintes
produtos com 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": "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 Associados a Campos Dinâmicos

A definição dos chamados campos dinâmicos permite que você os associe a um catálogo. Este catálogo também pode ser gerenciado através de filas.

Exemplo de Carga de Catálogo Dinâmico.

Passos

Vá para o menu Administração na opção Atributo de Elementos, lá será criado o campo dinâmico que terá que ser definido como tipo AUTOCOMPLETE BY CATALOG. (AUTOCOMPLETADO POR CATÁLOGO)

1. Uma vez criado o novo atributo, a partir do Produtor RabbitMQ, os dados associados podem ser enviados para o novo catálogo
   
   
   
   
   
2. Para acessar o resultado da importação, você terá que ver a opção Monitor de Importação no menu SUPORTE.

 4. Na Administração, Importação de Catálogo você pode ver os dados inseridos.

5. Na promoção você pode selecionar os dados inseridos.

6. Para que o motor avalie a promoção, o atributo criado na etapa deve ser distribuído (Esta distribuição exige que o motor seja reiniciado).

7. Distribua o mapa com a promoção para avaliá-lo.

Promo como Produtor

O Promo permite o envio de informações via filas RabbitMQ (função do produtor). Por padrão, essas informações são enviadas a cada 30 minutos (processo de segundo plano) para o servidor da fila.

Configuração do Produtor

Para suportar essa funcionalidade, as seguintes entradas devem ser configuradas no menu Administração, no sub-menú de informações de configuração:

Novamente a configuração via URI é exclusiva da configuração por parâmetros separados. Então teremos duas configurações:

Configuração via URI:

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

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

• rabbitMQ.promotion.endpointName:<NomeFila para postar promoções>

• rabbitMQ.limitstatus.endpointName:<NomeFila para postar o status dos limites>
  

• rabbitMQ.cardhistory.endpointName: <Nome da fila RabbitMQ para postar dados do tipo CardHistory>
  

• rabbitMQ.enginestatus.endpointName: <nomeFila para postar o status do motor e do console>
  

Segundo a configuração 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:<nomeFila para postar promoções>

• rabbitMQ.limitstatus.endpointName:<nombreFila  para postar o status dos limites>

• rabbitMQ.cardhistory.endpointName: <nomeFila para postar o CardHistory>
  

• rabbitMQ.enginestatus.endpointName:<nomeFila  para postar o status do motor e do console>

RabbitMQ - Histórico do Cartão

A fila de mensagens disponível para envio do histórico do cartão:

• rabbitMQ.cardhistory.endpointName  >> Nome da fila RabbitMQ para postar dados do histórico do cartão.

Exemplo do Json sendo enviado:

{
 "_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
}

Detalhe dos campos:

Data de criação do cartão fidelidade.

RabbitMQ - Estado dos Limites

A fila de mensagens disponível para envio do status do limite é:

• rabbitMQ.limitstatus.endpointName >> Nome da fila RabbitMQ para postar dados do tipo LimitStatus (relatará movimentos de todos os tipos de limites)

Exemplo do Json sendo enviado:

{
                "_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
}

Detalhe dos campos:

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

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

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

RabbitMQ – Status do Motor e do Console

A fila de mensagens disponível para envio do status do motor e do console é:

• rabbitMQ.enginestatus.endpointName >> Nome da fila RabbitMQ para postar o status do motor e do console.

Configuração

O Trabalho padrão será executado a cada 5 minutos, podendo modificar o tempo de execução das tarefas programadas pela Administração ->.

Configurando o arquivo promoplus.properties

Para identificar o console, devem ser configurados os seguintes parâmetros: promo.general.id e promo.general.name. Se esses parâmetros estiverem vazios ou não definidos, o ip será utilizado nos processos em ambos os parâmetros.

Exemplo do Json sendo enviado do 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"
}

O RabbitMQ Json conterá o seguinte formato:

Mensagens: Cache de Promoções

Quando o processo que avalia e gera o cache de Promoções do Promo é executado, uma série de mensagens são geradas para a fila do  Rabbit com o seguinte formato geral.

Cada início de lote receberá uma primeira mensagem como:

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

Em seguida, cada promoção associada ao produto terá o seguinte formato:

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

Gerenciamento de Erros

No caso de registros de postagens no servidor RabbitMQ com ERRO, um aviso (banner) será exibido no cabeçalho Promo, indicando de forma geral o incidente.

1) Banner com detalhes do incidente.
- Para saber os detalhes do incidente, pressione Veja mais detalhes.

2. Lista de processos de exportação com falha.
- No campo Descrição: você pode ver a causa do erro

          - Uma vez corrigido erro que causa a falha na postagem de mensagens para o servidor RabbitMQ, você deve pressionar o botão Reprocessamento

3. Se o processamento de falhas relacionadas à publicação de dados via RabbitMQ for bem-sucedido, a rede deve ficar sem registros para reprocessar.

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