Im BI-Builder können externe MySQL- und PostgreSQL-Datenbanken angebunden werden. Dies ist besonders praktisch, wenn ein Teil der Unternehmensdaten separat gespeichert wird, zum Beispiel in einem Onlineshop, einem internen Service oder einer anderen Unternehmensdatenbank.

Wenn ein Unternehmen Bestellungen in PostgreSQL speichert, können Sie nach der Verbindung der Datenbank mit dem BI-Builder eine Tabelle mit Verkaufsdaten auswählen, einen Datensatz erstellen und ein Diagramm auf Basis der Bestellsummen generieren. So erhält die Geschäftsführung eine übersichtliche Darstellung der Verkaufsdynamik in einem Bericht – gemeinsam mit den Daten aus Bitrix24.

Verbindung einer Datenbank vorbereiten

Öffnen Sie den Bereich BI-Builder > Analytik-Hub > Verbindungen > Erstellen und wählen Sie MySQL oder PostgreSQL.

Die weiteren Schritte hängen von der Bitrix24-Version ab.

Cloud-Version von Bitrix24. Die externe Datenbank wird über eine Server-Anwendung verbunden. Zuerst muss die Anwendung gemäß der Anleitung eingerichtet werden, bevor die Verbindung hergestellt werden kann.

Die Anwendung dient als Brücke zwischen Bitrix24 und der externen Datenbank: Sie empfängt Anfragen von Bitrix24, verbindet sich mit MySQL oder PostgreSQL, liest die Tabellenstruktur und Felder aus und überträgt die Daten in den BI-Builder.
Server-side Local Application without User Interface

Für die Einrichtung der Anwendung benötigen Sie:

• Einen Server – einen physischen Computer oder eine virtuelle Maschine, auf der die Anwendung gehostet wird. Dort werden die Dateien gespeichert und die Anwendung ausgeführt.
• Docker und Docker Compose – Installieren Sie diese auf dem Server, um die Anwendung in einem Container auszuführen. Docker erstellt eine isolierte Umgebung, Docker Compose erleichtert die Konfiguration.
  Docker Desktop für Windows
  Docker Desktop für Linux
  Docker Desktop für Mac
• Dateien für die Anwendung – Laden Sie die Dateien aus dem Repository herunter und übertragen Sie diese auf den Server.
  Bitrix24 BI Connector Extension
• Zugang zur externen MySQL- oder PostgreSQL-Datenbank – Bereiten Sie die Serveradresse, den Port, den Datenbanknamen, den Benutzernamen und das Passwort vor.
• Eine öffentliche HTTPS-Adresse für die Anwendung – Bitrix24 muss die Anwendung über eine externe Adresse erreichen können, zum Beispiel https://bi-connector.company.de.

On-Premise-Version von Bitrix24. Hier ist keine serverseitige Anwendung erforderlich. Nach der Auswahl von MySQL oder PostgreSQL können Sie die Verbindungsparameter direkt eingeben. Stellen Sie sicher, dass der Bitrix24-Server die externe Datenbank im Netzwerk erreichen kann.

Überprüfen Sie die Tabellen- und Feldnamen in der externen Datenbank. Diese müssen folgenden Regeln entsprechen:

• Tabellennamen müssen mit einem lateinischen Buchstaben beginnen und dürfen nur Kleinbuchstaben, Zahlen und Unterstriche enthalten, zum Beispiel users oder order_items.
• Feldnamen müssen mit einem lateinischen Buchstaben beginnen und dürfen nur Groß- und Kleinbuchstaben, Zahlen und Unterstriche enthalten, zum Beispiel ID, USER_ID oder order_date.

Anwendung auf dem Server installieren

Die serverseitige Anwendung verbindet Bitrix24 mit der externen Datenbank. Sie führt 4 Aktionen aus:

• überprüft die Verbindung zur Datenbank,
• ruft die Tabellenliste ab,
• ruft die Tabellenstruktur und Feldtypen ab,
• übertragung die Daten in den BI-Builder.

Der Nutzer muss diese Aktionen nicht manuell ausführen. Sie werden automatisch ausgeführt, wenn die Verbindung geprüft, eine Tabelle ausgewählt oder ein Dashboard erstellt wird. Um die Anwendung zu installieren, führen Sie diese 6 Schritte aus:

1. Wechseln Sie in den Anwendungsordner auf dem Server. Alle Befehle müssen auf dem Server ausgeführt werden, auf dem die Anwendung laufen soll. Öffnen Sie das Terminal und wechseln Sie in den Ordner mit den Anwendungsdateien. Stellen Sie sicher, dass die Datei docker-compose.yml im Ordner vorhanden ist. Wenn sie im Verzeichnis angezeigt wird, befinden Sie sich im richtigen Ordner. Docker-Compose-Befehle müssen von hier aus ausgeführt werden.

