Rys. 1. Bazy danych wykorzystane w niniejszym tutorialu
[DRAFT - obecnie przygotowywana jest aktualna wersja opisu ]
Niniejszy artykuł przedstawia opis kroków niezbędnych do realizacji integracji z systemami zewnętrznymi. Przez system zewnętrzny należy rozumieć każdy inny system informatyczny (ERP, FK, HM, CRM), z którego pragniemy pobrać dane lub któremu chcemy dane udostępnić. Obecnie według tego mechanizmu istnieje możliwość integracji z m.in.
W niniejszym artykule wykorzystamy dla celów przykładowych jako system zewnętrzny bazy prezentacyjne systemów Comarch CDN XL oraz Sage Forte oraz dodatkową bazę danych eDok, która będzie naszą bazą pośrednią w procesie integracji. Baza pośrednia ma tę zaletę, gdyż uwalnia administratora bazy systemu informatycznego od tworzenia specjalnych schematów oraz nadawania uprawnień użytkownikowi do obiektów w tym schemacie. Stanowi ona pewien element izolacji przed ingerencją osób trzecich w bazę systemu informatycznego.
Aby móc wykorzystać funkcjonalności mechanizmu BSConnect wymaga się, aby minimalna wersja systemu eDokumenty to 3.8.159. Jednocześnie zastrzega się, iż niektóre funkcjonalności mechanizmu pojawiły się w wersji 4.0.x
Integracja z systemami zewnętrznymi wykorzystuje mechanizm BSConnect, który potrafi pobierać dane z wielu źródeł, jak bazy danych lub pliki XML, jak i również uczestniczyć w generowaniu plików eksportu / eksporcie danych do systemów zewnętrznych. Dzięki temu możliwe jest połączenie z dowolnym systemem, na którego bazie danych można zdefiniować widoki, z których dane zostaną pobrane (albo bezpośrednio, ale poprzez wygenerowane pliki XML).
Rys. 1. Bazy danych wykorzystane w niniejszym tutorialu
W niniejszej sekcji opisano czynności podstawowe związane z konfiguracją połączenia z bazą pośrednią systemu zewnętrznego. Szczegółowy opis konfiguracji znajduje się na stronie:
W niniejszej sekcji zostanie opisany import danych z systemów zewnętrznych. Integracja ta może być realizowana na dwa sposoby:
Szczegółowy opis konfiguracji importu znajduje się na stronie :
W niniejszej sekcji zostanie opisany eksport danych z systemu eDokumenty do systemów zewnętrznych. Podobnie jak import, eksport danych realizowany może być również na dwa sposoby:
Szczegółowy opis konfiguracji eksportu znajduje się na stronie Eksport danych do systemów zewnętrznych
Aby móc realizować operacje przy wykorzystaniu mechanizmu BSConnect należy danemu użytkownikowi / grupie nadać odpowiednie uprawnienia. Uprawnienia te znajdują się na karcie pracownika(użytkownika)/grupy z zakładce Prawa do jednostek. W okienku należy rozwinąć gałąź Usługi systemowe i nadać uprawnienie do jednostki EXTSYS Usługa systemu zewnętrznego.
Schemat uprawniania przedstawia poniższy rysunek
Rys. 2. Przykład uprawniania użytkownika do usługi systemu zewnętrznego
Po zamknięciu kartoteki pracownika z poziomu administratora użytkownik powinien się wylogować z systemu. Następnie powinien zalogować się ponownie. Po przejściu na moduł np. Klienci pojawi się na pasku przycisk Połączenie, który po naciśnięciu pokazuje obiekty integracji dostępne w danym module.
Rys. 3. Przycisk Połączenie dostępny w module Klienci
System eDokumenty pozwala uruchomić zadania synchronizacji automatycznie. Wykorzystuje do tego celu systemowy Harmongram Zadań (w linuksie cron). Mechanizm ten uruchamia skrypt CronRunner.php w trybie klienta. Skrypt ten odpowiedzialny jest za realizację zadań zapisanych w bazie danych systemu eDokumenty (konkretnie w tabeli crontab).
Konfiguracja środowiska
Zanim zostanie utworzone pierwsze zadanie - system trzeba przygotować do uruchamiania skryptu CronRunner.php. W tym celu w systemie linux należy dodać odpowiedni wpis do pliku /etc/crontab
*/1 * * * * www-data cd /home/edokumenty/public_html/apps/edokumenty && php -f CronRunner.php >> /var/log/cronrunner.log
Natomiast w systemie Windows można utworzyć zadanie w systemowym panelu Harmonogram Zadań lub też wykonać z lini poleceń (cmd) komendę:
schtasks /create /sc co_minutę /mo 5 /tn "CronRunner" /tr "php -f C:\Program Files\BetaSoft\eDokumenty\CronRunner.php"
W tym momencie należy przetestować działanie skryptu. Na systemie Windows należy uruchomić zadanie i sprawdzić w historii pobierania, czy wykonała się synchronizacja. Tutaj oprzemy się o testowaniu na systemie Linux. W tym celu należy przejść na konto użytkownika www-data:
su - www-data
Rys. 4.
Jeżeli uruchomi się powłoka sh należy wykonać polecenie:
bash
Rys. 5.
Będąc w powłoce bash należy wykonać polecenie:
cd /home/edokumenty/public_html/apps/edokumenty && php -f CronRunner.php >> /var/log/cronrunner.log
Po kliknięciu przycisku Enter w konsoli powinna się pojawić standardowa linia ze znakiem zachęty. Jeżeli pokaże sie jakikolwiek komunikat, to znaczy, że coś nie działa
Poniższe zrzuty ekranu pokazują typowe problemy napotkane przy uruchamianiu CronRunner-a.:
Brak uprawnień do pliku CronRunner.log
Rys. 6.
W celu rozwiązania tego problemu należy w odpowiedniej lokalizacji np. w katalogu /var/log/ z poziomu użytkownika root utworzyć plik (pusty) i nadać mu odpowiednie uprawnienia:
#cd /var/log #vim CronRunner.log -> następnie w Vimie zapisać pusty plik poleceniem :wq #chmod 664 CronRunner.log #chown www-data:edokumenty CronRunner.log
Rys. 7.
Testując powinniśmy uzyskać następujący efekt:
Rys. 8.
Taki widok w konsoli oznacza, że skrypt wykonał się. Na wszelki wypadek nalezy spojrzeć do pliku log-a:
#tail /var/log/CronRunner.log
W przypadku wystąpienia następującego komunikatu:
Rys. 9.
Oznacza to, że w pliku /etc/php5/cli/php.ini jest zła konfiguracja. Sposób postępowania jest podobny także w przypadkach np. braków rozszerzeń do obsługi innych systemów. W celu naprawy sytuacji należy utworzyć link symboliczny do php.ini apache'a, który wiemy, ze jest prawidłowy.
#cd /etc/php5/cli/ #mv php.ini php.ini.bak #ln -s /etc/php5/apache2/php.ini php.ini
Rys. 10.
Wynikiem tej operacji powinien być log, w którym nie pojawił się żadeń nowy wpis z błędem.
Rys. 11.
Konfiguracja zadań w systemie eDokumenty
Poniższe przykłady realizowane były w starszych wersjach systemu eDokumenty. Pokazane przykłady nie są już obecnie wspierane. Zaleca się aktualizację do najnowszej wersji systemu (z uwzględnieniem posiadanej licencji)