En BI Builder puedes trabajar con bases de datos externas MySQL y PostgreSQL. Esto resulta útil si parte de los datos se almacena por separado: en una tienda online, un servicio interno u otra base de datos corporativa.

Por ejemplo, si una empresa almacena los pedidos en PostgreSQL. Después de conectar la base de datos a BI Builder, puedes seleccionar una tabla con ventas, crear un conjunto de datos y generar un gráfico basado en el importe de los pedidos. Así, el responsable podrá ver la dinámica de ventas en un solo informe junto con los datos de Bitrix24.

Qué debes preparar para conectar una base de datos

Ve a BI Builder > Analytics hub > Conexiones > Crear y selecciona MySQL o PostgreSQL.

Los siguientes pasos dependen de la versión de Bitrix24.

Bitrix24 en la nube. La base de datos externa se conecta mediante una aplicación del lado del servidor. Primero debes configurar la aplicación siguiendo las instrucciones y luego volver a la creación de la conexión.

La aplicación actuará como intermediaria entre Bitrix24 y la base de datos: recibirá una solicitud, se conectará a MySQL o PostgreSQL, leerá la lista de tablas y la estructura de los campos, y después transferirá los datos a BI Builder.
Aplicación local del lado del servidor sin interfaz de usuario

Para configurar la aplicación, prepara lo siguiente:

• Un servidor: una computadora o máquina virtual donde se alojará la aplicación. Allí se almacenarán los archivos y se ejecutará la aplicación. Por ejemplo, puedes utilizar un servidor virtual de la empresa o un servidor independiente dentro de tu infraestructura.
• Docker y Docker Compose: instálalos en el servidor para ejecutar la aplicación en un contenedor. Docker crea un entorno aislado para la aplicación y Docker Compose ayuda a iniciarla con la configuración necesaria. Consulta la documentación de Docker e instala la versión correspondiente a tu sistema operativo:
  Docker Desktop on Windows
  Docker Desktop on Linux
  Docker Desktop on Mac
• Archivos para compilar la aplicación del lado del servidor. Descarga los archivos del repositorio y súbelos al servidor.
  Bitrix24 BI Connector Extension
• Acceso a una base de datos MySQL o PostgreSQL externa. Es necesario para que la aplicación pueda conectarse a la base y leer los datos. Prepara la dirección de la base de datos, el puerto, el nombre de la base, el nombre de usuario y la contraseña de un usuario con permisos de lectura de tablas.
• Una dirección HTTPS pública para la aplicación del servidor. Es necesaria para que Bitrix24 pueda comunicarse con ella. Una dirección como localhost no sirve porque solo está disponible dentro del propio servidor. Utiliza una dirección como https://bi-connector.company.com.

Versión local de Bitrix24. No es necesario configurar una aplicación del lado del servidor. Después de seleccionar MySQL o PostgreSQL, puedes especificar directamente los parámetros de conexión y empezar a trabajar con la base de datos. Antes de configurar la conexión, prepara la dirección de la base, el puerto, el nombre de la base de datos, el nombre de usuario y la contraseña. Asegúrate de que el servidor de Bitrix24 pueda acceder a la base de datos a través de la red.

Comprueba los nombres de las tablas y los campos en la base de datos externa. Deben cumplir dos reglas:

• Los nombres de las tablas deben comenzar con una letra latina y contener únicamente letras latinas minúsculas, números y guiones bajos. Por ejemplo: users, order_items, customer_data_2024.
• Los nombres de los campos deben comenzar con una letra latina y contener únicamente letras latinas mayúsculas, números y guiones bajos. Por ejemplo: ID, USER_ID, ORDER_DATE.

Cómo instalar la aplicación en el servidor

La aplicación del lado del servidor conecta Bitrix24 con la base de datos externa. Realiza cuatro acciones:

• comprueba la conexión con la base de datos,
• obtiene la lista de tablas,
• obtiene la estructura de la tabla y los tipos de campos,
• transfiere los datos a BI Builder.

El usuario no necesita ejecutar estas acciones manualmente. Se realizan automáticamente cuando se comprueba la conexión, se selecciona una tabla o se crea un informe. Para instalar la aplicación, sigue estos seis pasos:

