Integrador
El integrador del Gestión de Relaciones | CRM es una herramienta, destinada a facilitar la integración de otros sistemas disponibles en el mercado con el Gestión de Relaciones | CRM y viceversa. Permite crear y gestionar las integraciones, mediante configuraciones de sistema o parametrización, sin necesidad de desarrollar nuevas fuentes.
En términos de ejecución, el Integrador solo ejecuta lo que se configuró para él, pues no realiza todas las acciones automáticamente. Lo que hace el Integrador es interpretar y ejecutar las configuraciones de una determinada integración ya registrada, en el momento en que es llamada para ejecución, a través de una URL. Con eso, es necesario configurarla correctamente y ejecutar la llamada. Existen tres tipos de ejecución que tienen la misma estructura de configuración, con sus propias peculiaridades:
Para utilizar el Integrador, es necesario utilizar un software capaz de realizar solicitudes, creando el paquete HTTP con parámetros específicos en el header. Para eso, recomendamos el software Postman.
La ejecución de cada integración es vía llamanda de una URL con algunos parámetros de ejecución de la integración informados, pudiendo contener parámetros configurados para una integración exclusiva, además de los valores obligatorios:
- EMPRESA_ID o EMPRESA_FILIAL_ID: identificador de la empresa del CRM o identificador de la empresa y sucursal del CRM, según el sistema del cliente para múltiples empresas;
- BASE_CRM: nombre de la base de datos del cliente en el CRM;
- INTEGRACAO_SERVICO_ID: identificador del servicio a ser ejecutado;
- TOKEN_CRM: clave de seguridad que permite acceso a una determinada base de datos, conforme permiso. Este valor debe ser agregado en el header de la solicitud.
El TOKEN_CRM es obligatorio en todas las integraciones.
Ejemplo:
URL para llamar a una integración particular: https://Integrador.crmsenior.com.br/Integrador/integrar.php?empresa_id=1&base_crm=crmsenior&servico_integracao_id=1
Paquete completo utilizando la herramienta Postman para envío de la solicitud:
Params
Headers
Cada identificador de empresa del CRM por cliente genera un archivo de log de errores y accesos, que registrará los pasos realizados y los errores encontrados durante la ejecución, sean advertencias o errores fatales, para posibles correcciones. Para que cualquier integración se realice, es necesario configurar los datos de la conexión en un archivo que será cargado por el Integrador.
El Integrador se basa en cinco tablas del CRM, donde es hecha una consulta de acuerdo con la integración a ser ejecutada y relacionada a las informaciones para integración entre los sistemas, siendo:
| Tablas | Descripción |
|---|---|
| CONEXAO_INTEGRACAO | Esta tabla es responsable por configurar las conexiones de acceso del integrador a los proveedores o receptores de datos. |
| INTEGRACOES | Las integraciones son definidas con determinado sistema y sus particularidades. |
| CAMPOS_INTEGRACAO | Descripto todos los campos que formarán la integración y sus equivalentes, en el sistema receptor o proveedor. |
| DEPENDENCIAS | Cuáles son las dependencias de una determinada integración. Es decir, los valores originados en otras tablas del sistema. |
| REGLAS |
Las reglas para ejecución de la integración, cuando vinculadas a los campos, serán ejecutadas para ajustar las informaciones de acuerdo con el sistema, receptor o base de datos del cliente en el CRM que está preparado para recibir. |
Para poder ajustar las informaciones de la integración conforme el sistema está preparado para recibir, es necesario cargar las reglas disponibles. La mayoría de las reglas que son ejecutadas son parte del integrador, construidas en código integrado y cargadas por el integrador en tiempo de ejecución.
Para cada tipo de integración un código de regla diferente es cargado, ya que se comportan de manera diferente para cada tipo. Hay casos en los que es necesario crear reglas específicas para una integración, es decir, personalizar reglas para los clientes para suministrar un proceso o ajustar una información, permitiendo que el sistema receptor o la base de datos del CRM comprenda la información y la procese correctamente. Así que es necesaria una acción del desarrollo.
Importante
Para que la regla sea ejecutada en un campo de la integración, es necesario que esté registrada en la tabla REGLAS, con las informaciones relevantes.
Con las definiciones del Integrador presentadas, consulte las instrucciones para crear las integraciones GET/INFO y SET.
En los casos de integraciones vía web service, el integrador genera un registro de envío y recepción de XML, denominado de la siguiente manera: base_empresa_requisição.xml e base_empresa_resposta.xml, donde base es la base del cliente igual al parámetro base_crm y empresa es la id de la empresa cliente, igual al parámetro empresa_id o empresa_filial_id.
Para cada integración realizada con estado de error, el Integrador intentará enviar un mensaje de e-mail al correo electrónico general del cliente con el contenido del registro de errores generado por la integración, los archivos XML de envío y recepción, si la integración es por servicio web y los mensajes retornados por la integración.
Configuración del archivo de conexión
Toda integración tiene como prerrequisito una conexión, que es configurada en un archivo para ser cargado por el Integrador. Este archivo es interpretado junto con el código fuente del integrador y es importante observar los caracteres como: paréntesis, comas y comillas.
Para configurar la conexión, el archivo debe estar en el directorio de configuraciones del Integrador, con el nombre NOME-DA-BASE.connection. Este archivo debe contener un array con los datos de conexión, donde cada índice del array representa una conexión.
Ejemplo:
En el ejemplo, se hará referencia al índice de la conexión, resaltado en rojo, más adelante en la tabla CONEXAO_INTEGRACAO. El índice DEFAULT es obligatorio y debe existir en toda configuración, pues representa la conexión con el propio CRM y debe contener los datos de conexión del CRM. Cada nueva conexión configurada debe tener su propio índice.
Hay tres tipos de conexión posibles para el Integrador: Base de Datos, Web Service y API (web, http). Cada una de las conexiones tiene sus propios parámetros y un layout para configurar los datos de la conexión, sin embargo, para la paginación, todas las conexiones utilizan la misma estructura para la configuración. Los layouts para configurar la conexión de cada tipo de conexión son:
Base
Serán utilizados diferentes campos para cada conexión, es recomendable investigar para encontrar la mejor manera de conectarse.
- dbname: nombre de la base;
- user: usuario de conexión a la base de datos;
- password: contraseña de conexión;
- host: servidor de la conexión;
- driver: la herramienta de conexión que el Integrador utilizará, difiere de una base a otra y hay un número limitado de drivers para la conexión, siendo ellos: ibm_db2 para IBM-db, pdo_mysql para MySQL, pdo_pgsql para PostgreSQL, pdo_sqlite para SQLite. El integrador utiliza una herramienta para crear las conexiones con los drivers y, caso necesite ajustes específicos, puede acceder a la documentación de la herramienta, que trae los pasos para la configuración.
- charset: encoding para la conexión, estándar UTF-8;
- dsn: un texto de conexión personalizado;
- pdo: funciona como el driver, para conexiones personalizadas.
Para obtener más información, acceda a la documentación oficial sobre el método de conexión.
Web service
Conexiones web service tienen los mismos campos, algunos de los cuales son obligatorios:
- host: servidor de la conexión, obligatorio;
- port: puerta de la conexión;
- charset: encoding para la conexión, estándar UTF-8;
- header: array con datos de encabezado para la solicitud, algunos web services necesitan de enviar autenticación por encabezado;
- body: un array con una plantilla de cuerpo estándar para las solicitudes, en lo que el índice debe contener un valor "#BODY#", que será reemplazado por el cuerpo de la requisición generada por el Integrador y funciona como si fuera una cubierta de envío para todas las requisiciones.
API
Las conexiones vía API son utilizadas para cargar valores a través de la web, pero sin la necesidad de un protocolo WSDL. Las conexiones vía API solo aceptan transacciones de contenido JSON, es decir, si la API consumida por el integrador no devuelve valores JSON, la integración no será hecha.
- host: servidor de la conexión, obligatorio;
- port: puerta de la conexión;
- method: cual es el método de envío del mensaje para la API, el estándar es GET y los tipos admitidos son: GET, POST, PUT, PATCH y DELETE;
- header: un array con los campos de headers estándar para la integración puede ser utilizado para rellenar campos de authorization, por ejemplo. Este campo se fusiona con el campo establecido en la columna CONSULTA para las integraciones GET y INFO.
Paginación
La estructura de paginación pasa por un índice de configuración, definido como pagination, que debe estar junto a las configuraciones de la conexión.
El índice es compuesto por tres parámetros que definen el formato en el que se realiza la paginación, son ellos:
- pager: define una clave de registro que esté presente en el resultado de la integración como un paginador. De esta manera, la integración utilizará este índice para recuperar los valores de las páginas, para pasarlos a la siguiente solicitud. Por ejemplo: si la búsqueda de datos devuelve una clave llamada paginaAtual con el número de la página, simplemente configure el pager en paginaAtual que la integración utilizará este valor como paginador para la próxima solicitud;
- endpoint: define como la integración reconoce cuando las páginas agotaron o cual fue la última página. Para esta configuración, es posible definir un índice presente en el resultado de la integración como validador, para que la integración interprete si las páginas se han agotado o utilizar palabras clave que definan este validador automáticamente. Si se utiliza un índice como validador, la integración validará los valores: OK - OK - S - NULL como finalizado. Cualquier valor distinto a estos será interpretado como no finalizado. Si se utilizan palabras clave, pueden ser:
- none: la integración no se paginará, ya que se entiende que solo hay una página;
- empty: la integración solo entenderá que las páginas se han acabado cuando una de las páginas requeridas retornar un resultado vacío, sin registros.
- type: define qué cálculo se utilizará para cargar los números de las páginas. Hay tres tipos de cálculos posibles:
- NU: cálculo numérico simple con la fórmula: Pagina = Pagina + 1;
- QR: cálculo de la cantidad de registros con la fórmula: Pagina = count (registros);
- RG: cálculo de registro específico con la fórmula: Pagina = UltimoRegistro[pager]. Este cálculo utiliza el pager obligatoriamente.
Si ninguna configuración de paginación esté definida en las configuraciones de conexión, el integrador utilizará la siguiente configuración de forma predeterminada:
Importante
Las bases aprobados para conexión vía Base son:
- Oracle;
- Servidor SQL;
- MySQL;
- PostgreSQL;
- DB2;
- Caché DB.
English
Español
