Przewodnik wdrożeniowca > Synchronizacja kontrahentów

Strona główna Integracji
Strona główna sekcji importu danych

Menu

1. Wstęp
2. Kontrahenci
3. Adresy
4. Konta bankowe
5. Osoby kontaktowe
6. Opiekun kontrahenta

Wstęp

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.

Powrót do menu

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:

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

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ć:

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

  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).

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.

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:

-- 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.

Powrót do menu

Adresy kontrahenta

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

Rys. 4. Przykładowy widok adresów kontrahentów

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

Rys. 5. Przykład mapowania adresów kontrahentów

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

[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

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:

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:

Rys. 6. Konfiguracja pobierania adresów kontrahentów

Powrót do menu

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

Rys. 7. Przykładowy widok kont bankowych kontrahentów

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

Rys. 8. Przykład mapowania kont bankowych kontrahentów

Mapowanie kolumn kont bankowych kontrahenta należy rozpocząć od zdefiniowania w pliku sekcji [BANK_ACCOUNT]

[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

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:

Rys. 9. Konfiguracja pobierania kont bankowych kontrahentów

Powrót do menu

Osoby kontaktowe

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:

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ń

Powrót do menu

Mapowanie kolumn

Mapowanie kolumn dla Osoby kontaktowej przedstawia się następująco:

[CONTACTPERSON]
imie = firnam
nazwisko = lasnam
tytul = place_
email = email_
telefon = ph_num
osoba = data__

Szablon mapowania osób kontaktowych jest nastepujący:

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

Powrót do menu

Opiekun kontrahenta

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ŚĆ}'.

Powrót do menu