No Criador de BI, é possível trabalhar com bancos de dados externos MySQL e PostgreSQL. Isso é útil quando parte dos dados é armazenada separadamente, por exemplo, em uma loja virtual, serviço interno ou outra base corporativa.

Por exemplo, se a empresa armazena pedidos em PostgreSQL. Após conectar o banco ao Criador de BI, é possível selecionar a tabela com as vendas, criar um conjunto de dados e construir um gráfico com o total dos pedidos. Assim, o gestor verá a dinâmica de vendas em um único relatório, junto com os dados do Bitrix24.

O que é necessário preparar para conectar o banco de dados

Acesse a seção Criador de BI > Hub de análises > Conexões > Criar e selecione MySQL ou PostgreSQL.

As etapas seguintes dependem da versão do Bitrix24.

Bitrix24 na nuvem. O banco de dados externo é conectado por meio de um aplicativo de servidor. Primeiro, é necessário configurar o aplicativo seguindo as instruções e, em seguida, retornar à criação da conexão.

O aplicativo atua como ponte entre o Bitrix24 e o banco de dados: recebe a solicitação, conecta-se ao MySQL ou PostgreSQL, lê a lista de tabelas e a estrutura dos campos e, então, transmite os dados ao Criador de BI.
Aplicativo local de servidor sem interface de usuário

Para configurar o aplicativo, prepare:

• Servidor: computador ou máquina virtual para hospedar o aplicativo. Nele, os arquivos serão armazenados e o aplicativo será executado. Por exemplo, é possível usar um servidor virtual da empresa ou um servidor dedicado em sua infraestrutura.
• Docker e Docker Compose: instale no servidor para executar o aplicativo em contêiner. O Docker cria um ambiente isolado para o aplicativo, e o Docker Compose ajuda a executá-lo com as configurações necessárias. Consulte a documentação do Docker e instale a versão adequada para seu sistema operacional:
  Docker Desktop no Windows
  Docker Desktop no Linux
  Docker Desktop no Mac
• Arquivos para compilar o aplicativo de servidor. Baixe os arquivos do repositório e carregue-os no servidor.
  Extensão Conector de BI do Bitrix24
• Acesso ao banco externo MySQL ou PostgreSQL: necessário para que o aplicativo possa se conectar ao banco e ler os dados. Prepare o endereço do banco, porta, nome do banco, login e senha de um usuário com permissões de leitura nas tabelas.
• Endereço HTTPS público para o aplicativo de servidor: necessário para que o Bitrix24 possa acessar o aplicativo. Endereços como localhost não funcionarão, pois estão disponíveis apenas internamente no servidor. Use um endereço como https://bi-connector.empresa.com.br.

Versão local (on-premise) do Bitrix24. Não é necessário configurar o aplicativo de servidor. Após selecionar MySQL ou PostgreSQL, você pode informar diretamente os parâmetros de conexão e trabalhar com o banco de dados. Antes da configuração, prepare o endereço do banco, porta, nome do banco, login e senha do usuário. Garanta que o servidor do Bitrix24 tenha visibilidade de rede para o banco.

Verifique os nomes das tabelas e campos no banco externo. Eles devem seguir duas regras:

• Os nomes das tabelas devem começar com uma letra latina e conter apenas letras latinas minúsculas, números e sublinhado. Exemplo: users, order_items, customer_data_2024.
• Os nomes dos campos devem começar com uma letra latina e conter apenas letras latinas maiúsculas, números e sublinhado. Exemplo: ID, USER_ID, ORDER_DATE.

Como instalar o aplicativo no servidor

O aplicativo de servidor faz a ponte entre o Bitrix24 e o banco externo. Ele executa quatro ações:

• verifica a conexão com o banco,
• obtém a lista de tabelas,
• obtém a estrutura da tabela e os tipos de campos,
• transmite os dados para o Criador de BI.

