INTRODUCCIÓN

Este documento tiene como finalidad describir en detalle el modelo de datos utilizado en la integración del Plugin Bridge2SQL con SQL Server. La finalidad del documento es proporcionar una referencia técnica para el diseño, implementación y mantenimiento de la base de datos, asegurando la correcta estructuración de las transacciones procesadas desde el sistema Bridge Manager Central hasta su almacenamiento en SQL Server.

El objetivo principal es establecer un marco de referencia claro para la gestión de datos en el entorno de integración, facilitando la interoperabilidad entre los distintos sistemas involucrados. Se incluyen detalles sobre la arquitectura del sistema, el flujo de procesamiento de datos, la estructura de las tablas en la base de datos y el mapeo de información entre los formatos JSON y SQL.

Este documento está dirigido a desarrolladores, arquitectos de sistemas y administradores de bases de datos que requieran comprender el funcionamiento interno del Plugin Bridge2SQL y su impacto en la estructura de datos.

DIAGRAMA DE ARQUITECTURA

El sistema se conforma de cuatro componentes principales:

• Bridge Manager Central: Sistema exportador.

• Sistema de Colas RabbitMQ: Para encolar los datos exportados.

• Plugin Bridge2Sql: Lee las colas RabbitMQ y escribe los datos en SQL.

• Servidor SQL: Almacena los datos procesados.

Todos los componentes pueden convivir en el mismo servidor si fuera necesario.

DESCRIPCIÓN DE LOS COMPONENTES

Bridge Manager Central

Actúa como BackOffice complementando la operación en tienda de los puntos de venta. La solución cuenta con un conjunto de módulos que contemplan las operaciones reducidas de Cash Office, su módulo de abastecimiento y provee una serie de interfaces de integración con sistemas externos como ERP, sistemas legacy, etc.

Cuenta con una "Consola de administración", encargada de brindar una herramienta centralizada de administración. Esta consola es Web y funciona sobre un servidor de aplicaciones. Permite configurar qué tipos de transacciones se pueden exportar y hacía donde se expone la información por ejemplo “rabbit”.

Colas RabbitMQ

Sistema de mensajería que almacena datos encolados para procesamiento. Actúa como intermediario confiable entre sistemas distribuidos.

Su principal responsabilidad es almacenar los datos encolados para su procesamiento. RabbitMQ facilita la comunicación entre aplicaciones distribuidas al actuar como un intermediario confiable que encola, enruta y entrega mensajes de manera eficiente y flexible. Su uso permite la creación de sistemas robustos y escalables que pueden manejar grandes volúmenes de mensajes de manera confiable.

Las colas en RabbitMQ son puntos de almacenamiento temporales para los mensajes y actúan como buffers donde los mensajes son encolados hasta que son consumidos por los consumidores, en nuestro caso el plugin Bridge2Sql.

Plugin Bridge2Sql

Es un componente más de la solución Bridge que actua como el consumidor de los mensajes encolados en RabbitMQ y los procesa para insertarlos en el servidor de base de datos SQL. Una de las responsabilidades de este sistema es determinar a qué tablas se realizarán las inserciones de los registros dependiendo del valor de los campos de control.

Si bien realiza algunas operaciones de procesamiento, la mayor prioridad de este sistema será la lectura y escritura de la información.

Componentes:

1. Configuración Inicial: Configurar conexión a RabbitMQ y a SQL Server

2. Conexión a RabbitMQ: Configurar canales y declaración de colas a leer.

3. Consumo de Mensajes: Recibe un mensaje, lo procesa extrayendo la información relevante para insertar en SQL.

4. Procesamiento de Mensajes: Implica la deserialización del mensaje (si está en un formato específico, como JSON o XML), la validación de los datos y la preparación para la inserción en la base de datos.

5. Conexión a la Base de Datos SQL Server: Abrir una conexión con SQL de forma segura.

6. Inserción de Registros en la Base de Datos: Ejecutar los scripts de SQL

