Przewodnik wdrożeniowca > Podstawowa konfiguracja systemu eDokumenty (uruchomienie modułu BSConnect)

Strona główna Integracji

Wprowadzenie

1. Konfiguracja źródeł danych
2. Uruchomienie modułu BSConnect
3. Konfiguracja źródeł wymiany danych
4. Tworzenie połączenia z systemem zewnętrznym
5. Tabela bs_export_queue dla połączeń typu DB

Konfiguracja źródła danych

Sekcja ta opisuje sposób konfiguracji źródła danych. Źródło jest ciągiem tekstowym, który zawiera dane połączenia do zewnętrznej bazy danych, takie jak:

• Server - Nazwę instancji serwera. Zawiera w sobie adres hosta serwera baz danych, numer portu (np. dla zdalnych połączeń z Ms SQL Server). Przykładowe dane to localhost\sqlexpress lub też 192.168.0.1:1024,
• Database - Nazwę bazy danych.
• Uid, User - identyfikator użytkownika baz danych
• Pwd, Password - hasło użytkownika bazy danych
• Port - [parametr opcjonalny] numer portu, na którym nasłuchuje serwer baz danych. Parametr nie jest wykorzystywany przez Ms SQL Server.
• Encoding - [parametr opcjonalny] kodowanie połączenia z systemem zewnętrznym.

W poniższym listingu przedstawiono przykładowe ciągi połączeń dla różnych systemów zarządzania bazami danych:

# Microsoft SQL Server :
Server=localhost\sqlexpress;Database=eDok;Uid=edokumenty;Pwd=edokumenty;
lub 
Server=192.168.0.1:1433;Database=eDok;Uid=edokumenty;Pwd=edokumenty;

# MySQL :
Server=192.168.0.1;Port=3306;Database=eDok;User=edokumenty;Password=edokumenty;

# Oracle :
Server=192.168.0.1;Database=192.168.0.1/eDok;Uid=edokumenty;Pwd=edokumenty;encoding=AL32UTF8;

# PostgreSQL :
host=localhost port=5432 dbname=eDok user=edokumenty password=edokumenty

# ODBC
DSN=SYSTEMOWE_ZRODLO_32BIT_ODBC_TYPU_SQL_SERVER;Server=localhost ;Database=eDok;Uid=edokumenty;Pwd=edokumenty;

# Firebird
User=SYSDBA;Password=masterkey;Server=localhost;database=D:\SQL\Firebird\FIREBIRD_TEST.FDB;Dialect=3;Charset=UTF8;

Konfigurację źródła danych przeprowadzamy w menu Ustawienia > Panel Sterowania > Źródła danych :

Rys. 1. Ustawienia > Panel Sterowania

Rys. 2. Panel Sterowania i Źródła danych

Rys. 3. Okno konfiguracji źródeł danych

W oknie tym można uruchamiać dodawanie, edycję lub też usuwać źródła danych. W przypadku dodawania lub edycji uruchomi się okno, w którym należy:

• wprowadzić unikalną nazwę (najlepiej identyfikującą system zewnętrzny)
• wybrać sterownik do odpowiedniego SZBD
• wpisać ciąg połączenia.

Rys. 4. Okno dodawania / edycji źródła danych

Po kliknięciu przycisku Zapisz okienko edycji powinno się zamknąć. Oznacza to, że źródło zostało poprawnie dodane. W przeciwnym przypadku zostanie wyświetlony komunikat o błędzie połączenia.

Powrót do menu

Uruchomienie modułu BSCOnnect

Kolejnym etapem w procesie Integracji z systemem zewnętrznym jest uruchomienie modułu BSConnect. Aby rozpocząć prace integracyjne należy włączyć moduł BSConnect. Moduł ten włącza się modyfikując plik config.inc w katalogu: [katalog instalacji]/public_html/apps/edokumenty/config.inc . W pliku tym należy wprowadzić następujace wyrażenie:

define('SYNC_ACTIVE', 'NEW');

Rys. 5. Wpis w pliku config.inc

Następnie należy zalogować się ponownie na koncie administratora systemu eDokumenty. Po ponownym zalogowaniu się w menu Narzędzia powinno pojawić się polecenie Połączenia z systemami zewnętrznymi:

Rys. 6. Widok menu po uruchomieniu modułu BSConnect

Klikając na polecenie: Narzędzia > Połączenia z systemami zewnętrznymi uruchamia się okno konfiguracji połączeń z systemami zewnętrznymi.:

Rys. 7. Okno konfiguracji połączeń z systemami zewnętrznymi

Powrót do menu

Konfiguracja źródeł wymiany danych

Sprzedane na allegro:

Mając otwarte okno konfiguracji połączeń z systemami zewnętrznymi można odpowiednio:

• dodawać nowe połączenie
• edytować połączenie
• usuwać połączenie
• planować zadania dla każdego z połączeń osobno
• przeglądać historię dla wybranego połączenia
• przeglądać dziennik zdarzeń związanych z wybranym połączeniem
• definiować źródło wymiany danych

