Nel Generatore BI puoi lavorare con database esterni MySQL e PostgreSQL. È utile se una parte dei dati viene archiviata separatamente: in un online store, in un servizio interno o in un altro database aziendale.

Ad esempio, un’azienda può archiviare gli ordini in PostgreSQL. Dopo aver collegato il database al Generatore BI, puoi selezionare la tabella delle vendite, creare un dataset e enerare un grafico basato sull’importo degli ordini. In questo modo il responsabile potrà visualizzare l’andamento delle vendite in un’unica dashboard insieme ai dati di Bitrix24.

Cosa preparare per collegare il database

Vai in Generatore BI > Analytics hub > Connessioni > Crea e seleziona MySQL oppure PostgreSQL.

Le operazioni successive dipendono dalla versione di Bitrix24.

Bitrix24 cloud. Il database esterno viene collegato tramite un’applicazione server. Prima configura l’applicazione seguendo le istruzioni, poi torna alla creazione della connessione.

L’applicazione collegherà Bitrix24 e il database: riceverà la richiesta, si collegherà a MySQL o PostgreSQL, leggerà l’elenco delle tabelle e la struttura dei campi, quindi trasferirà i dati al Generatore BI.
Applicazione locale server-side senza interfaccia utente

Per configurare l’applicazione, prepara:

• Server: un computer o una macchina virtuale per ospitare l’applicazione. Qui verranno archiviati i file e verrà eseguita l’applicazione. Ad esempio, puoi utilizzare un server virtuale aziendale o un server separato nella tua infrastruttura.
• Docker e Docker Compose: installali sul server per eseguire l’applicazione nel container. Docker crea un ambiente isolato per l’applicazione, mentre Docker Compose aiuta ad avviarla con le impostazioni necessarie. Consulta la documentazione Docker e installa la versione per il tuo sistema operativo:
  Docker Desktop on Windows
  Docker Desktop on Linux
  Docker Desktop on Mac
• File per compilare l’applicazione server. Scarica i file dal repository e caricali sul server.
  Bitrix24 BI Connector Extension
• Accesso al database esterno MySQL o PostgreSQL: necessario affinché l’applicazione possa collegarsi al database e leggere i dati. Prepara l'indirizzo del database, la porta, il nome del database, il login e la password dell’utente con autorizzazioni di lettura delle tabelle.
• Indirizzo HTTPS pubblico per l’applicazione server: necessario affinché Bitrix24 possa accedere all’applicazione. Un indirizzo come localhost non è adatto perché è disponibile solo all’interno del server. Utilizza un indirizzo come https://bi-connector.company.com.

Versione On-Premise di Bitrix24. Non è necessario configurare l’applicazione server. Dopo aver selezionato MySQL o PostgreSQL, puoi specificare subito i parametri di connessione e lavorare con il database. Prima della configurazione prepara l'indirizzo del database, la porta, il nome del database, il login e la password dell’utente. Assicurati che il server Bitrix24 possa raggiungere il database tramite rete.

Controlla i nomi delle tabelle e dei campi nel database esterno. Devono rispettare due regole:

• I nomi delle tabelle devono iniziare con una lettera latina e contenere solo lettere latine minuscole, numeri e underscore. Ad esempio: users, order_items, customer_data_2024.
• I nomi dei campi devono iniziare con una lettera latina e contenere solo lettere latine maiuscole, numeri e underscore. Ad esempio: ID, USER_ID, ORDER_DATE.

Come installare l’applicazione sul server

L’applicazione server collega Bitrix24 e il database esterno. Esegue quattro operazioni:

• verifica la connessione al database,
• ottiene l’elenco delle tabelle,
• ottiene la struttura della tabella e i tipi di campo,
• trasferisce i dati al Generatore BI.

L’utente non deve avviare queste operazioni manualmente. Vengono eseguite automaticamente quando l’utente verifica la connessione, seleziona una tabella o crea una dashboard. Per installare l’applicazione, segui questi sei passaggi:

1. Vai nella cartella dell’applicazione sul server. Tutti i comandi devono essere eseguiti sul server in cui verrà eseguita l’applicazione. Apri il terminale e vai nella cartella con i file dell’applicazione. Verifica che nella cartella sia presente il file docker-compose.yml. Se compare nell’elenco, significa che ti trovi nella cartella corretta. I comandi Docker Compose devono essere eseguiti proprio da questa cartella.

2. Crea il file delle impostazioni. Nella cartella dell’applicazione è presente il file .env.example. È un esempio di configurazione. In base a questo file devi creare il file operativo .env. Il file contiene le impostazioni dell’applicazione: indirizzo pubblico, parametri di logging, impostazioni della cache e dati dell’applicazione locale Bitrix24. Esegui il comando:

 cp .env.example .env 

3. Specifica l’indirizzo pubblico dell’applicazione. Apri il file .env e specifica l’indirizzo tramite cui Bitrix24 accederà all’applicazione server. Esempio di configurazione:

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

APP_DOMAIN è l’indirizzo HTTPS pubblico dell’applicazione. Deve essere accessibile da internet affinché Bitrix24 cloud possa inviare richieste all’applicazione. Un indirizzo come localhost non è adatto. Questo tipo di indirizzo è disponibile solo all’interno del server o del container. Ad esempio, se l’applicazione viene eseguita su un server in Docker e all’esterno è disponibile tramite dominio, lo schema può essere il seguente:

 https://bi-connector.company.com → server con l’applicazione → container Docker 

Utilizza un certificato SSL valido. Bitrix24 deve poter aprire l’indirizzo dell’applicazione tramite HTTPS senza avvisi di sicurezza.

4. Controlla la rete Docker. L’applicazione utilizza la rete esterna shared_db_network. Serve affinché l’applicazione possa accedere ai database eseguiti in Docker o disponibili tramite rete condivisa. Se avvii l’applicazione con il comando make start, la rete verrà creata automaticamente. Se avvii i container direttamente tramite Docker Compose, crea la rete manualmente:

 docker network create shared_db_network 

Se Docker risponde che la rete esiste già, non si tratta di un errore. Significa che è stata creata in precedenza.

5. Avvia l’applicazione. Compila e avvia l’applicazione sul server. Esegui il comando:

 make build make start 

Il comando make build crea l’immagine Docker dell’applicazione. Il comando make start avvia il container.

6. Verifica che l’applicazione sia stata avviata. Esegui il comando per controllare lo stato dei container:

 docker compose ps 

Se l’applicazione è in esecuzione, nello stato del container verrà visualizzato il valore Up. Successivamente verifica che l’applicazione risponda tramite indirizzo pubblico:

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

Se l’applicazione risponde, puoi passare alla creazione dell’applicazione locale in Bitrix24. La risposta può apparire come un messaggio di errore senza azione, ad esempio: {"error":"Unknown action: "}. Questa risposta compare quando la richiesta viene inviata senza parametro action. Le richieste operative verranno inviate da Bitrix24 durante la verifica della connessione, la selezione della tabella e la creazione del dataset.

Come creare un’applicazione locale in Bitrix24

Vai in Applicazioni > Risorse per sviluppatori > Altro > Applicazione locale. Compila i parametri:

• Applicazione locale: specifica il tipo Server. Questo tipo è adatto per un’applicazione eseguita sul server che scambia dati con Bitrix24 tramite REST API.
• Il tuo percorso gestore: indirizzo HTTPS pubblico dell’applicazione server. Tramite questo indirizzo Bitrix24 invierà le richieste all’applicazione. Ad esempio: https://bi-connector.company.com/.
• Percorso di installazione iniziale: indirizzo del file di installazione dell’applicazione. Viene utilizzato durante l’installazione dell’applicazione locale in Bitrix24. Ad esempio: https://bi-connector.company.com/install.php.
• Solo script: attiva l’opzione. È necessaria per un’applicazione senza interfaccia separata in Bitrix24. L’utente non aprirà l’applicazione come pagina: il Generatore BI vi accederà automaticamente tramite REST API.
• Assegna autorizzazioni: aggiungi il permesso Connettore innativo BI (biconnector). Questo permesso è necessario affinché l’applicazione possa lavorare con le origini dati del Generatore BI.

