INTRODUCCIÓN

Este manual ha sido diseñado para proporcionar una guía clara, estructurada y práctica sobre el proceso de instalación de plugins en el ecosistema de Bridge. Su propósito es servir como referencia tanto para usuarios técnicos como para administradores de sistemas, asegurando que cualquier persona involucrada en la implementación de plugins pueda comprender los pasos necesarios, validar los requisitos previos, configurar correctamente el entorno y poner en funcionamiento el servicio de manera segura y eficiente.

Objetivo del Documento

El objetivo de este manual es:

• Explicar qué es un plugin dentro de la arquitectura de Bridge y su rol en la ampliación de funcionalidades.

• Describir los requisitos técnicos y archivos necesarios para su instalación.

• Detallar el proceso de despliegue tanto manual como automatizado.

• Instruir sobre la configuración adecuada para su correcto registro y funcionamiento dentro de Bridge.

• Establecer las validaciones recomendadas tras la instalación para garantizar su operatividad.

¿A quién está dirigido este Manual?

Este documento está pensado para:

• Administradores de sistemas, que deberán instalar y mantener los plugins.

• Equipos de soporte técnico, que realizarán el monitoreo y troubleshooting de las integraciones.

• Desarrolladores, que pueden necesitar comprender el proceso de instalación para adaptar o crear nuevos plugins.

• Consultores de implementación, que deben garantizar una puesta en marcha estandarizada y alineada con las prácticas de Bridge.

Alcance del Documento

Este manual aborda la instalación de cualquier plugin estándar desarrollado para el ecosistema Bridge, siguiendo las prácticas generales definidas para:

• Plugins de integración de datos (ej.: exportación a bases SQL, APIs externas).

• Plugins de generación de informes personalizados.

• Plugins de procesamiento de transacciones o servicios complementarios.

¿Qué es un Plugin de Bridge?

Un Plugin de Bridge es un componente modular que se integra al ecosistema de Bridge para extender sus funcionalidades sin necesidad de modificar el código base de la plataforma.

Los plugins permiten a cada cliente o implementación:

• Agregar nuevas capacidades, como generación de reportes, integración con bases de datos externas, procesamiento de transacciones, entre otros.

• Personalizar el sistema de forma segura y controlada.

• Mantener la independencia y escalabilidad de Bridge ante nuevas necesidades de negocio.

Características principales de un Plugin de Bridge:

• Desarrollo independiente: el plugin se construye como un servicio separado que se comunica con Bridge mediante APIs.

• Comunicación automática: utiliza la librería Bridge API Lib para interactuar con Bridge, registrándose y actualizándose automáticamente a través de mensajes de heartbeat enviados cada 30 segundos​.

• Configuración flexible: su comportamiento se define a través de archivos JSON, permitiendo configurar aspectos como endpoints, filtros y visualizaciones​.

• Ejecutado como servicio: se instala en servidores Linux o Windows y corre como un servicio autónomo, administrado por PM2 o NSSM, respectivamente​.

• Visualización embebida: su contenido (por ejemplo, reportes) se muestra dentro de Bridge a través de un iframe, garantizando una integración visual consistente​.

Beneficios de usar Plugins en Bridge:

• Permiten personalizar la solución Bridge para diferentes clientes o escenarios sin afectar el núcleo del sistema.

• Facilitan actualizaciones rápidas y seguras al no depender de cambios en el sistema base.

• Mejoran la escalabilidad y la adaptabilidad, ya que pueden ser instalados, actualizados o eliminados de forma independiente.

• Incrementan el control y la seguridad gracias al uso de permisos y validaciones nativas de Bridge para los reportes o funcionalidades expuestas.

Requisitos Previos para la Instalación

Antes de proceder con la instalación de un plugin en Bridge, es fundamental verificar que el entorno de destino cumpla con los siguientes requisitos técnicos y operativos.
La correcta preparación del entorno asegura un despliegue exitoso y minimiza posibles errores de ejecución o de comunicación.

Requisitos Técnicos del Servidor