7. Manejo de Errores y Reintentos: El plugin debe implementar mecanismos de manejo de errores y reintentos para garantizar la fiabilidad y la integridad de los datos.

8. Cierre de Conexiones: Una vez que el plugin ha terminado de procesar los mensajes o se detiene su ejecución, debe cerrar todas las conexiones abiertas con RabbitMQ y la base de datos SQL Server de manera adecuada para liberar recursos y garantizar una terminación limpia.

SQL Server

Es un sistema de gestión de bases de datos relacional (RDBMS) desarrollado por Microsoft. Proporciona un entorno robusto y seguro para almacenar, administrar y recuperar datos de manera eficiente. Es ampliamente utilizado en empresas de todos los tamaños y sectores para almacenar y gestionar datos críticos de negocio.

FLUJO DE DATOS

El Plugin Bridge2SQL procesa transacciones marcadas como pendientes y determina el flujo de procesamiento según los siguientes criterios:

Transactions

Evalúa el campo trxType y si es "Sale", "ManualExchange" o "Exchange", inserta en:

• transactionRetail (cabecera de la transacción).

• transactionRetailItem (detalle de ítems).

• transactionRetailPayment (detalle de pagos).

• transactionRetailDiscount (detalle de descuentos).

New Customer

Si el campo typeCode es "NewCustomer", "PRS" o "OGN", inserta en:

• party (cabecera del cliente).

• partyContactMethod (métodos de contacto).

Tender Transaction

Si el campo typeCode es "TenderLoan", "TenderPickup" o "TenderWithdrawal", inserta en:

• tenderTransaction (cabecera de la transacción).

• tenderTransactionDetail (detalle de ítems).

Control Transaction

Si el campo trxType es "BusinessEOS" o "BusinessSOS", inserta en:

• controlTransaction (cabecera).

Safe Transaction

Si el campo trxType es "TenderInflow" o "TenderOutflow", inserta en:

• safeTransaction (cabecera).

• safeTransactionDetail (detalle).

MAPEO DE LA INFORMACIÓN JSON - SQL

Una de las ideas del diseño de esta solución es que los nombres de los campos entre el JSON y SQL Sea el mismo y represente la misma información. En las tablas se mostrarán las correspondencias y se destacarán los casos en los que existe diferencia.

JSON Sale – SQL transactionRetail

JSON Sale.items – SQL transactionRetailItem

JSON Sale.discounts – SQL transactionRetailDiscount

JSON Sale.payments – SQL transactionRetailPayment

JSON NewCustomer – SQL party

JSON NewCustomer.contactMethods – SQL partyContactMethod

JSON TenderTransaction – SQL tenderTransaction

JSON TenderTransaction.tenderTranItems – SQL tenderTransactionDetail

JSON TenderInflow – SQL safeTransaction

orado las actualizaciones detectadas en el nuevo script SQL.

JSON TenderInFlow.tenderControlTransactionTenderLineItems – SQL safeTransactionDetail

JSON BusinessEOD – SQL controlTransaction

JSON newOrder – SQL newOrder

orderTypeCode

orderTypeCode

isPaid

isPaid

JSON NewOrder.detail  – SQL newOrderDetail

JSON NewOrder.detail.priceModifiers  – SQL newOrderDetailPriceModifiers

JSON NewOrder.payments   – SQL newOrderPayments

JSON NewOrder.transactions   – SQL newOrderTransactions

trxDate

trxDate

JSON tillConciliation   – SQL tillConciliation  

JSON tillConciliation.tenderAdditionalData   – SQL tillConciliationTenderAdditionalData 

JSON tillConciliation.subperiods   – SQL tillConciliationSubperiods

JSON tillConciliation.controlTransaction.TillConciliation.controlTransactionTillLineItems – SQL tillConciliationTillLineItems

JSON tillConciliation.controlTransaction.TillConciliation.controlTransactionTillLineItems.controlTransactionTillTenderLineItems –