Dopo aver compilato i parametri, fai clic su Salva.

Dopo il salvataggio, Bitrix24 mostrerà i campi di servizio:

• ID applicazione (client_id): identificatore dell’applicazione locale. È necessario affinché l’applicazione server possa accedere a Bitrix24.
• Chiave applicazione (client_secret): chiave segreta dell’applicazione locale. Conferma che le richieste provengano dalla tua applicazione.

Copia client_id e client_secret. Torna sul server e compila i parametri nel file .env:

 BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID=your_client_id BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET=your_client_secret BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnector 

Salva il file .env con codifica UTF-8 senza simboli aggiuntivi all’inizio del file. In caso contrario, l’applicazione potrebbe non leggere le impostazioni. Successivamente riavvia l’applicazione sul server:

 docker compose restart app 

Torna nella scheda dell’applicazione locale in Bitrix24 e fai clic su Reinstalla. Dopo questo passaggio sarà possibile configurare la connessione al database nel Generatore BI.

Come collegare un database esterno

Vai in Generatore BI > Analytics hub > Connessioni > Crea. Seleziona l’origine dati: MySQL Database Connector oppure PostgreSQL Database Connector.

Compila i parametri di connessione:

• Name: specifica un nome chiaro per la connessione. Verrà visualizzato nell’elenco delle connessioni del Generatore BI.
• Host: indirizzo del server su cui si trova il database. Non specificare localhost se il database si trova su un altro server: l’applicazione cercherà il database nel proprio ambiente. Ad esempio, specifica db.company.local, 10.10.20.15 oppure il nome del container se il database viene eseguito in Docker ed è collegato alla stessa rete.
• Port: porta di connessione al database. PostgreSQL utilizza la porta 5432, MySQL la 3306. Se nella tua infrastruttura è configurata una porta diversa, specifica quella.
• Database: nome del database da cui ottenere i dati per le dashboard.
• Username: login dell’utente del database.
• Password: password dell’utente del database.

Dopo aver compilato i parametri, fai clic su Verifica connessione. Se la verifica è stata completata correttamente, fai clic su Crea. Dopo la creazione della connessione, Bitrix24 proporrà di creare una tabella dal database esterno. Fai clic su Crea tabella.

Come creare una tabella e un dataset

Nel modulo di creazione della tabella seleziona la Tabella necessaria dal database esterno. A destra verrà visualizzata l’Anteprima dati. Qui puoi verificare quali campi e righe il Generatore BI ha ottenuto dal database esterno. In modalità anteprima viene mostrata solo una parte dei dati.

Nel blocco Parametri della tabella controlla nome e descrizione. Il nome viene compilato automaticamente in base al nome della tabella nel database esterno, ma può essere modificato manualmente prima della creazione della tabella.

Nel blocco Colonne della tabella verifica che Bitrix24 abbia determinato correttamente i campi e i relativi tipi di dati. Se i campi e i tipi di dati sono corretti, fai clic su Crea.
Come configurare le colonne
Come configurare formati e tipi di dati

Successivamente Bitrix24 mostrerà un messaggio che conferma la creazione della tabella. Fai clic su Crea dataset. Il dataset è necessario per utilizzare i dati nelle dashboard e nei grafici del Generatore BI.

Dopo aver creato il dataset, puoi creare un grafico e aggiungerlo alla dashboard. Ad esempio, in base alla tabella puoi creare un dataset sugli ordini, generare un grafico sull’importo delle vendite e aggiungerlo alla dashboard del responsabile.
Come creare dashboard nel Generatore BI