2. Erstellen Sie eine Konfigurationsdatei. Der Anwendungsordner hat eine Datei .env.example. Diese dient als Vorlage für die Einstellungen. Erstellen Sie daraus eine Arbeitsdatei .env, welche die Einstellungen der Anwendung speichert: öffentliche Adresse, Logging-Parameter, Cache-Einstellungen und Daten der lokalen Bitrix24-Anwendung. Führen Sie den Befehl aus:

 cp .env.example .env 

3. Geben Sie die öffentliche Adresse der Anwendung an. Öffnen Sie die Datei .env und geben Sie die Adresse an, über die Bitrix24 auf die serverseitige Anwendung zugreifen wird. Beispiel:

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

APP_DOMAIN ist die öffentliche HTTPS-Adresse der Anwendung. Sie muss aus dem Internet zugänglich sein, damit die Bitrix24 Cloud-Version Anfragen an die Anwendung senden kann. Adressen wie localhost sind nicht geeignet, da sie nur innerhalb des Servers oder Containers zugänglich sind. Wenn die Anwendung auf einem Server in Docker läuft und über eine Domain zugänglich ist, könnte die Struktur wie folgt aussehen:

 https://bi-connector.company.de → Server mit der Anwendung → Docker-Container 

Verwenden Sie ein gültiges SSL-Zertifikat. Bitrix24 muss die Adresse der Anwendung über HTTPS ohne Sicherheitswarnungen öffnen können.

4. Überprüfen Sie das Docker-Netzwerk. Die Anwendung verwendet das externe Netzwerk shared_db_network. Dieses Netzwerk ermöglicht der Anwendung den Zugriff auf Datenbanken, die in Docker laufen oder über ein gemeinsames Netzwerk verfügbar sind. Wenn Sie die Anwendung mit dem Befehl make start starten, wird das Netzwerk automatisch erstellt. Wenn Sie die Container direkt über Docker Compose starten, erstellen Sie das Netzwerk manuell:

 docker network create shared_db_network 

Wenn Docker meldet, dass das Netzwerk bereits existiert, ist das kein Fehler. Es bedeutet, dass es zuvor erstellt wurde.

5. Starten Sie die Anwendung. Bauen und starten Sie die Anwendung auf dem Server. Führen Sie die Befehle aus:

 make build make start 

Der Befehl make build erstellt das Docker-Image der Anwendung. Der Befehl make start startet den Container.

6. Überprüfen Sie, ob die Anwendung läuft. Führen Sie den Befehl aus, um den Status der Container anzuzeigen:

 docker compose ps 

Wenn die Anwendung läuft, zeigt der Status des Containers den Wert Up an. Überprüfen Sie anschließend, ob die Anwendung unter der öffentlichen Adresse antwortet:

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

Wenn die Anwendung antwortet, können Sie mit der Erstellung einer lokalen Anwendung in Bitrix24 fortfahren. Die Antwort kann wie eine Fehlermeldung ohne Aktion aussehen, z. B.: {"error":"Unknown action: "}. Solche Antworten erscheinen, wenn die Anfrage ohne Aktionsparameter gesendet wird. Funktionierende Anfragen werden von Bitrix24 gesendet, z. B. bei der Verbindungsprüfung, Tabellenauswahl und Dataset-Erstellung.

Lokale Anwendung in Bitrix24 erstellen

Öffnen Sie den Bereich Anwendungen > Für Entwickler > Sonstiges > Lokale Anwendung und füllen Sie die folgenden Parameter aus:

• Lokale Anwendung – Wählen Sie den Typ Server. Dieser Typ eignet sich für Anwendungen, die auf einem Server laufen und Daten über die REST-API mit Bitrix24 austauschen.
• Ihr Handler-Pfad – Die öffentliche HTTPS-Adresse der serverseitigen Anwendung. Bitrix24 sendet Anfragen an diese Adresse. Beispiel: https://bi-connector.company.de/.
• Ursprünglicher Installationspfad – Die Adresse der Installationsdatei der Anwendung. Diese wird beim Installieren der lokalen Anwendung in Bitrix24 aufgerufen. Beispiel: https://bi-connector.company.de/install.php.
• Nur Skript (Keine Benutzeroberfläche) – Aktivieren Sie diese Option. Sie ist für Anwendungen ohne separate Benutzeroberfläche in Bitrix24 erforderlich. Der Nutzer öffnet die Anwendung nicht als Seite – der BI-Builder ruft sie automatisch über die REST-API auf.
• Zugriffsrechte definieren – Fügen Sie das Recht Connector der BI-Analytik (biconnector) hinzu. Dieses Recht ist erforderlich, damit die Anwendung Datenquellen des BI-Builders verarbeiten kann.

