= Integracja z zewnętrznymi systemami > Optima = #menu

=== Menu ===
 1. [#wprowadzenie Wprowadzenie]
 2. [#definiowanie Definiowanie źródła danych do Optimy]
 3. [#konfiguracja_komunikacji Konfiguracja komunikacji z system Optima]

== Wprowadzenie == #wprowadzenie

W niniejszym artykule przedstawiamy sposób połączenia eDokumentów z systemem Optima. Zakładamy, że istnieje w sieci serwer/komputer z zainstalowaną Optimą. Oczywiście nic nie stoi na przeszkodzie, aby Optima była zainstalowana na serwerze, na których rezydują eDokumenty (dotyczy systemów z rodziny Windows).

Prace te zawierają się w kilku etapach:
 1. Definiowanie źródła danych
 2. Konfiguracja komunikacji z systemem Optima

== Definiowanie źródła danych do Optimy == #definiowanie

Pierwszym etapem jest definicja źródła danych do bazy danych systemu Optima. Czynność tę realizujemy w menu ''Ustawienia > Panel Sterowania > [Pozostałe ustawienia]: Źródła danych''. Otwiera się okienko, w którym definiujemy źródła danych:

[[BR]][[Image(img001.png)]][[BR]]''(Rys.1 Okno źródeł danych'')[[BR]]

Po kliknięciu ''Nowa'' otwiera się okno definicji źródła danych. W oknie tym wskażemy dane do podłączenia się Optimą takie jak:

[[BR]][[Image(img002.png)]][[BR]]''(Rys.2 Definicja źródła danych do Optimy'')[[BR]]

 * Identyfikator źródła danych - unikalna nazwa źródła danych, np. Optima
 * Sterownik - MsSQL
 * Ciąg połączenia - np. ''Server=.\OPTIMA;Database=CDN_Firma_Demo;Uid=sa;Pwd=Optima1234!@#$'', gdzie:[[BR]]
  * Server - to adres serwera, lokalnie może być: {{{.\OPTIMA}}}, lub zdalnie np. {{{192.168.0.2\OPTIMA}}}[[BR]]
  * Database - nazwa bazy danych[[BR]]
  * Uid - nazwa użytkownika bazy danych, który ma uprawnienia do bazy, np. sa[[BR]]
  * Pwd - hasło powyższego użytkownika

Po wypełnieniu tych danych pojawia nam się zdefiniowane źródło danych w okienku Źródeł danych.

''Przejdź do [#menu Menu]''

== Konfiguracja komunikacji z system Optima == #konfiguracja_komunikacji

Następnym krokiem w procesie jest konfiguracja komunikacji systemu eDokumenty z Optimą. Do tego celu będziemy musieli wykorzystać ukryte narzędzie eDokumentów, jakim jest konfigurator połączeń z systemami zewnętrznymi.
Domyślnie jest on wyłączony. Aby go uaktywnić należy w pliku {{{config.inc}}} odszukać frazę ''SYNC_ACTIVE'' lub też dodać do niego kod:

{{{
#!php
//Okno konfiguracji połączeń z systemami zewnętrznymi.
define('SYNC_ACTIVE', TRUE);
}}}

Następnie należy się przelogować i w menu ''Narzędzia'' zobaczymy nowy przycisk:

[[BR]][[Image(img003.png)]][[BR]]''(Rys.3 Menu Narzędzia z konfiguratorem połączeń'')[[BR]]

''Przejdź do [#menu Menu]''

Po uruchomieniu się okna połączeń wybieramy ''Nowa''. Polecenie to uruchamia wspomniany konfigurator:

[[BR]][[Image(img004.png)]][[BR]]''(Rys.4 Konfigurator połączenia z systemami zewnętrznymi'')[[BR]]

W konfiguratorze tym wybieramy:
 * System - system, z którym będziemy się integrować, tutaj Optima
 * Źródło danych - utworzone wcześniej źródło danych.
Pozostałe parametry są domyślnie zdefiniowane.

Zanim klikniemy wykonaj, należy pobrać i wykonać na serwerze (odpowiedniej bazie Optimy) Ms SQL (np. przy użyciu Management Studio) dwa skrypty T-SQL.

[[BR]][[Image(img005.png)]][[BR]]''(Rys.5 Wykonanie skryptów na bazie Optimy'')[[BR]]

Po wykonaniu ich, wracamy do eDokumentów i klikamy polecenie ''Wykonaj''. Jeżeli wszystko przejdzie bez błędów, to powinien pojawić się taki komunikat:

[[BR]][[Image(img006.png)]][[BR]]''(Rys.6 Raport wykonania połączenia do systemu'')[[BR]]

[[BR]][[Image(img007.png)]][[BR]]''(Rys.7 Zdefiniowane połączenie do Optimy'')[[BR]]


To tyle w zakresie tworzenia połączenia z systemem Optima.








{{{
#!comment
Aby umożliwić synchronizację z systemem Optima należy wykonać poniższe czynności.

 *  zmiana stałej w pliku config.inc
 *  sprawdzenie danych w tabeli wsdl_config_table w systemie eDokumenty
 *  utworzenie tabeli kolejki w systemie Optima
 *  założenie triggerów na tabele
    * dok!__Dokument
    * adr!__Ewid
    * kh!__Kontrahent
 *  założenie widoków (eDokumenty > 2.0 RC15)
    * optima_export_all_contacts_documents_view.sql
    * optima_export_all_contacts_view.sql
    * optima_export_all_queued_contacts_documents_view.sql
    * optima_export_all_queued_contacts_view.sql

== Zmiana stałej ==
W pliku config.inc należy zmienić stałą "OPTIMA_DATA_SOURCE_DTSCNM" na
{{{
 define('OPTIMA_DATA_SOURCE_DTSCNM', 'nazwa');
}}}
gdzie nazwę należy zastąpić nazwą bazy danych systemu Optima

== Sprawdzenie danych w tabeli ==
Jeśli w systemie !eDokumenty tabela wsdl_config_table jest pusta należy wykonać odpowiedni skrypt SQL dla Optima znajduję się on w katalogu

{{{
apps\edokumenty\classes\BsConnect\install\data\optima_wsdl_ins.sql
}}}
następnie należy przejść do punktu "Konfiguracja tabeli wsdl_config_table" aby dokonać niezbędnych poprawek oraz ustawień według zaleceń.

== Ustawienia w tabeli wsdl_config_table ==
Następny krok to sprawdzenie tabeli wsdl_config_table oraz czy zawiera dane. W przypadku jeśli jest pusta proszę udać się na stronę z integracją wybranego systemu. Edycję ustawień połączeń możemy dokonać z interfejsu eDokumentów '''Ustawienia -> Systemy zewnętrzne'''

'''Opis kolumn'''
 *  Adres - adres pliku (serwera), jeśli w nazwie występuje słowo {host} należy ja zamienić na lokalizacje systemu eDokumenty standardowo jest to localhost, w przypadku vhosta należy podać port (np.: localhost:8080), jeśli system znajduje się katalogu różnym niż public należy dodać nazwę tego katalogu do nazwy (np.: localhost:8080/edokumenty), zmianę tą można dokonać z linii poleceń psql według ustawień instalacji [[br]]
{{{
UPDATE wsdl_config_table SET wsdl__ = replace(wsdl__, '{host}', 'localhost:8080/edokumenty');
}}}
 *  System - wskazuje na nazwę systemu dla którego konfigurowana jest dana metoda(zostawiamy bez zmian)
 *  Warunek SQL - warunek po jakim będą synchronizowane dane
   * dla akcji "Podwiąż kontakt" z lewej strony znaku równości wskazujemy kolumnę z systemu zew. natomiast z prawej w wąsach kolumnę z systemu eDokumenty 
{{{
(np. dla OPT!MY: Knt_Nip='{nip___}' AND Knt_Nazwa1='{name_1}' co oznacza, że będzie 
wyszukiwanie kontaktu w systemie OT!MA gdzie kolumna Knt_Nip będzie równa numerowi nip 
kontaktu z systemu eDokumenty (token {nip___} jest zamieniany na dane) itd)
}}}

   *  dla pozostałych akcji po lewej stronie jest nazwa kolumny z systemu eDokumety a z prawej token z maski(zobacz w katalogu apps\edokumenty\etc\sync) z jakimi zostanie zastąpiony.

Różnica między tymi metodami polega na tym iż w przypadku szukania kontaktu w systemie zew. należy wykonać zapytanie na zew. bazie dlatego z lewej strony są nazwy kolumn z systemu zew. a z prawej tokeny nazwy kolumn systemu eDokumenty, które zostaną zastąpione danymi wybranego kontaktu.

Reszta metod służy do porównania danych przychodzących z systemu zew. do systemu eDokumenty. Zapytanie jest wykonywane na bazie eDokumenty dlatego z lewej strony wstawiamy nazwę kolumny z tabeli z bazy eDokumenty natomiast z prawej dane z tablicy "mapy" z systemu zew. 

Tablica (mapa kolumn) ułatwia sparsowanie danych i lepsze rozeznanie przykład

{{{
apps\edokumenty\etc\sync\OPTIMA_columns_map.ini
Przykładowa konfiguracja tablicy mapy dla kontaktu dla OPT!MY
[contacts]
Knt_KntID = contid
Knt_Nazwa1 = name_1
Knt_Nazwa2 = name_2
Knt_Nazwa3 = name_2
Knt_Kraj = countr
Knt_Wojewodztwo = woj___
Knt_Powiat = powiat
Knt_Ulica = street
Knt_NrDomu = bldnum
Knt_NrLokalu = fltnum
Knt_Miasto = city__
Knt_KodPocztowy = code__
Knt_Nip = nip___
}}}
Oznacza to, że do dyspozycji będą dane pod danymi kluczami np.: klucz "nip_!__" będzie zawierał numer nip kontaktu z systemu zew. (w tym przypadku OPT!MA) dlatego warunek zapytania w bazie eDokumeny będzie miało postać
{{{
nip___='{nip___}'
}}}
Czyli szukamy kontaktu w bazie eDokumenty gdzię nip_!__ (lewa strona) kontaktu z bazy eDokumenty jest równy numerow nip z tabeli - mapy danych jakie otrzymamy z systemu zew. Należy pamiętać aby token w wąsach był dodatkowo w pojedyńczych apostrofach. Ze względu na różny typ danych i sposób w jaki mogą być potraktowane przez SQL (cyfry, liczby nie wymagają apostrofów natomiast litery tak!!) lepiej jest dla każdego typu danych w wąsach stosować apostrofy.

== Utworzenie tabeli kolejki ==
W systemie Optima (w bazie) wykonujemy skrypt z pliku 
{{{
apps\edokumenty\classes\BsConnect\install\sql\optima\optima_export_queue.sql

}}}
Po wykonaniu tego skryptu w systemie Optima powinna pojawić się dodatkowa tabela o nazwie export_queue.

== Założenie triggerów ==
Triggery mają za zadanie dodawać do kolejki dokumenty i kontaktu które zostały zmodyfikowane bądź dodane do systemu Optima. Triggery wykonujemy z załączników bądź w folderze
{{{
apps\edokumenty\classes\BsConnect\install\sql\optima
}}}
znajdują się pliki oryginalne. Kolejność ich wykonywania nie ma znaczenia. Po ich wykonaniu należy sprawdzić czy tabele dok__Dokument, adr__Ewid oraz Kontrahent posiadają dodatkowe triggery. Można tego dokonać za pomocą narzędzia SQL Manager Lite for SQL Server firmy EMS. (http://www.sqlmanager.net/)
[[BR]]Dla tabeli dokumentów
[[BR]]
[[Image(opDk.png, nolink)]] [[BR]]

Natomiast dla tabeli Kontrahenci [[BR]]
[[Image(opKh.png, nolink)]] [[BR]]

Możemy przetestować działanie mechanizmy poprzez dodanie do systemu Optima dokumentu lub kontrahenta i sprawdzeniu czy w tabeli export_queue pojawiły się wpisy.

== Założenie widoków ==
Począwszy od wersji 2.0 RC16 można decydować jakie dane mają być pobierane z systemu zew. poprzez modyfikacje specjalnych widoków przeznaczonych do synchronizacji. Widoki te są wymagane w celu prawidłowego funkcjonowania. Można je znaleźć w katalogu
{{{
edokumenty\classes\BsConnect\install\sql\optima\views
}}}

Można też je pobrać z załączonego niżej katalogu optima.zip. Widoki należy wykonać na bazie Optima (MsSQL).

''' Opis widoków '''
 *  optima_export_all_contacts_documents_view - wyświetla wszystkie dokumenty, które mają kontrahenta
 *  optima_export_all_contacts_view - wyświetla wszystkich kontrahentów
 *  optima_export_all_queued_contacts_documents_view - wyświetla wszystkie dokumenty, które mają kontrahenta oraz zostały zmodyfikowane(dodane do systemu) i znajdują się w tabeli export_queue w systemie zew.
 *  optima_export_all_queued_contacts_view - wyświetla wszystkich kontrahentów którzy zostali zmodyfikowani(dodani do systemu) i znajdują się w tabeli export_queue w systemie zew.

kolejność wykonywania nie ma znaczenia.

Widoki te można modyfikować według potrzeb(dodawać kolumny itd) eliminując w ten sposób dodatkową pracę ze strony programisty i aktualizacji w postaci nowej wersji ze zmodyfikowanym widokiem.
Widoki modyfikujemy jeśli klient zażyczy sobie aby z systemu zew. były pobierane dodatkowe dane, których podstawowa definicja nie uwzględniła. Następnie w pliku konfiguracyjnym 
{{{
OPTIMA_columns_map.ini
}}}
dodajemy kolejny wpis pod odpowiednim indeksem [contacts] - kontakty, [documents] - dokumenty z rzutowaniem danych z dodanej kolumny w widoku na kolumnę w systemie eDokumenty.

''' Jaka metoda jaki widok wykorzystuje '''
 *  Importuj wszystkie kontakty - Optima_export_all_contacts_view
 *  Aktualizuj dane - optima_export_all_queued_contacts_view
 *  Aktualizuj dokumenty - optima_export_all_queued_contacts_documents_view
 *  Aktualizuj dane kontaktów - optima_export_all_queued_contacts_view
 *  Aktualizuj dokumenty kontaktów - optima_export_all_queued_contacts_documents_view
 *  Pobierz wszystkie dokumenty - optima_export_all_contacts_documents_view

== Reset ==
Na wypadek gdyby wprowadzone zmiany miały być z jakiegoś względu wycofane z bazy optimy, należy wykonać plik reset_optima.sql który usuwa tabele export_queue, triggery oraz widoki.

== Raporty z parametrem klienta ==

Aby raportować rozrachunki z klientem, sprzedaż czy cokolwiek z nim związane można do tego użyć raportów ze zdefiniowanym zewnętrznym źródłem danych patrz: [wiki:DeployerGuide/Customization/AdvancedReporting tworzenie raportów SQL]
}}}