1. Ve a la carpeta de la aplicación en el servidor. Todos los comandos deben ejecutarse en el servidor donde funcionará la aplicación. Abre la terminal y ve a la carpeta con los archivos de la aplicación. Comprueba que la carpeta contiene el archivo docker-compose.yml. Si aparece en la lista, significa que estás en la carpeta correcta. Los comandos de Docker Compose deben ejecutarse desde ella.

2. Crea el archivo de configuración. En la carpeta de la aplicación hay un archivo .env.example. Es un ejemplo de configuración. A partir de él debes crear el archivo operativo .env. Este archivo almacena la configuración de la aplicación: dirección pública, parámetros de registro, configuración de caché y datos de la aplicación local de Bitrix24. Ejecuta el siguiente comando:

 cp .env.example .env 

3. Especifica la dirección pública de la aplicación. Abre el archivo .env e indica la dirección que Bitrix24 utilizará para acceder a la aplicación del servidor. Ejemplo de configuración:

 APP_DOMAIN=https://bi-connector.company.com
APP_ENV=production LOG_LEVEL=INFO 

APP_DOMAIN es la dirección HTTPS pública de la aplicación. Debe estar accesible desde Internet para que Bitrix24 en la nube pueda enviar solicitudes a la aplicación. Una dirección como localhost no sirve, ya que solo está disponible dentro del servidor o del contenedor. Por ejemplo, si la aplicación se ejecuta en un servidor mediante Docker y se accede a ella desde el exterior a través de un dominio, el esquema puede ser el siguiente:

 https://bi-connector.company.com → servidor con la aplicación → contenedor Docker 

Utiliza un certificado SSL válido. Bitrix24 debe poder abrir la dirección de la aplicación mediante HTTPS sin advertencias de seguridad.

4. Comprueba la red de Docker. La aplicación utiliza la red externa shared_db_network. Es necesaria para que la aplicación pueda acceder a bases de datos que se ejecutan en Docker o que están disponibles a través de una red compartida. Si inicias la aplicación con el comando make start, la red se creará automáticamente. Si ejecutas los contenedores directamente mediante Docker Compose, crea la red manualmente:

 docker network create shared_db_network 

Si Docker responde que la red ya existe, no es un error. Significa que fue creada anteriormente.

5. Inicia la aplicación. Compila e inicia la aplicación en el servidor. Ejecuta los siguientes comandos:

 make build make start 

El comando make build crea la imagen Docker de la aplicación. El comando make start inicia el contenedor.

6. Comprueba que la aplicación se ha iniciado. Ejecuta el siguiente comando para ver el estado de los contenedores:

 docker compose ps 

Si la aplicación se está ejecutando, el estado del contenedor mostrará el valor Up. Después, comprueba que la aplicación responde en la dirección pública:

 curl -i https://bi-connector.company.com/

Si la aplicación responde, puedes pasar a la creación de una aplicación local en Bitrix24. La respuesta puede ser un mensaje de error sin acción, por ejemplo: {"error":"Unknown action: "}. Esta respuesta aparece cuando la solicitud se envía sin un parámetro de acción. Las solicitudes de trabajo serán enviadas automáticamente por Bitrix24 al comprobar la conexión, seleccionar una tabla o crear un conjunto de datos.

Cómo crear una aplicación local en Bitrix24

Ve a Aplicaciones > Recursos para desarrolladores > Otro > Aplicación local. Completa los siguientes parámetros:

• Aplicación local: selecciona el tipo Servidor. Este tipo es adecuado para aplicaciones que se ejecutan en un servidor e intercambian datos con Bitrix24 mediante REST API.
• Ruta de su controlador: dirección HTTPS pública de la aplicación del servidor. Bitrix24 enviará solicitudes a la aplicación mediante esta dirección. Por ejemplo: https://bi-connector.company.com/.
• Ruta de instalación inicial: dirección del archivo de instalación de la aplicación. Se utiliza durante la instalación de la aplicación local en Bitrix24. Por ejemplo: https://bi-connector.company.com/install.php.
• Solo script: activa esta opción. Es necesaria para una aplicación que no tiene una interfaz independiente en Bitrix24. El usuario no abrirá la aplicación como una página independiente: BI Builder se comunicará con ella automáticamente mediante REST API.
• Asignar permisos: añade el permiso Conector analítico BI (biconnector). Este permiso es necesario para que la aplicación pueda trabajar con las fuentes de datos de BI Builder.