O usuário não precisa executar essas ações manualmente. Elas ocorrem automaticamente quando o usuário testa a conexão, seleciona uma tabela ou cria um relatório. Para instalar o aplicativo, siga seis etapas:

1. Acesse a pasta do aplicativo no servidor. Todos os comandos devem ser executados no servidor onde o aplicativo será executado. Abra o terminal e navegue até a pasta com os arquivos do aplicativo. Verifique se o arquivo docker-compose.yml está presente. Se ele estiver listado, você está na pasta correta. Os comandos do Docker Compose devem ser executados a partir dela.

2. Crie o arquivo de configuração. Na pasta do aplicativo, há um arquivo .env.example. Este é um exemplo de configuração. Com base nele, crie o arquivo de trabalho .env. Este arquivo armazena as configurações do aplicativo: endereço público, parâmetros de registro, configurações de cache e dados do aplicativo local do Bitrix24. Execute o comando:

 cp .env.example .env 

3. Informe o endereço público do aplicativo. Abra o arquivo .env e insira o endereço pelo qual o Bitrix24 acessará o aplicativo de servidor. Exemplo de configuração:

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

APP_DOMAIN: endereço HTTPS público do aplicativo. Ele deve estar acessível pela internet para que o Bitrix24 na nuvem possa enviar solicitações ao aplicativo. Endereços como localhost não funcionarão, pois estão disponíveis apenas dentro do servidor ou contêiner. Por exemplo, se o aplicativo estiver em um servidor com Docker e for acessível externamente por um domínio, o esquema pode ser:

 https://bi-connector.empresa.com.br → servidor com aplicativo → contêiner Docker 

Use um certificado SSL válido. O Bitrix24 deve acessar o endereço do aplicativo via HTTPS sem avisos de segurança.

4. Verifique a rede Docker. O aplicativo usa a rede externa shared_db_network. Ela é necessária para que o aplicativo possa acessar bancos de dados que estejam em contêineres Docker ou disponíveis pela rede compartilhada. Se você iniciar o aplicativo com o comando make start, a rede será criada automaticamente. Se iniciar os contêineres diretamente pelo Docker Compose, crie a rede manualmente:

 docker network create shared_db_network 

Se o Docker informar que a rede já existe, isso não é um erro. Significa que ela foi criada anteriormente.

5. Inicie o aplicativo. Compile e execute o aplicativo no servidor. Execute o comando:

 make build make start 

O comando make build compila a imagem Docker do aplicativo. O comando make start inicia o contêiner.

6. Verifique se o aplicativo foi iniciado. Execute o comando para ver o status dos contêineres:

 docker compose ps 

Se o aplicativo estiver em execução, o status do contêiner será Up. Em seguida, verifique se o aplicativo responde ao endereço público:

 curl -i https://bi-connector.empresa.com.br/ 

Se o aplicativo responder, você pode prosseguir para criar o aplicativo local no Bitrix24. A resposta pode parecer uma mensagem de erro sem ação, como: {"error":"Unknown action: "}. Essa resposta aparece quando a solicitação é enviada sem o parâmetro de ação. As solicitações de trabalho serão enviadas pelo Bitrix24: ao testar a conexão, selecionar tabelas e criar conjuntos de dados.

Como criar um aplicativo local no Bitrix24

Acesse a seção Aplicativos > Recursos para desenvolvedores > Outro > Aplicativo local. Preencha os parâmetros:

• Aplicativo local: selecione o tipo Servidor. Esse tipo é adequado para um aplicativo que roda no servidor e troca dados com o Bitrix24 via REST API.
• Seu caminho do manipulador: endereço HTTPS público do aplicativo de servidor. Por esse endereço, o Bitrix24 enviará solicitações ao aplicativo. Exemplo: https://bi-connector.empresa.com.br/.
• Caminho de instalação inicial: endereço do arquivo de instalação do aplicativo. Ele é chamado durante a instalação do aplicativo local no Bitrix24. Exemplo: https://bi-connector.empresa.com.br/install.php.
• Apenas script (sem interface de usuário): ative esta opção. Ela é necessária para aplicativos sem interface própria no Bitrix24. O usuário não abrirá o aplicativo como uma página: o Criador de BI o acessará automaticamente via REST API.
• Atribuir permissões: adicione a permissão Conector de análise BI (biconnector). Essa permissão é necessária para que o aplicativo possa trabalhar com as fontes de dados do Criador de BI.