Pierwszym krokiem, który należy wykonać to zdefiniować źródło wymiany danych. Jest obiekt pośredniczący, który definiuje przy pomocy jakich mechanizmów dane połączenie będzie miało pobierać lub eksportować dane. W tym celu na pasku menu należy kliknąć Źródła wymiany danych. W nowo otwartym oknie po wybraniu opcji Nowe otworzy się okno, w którym można zdefiniować parametry źródła wymiany danych. Są to:

• Nazwa unikalna źródła wymiany danych
• Typ źródła wymiany danych

Rys. 8. Konfiguracja źródła wymiany danych

Wyróżnia się następujące typy źródeł wymiany danych:

• DB - Wymaga danych poprzez bazę danych (wymaga utworzenia dedykowanych widoków)
• CUSTOM_DB - Wymaga danych poprzez bazę danych z wykorzystaniem dedykowanej klasy PHP. Klasę należy umieścić w lokalizacji

  public_html/apps/edokumenty/classes/BSConnectReadOnly/exchange/custom.
  

Przykład takiej klasy zamieszczono poniżej.

• XML - Wymiana poprzez plik XML o odpowiedniej strukturze.
• CUSTOM_XML - Wymiana poprzez plik XML o odpowiedniej strukturze z dedykowaną klasę PHP.
• CUSTOM_SOAP - Wymiana danych poprzez usługę SOAP - określenie dedykowanej klasy PHP
• EPUAP - Wymiana danych ze skrzynką podawczą ePUAP (określenie konfiguracji podmiotu ePUAP)

Przykład klasy PHP dla wymiany CUSTOM_DB.

<?php

require_once('./classes/BSConnectReadOnly/exchange/db/BSConnectDBExchange.inc');

final class CustomDBExchange extends BSConnectDBExchange {

    // Dostępne klasy w BSConnect
    // DOCUMENT
    // CONTACT
    // CONTACTPERSON
    // PRODUCT

    public function releaseFromQueue($configuration, $clsnam, $keyval) {
        
            parent::releaseFromQueue($configuration, $clsnam, $keyval);
            
            // Wywołanie obiektu połączenia z PostgreSQL
            $db = PgManager::getInstance();
            
            // Sprawdzanie, czy klucz jest liczbą, czy tablicą (musi być tablicą)
            if (is_numeric($keyval)){
                $keyval = array($keyval);
            }
                
            // Wywołanie dla każdego obiektu
            if (is_array($keyval)) {
                
                foreach($keyval AS $contid){
                    
                                // tutaj operacje

                }
            }
    }

} // class CustomDBExchange

?>

Dalsze parametry źródła wymiany danych zależą od wybranego typu. dla typu:

• DB
  • Źródło danych - zdefiniowane źródło danych (Ustawienia > Panel Sterowania > Źródła danych )
  • Nazwa schemy - nazwa schematu w bazie danych (Uwaga, dla SZBD typu MsSQL pole należy zostawić puste. Spowodowane jest to faktem, że system ten nie obsługuje schematów).

Rys. 9. Opcje dla typu DB

• CUSTOM_DB - zawiera podobne pola jak typ DB, z dodatkowym polem na nazwę klasy np. CustomDBExchange

Rys. 10. Opcje dla typu CUSTOM_DB

• XML
  • Ścieżka składu - ścieżka dostępu do pliku XML, np. /mnt/integration/ lub dla Ms Windows D:/Integracja/ . Uwaga należy używać znaków slash zamiast back-slash (jak jest to pokazane w przykładach)
  • Szablon - nazwa pliku szablonu flexy .tpl znajdującego się w katalogu systemu eDokumenty: public_html/apps/edokumenty/var/tpl/bs_connect.

Rys. 11. Opcje dla typu XML

• CUSTOM_XML - integracja poprzez plik XML ze wskazaniem własnej klasy. Nazwę klasy należy podać zamiast szablonu nazwę klasy.

Rys. 12. Opcje dla typu CUSTOM_XML

• CUSTOM_SOAP - Wykorzystujący mechanizm SOAP:
  • Klasa - nazwa klasy np. MojaKlasa zapisana jako plik MojaKlasa.inc w katalogu: public_html//apps/edokumenty/classes/BSConnectReadOnly/exchange/custom.
  • Adres serwisu - Adres web serwisu obsługującego żadania. W przypadku pustego pola wymagane jest aby to dedykowana klasa miała skonfigurowany adres web serwisu.

Rys. 13. Opcje dla typu CUSTOM_SOAP

• ePUAP - w tej konfiguracji podawany jest z listy wyboru podmiot ePUAP, z którą nastąpi połączenie. Jeśli lista jest pusta należy przejść do Narzędzia -> Konfiguracja podmiotów ePUAP i tam postępując zgodnie z dokumentacją zdefiniować podmiot ePUAP.

Rys. 14. Opcje dla typu ePUAP

Na tym kończy się konfiguracja źródeł wymiany danych. W następnej części opisano tworzenie Połączenia z systemem zewnętrznym. Powrót do menu

