W Kreatorze BI można pracować z zewnętrznymi bazami danych MySQL i PostgreSQL. To wygodne rozwiązanie, jeśli część danych jest przechowywana osobno: w sklepie internetowym, wewnętrznym serwisie lub innej firmowej bazie danych.

Na przykład firma przechowuje zamówienia w PostgreSQL. Po podłączeniu bazy do Kreatora BI można wybrać tabelę ze sprzedażą, utworzyć zestaw danych i zbudować wykres sumy zamówień. Dzięki temu kierownik zobaczy dynamikę sprzedaży w jednym raporcie razem z danymi z Bitrix24.

Co należy przygotować do podłączenia bazy danych

Przejdź do sekcji Kreator BI > Miejsce pracy analityka > Połączenia > Utwórz i wybierz MySQL lub PostgreSQL.

Dalsze działania zależą od wersji Bitrix24.

Bitrix24 w Chmurze. Zewnętrzna baza danych jest podłączana przez aplikację serwerową. Najpierw należy skonfigurować aplikację zgodnie z instrukcją, a następnie wrócić do tworzenia połączenia.

Aplikacja będzie łączyć Bitrix24 z bazą danych: odbierać zapytania, łączyć się z MySQL lub PostgreSQL, odczytywać listę tabel i strukturę pól, a następnie przekazywać dane do Kreatora BI.

Aby skonfigurować aplikację, przygotuj:

• Serwer — komputer lub maszynę wirtualną do hostowania aplikacji. Będą na nim przechowywane pliki i wykonywana praca aplikacji. Możesz na przykład użyć firmowego serwera wirtualnego lub oddzielnego serwera w swojej infrastrukturze.
• Docker i Docker Compose — zainstaluj je na serwerze, aby uruchomić aplikację w kontenerze. Docker tworzy izolowane środowisko dla aplikacji, a Docker Compose pomaga uruchomić ją z odpowiednimi ustawieniami. Zapoznaj się z dokumentacją Docker i zainstaluj wersję dla swojego systemu operacyjnego:
  Docker Desktop on Windows
  Docker Desktop on Linux
  Docker Desktop on Mac
• Pliki do budowy aplikacji serwerowej. Pobierz pliki z repozytorium i prześlij je na serwer.
  Bitrix24 BI Connector Extension
• Dostęp do zewnętrznej bazy MySQL lub PostgreSQL — potrzebny, aby aplikacja mogła połączyć się z bazą i odczytać dane. Przygotuj adres bazy, port, nazwę bazy, login i hasło użytkownika z uprawnieniami do odczytu tabel.
• Publiczny adres HTTPS aplikacji serwerowej — potrzebny, aby Bitrix24 mógł połączyć się z aplikacją. Adres typu localhost nie zadziała, ponieważ jest dostępny tylko wewnątrz serwera. Użyj adresu w formacie https://bi-connector.company.ru.

Wersja On-Premise Bitrix24. Nie trzeba konfigurować aplikacji serwerowej. Po wybraniu MySQL lub PostgreSQL można od razu podać parametry połączenia i pracować z bazą danych. Przed konfiguracją przygotuj adres bazy, port, nazwę bazy, login i hasło użytkownika. Upewnij się, że serwer Bitrix24 ma dostęp do bazy przez sieć.

Sprawdź nazwy tabel i pól w zewnętrznej bazie danych. Muszą one spełniać dwa wymagania:

• Nazwy tabel muszą zaczynać się od litery alfabetu łacińskiego i zawierać wyłącznie małe litery łacińskie, cyfry oraz znak podkreślenia. Na przykład: users, order_items, customer_data_2024.
• Nazwy pól muszą zaczynać się od litery alfabetu łacińskiego i zawierać wyłącznie wielkie litery łacińskie, cyfry oraz znak podkreślenia. Na przykład: ID, USER_ID, ORDER_DATE.

Jak zainstalować aplikację na serwerze

Aplikacja serwerowa łączy Bitrix24 z zewnętrzną bazą danych. Wykonuje cztery działania:

• sprawdza połączenie z bazą danych,
• pobiera listę tabel,
• pobiera strukturę tabeli i typy pól,
• przekazuje dane do Kreatora BI.

Użytkownik nie musi uruchamiać tych działań ręcznie. Są wykonywane automatycznie, gdy użytkownik sprawdza połączenie, wybiera tabelę lub tworzy raport. Aby zainstalować aplikację, wykonaj sześć kroków:

1. Przejdź do folderu aplikacji na serwerze. Wszystkie polecenia należy wykonywać na serwerze, na którym będzie działać aplikacja. Otwórz terminal i przejdź do folderu z plikami aplikacji. Sprawdź, czy w folderze znajduje się plik docker-compose.yml. Jeśli jest widoczny na liście, oznacza to, że jesteś w odpowiednim folderze. Polecenia Docker Compose należy wykonywać właśnie w tym miejscu.

2. Utwórz plik ustawień. W folderze aplikacji znajduje się plik .env.example. To przykładowy plik ustawień. Na jego podstawie należy utworzyć roboczy plik .env. Plik przechowuje ustawienia aplikacji: publiczny adres, parametry logowania, ustawienia pamięci podręcznej oraz dane lokalnej aplikacji Bitrix24. Wykonaj polecenie:

 cp .env.example .env 

3. Podaj publiczny adres aplikacji. Otwórz plik .env i wpisz adres, pod którym Bitrix24 będzie łączyć się z aplikacją serwerową. Przykład ustawień:

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

APP_DOMAIN — publiczny adres HTTPS aplikacji. Musi być dostępny z internetu, aby chmurowy Bitrix24 mógł wysyłać zapytania do aplikacji. Adres typu localhost nie zadziała. Taki adres jest dostępny tylko wewnątrz serwera lub kontenera. Na przykład, jeśli aplikacja działa na serwerze w Dockerze, a z zewnątrz jest dostępna przez domenę, schemat może wyglądać tak:

 https://bi-connector.company.ru → serwer z aplikacją → kontener Docker 

Użyj ważnego certyfikatu SSL. Bitrix24 musi otwierać adres aplikacji przez HTTPS bez ostrzeżeń o bezpieczeństwie.

4. Sprawdź sieć Docker. Aplikacja używa zewnętrznej sieci shared_db_network. Jest ona potrzebna, aby aplikacja mogła łączyć się z bazami danych działającymi w Dockerze lub dostępnymi przez wspólną sieć. Jeśli uruchamiasz aplikację poleceniem make start, sieć zostanie utworzona automatycznie. Jeśli uruchamiasz kontenery bezpośrednio przez Docker Compose, utwórz sieć ręcznie:

 docker network create shared_db_network 

Jeśli Docker zwróci informację, że sieć już istnieje, nie jest to błąd. Oznacza to, że została utworzona wcześniej.

5. Uruchom aplikację. Zbuduj i uruchom aplikację na serwerze. Wykonaj polecenie:

 make build make start 

Polecenie make build buduje obraz Docker aplikacji. Polecenie make start uruchamia kontener.

6. Sprawdź, czy aplikacja została uruchomiona. Wykonaj polecenie, aby sprawdzić status kontenerów:

 docker compose ps 

Jeśli aplikacja działa, status kontenera będzie miał wartość Up. Następnie sprawdź, czy aplikacja odpowiada pod publicznym adresem:

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

Jeśli aplikacja odpowiada, można przejść do tworzenia lokalnej aplikacji w Bitrix24. Odpowiedź może wyglądać jak komunikat o błędzie bez działania, na przykład: {"error":"Unknown action: "}. Taki komunikat pojawia się, gdy zapytanie zostało wysłane bez parametru działania. Prawidłowe zapytania będzie wysyłać Bitrix24: podczas sprawdzania połączenia, wyboru tabeli i tworzenia zestawu danych.

Jak utworzyć aplikację lokalną w Bitrix24

Przejdź do sekcji Aplikacje > Dla deweloperów > Inne > Aplikacja lokalna. Uzupełnij parametry:

• Aplikacja lokalna — wybierz typ Serwerowa. Ten typ jest odpowiedni dla aplikacji działającej na serwerze i wymieniającej dane z Bitrix24 przez REST API.
• Ścieżka Twojego handlera — publiczny adres HTTPS aplikacji serwerowej. Pod tym adresem Bitrix24 będzie wysyłać zapytania do aplikacji. Na przykład: https://bi-connector.company.ru/.
• Ścieżka do początkowej instalacji — adres pliku instalacyjnego aplikacji. Jest wywoływany podczas instalacji aplikacji lokalnej w Bitrix24. Na przykład: https://bi-connector.company.ru/install.php.
• Używa tylko API — włącz tę opcję. Jest potrzebna dla aplikacji bez osobnego interfejsu w Bitrix24. Użytkownik nie będzie otwierać aplikacji jako strony — Kreator BI będzie komunikować się z nią automatycznie przez REST API.
• Konfiguracja uprawnień — dodaj uprawnienie Konektor analityki BI (biconnector). Jest ono wymagane, aby aplikacja mogła pracować ze źródłami danych Kreatora BI.