• Sistema Operativo Compatible:

  • Windows Server 2016 o superior

  • Distribuciones Linux modernas (Ubuntu 18.04+, CentOS 7+, Debian 10+)

• Node.js:

  • Versión 14.x o superior instalada y correctamente configurada en el servidor.

  • Se recomienda validar la instalación ejecutando el comando:

    • node -v

• Gestor de procesos según Sistema Operativo:

  • PM2 instalado globalmente en entornos Unix/Linux.
    Instalación recomendada mediante:

    • npm install -g pm2
      
      

  • NSSM (Non-Sucking Service Manager) disponible en el servidor para entornos Windows, utilizado para gestionar el servicio del plugin.

• Acceso a Internet o conectividad interna:

  • Si el plugin requiere acceder a servicios externos, APIs, o a Bridge Manager Central, se debe asegurar la conectividad adecuada entre el servidor del plugin y los servicios destino.

Requisitos de Software Complementario

• Instalación de librerías del proyecto:
  El servidor debe permitir la instalación de dependencias vía npm, incluyendo la librería bridge-api-lib y las demás dependencias propias del plugin.

• Herramientas de compresión:
  El servidor debe contar con herramientas para descomprimir archivos .zip, ya que el plugin suele ser entregado empaquetado.

Requisitos de Configuración

• Archivo de configuración disponible:
  El paquete del plugin debe incluir un archivo de configuración (usualmente ubicado en /config/default.json) donde se definirán:

  • Parámetros de conexión a Bridge .

  • Parámetros específicos del funcionamiento del plugin.

• Credenciales y endpoints necesarios:
  Deben estar disponibles y validadas las credenciales de acceso a Bridge (usuario, contraseña, API keys) y las rutas (URLs) de los servicios a integrar.

• Permisos en el sistema operativo:
  Se requiere acceso con permisos de administrador (root o administrador local) para:

  • Instalar Node.js, PM2 o NSSM.

  • Ejecutar servicios de sistema.

  • Copiar y extraer archivos en las carpetas destino.

Archivos Necesarios

Para llevar a cabo la instalación de un plugin en Bridge, es fundamental contar con todos los archivos que conforman el paquete del plugin y sus elementos complementarios. A continuación, se detalla qué incluye ese paquete y qué otros recursos pueden ser necesarios según el sistema operativo.

Paquete Principal del Plugin

El plugin se entrega habitualmente en formato comprimido .zip y debe contener como mínimo los siguientes elementos:

• Archivo .zip del plugin:
  Contiene todos los archivos fuente, configuraciones y dependencias necesarias del plugin.

  • Ejemplo de nombre de plugin: plugin-template.zip

• Carpeta config:
  Incluye el archivo de configuración principal donde se definen los parámetros necesarios para la conexión y funcionamiento del plugin. 
  • Ejemplo de ruta y archivo: /config/default.json
• Archivos del proyecto (código fuente):
  Contienen los scripts, módulos y servicios del plugin que serán ejecutados en el entorno del servidor.
  • Ejemplo: /dist/plugin-template.js

Scripts de Despliegue

El paquete suele incluir scripts para automatizar el proceso de instalación y configuración del plugin según el sistema operativo:

• Para entornos Unix/Linux: deploy.sh
• Para entornos Windows: deploy.ps1

Estos scripts facilitan tareas como descompresión, instalación de dependencias y configuración del servicio (PM2 o NSSM).

Archivos Complementarios (Solo Windows)

En entornos Windows, además del paquete principal del plugin, se requiere el ejecutable del gestor de servicios:

• nssm.exe:
  Herramienta necesaria para instalar el plugin como servicio en Windows.

  Este archivo debe copiarse a la misma carpeta donde se encuentra el .zip del plugin.

Archivos de Dependencias

Algunos plugins pueden requerir dependencias adicionales no incluidas directamente en el .zip principal, por ejemplo:

• bridge-api-lib:
  Librería de integración con Bridge, que suele instalarse mediante: 

  npm install bridge-api-lib.tar.gz