Tworzenie połączenia z systemem zewnętrznym

Na tym etapie zostanie utworzone połączenie z systemem zewnętrznym. Mając otwarte okno definicji Połączeń z systemami zewnętrznymi, które należy wywołać z menu Narzędzia klikamy Nowy.

Rys. 15. Okno definicji Połączenia z systemem zewnętrznym

W oknie tym są trzy przyciski na pasku poleceń:

• Zaplanowane zadania - definicja automatycznego wykonywania akcji przy wykorzystaniu linuksowego Cron-a lub Harmonogramu Zadań systemu Windows.
• Historia połączenia - historia wyników operacji dla danego połączenia
• Dzienniki zdarzeń - eksplorator plików log-ów z każdego wywołania połączenia z systemem zewnętrznym.

Pola, które dla danego połączenia należy wypełnić to:

• Nazwa - unikalna nazwa połączenia z systemem zewnętrznym.
• Opis - [parametr opcjonalny] - opis połączenia z systemem zewnętrznym.
• Identyfikator systemu - uwaga, dla integracji z wykorzystaniem BSConnect domyślnie należy wybrać inny.
• Źródło wymiany danych - domyślne źródło wymiany danych dla całego połączenia.
• Priorytet - [parametr opcjonalny] Domyślnie puste (automatycznie nadawane przez system). Parametr służy ustawieniu kolejności wyświetlania danego połączenia na liście połączeń.
• Domyślne połączenie - znacznik, czy dane połączenie jest połączeniem domyślnym.

Należy dodać, iż jedno połączenie może zawierać w sobie odwołania do wielu źródeł wymiany danych. Np. w konfiguracji ogólnej możemy wybrać jedno domyślne źródło wymiany danych (np. typu DB), natomiast dla poszczególnych akcji połączenia z systemem zewnętrznym możemy wybrać inne (np. CUSTOM_DB lub XML).

Po zapisaniu formatki pojawia się zakładka synchronizacja, w której konfigurowane będą akcje dla każdego z obiektów synchronizacji.

Powrót do menu

Tabela bs_export_queue dla połączeń typu DB

Konfigurację pobierania danych z systemu zewnętrznego z wykorzystaniem źródła wymiany danych typu DB należy rozpocząć od utworzenia na bazie danych systemu zewnętrznego (lub bazie pośredniej) tabeli: <nazwa schematu>.bs_export_queue.

Wymagana struktura tabeli powinna być następująca:

Kolumna	Typ danych	NULL?	Klucz główny	Auto increment	Default
exp_id	bigint	NOT NULL	Tak	Tak	-
keyval	int	NULL	Nie	-	-
clsnam	varchar(32)	NULL	Nie	-	-
chadat	timestamp with time zone / datetime	NULL	Nie	-	GETDATE()

Przykładowe skrypty tworzące tabelę:

-- Ms SQL Server --
USE <nazwa_bazy_danych>
GO

IF OBJECT_ID('edokumenty.bs_export_queue') IS NOT NULL
BEGIN
        DROP TABLE edokumenty.bs_export_queue
END
GO

CREATE TABLE edokumenty.bs_export_queue(
        exp_id bigint IDENTITY(1,1) NOT NULL,
        keyval int NULL,
        clsnam varchar(32) NULL,
        chadat datetime NULL,
 CONSTRAINT pk_exp_id PRIMARY KEY CLUSTERED (exp_id ASC)
) ;

GO

ALTER TABLE edokumenty.bs_export_queue ADD DEFAULT (getdate()) FOR chadat
GO

-- PostgreSQL --
DROP TABLE IF EXISTS edokumenty.bs_export_queue CASCADE;

CREATE TABLE edokumenty.bs_export_queue (
        exp_id bigint NOT NULL PRIMARY KEY,
        keyval int NULL,
        clsnam varchar(32) NULL,
        chadat timestamp with time zone DEFAULT current_timestamp
);


DROP SEQUENCE IF EXISTS edokumenty.bs_export_queue_seq CASCADE;

CREATE SEQUENCE edokumenty.bs_export_queue_seq
INCREMENT BY 1
START 1
NO MAXVALUE
OWNED BY edokumenty.bs_export_queue.exp_id;

ALTER TABLE edokumenty.bs_export_queue
ALTER COLUMN exp_id SET DEFAULT nextval('edokumenty.bs_export_queue_seq');

ALTER TABLE edokumenty.bs_export_queue
  OWNER TO edokumenty;
GRANT ALL ON TABLE edokumenty.bs_export_queue TO edokumenty;
GRANT ALL ON TABLE edokumenty.bs_export_queue TO http;

-- MySQL --

DROP TABLE IF EXISTS bs_export_queue;

CREATE TABLE bs_export_queue(
        exp_id BIGINT NOT NULL PRIMARY KEY AUTO_INCREMENT,
        keyval INT NULL,
        clsnam VARCHAR(32) NULL,
        chadat TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Import danych z systemu zewnętrznego
Powrót do menu