SQL tillConciliationTillTenderLineItems

SON tillConciliation.controlTransaction.TillConciliation.controlTransactionTillLineItems.controlTransactionSecondaryTillLineItems –

SQL tillConciliationSecondaryTillLineItems

JSON tillConciliation.controlTransaction.TillConciliation.controlTransactionTillLineItems.controlTransactionSecondaryTillLineItems.controlTransactionSecondaryTillTenderLineItems– SQL tillConciliationSecondaryTillTenderLineItems

INSTALACIÓN DEL PLUGIN

• Para que el plugin funcione, deben haberse dado los siguientes pasos: 
  • Creación de la base de datos Bridge2SQL en MongoDB.
  • Creación de la base de datos Bridge2SQL en SQL Server.
  • Haber corrido los scripts en la base de datos Bridge2SQL de SQL Server y los incrementales.
  • Haber instalado el plugin NodeJS.
  • Haber configurado bien el plugin, apuntando a central, base de datos mongo y SQL.
  • Haber habilitado la exportación a Rabbit desde BMC.
  • Haber configurado en el config del plugin, que colecciones va a exportar, es decir, esto se configura en BMC (habilitando la exportación a Rabbit) y luego en el plugin (indicando cuales son las colas Rabbit que escucha).
• Se debe crear una nueva base de datos con un nombre alusivo en un Servidor SQL Server, por ejemplo Bridge2SQLMarti
• En MongoDB, en el servidor en donde ejecuta BMC o BAPIC, se debe crear una base de datos MongoDB con un nombre alusivo, por ejemplo Bridge2SQLMarti
• Se deben correr el script principal y los incrementales en el siguiente orden: 
  • CreacionTablas.sql
  • 20240606-NAPSEPD-31693-AlterTenderReferenceNumber.sql
  • 20240819-NAPSEPD-32712-AlterTransactionRetail.sql
  • 20240821-NAPSEPD-32527-AlterTransactionRetailPayment.sql
  • 20240924-NAPSEPD-34679-AlterTransactionRetail.sql
  • 20241120-NAPSEPD-36262-AlterTransactionRetailPayment.sql
  • 20250327-NAPSDPD-35846-AgregaCamposDeProcesamientoEnTablas.sql
  • 20250410-NAPSDPD-35846-AcomodaCamposSiNoExisten.sql
• La base deberá verse así: 

• El próximo paso, es configurar el archivo de configuración: 

• {
    "app": {
      "db": {
        "mongoUrl": "mongodb://admin:[email protected]:27017/pluginSQLmarti?replicaSet=bridge&authSource=admin"
      },
      "rabbit": {
        "url": "amqp://admin:[email protected]:5672",
        "active": true,
        "queues":["transactions.sql", "customers.sql"]
      },
      "server": {
        "port": "8682",
        "logMode": "debug",
        "isSsl": false
      },
      "bridge": {
        "url": "http://10.4.203.65:8081",
        "client": "bridge-api",
        "secret": "DA39A3EE5E6B4B0D3255BFEF95601890AFD80709",
        "topTransactions": 10
      },
      "sql": {
        "user": "napse_usr",
        "password": "Read+Card-Bell",
        "database": "DW_NAPSE",
        "server": "10.72.250.11",
        "port": 1433
      }
    }
  }
  
  

• Los datos del archivo, son los siguientes: 
  • mongoUrl es la dirección del servidor de base de datos contra el cual operará el plugin, NO se trata de la base productiva de BRIDGE, si no, de una nueva base que será utilizada por el plugin.
  • rabbit: se debe configurar la IP de RabbitMQ de donde el plugin tomará los registros que se exportan.
  • rabbit.queues: se deben definir que colas se tomarán.
  • bridge: son los datos de BRIDGE API.
  • sql: es la información del servidor de SQL Server en donde cree la base.
• Luego, se instala el plugin como cualquier otro, es decir, si es en Linux, se configura en ecosystem o si es en Windows, como servicio.