Po uzupełnieniu parametrów kliknij Zapisz.

Po zapisaniu Bitrix24 wyświetli pola systemowe:

• Kod aplikacji (client_id) — identyfikator aplikacji lokalnej. Jest potrzebny aplikacji serwerowej do komunikacji z Bitrix24.
• Klucz aplikacji (client_secret) — tajny klucz aplikacji lokalnej. Potwierdza, że zapytania pochodzą z Twojej aplikacji.

Skopiuj client_id i client_secret. Wróć na serwer i uzupełnij parametry w pliku .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 

Zapisz plik .env w kodowaniu UTF-8 bez dodatkowych znaków na początku pliku. W przeciwnym razie aplikacja może nie odczytać ustawień. Następnie uruchom ponownie aplikację na serwerze:

 docker compose restart app 

Wróć do formularza aplikacji lokalnej w Bitrix24 i kliknij Zainstaluj ponownie aplikację. Następnie w Kreatorze BI będzie można skonfigurować połączenie z bazą danych.

Jak podłączyć zewnętrzną bazę danych

Przejdź do sekcji Kreator BI > Miejsce pracy analityka > Połączenia > Utwórz. Wybierz źródło danych: MySQL Database Connector lub PostgreSQL Database Connector.

Uzupełnij parametry połączenia:

• Nazwa — podaj zrozumiałą nazwę połączenia. Będzie wyświetlana na liście połączeń Kreatora BI.
• Host — adres serwera, na którym znajduje się baza danych. Nie podawaj localhost, jeśli baza znajduje się na innym serwerze: aplikacja będzie szukać bazy we własnym środowisku. Na przykład wpisz db.company.local, 10.10.20.15 lub nazwę kontenera, jeśli baza działa w Dockerze i jest podłączona do tej samej sieci.
• Port — port połączenia z bazą danych. Dla PostgreSQL używa się portu 5432, a dla MySQL — 3306. Jeśli w Twojej infrastrukturze skonfigurowano inny port, podaj go.
• Database — nazwa bazy danych, z której będą pobierane dane do raportów.
• Username — login użytkownika bazy danych.
• Password — hasło użytkownika bazy danych.

Po uzupełnieniu parametrów kliknij Sprawdź połączenie. Jeśli test zakończy się powodzeniem, kliknij Utwórz. Po utworzeniu połączenia Bitrix24 zaproponuje utworzenie tabeli z zewnętrznej bazy danych. Kliknij Utwórz tabelę.

Jak utworzyć tabelę i zestaw danych

W formularzu tworzenia tabeli wybierz odpowiednią Tabelę z zewnętrznej bazy danych. Po prawej stronie pojawi się Podgląd danych. Możesz w nim sprawdzić, jakie pola i wiersze Kreator BI pobrał z zewnętrznej bazy danych. W trybie podglądu wyświetlana jest tylko część danych.

W bloku Właściwości tabeli sprawdź nazwę i opis. Nazwa jest automatycznie pobierana z nazwy tabeli w zewnętrznej bazie danych, ale w razie potrzeby można ją ręcznie zmienić przed utworzeniem tabeli.

W bloku Konfiguracja kolumn tabeli sprawdź, czy Bitrix24 poprawnie rozpoznał pola i ich typy danych. Jeśli pola i typy danych są poprawne, kliknij Utwórz.
Jak skonfigurować kolumny
Jak skonfigurować formaty i typy danych

Następnie Bitrix24 wyświetli komunikat o utworzeniu tabeli. Kliknij Utwórz zestaw danych. Zestaw danych jest potrzebny, aby używać danych w raportach i wykresach Kreatora BI.

Po utworzeniu zestawu danych można zbudować wykres i dodać go do dashboardu. Na przykład na podstawie tabeli można utworzyć zestaw danych dotyczący zamówień, zbudować wykres sumy sprzedaży i dodać go do raportu kierownika.
Jak tworzyć raporty w Kreatorze BI