= [wiki:DeployerGuide Przewodnik wdrożeniowca] > Synchronizacja kontrahentów = #kontrahent

[wiki:DeployerGuide/Customization/Integration Strona główna Integracji][[br]]
[wiki:DeployerGuide/Customization/Integration/Import Strona główna sekcji importu danych]

=== Menu ===
 1. [#wstep Wstęp]
 2. [#kontrahenci Kontrahenci]
 3. [#adresy Adresy]
 4. [#konta_bankowe Konta bankowe]
 5. [#osoby Osoby kontaktowe]
 6. [#opiekun Opiekun kontrahenta]


== Wstęp == #wstep
Niniejsza sekcja opisuje synchronizację Kontrahentów.
Do tego można zaliczyć pobieranie :
 * kartotek kontrahentów,
 * kont bankowych kontrahentów,
 * osób kontaktowych kontrahenta

Dla każdego obszaru zostanie pokazane:
 * przykładowy wygląd widoku z definicją kluczowych kolumn
 * mapowanie kolumn
 * przykład szablonu dla różnych akcji synchronizacji.

Niniejszy opis dotyczy integracji przy pomocy połączenia typu DB.

[#kontrahent Powrót do menu]

== Kontrahenci == #kontrahenci

=== Widoki (perspektywy) ===

Do obsługi pobierania danych kontrahentów należy po stronie zewnętrznego systemu (w odpowiednim schemacie - tym samym, co tabela bs_export_queue) zdefiniować dwa widoki (perspektywy):
 * '''bs_contacts_view'''
 * '''bs_modified_contacts_view'''

Perspektywa '''bs_contacts_view zawiera kartoteki wszystkich kontrahentów, natomiast '''bs_modified_contacts_view''' jest złączeniem wewnętrznym tabeli '''bs_export_queue''' z widokiem '''bs_contacts_view'''. Definicja takiego widoku zostanie przedstawiona poniżej.
Przykładowy widok '''bs_contacts_view''' może wyglądać w sposób następujący:

[[Image(cnt_001.png)]][[BR]]''Rys. 1. Przykład widoku bs_contacts_view''

W definicji widoku zaleca się następujących kolumn (pogrubione kolumny są wymagane):
||Kolumna||Typ danych||Ograniczenia||Opis||Wymagalność||
||'''bs_contact_id'''||int||PRIMARY KEY (UNIQUE, NOT NULL)||Kolumna z identyfikatorem numerycznym typu całkowitego. ||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||
||'''Nazwa'''||varchar(n)||NOT NULL||Nazwa kontrahenta||Kolumna wymagana||
||Skrot||varchar(n)||NOT NULL (UNIQUE)||Skrót nazwy kontrahenta||Opcjonalna, służyć może jako kolumna szablonowa do porównań istnienia kontrahentów||
||NIP||varchar(n)||NOT NULL (UNIQUE)||NIP kontrahenta||Opcjonalna, służyć może jako kolumna szablonowa do porównań istnienia kontrahentów||

[#kontrahent Powrót do menu]

=== Mapowanie kolumn ===
W lokalizacji {{{ public_html/apps/edokumenty/etc/sync }}} należy utworzyć pliki .ini o nazwie ''x_columns_map.ini'' , gdzie "x" oznacza numer połączenia z systemem zewnętrznym. Np. połączenie nr. 1 będzie szukać pliku 1_colaumns_map.ini.
Dla kontrahenta przykładowe mapowanie winno wyglądać:

[[Image(cnt_002.png)]][[BR]]''Rys. 2. Przykład mapowania dla kontrahenta''

Jak widać na powyższym obrazku mapowania składa się z dwóch części:
 * nazwy sekcji [CONTACT]
 * mapowania kolumn
{{{
#!ini
nazwa = name_1
skrot = name_2
nip_bk = nip___
regon = regon_
pesel = pesel_
kraj = countr
powiat = powiat
gmina = gmina_
ulica = street
kod_pocztowy = code__
miasto = city__
wojewodztwo = woj___
telefon = ph_num
fax = faxnum
}}}


W mapowaniu kolumn należy mieć na uwadze to, że po lewej stronie znaku "=" znajdują się kolumny z widoku bs_contacts_view, a po prawej nazwy kolumn z bazy systemu eDokumenty (z kilkoma wyjątkami, ale dotyczącymi innych obszarów).
W pliku tym nie wprowadzamy kolumn kluczowych, czyli w tym przypadku '''bs_contact_id''' !!!

W poniższej tabelce przedstawiono przykłady pól z systemu eDokumenty (po prawej stronie znaku "=") z opisem:

||Nazwa pola|||Opis pola||
||name_1||Nazwa kontrahenta||
||name_2||Skrót (akronim) kontrahenta||
||symbol||Symbol kontrahenta||
||street||Ulica domyślnego/podstawowego adresu kontrahenta||
||bldnum||Numer budynku domyślnego/podstawowego adresu kontrahenta||
||fltnum||Numer lokalu domyślnego/podstawowego adresu kontrahenta||
||code__||Kod pocztowy domyślnego/podstawowego adresu kontrahenta||
||{{{city__}}}||Miejscowość domyślnego/podstawowego adresu kontrahenta||
||{{{post__}}}||Poczta domyślnego/podstawowego adresu kontrahenta||
||gmina_||Gmina domyślnego/podstawowego adresu kontrahenta||
||powiat||Nazwa powiatu domyślnego/podstawowego adresu kontrahenta||
||woj___||Województwo (nazwa powinna się zgadzać ze słownikiem województw ''Ustawienia>Panel Sterowania)||
||countr||Kraj (nazwa powinna się zgadzać ze słownikiem krajów ''Ustawienia>Panel Sterowania)||
||nip___||Numer NIP kontrahenta||
||regon_||Numer REGON kontrahenta||
||pesel_||Numer PESEL kontrahenta||
||ph_num||Numer stacjonarny kontrahenta||
||faxnum||Numer faksu kontrahenta||
||email_||Adres email kontrahenta||
||websit||Adresy strony WWW kontrahenta||
||saldo_||Saldo obrotów z kontrahentem||

Uwaga! Jedna kolumna nie może być podwójnie mapowana (do dwóch różnych pól).

[#kontrahent Powrót do menu]

=== konfigurowanie akcji ===
Po stworzeniu pliku mapowania kolumn następnym krokiem jest konfiguracja akcji pobierania danych.
W tym celu należy:
 1. Wejść do konfiguracji Połączeń z systemami zewnętrznymi {{{Narzędzia > Połączenia z systemami zewnętrznymi}}}. 
 2. W otwartym oknie wybiera się utworzone połączenie i otwieramy je do edycji. 
 3. W oknie edycji połączenia należy przejść na zakładkę Synchronizacja. 
 4. Na zakładce Synchronizacja klikając Nowy dodajemy obiekt: '''Klient''' (dzieje się to w małlym okienku pt. ''Nowy obiekt synchronizacji''). Po zatwierdzeniu dodania obiektu kreator pyta się, czy dodać domyślne akcje (dodaje wszystkie akcje zdefiniowane na tym obiekcie) oraz czy przejść do konfiguracji.
 5. Wybierając wybraną akcję należy kliknąć ikonę ołówka w celu wyedytowania jej.
 6. Istotną kwestią jest wprowadzenie szablonu mapowania (zaznaczony obszar na poniższym obrazku). Jeżeli przycisk przy polu Użyj szablonu jest zaznaczony, to szablon musi być wprowadzony. W przeciwnym przypadku należy odznaczyć pole Użyj 
szablonu.


[[Image(cnt_003.png)]][[BR]]''Rys. 3. Konfiguracja akcji Pobierania wszystkich klientów''

Przeznaczenie funkcji ''Użyj szablonu'' jest następujące. Na podstawie szablonu system wyszukuje, czy w bazie systemu eDokumenty istnieje już klient o takich samych danych, co aktualnie pobierane z systemu zewnętrznego. Konstrukcja jest następująca:
{{{
warunek po stornie PostgreSQL = warunek po stronie SZBD systemu zewnętrznego
}}}
Poniżej przedstawiono kilka przykładowych szablonów mapowania:
{{{
#!sql
-- Przykład 1.
trim(nip___) = ltrim(rtrim('{nip___}'))
-- Przykład 2.
lower(symbol) = lower('{symbol}')
}}}

W przykładzie 1. następuje porównanie pól nip-u (usuwanie zbędnych spacji przed i po numeru NIP). Lewa strona warunku to kolumna ''nip!___'' w bazie eDokumenty w tabeli 
''contacts''. Po prawej stronie jest brana pod uwagę prawa kolumna z pliku mapowana (Uwaga, dla niektórych akcji ta zasada jest inna!!!). Dodatkowo muszą być wykorzystywane funkcje dostępne w SZBD Systemu zewnętrznego (tutaj z MS SQL Server).

Analogicznie w przykładzie 2. Tu bierzemy pod uwagę pole ''symbol'' i dla ujednolicenia wyszukiwania sprawdzamy wg. małych liter w symbolu.

Opcji wyszukiwania jest wiele. Powyższe stanowią najczęściej stosowane przypadki.

[#kontrahent Powrót do menu]

== Adresy kontrahenta == #adresy

Pobieranie adresów kontrahenta jest ściśle związane z pobieraniem kartotek kontrahentów.
'''UWAGA !!! Widok ten nie może zawierać adresów, które są w widoku bs_contacts_view'''

=== Widoki (perspektywy) ===
Na potrzeby pobierania adresów kontrahenta należy w schemacie integracji utworzyć widok:
 * '''bs_contact_addresses_view'''

W widoku wymaganym jest zdefiniowanie następujących kolumn:

||Kolumna||Typ danych||Ograniczenia||Opis||Wymagalność||
||'''bs_address_id'''||int||PRIMARY KEY (UNIQUE, NOT NULL)||Identyfikator numeryczny adresu kontrahenta||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||
||'''bs_contact_id'''||int|| NOT NULL||Kolumna z identyfikatorem kontrahenta numerycznym typu całkowitego. ||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||

[[Image(cnt_004.png)]][[BR]]''Rys. 4. Przykładowy widok adresów kontrahentów''

[#kontrahent Powrót do menu]

=== Mapowanie kolumn ===

Mapowanie kolumn odbywa się w tym samym pliku {{{ x_columns_map.ini }}}, co mapowanie kontrahenta.Przykładowy schemat mapowania przedstawiony na poniższym rysunku

[[Image(cnt_005.png)]][[BR]]''Rys. 5. Przykład mapowania adresów kontrahentów''

Mapowanie kolumn adresów kontrahenta należy rozpocząć od zdefiniowania w pliku sekcji [CONTACT_ADDRESS]

{{{
#!ini
[CONTACT_ADDRESS] 
ulica = street_
miasto = city__
kod_pocztowy = code__
poczta = post__
powiat = powiat
gmina = gmina_
wojewodztwo = woj___
kraj = countr
odleglosc = distkm
}}}

||Nazwa pola|||Opis pola||
||street||Ulica domyślnego/podstawowego adresu kontrahenta||
||bldnum||Numer budynku domyślnego/podstawowego adresu kontrahenta||
||fltnum||Numer lokalu domyślnego/podstawowego adresu kontrahenta||
||!code__||Kod pocztowy domyślnego/podstawowego adresu kontrahenta||
||!city__||Miejscowość domyślnego/podstawowego adresu kontrahenta||
||post__||Poczta domyślnego/podstawowego adresu kontrahenta||
||gmina_||Gmina domyślnego/podstawowego adresu kontrahenta||
||powiat||Nazwa powiatu domyślnego/podstawowego adresu kontrahenta||
||woj___||Województwo (nazwa powinna się zgadzać ze słownikiem województw ''Ustawienia>Panel Sterowania)||
||countr||Kraj (nazwa powinna się zgadzać ze słownikiem krajów ''Ustawienia>Panel Sterowania)||
||distkm||Dystans w kilometrach||
||is_def|| Wartość 0,1 lub t,f - znacznik domyślności danego adresu||
 
[#kontrahent Powrót do menu]

=== konfigurowanie pobierania ===

Pobieranie adresów kontrahentów nie posiada swoich dedykowanych akcji. Jest ono powiązane ściśle z pobieraniem samych kartotek kontrahentów.
Aby skonfigurować pobieranie adresów należy:
 1. Wejść do konfiguracji Połączeń z systemami zewnętrznymi {{{Narzędzia > Połączenia z systemami zewnętrznymi}}}. 
 2. Wyedytować połączenie. Otworzy się okno z obiektami synchronizacji.
 3. Zaznaczyć pojedynczym kliknięciem obiekt: ''Klient'', a następnie wyedytować go.
 4. Na głównej zakładce należy wybrać opcję ''Pobierz adresy''

Dodatkowo od wersji 4.2.xx pojawiła się opcja łączenia adresów. Oznacza to, że w przypadku zaistnienia takiego samego adresu (np. ulica + kod pocztowy) to taki adres dostaje dodatkowe powiązania, natomiast nie jest duplikowany w bazie danych.
Przykładowy warunek może być następujący:
{{{
#!sql
lower(street) = lower('{street}') AND COALESCE(regexp_replace(code__, '[ |-]*', '', 'g'), '') = COALESCE(regexp_replace('{code__}', '[ |-]*', '', 'g'), '')
}}}

Poniższy rysunek przedstawia konfigurowanie akcji pobierania adresów kontrahenta:

[[Image(cnt_006.png)]][[BR]]''Rys. 6. Konfiguracja pobierania adresów kontrahentów''

[#kontrahent Powrót do menu]

== Konta bankowe == #konta_bankowe

Analogicznie jak pobieranie adresów kontrahenta, import kont bankowych jest ściśle związane z pobieraniem kartotek kontrahentów.

=== Widoki (perspektywy) ===
Na potrzeby pobierania adresów kontrahenta należy w schemacie integracji utworzyć widok:
 * '''bs_bank_accounts_view'''

W widoku wymaganym jest zdefiniowanie następujących kolumn:

||Kolumna||Typ danych||Ograniczenia||Opis||Wymagalność||
||'''bs_bank_account_id'''||int||PRIMARY KEY (UNIQUE, NOT NULL)||Identyfikator numeryczny konta bankowego kontrahenta||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||
||'''bs_contact_id'''||int|| NOT NULL||Kolumna z identyfikatorem kontrahenta numerycznym typu całkowitego. ||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||

[[Image(cnt_007.png)]][[BR]]''Rys. 7. Przykładowy widok kont bankowych kontrahentów''

[#kontrahent Powrót do menu]

=== Mapowanie kolumn ===

Mapowanie kolumn odbywa się w tym samym pliku {{{ x_columns_map.ini }}}, co mapowanie kontrahenta.Przykładowy schemat mapowania przedstawiony na poniższym rysunku

[[Image(cnt_008.png)]][[BR]]''Rys. 8. Przykład mapowania kont bankowych kontrahentów''

Mapowanie kolumn kont bankowych kontrahenta należy rozpocząć od zdefiniowania w pliku sekcji [BANK_ACCOUNT]
{{{
#!ini
[BANK_ACCOUNT]
nazwa_banku = baname
numer_konta = number
waluta = cursmb
domyslne = is_def
}}}

||Nazwa pola||Opis pola||
||baname||Nazwa banku - tytuł konta bankowego||
||number||Numer konta bankowego||
||cursmb||Waluta konta||
||is_def|| Wartość 0,1 lub t,f - znacznik domyślności danego konta bankowego||
 
[#kontrahent Powrót do menu]

=== konfigurowanie pobierania ===

Pobieranie kont bankowych kontrahentów nie posiada swoich dedykowanych akcji. Jest ono powiązane ściśle z pobieraniem samych kartotek kontrahentów.
Aby skonfigurować pobieranie kont należy:
 1. Wejść do konfiguracji Połączeń z systemami zewnętrznymi {{{Narzędzia > Połączenia z systemami zewnętrznymi}}}. 
 2. Wyedytować połączenie. Otworzy się okno z obiektami synchronizacji.
 3. Zaznaczyć pojedynczym kliknięciem obiekt: ''Klient'', a następnie wyedytować go.
 4. Na głównej zakładce należy wybrać opcję ''Pobierz konta''

Poniższy rysunek przedstawia konfigurowanie akcji pobierania kont bankowych kontrahenta:

[[Image(cnt_009.png)]][[BR]]''Rys. 9. Konfiguracja pobierania kont bankowych kontrahentów''

[#kontrahent Powrót do menu]

== Osoby kontaktowe == #osoby
Pobieranie osób kontaktowych jest wyodrębnionym procesem w synchronizacji BSConnect. Wykonuje się ją w module Kontakty.

=== Widok ===

Na wstępie potrzebne jest utworzenie widoków:
 * '''bs_contact_persons_view'''
 * '''bs_modified_contact_persons_view'''

Schemat takiego widoku przedstawiono na poniższym obrazku:

[[Image(cnt_010.png)]][[BR]]''Rys. 10. Przykład widoku osób kontaktowych''

W widoku wymaganym jest zdefiniowanie następujących kolumn:

||Kolumna||Typ danych||Ograniczenia||Opis||Wymagalność||
||'''bs_contact_person_id'''||int||PRIMARY KEY (UNIQUE, NOT NULL)||Identyfikator numeryczny osoby kontaktowej||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||
||'''bs_contact_id'''||int|| NOT NULL||Kolumna z identyfikatorem kontrahenta numerycznym typu całkowitego. ||Kolumna wymagana.'''Nazwa kolumny nie może być zmieniona'''||
||osoba ({{{data__}}})||varchar||NOT NULL||Imię i nazwisko osoby kontaktowej.||Kolumna wymagana, wykorzystywana w procesie integracji jako szablon porównań||

[#kontrahent Powrót do menu]
=== Mapowanie kolumn ===
Mapowanie kolumn dla Osoby kontaktowej przedstawia się następująco:
{{{
#!ini
[CONTACTPERSON]
imie = firnam
nazwisko = lasnam
tytul = place_
email = email_
telefon = ph_num
osoba = data__
}}}

Szablon mapowania osób kontaktowych jest nastepujący:
{{{
#!sql
lower(data__) = lower('{data__}')
}}}

||Nazwa pola||Opis pola||
||{{{data__}}}||Imię i nazwisko osoby kontaktowej||
||firnam||Imię osoby kontaktowej||
||lasnam||Nazwisko osoby kontaktowej||
||place_||Stanowisko||
||email_||Adres(y) email||
||ph_num||numer telefonu||



[#kontrahent Powrót do menu]


== Opiekun kontrahenta == #opiekun

Kolumnę wystawioną w zew. systemie jako opiekun należy mapować na macrtk.

Logika wiązania z użytkownikiem w systemie eDokumenty jest taka:
- jeśli wartość jaka przyjdzie z zew. systemu to INTEGER wtedy traktowane jest jako usr_id i takie coś jest wstawiane do macrtk - trzeba pamiętać aby występowało w tabeli users

- jeśli wartość jako przyjdzie z zew. systemu nie jest typu INTEGER (czyli TEXT np. akowal lub anna kowal) wtedy system sprawdza czy w tej wartości jest spacja. Jeśli nie ma spacji (czyli np. akowal) wtedy wartość traktowana jest jako login i sprawdzana w kolumnie users.usrnam. Jeśli jest spacja wtedy wartość traktowana jest jako imię plus nazwisko i sprawdzana jako 

{{{
users.firnam||' '||lusers.asnam = '{WARTOŚĆ}'.
}}}


[#kontrahent Powrót do menu]