Após preencher os parâmetros, clique em Salvar.

Após salvar, o Bitrix24 exibirá os campos de serviço:

• Código do aplicativo (client_id): identificador do aplicativo local. Ele é necessário para que o aplicativo de servidor acesse o Bitrix24.
• Chave do aplicativo (client_secret): chave secreta do aplicativo local. Ela confirma que as solicitações vêm do seu aplicativo.

Copie o client_id e o client_secret. Volte ao servidor e preencha os parâmetros no arquivo .env:

 BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID=seu_client_id BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET=seu_client_secret BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnector 

Salve o arquivo .env com codificação UTF-8, sem caracteres adicionais no início do arquivo. Caso contrário, o aplicativo pode não ler as configurações. Em seguida, reinicie o aplicativo no servidor:

 docker compose restart app 

Volte à página do aplicativo local no Bitrix24 e clique em Reinstalar. Depois disso, será possível estabelecer a conexão com o banco de dados no Criador de BI.

Como conectar um banco de dados externo

Acesse a seção Criador de BI > Hub de análises > Conexões > Criar. Selecione a fonte de dados: MySQL ou PostgreSQL.

Preencha os parâmetros de conexão:

• Nome: informe um nome claro para a conexão. Ele será exibido na lista de conexões do Criador de BI.
• Host: endereço do servidor onde o banco de dados está localizado. Não use localhost se o banco estiver em outro servidor: o aplicativo procurará o banco dentro de seu próprio ambiente. Por exemplo, informe db.empresa.local, 10.10.20.15 ou o nome do contêiner, se o banco estiver em Docker e conectado à mesma rede.
• Porta: porta de conexão com o banco de dados. Para PostgreSQL, usa-se a porta 5432; para MySQL, a 3306. Se sua infraestrutura usar outra porta, informe-a.
• Banco de dados: nome do banco do qual os dados serão obtidos para os relatórios.
• Usuário: login do usuário do banco de dados.
• Senha: senha do usuário do banco de dados.

Após preencher os parâmetros, clique em Testar conexão. Se o teste for bem-sucedido, clique em Criar. Após criar a conexão, o Bitrix24 oferecerá a criação de uma tabela a partir do banco externo. Clique em Criar tabela.

Como criar uma tabela e um conjunto de dados

No formulário de criação da tabela, selecione a Tabela desejada no banco externo. À direita, aparecerá uma pré-visualização dos Dados da tabela. Nela, é possível verificar quais campos e linhas o Criador de BI obteve do banco externo. No modo de pré-visualização, apenas uma parte dos dados é exibida.

No bloco Parâmetros da tabela, verifique o nome e a descrição. O nome é preenchido automaticamente com o nome da tabela no banco externo, mas, se necessário, pode ser alterado manualmente antes da criação da tabela.

No bloco Colunas da tabela, verifique se o Bitrix24 identificou corretamente os campos e seus tipos de dados. Se os campos e tipos estiverem corretos, clique em Salvar.
Configurar colunas do conjunto de dados
Configurar formatos e tipos de dados para importar um arquivo CSV

Em seguida, o Bitrix24 exibirá uma mensagem informando que a tabela foi criada. Clique em Criar conjunto de dados. O conjunto de dados é necessário para usar as informações em relatórios e gráficos do Criador de BI.

Após criar o conjunto de dados, é possível construir um gráfico e adicioná-lo a um painel. Por exemplo, com base na tabela, é possível criar um conjunto de dados de pedidos, construir um gráfico com o total de vendas e adicioná-lo ao relatório do gestor.
Criar painéis no Criador de BI