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
Konfigurację automatycznego pobierania przeprowadzamy w oknie mechanizmu BSConnect. Należy przejść na koncie administratora systemu eDokumenty Narzędzia > Połączenia z systemami zewnętrznymi. W otwartym oknie połączęń wybieramy połączenie i klikamy ikonę zaplanowane zadania
Rys. 12. Ikona Zaplanowane Zadania
W otwartym oknie widać wszystkie dotychczas skonfigurowane akcje z podziałem na typy obiektów synchronizacji.
Rys. 13. Skonfigurowane akcje
W oknie tym należy wybrać akcję i kliknąć przycisk nowy. Pojwai się okno, w którym wpisujemy własną nazwę zdarzenia oraz ustawiamy czas, kiedy ma się wykonywać operacja.
Rys. 14. Konfiguracja zaplanowanego zadania dla wybranej akcji
Po skonfigurowaniu i zapisaniu w oknie Zaplanowanych zadań przy akcji pojawi się ikona zaplanowanego zadania.
Rys. 15. Zaplanowane zadanie dla akcji
Historię wykonywanych operacji można podejrzeć klikając w oknie połączeń z systemami zewnętrznymi ikonę Historia Połączeń.
Rys. 16. Ikona Historia Połączeń
Otworzy sie okno, w którym można zobaczyć kto, kiedy wykonał jakie zadanie (akcję):
Rys. 17. Historia Połączeń
Klikając dwukrotnie w wybraną pozycję można zobaczyć komunikaty związane z danym połączeniem.
Zawartość log-ów BSConnect-a wykonywanych operacji można podejrzeć klikając w oknie połączeń z systemami zewnętrznymi ikonę Dzienniki Zdarzeń.
Rys. 18. Ikona Dzienniki Zdarzeń
W otwartym oknie widzimy pliki Log-ów.
Rys. 19. Okno Dzienniki Zdarzeń
Klikając prawym przyciskiem myszy uruchomi się menu, z którego można pobrać dany plik.
W celu integracji z systemami z którymi nie jest możliwe założenie widoków i triggerów na bazie danych można wykorzystać serwis synchronizacji, który odczytuje dane z zewnętrznego systemu i zapisuje w bazie edokumenty w dedykowanej do tego schemie. Schemat odzwierciedla zewnętrzną strukturę danych i do niego wówczas podłącza się tak jakby to była zewnętrzna baza. Serwis ponadto potrafi generować PDF-Y z dostarczonych z różnych źródeł danych.
Opisana poniżej konfiguracja zawiera opisy integracji z systemami QAD i SIMPLE.
Serwis integracji QAD? Serwis integracji SIMPLE?
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)