Cuando completes los parámetros, haz clic en Guardar.

Después de guardar, Bitrix24 mostrará los campos de servicio:

• ID de la aplicación (client_id): identificador de la aplicación local. La aplicación del servidor lo necesita para comunicarse con Bitrix24.
• Clave de la aplicación (client_secret): clave secreta de la aplicación local. Confirma que las solicitudes provienen de tu aplicación.

Copia los valores de client_id y client_secret. Vuelve al servidor y completa los parámetros en el archivo .env:

 BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID=tu_client_id BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET=tu_client_secret BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnector 

Guarda el archivo .env con codificación UTF-8 sin caracteres adicionales al inicio del archivo. De lo contrario, la aplicación podría no leer la configuración. Después, reinicia la aplicación en el servidor:

 docker compose restart app 

Vuelve a la ficha de la aplicación local en Bitrix24 y haz clic en Reinstalar. Después de esto, podrás crear una conexión con la base de datos en BI Builder.

Cómo conectar una base de datos externa

Ve a BI Builder > Analytics hub > Conexiones > Crear. Selecciona una fuente de datos: MySQL Database Connector o PostgreSQL Database Connector.

Completa los parámetros de conexión:

• Nombre (Name): especifica un nombre descriptivo para la conexión. Se mostrará en la lista de conexiones de BI Builder.
• Host: dirección del servidor donde se encuentra la base de datos. No utilices localhost si la base de datos está en otro servidor, ya que la aplicación buscará la base dentro de su propio entorno. Por ejemplo, utiliza db.company.local, 10.10.20.15 o el nombre del contenedor si la base de datos se ejecuta en Docker y está conectada a la misma red.
• Port: puerto de conexión a la base de datos. PostgreSQL utiliza normalmente el puerto 5432 y MySQL el puerto 3306. Si tu infraestructura utiliza otro puerto, especifícalo.
• Database: nombre de la base de datos desde la que se obtendrán los datos para los informes.
• Username: nombre de usuario de la base de datos.
• Password: contraseña del usuario de la base de datos.

Cuando completes los parámetros, haz clic en Comprobar conexión (Check connection). Si la comprobación es correcta, haz clic en Crear (Create). Después de crear la conexión, Bitrix24 propondrá crear una tabla a partir de la base de datos externa. Haz clic en Crear tabla.

Cómo crear una tabla y un conjunto de datos

En el formulario de creación de tablas, selecciona la Tabla necesaria de la base de datos externa. A la derecha aparecerá la sección Vista previa de datos (Table data). Allí puedes comprobar qué campos y registros ha obtenido BI Builder de la base de datos externa. En el modo de vista previa solo se muestra una parte de los datos.

En el bloque Propiedades de la tabla (Table parameters), comprueba el nombre y la descripción. El nombre se completa automáticamente a partir del nombre de la tabla de la base de datos externa, pero puedes modificarlo manualmente antes de crear la tabla.

En el bloque Configuración de las columnas de la tabla (Table columns), comprueba si Bitrix24 ha identificado correctamente los campos y los tipos de datos. Si todo es correcto, haz clic en Crear (Create).
Configurar las columnas del conjunto de datos
Configurar formatos y tipos de datos

Después de esto, Bitrix24 mostrará un mensaje indicando que la tabla se ha creado correctamente. Haz clic en Crear conjunto de datos (Create dataset). El conjunto de datos es necesario para utilizar la información en informes y gráficos de BI Builder.

Después de crear el conjunto de datos, podrás generar un gráfico y añadirlo a un dashboard. Por ejemplo, a partir de una tabla puedes crear un conjunto de datos de pedidos, generar un gráfico basado en el importe de las ventas y añadirlo al informe de un responsable.
Crear paneles de control en BI Builder