El paquete o el proveedor del plugin debe indicar si se entregan dependencias empaquetadas o si deben descargarse durante la instalación.

Despliegue del Plugin y Levantado del Servicio

El proceso de despliegue de un plugin en Bridge Manager puede realizarse de dos maneras:

• Despliegue automático: recomendado, rápido y menos propenso a errores.

• Despliegue manual con levantado de servicio: útil en casos donde no se pueden usar scripts automatizados o se requiere mayor control sobre cada paso.

Despliegue Automático

El paquete del plugin suele incluir scripts que automatizan las tareas de instalación, configuración e inicio del servicio.

Pasos generales:

• Preparar el entorno

• • Copiar el archivo .zip del plugin y el script correspondiente (deploy.sh o deploy.ps1) a la carpeta de destino en el servidor.

  • En Windows, asegurarse de tener nssm.exe en la misma carpeta.

• Modificar el script de despliegue

• • Editar el script para completar las variables:

    • ZIP_FILE: Nombre del archivo .zip del plugin.

    • APP_NAME: Nombre del plugin.

    • APP_EXEC_FILE: Ruta al archivo principal del plugin (solo en deploy.sh).

• Ejecutar el script

• • En Unix/Linux: 

    bash deploy.sh -setup

  • En Windows (PowerShell como administrador): 

    powershell -ExecutionPolicy Bypass -File deploy.ps1 -Setup

• Actualizar el entorno (cuando sea necesario)

  • Ejecutar el script sin -setup: 

    bash deploy.sh

  • o 

    powershell -ExecutionPolicy Bypass -File deploy.ps1

Despliegue Manual y Levantado del Servicio

Paso 1: Descomprimir el paquete

• Extraer el contenido del archivo .zip en la carpeta donde se alojará el plugin.

Paso 2: Configurar el archivo JSON

• Editar config/default.json con los parámetros correctos de conexión a Bridge y cualquier otra configuración requerida.

Paso 3: Instalar dependencias del proyecto

• Instalar librería bridge-api-lib:

  npm install bridge-api-lib.tar.gz

• Instalar demás dependencias: 

  npm install --production

Paso 4: Configurar y levantar el servicio

 Unix/Linux (PM2)

• Crear archivo ecosystem.config.js 

module.exports = {
  apps: [
    {
      name: 'plugin-template',
      script: './dist/plugin-template.js',
      watch: false,
      env: {
        NODE_ENV: 'production',
      },
    },
  ],
};

• Iniciar y configurar el servicio 

  pm2 start ecosystem.config.js
  pm2 startup
  pm2 save
  pm2 status plugin-template

• Revisar logs en caso de error 

  pm2 logs plugin-template

Windows (NSSM)

• Copiar nssm.exe a la carpeta del plugin.

• Crear archivo start.bat 

  @echo off
  cd %~dp0
  npm start

• Registrar el servicio con NSSM desde PowerShell

  & nssm.exe install "plugin-template" "cmd.exe" "/c start.bat"
  & nssm.exe set "plugin-template" AppDirectory (Get-Location).Path
  & nssm.exe set "plugin-template" AppNoConsole 1
  & nssm.exe set "plugin-template" DisplayName "plugin-template"
  & nssm.exe set "plugin-template" Description "Servicio para plugin-template"
  & nssm.exe set "plugin-template" Start SERVICE_AUTO_START

• Iniciar el servicio 

  Start-Service "plugin-template"

• Verificar el estado del servicio 

  Get-Service "plugin-template"

Configuración del Plugin

Una vez desplegado el plugin, es fundamental realizar su configuración correcta para garantizar que pueda conectarse a Bridge y cumplir su función prevista (reportes, integraciones, procesamiento de datos, etc.).

La configuración principal se realiza a través de un archivo JSON ubicado dentro de la carpeta config, generalmente llamado: "config/default.json"

Parámetros básicos en el archivo JSON

El archivo default.json incluye, entre otros, los siguientes parámetros principales:

• Identificación del Plugin

  • pluginCode: Código único del plugin.

  • name: Nombre descriptivo.

  • description: Breve descripción de su funcionalidad.

  • version: Versión del plugin.

• Conexión a Bridge

  • bridgeHost: Dirección o URL de Bridge Manager Central.

  • bridgePort: Puerto de conexión (si aplica).

  • apiKey / accessToken: Credenciales para autenticar la comunicación.

  • heartbeatInterval: Intervalo en segundos para el envío de heartbeat (generalmente 30 segundos).

• Ubicación de ejecución

  • location: Define si el plugin se ejecuta a nivel Central, Tienda o Terminal.

• Configuración de endpoints

  • Lista de endpoints expuestos, incluyendo:

    • url: Dirección de acceso al endpoint.

    • methods: Métodos HTTP soportados (GET, POST, etc.).

    • description: Breve descripción funcional.

• Filtros o parámetros del negocio

  • Configuración de filtros disponibles para reportes o consultas (por ejemplo: tienda, terminal, rango de fechas).

{
  "app": {
    "server": {
      "host": "localhost",
      "port": 8685,
      "logMode": "debug",
      "isSsl": false
    },
    "bridgeApi": {
      "baseUrl": "https://bridge.example.com:8081",
      "clientId": "bridge-api",
      "clientSecret": "abcdef123456",
      "jwtSecret": "00779ae4504f371218efdd2e5f41d99f",
      "authPath": "/auth/login",
      "statusPath": "/integration/status"
    },
    "mongoDb": {
      "uri": "mongodb://admin:[email protected]:27017/bridgeStore?authSource=admin&authMechanism=SCRAM-SHA-1"
    }
  }
}

Registro automático en Bridge

Una vez iniciado, el plugin enviará automáticamente un heartbeat cada 30 segundos:

• Si es detectado por primera vez, Bridge lo registrará automáticamente en su base de datos.

• Si el plugin ya estaba registrado, Bridge actualizará su configuración usando la información enviada en el heartbeat.

Este mecanismo garantiza que Bridge siempre tenga la versión más actualizada del plugin y permite verlo desde el Monitor de Integraciones o en el menú Otros Reportes (según la configuración).

Validaciones Post-Instalación

Después de instalar y levantar el servicio del plugin, es fundamental realizar una serie de validaciones para asegurarse de que todo funciona correctamente y evitar problemas en producción.

Validación del Servicio

• Unix/Linux (PM2): 

  pm2 status plugin-template

  • Confirmar que el estado sea “online”.

  • Revisar logs si hay errores: 

    pm2 logs plugin-template

• Windows (NSSM): 

  Get-Service "plugin-template"

  • Confirmar que el estado sea “Running”.
  • Consultar el Event Viewer o los logs generados por el plugin en caso de problemas.

Validación de Conectividad con Bridge

• Revisar en el Monitor de Integraciones de Bridge que el plugin aparece registrado.

• Confirmar que Bridge detecta el plugin como activo (heartbeat recibido cada ~30 segundos).

• Verificar en el log de Bridge que no se registran errores de autenticación, conexión o endpoints.

Validación de Endpoints y Funcionalidad

• Probar los endpoints del plugin (si aplica) desde un navegador, herramienta API (Postman) o directamente desde Bridge.

• Confirmar que los reportes, integraciones o procesos gestionados por el plugin: ✔ Funcionan correctamente.
  • Devuelven datos esperados.
  • Respetan filtros y parámetros configurados.

Validación de Logs del Plugin

Revisar los logs generados por el propio plugin para:

• Detectar errores de arranque.
• Identificar problemas de conexión a Bridge, bases de datos o servicios externos.
• Verificar que los procesos internos funcionan como se espera.

Validación en Reinicio del Servidor

Reiniciar el servidor (o simular un reinicio de servicios) y confirmar que:

• El plugin se inicia automáticamente.
• El estado del servicio (PM2 / NSSM) vuelve a ser “online” o “Running”.
• El heartbeat vuelve a aparecer en Bridge.