Nachdem Sie alle Parameter ausgefüllt haben, klicken Sie auf Speichern.

Nach dem Speichern zeigt Bitrix24 folgende Felder an:

• ID der Anwendung (client_id) – die ID der lokalen Anwendung. Die serverseitige Anwendung benötigt sie, um Anfragen an Bitrix24 zu senden.
• Schlüssel der Anwendung (client_secret) – der geheime Schlüssel der lokalen Anwendung. Er bestätigt, dass die Anfragen von Ihrer Anwendung stammen.

Kopieren Sie client_id und client_secret. Kehren Sie anschließend zum Server zurück und tragen Sie die Parameter in die Datei .env ein:

 BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID=Ihr_client_id BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET=Ihr_client_secret BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnector 

Speichern Sie die Datei .env im UTF-8-Format ohne zusätzliche Zeichen am Anfang der Datei. Andernfalls kann die Anwendung die Einstellungen nicht lesen. Starten Sie dann die Anwendung auf dem Server erneut:

 docker compose restart app 

Kehren Sie zur lokalen Anwendung in Bitrix24 zurück und klicken Sie auf Neu installieren. Danach können Sie im BI-Builder eine Verbindung zur Datenbank herstellen.

Externe Datenbank verbinden

Öffnen Sie den Bereich BI-Builder > Analytik-Hub > Verbindungen > Erstellen. Wählen Sie die Datenquelle: MySQL Database Connector oder PostgreSQL Database Connector.

Füllen Sie die Verbindungsparameter aus:

• Name – Geben Sie einen verständlichen Namen für die Verbindung an. Dieser Name wird in der Liste der Verbindungen im BI-Builder angezeigt.
• Host – Die Adresse des Servers, auf dem sich die Datenbank befindet. Verwenden Sie nicht localhost, wenn sich die Datenbank auf einem anderen Server befindet: Die Anwendung sucht die Datenbank innerhalb ihrer Umgebung. Geben Sie z. B. db.company.local, 10.10.20.15 oder den Namen des Containers an, wenn die Datenbank in Docker läuft und mit demselben Netzwerk verbunden ist.
• Port – Der Port für die Verbindung zur Datenbank. Für PostgreSQL wird Port 5432 verwendet, für MySQL 3306. Wenn in Ihrer Infrastruktur ein anderer Port konfiguriert ist, geben Sie diesen an.
• Database – Der Name der Datenbank, aus der die Daten für Dashboards abgerufen werden sollen.
• Username – Der Nutzername für die Datenbank.
• Password – Das Passwort für den Nutzer der Datenbank.

Nachdem Sie die Parameter ausgefüllt haben, klicken Sie auf Check connection. Wenn die Prüfung erfolgreich ist, klicken Sie auf Erstellen. Nach der Erstellung der Verbindung schlägt Bitrix24 vor, eine Tabelle aus der externen Datenbank zu erstellen. Klicken Sie auf Create table.

Tabelle und Datasatz erstellt

Wählen Sie im Formular zur Tabellenerstellung die gewünschte Tabelle aus der externen Datenbank aus. Auf der rechten Seite erscheint eine Datenvorschau. Dort können Sie überprüfen, welche Felder und Zeilen der BI-Builder aus der externen Datenbank abgerufen hat. In der Vorschau wird nur ein Teil der Daten angezeigt.

Im Bereich Tabellenparameter überprüfen Sie den Namen und die Beschreibung. Der Name wird automatisch basierend auf dem Tabellennamen aus der externen Datenbank eingefügt, kann jedoch bei Bedarf vor der Erstellung der Tabelle manuell geändert werden.

Im Bereich Tabellenspalten überprüfen Sie, ob Bitrix24 die Felder und deren Datentypen korrekt erkannt hat. Wenn die Felder und Datentypen korrekt sind, klicken Sie auf Erstellen.
BI-Builder: Datensatz aus der CSV-Datei erstellen
Datenformate und Typen für den Import der CSV-Datei konfigurieren

Danach zeigt Bitrix24 eine Meldung an, dass die Tabelle erstellt wurde. Klicken Sie auf Datensatz erstellen. Der Datensatz wird benötigt, um die Daten in Dashboards und Diagrammen des BI-Builders zu verwenden.

Nach der Erstellung des Datenasatzes können Sie ein Diagramm erstellen und es zum Dashboard hinzufügen. Beispielsweise können Sie basierend auf der Tabelle einen Datensatz für Bestellungen erstellen, ein Diagramm für die Verkaufsbeträge erstellen und es ins Dashboard einfügen.
Datenformate und Typen für den Import der CSV-Datei konfigurieren