Program bs4 core udostępnia mechanizmy pozwalające na integrację z innymi systemami oraz importowanie danych z zewnętrznych źródeł.

Do bieżącej integracji może być wykorzystywane API programu. Natomiast w sytuacjach takich jak:

• migracja danych do bs4 core,
• jednorazowe zasilenie bazy,
• okresowa aktualizacja danych,
• cykliczna synchronizacja z innym systemem,

można wykorzystać konfigurowalny silnik importów danych.

W systemie można zdefiniować wiele niezależnych importów i uruchamiać je wielokrotnie.

2. Źródła danych #

Import może korzystać z różnych źródeł danych.

2.1. Pliki CSV #

Dane mogą być pobierane z pliku CSV.

Podczas konfiguracji można między innymi określić separator poszczególnych wartości w pliku, np. przecinek lub średnik.

2.2. Pliki XLSX #

Możliwy jest również import z plików XLSX, czyli arkuszy kompatybilnych z programem Microsoft Excel.

2.3. Zewnętrzna baza SQL #

Źródłem importu może być zewnętrzna baza danych SQL.

Połączenie z bazą jest realizowane za pośrednictwem wcześniej zdefiniowanego w bs4 core konektora.

2.4. Plik znajdujący się na serwerze #

Import może pobierać dane również z pliku umieszczonego na zdalnym serwerze.

2.5. Pole tekstowe #

Jako źródło można również wskazać dane przekazane w polu tekstowym.

3. Tworzenie nowego importu #

Zdefiniowany import można później wykorzystywać wielokrotnie, bez konieczności ponownego konfigurowania sposobu interpretowania danych.

3.1. Dodanie importu #

Aby utworzyć nowy import:

1. Przejdź do kartoteki Administrator.
2. Otwórz zestawienie Importy danych.
3. Kliknij Dodaj nowe.
4. Wskaż importowaną klasę obiektów.
5. Wybierz rodzaj źródła danych.
6. Uzupełnij pozostałe ustawienia właściwe dla wybranego źródła.

3.2. Wybór importowanej klasy #

W formularzu należy wskazać klasę obiektów, które mają zostać utworzone lub zaktualizowane w wyniku importu.

Przykładowo można wskazać klasę:

Kontrahent

W takim przypadku poszczególne wiersze źródła danych będą interpretowane jako dane kontrahentów.

3.3. Wybór rodzaju źródła #

W zależności od potrzeb można wskazać źródło takie jak:

• wgrywany plik CSV,
• wgrywany plik XLSX,
• baza SQL,
• plik na serwerze,
• pole tekstowe.

Jeżeli wybrano CSV lub XLSX, plik z danymi można wskazać już podczas dodawania importu.

Po zapisaniu nowego importu program przechodzi do jego kartoteki, w której dostępna jest szczegółowa konfiguracja.

4. Konfiguracja importu z pliku CSV lub XLSX #

W przypadku importu plikowego jednym z pierwszych kroków powinno być wgranie przykładowego pliku zawierającego dane w takiej samej strukturze, jaka będzie wykorzystywana później.

Plik na tym etapie służy przede wszystkim do skonfigurowania sposobu interpretowania poszczególnych kolumn. Samo jego wgranie nie oznacza jeszcze wykonania importu.

4.1. Wgranie pliku #

W kartotece importu znajduje się pole umożliwiające wskazanie pliku zawierającego dane.

Po jego wgraniu należy zapisać ustawienia importu.

4.2. Separator danych #

W przypadku CSV należy określić znak oddzielający wartości w poszczególnych kolumnach.

Przykładowo separatorem może być:

• przecinek,
• średnik.

Jeżeli plik zostanie nieprawidłowo podzielony na kolumny, w pierwszej kolejności należy sprawdzić właśnie ustawienie separatora.

4.3. Pierwszy wiersz etykiet #

Należy również określić, czy pierwszy wiersz pliku zawiera nazwy kolumn.

Jeżeli pierwszy wiersz zawiera nagłówki, w polu Pierwszy wiersz etykiet należy wskazać:

Tak

Wiersz zostanie wówczas pominięty podczas właściwego importowania rekordów.

Jeżeli natomiast pierwszy wiersz zawiera już właściwe dane, należy wybrać:

Nie

5. Weryfikacja poprawności odczytu danych #

Przed definiowaniem powiązań kolumn warto upewnić się, że bs4 core prawidłowo odczytał plik.

5.1. Zakładka „Podgląd test danych” #

Do tego celu służy zakładka:

Podgląd test danych

Powinna być w niej widoczna tabela zawierająca pierwsze rekordy wgranego pliku.

5.2. Sprawdzenie podziału na kolumny #

Należy zweryfikować między innymi, czy:

• dane znajdują się w odpowiednich kolumnach,
• poszczególne wartości nie zostały niepotrzebnie połączone,
• nagłówki zostały właściwie rozpoznane.

Jeżeli dane nie zostały poprawnie rozdzielone na kolumny, prawdopodobną przyczyną jest niewłaściwie ustawiony separator.

Po potwierdzeniu poprawnego odczytu można rozpocząć konfigurację poszczególnych pól importu.

6. Konfiguracja pobieranych pól #

Sposób interpretowania poszczególnych kolumn określa się w zakładce:

Pobierane pola

Dla każdej kolumny, którą chcemy obsłużyć, należy utworzyć odpowiednią konfigurację.

6.1. Dodanie pola importu #

Aby zdefiniować nowe powiązanie:

1. Przejdź do zakładki Pobierane pola.
2. Kliknij Dodaj nowe.
3. Wskaż kolumnę źródłową.
4. Określ docelowe pole w bs4 core.
5. W razie potrzeby skonfiguruj konwersję.
6. Określ działanie importu dla pola.

7. Pole źródłowe #

Na liście:

Pole źródłowe

należy wskazać kolumnę pochodzącą ze źródła danych.

Przykładowo może to być pierwsza kolumna arkusza.

8. Docelowe pole własne #

W polu:

Docelowe pole własne

wskazuje się miejsce, do którego wartość z wybranej kolumny ma zostać zapisana w bs4 core.

8.1. Przykład #

Jeżeli pierwsza kolumna pliku zawiera nazwę firmy, można skonfigurować ją tak, aby jej wartość trafiała do pola Nazwa obiektu klasy Kontrahent.

W ten sposób dla każdej kolumny określamy odpowiadające jej miejsce w strukturze danych bs4 core.

9. Konwersja importowanych danych #

Przed zapisaniem wartości można opcjonalnie wykonać jej konwersję.

9.1. Przykładowe zastosowania konwersji #

Konwersja pozwala między innymi:

• zmienić format daty,
• usunąć wybrane znaki,
• zamienić przecinki na kropki,
• przygotować wartość źródłową do formatu oczekiwanego przez bs4 core.

Pozwala to korzystać z danych pochodzących z systemów, w których sposób zapisu poszczególnych informacji różni się od formatu stosowanego w programie.

10. Import danych powiązanych #

Podczas importu kontrahentów można obsługiwać również dane, które nie znajdują się bezpośrednio w klasie Kontrahent, ale są z nią powiązane.

Przykładem mogą być:

• numer telefonu osoby kontrahenta,
• adres e-mail osoby kontrahenta.

W źródłowym arkuszu dane te często znajdują się w tym samym wierszu co podstawowe informacje o firmie. Mechanizm importu pozwala odpowiednio je zinterpretować i zapisać w strukturze danych programu.

11. Pole „Działanie” #

Jednym z najważniejszych ustawień każdego pobieranego pola jest:

Działanie

Określa ono, w jaki sposób bs4 core ma wykorzystać wartość z danej kolumny.

Dostępne są cztery warianty:

• Wstaw lub aktualizuj,
• Wstaw,
• Aktualizuj,
• Użyj do szukania.

12. Działanie „Wstaw” #

Opcja:

Wstaw

oznacza, że wartość pola ma być zapisana podczas tworzenia nowego rekordu.

Można dzięki temu wskazać dane, które powinny być uzupełniane przy dodawaniu nowych obiektów.

13. Działanie „Aktualizuj” #

Opcja:

Aktualizuj

oznacza, że dane mają być zmieniane w rekordzie, który już istnieje w bs4 core i został odnaleziony podczas importu.

13.1. Przykład #

Jeżeli istniejącego kontrahenta rozpoznajemy po NIP-ie, a dla pola Nazwa ustawimy działanie Aktualizuj, program po odnalezieniu kontrahenta zmieni jego nazwę zgodnie z wartością z importowanego pliku.

14. Działanie „Wstaw lub aktualizuj” #

Opcja:

Wstaw lub aktualizuj

łączy obydwa powyższe zastosowania.

Pole:

• zostanie zapisane podczas tworzenia nowego obiektu,
• zostanie zaktualizowane, jeżeli import dotyczy obiektu już istniejącego.

14.1. Przykład #

Jeżeli dla pola Nazwa wybrano Wstaw lub aktualizuj, nazwa:

• zostanie dodana dla nowego kontrahenta,
• zostanie zmieniona dla kontrahenta odnalezionego już w bazie.

15. Działanie „Użyj do szukania” #

Opcja:

Użyj do szukania

ma szczególne znaczenie. Wskazuje pola służące do rozpoznania, czy importowany rekord ma już swój odpowiednik w bazie bs4 core.

15.1. Przykład wyszukiwania kontrahenta po NIP-ie #

Typowym identyfikatorem kontrahenta może być numer NIP.

Jeżeli dla kolumny zawierającej NIP ustawimy:

Użyj do szukania

program:

1. pobierze NIP z importowanego wiersza,
2. przeszuka odpowiednie pole NIP w bazie bs4 core,
3. sprawdzi, czy istnieje już rekord o tej samej wartości,
4. jeżeli znajdzie odpowiednik, potraktuje rekord jako istniejący,
5. wykona aktualizację tych pól, dla których skonfigurowano odpowiednie działanie.

16. Brak pól „Użyj do szukania” #

Nie ma obowiązku definiowania pola wykorzystywanego do wyszukiwania istniejących rekordów.

Jeżeli żadne pole nie zostanie oznaczone jako Użyj do szukania, każdy importowany wiersz będzie traktowany jako nowy rekord.

Rozwiązanie takie może być właściwe przy jednorazowej migracji danych, jeżeli wiadomo, że źródło nie zawiera rekordów znajdujących się już w systemie.

17. Wyszukiwanie po kilku polach #

Jako Użyj do szukania można oznaczyć więcej niż jedno pole.

W takim przypadku program stosuje pomiędzy nimi warunek logiczny i.

17.1. Przykład #

Jeżeli jako pola wyszukiwania ustawimy jednocześnie:

• NIP,
• nazwę kontrahenta,

program uzna rekord za istniejący dopiero wtedy, gdy znajdzie kontrahenta posiadającego jednocześnie:

• identyczny NIP,
• identyczną nazwę.

Pozwala to precyzyjniej określić kryteria identyfikujące istniejące rekordy.

18. Import nowych i aktualizacja istniejących danych #

Połączenie działań:

• Użyj do szukania,
• Wstaw,
• Aktualizuj,
• Wstaw lub aktualizuj

pozwala wykorzystać jeden mechanizm zarówno do wprowadzania nowych danych, jak i aktualizowania istniejącej bazy.

Dla każdego pola można niezależnie określić, jak powinno zachowywać się w obu sytuacjach.

19. Konfiguracja wielu pól #

Operację definiowania pobieranego pola należy powtórzyć dla wszystkich kolumn, które mają zostać wykorzystane podczas importu.

Nie ma konieczności obsługiwania wszystkich kolumn znajdujących się w źródłowym pliku.

Jeżeli arkusz zawiera więcej informacji niż potrzebujemy, można zdefiniować powiązania wyłącznie dla wybranych pól.

Pozostałe kolumny zostaną pominięte.

20. Wykonanie importu #

Po skonfigurowaniu wszystkich potrzebnych pól można uruchomić właściwy import.

20.1. Ręczne wykonanie #

Aby rozpocząć import:

1. Upewnij się, że został wgrany właściwy plik lub skonfigurowane inne źródło danych.
2. Przejdź do zakładki Wykonaj.
3. Potwierdź opcję Wykonaj import.

Program przetworzy dane zgodnie z przygotowaną konfiguracją.

21. Wielokrotne wykorzystywanie importu #

Raz przygotowana konfiguracja może być używana ponownie.

Jeżeli struktura pliku nie uległa zmianie:

1. otwórz wcześniej przygotowany import,
2. podmień plik na jego aktualną wersję,
3. uruchom ponownie opcję Wykonaj.

Nie trzeba ponownie konfigurować mapowania kolumn ani działań.

Dzięki temu import może być wykorzystywany zarówno jednorazowo, jak i do regularnych aktualizacji danych.

22. Zaawansowane ustawienia importu #

Konfiguracja importu zawiera również dodatkowe opcje przeznaczone do bardziej zaawansowanych zastosowań.

22.1. Triggery wykonywane przed i po imporcie #

Możliwe jest uruchamianie triggerów:

• przed wykonaniem importu,
• po wykonaniu importu.

Pozwala to powiązać proces importowania z innymi działaniami wykonywanymi przez bs4 core.

22.2. Kodowanie znaków #

Dla importowanego pliku można narzucić konkretne kodowanie znaków.

Przykładem jest:

CP1250

Może to być potrzebne w przypadku starszych źródeł danych lub plików generowanych przez systemy korzystające z określonego standardu kodowania.

23. Import z zewnętrznej bazy SQL #

Alternatywą dla importowania pliku jest pobieranie danych bezpośrednio z zewnętrznej bazy SQL.

23.1. Konektor do bazy danych #

Połączenia z zewnętrznymi bazami są definiowane w bs4 core jako konektory.

W kartotece Administrator można utworzyć konektor i podać w nim parametry potrzebne do połączenia z określoną bazą.

23.2. Wskazanie konektora w imporcie #

Na poziomie konfiguracji samego importu nie definiuje się ponownie parametrów połączenia.

Należy jedynie wskazać jeden z wcześniej utworzonych konektorów.

Pozwala to oddzielić konfigurację techniczną połączenia od logiki konkretnego importu.

24. Ręczne i automatyczne uruchamianie importów #

Import można wykonywać zarówno ręcznie, jak i automatycznie.

24.1. Uruchamianie ad hoc #

Aby uruchomić import ręcznie:

1. Otwórz zestawienie Importy danych.
2. Wejdź do wybranego importu.
3. Kliknij Wykonaj.

24.2. Uruchamianie z triggera #

Wykonanie importu można wywołać za pomocą odpowiedniej komendy triggera.

Pozwala to uruchamiać import automatycznie po spełnieniu określonych warunków lub w ramach większego procesu.

24.3. Prace cykliczne #

Import może zostać również uruchomiony w ramach pracy cyklicznej.

W konfiguracji można określić między innymi:

• dni miesiąca,
• dni tygodnia,
• godziny wykonania.

Rozwiązanie to jest szczególnie przydatne w przypadku źródeł, których zawartość jest regularnie aktualizowana.

25. Przykład cyklicznej aktualizacji danych z SQL #

Załóżmy, że bs4 core jest połączony z zewnętrzną bazą danych, w której codziennie zmieniają się dane kontrahentów.

Można wtedy:

1. utworzyć konektor do zewnętrznej bazy,
2. zdefiniować import wykorzystujący ten konektor,
3. wskazać pola pozwalające znaleźć istniejących kontrahentów,
4. określić pola podlegające aktualizacji,
5. utworzyć pracę cykliczną uruchamiającą import o wybranej godzinie.

W ten sposób dane w bs4 core mogą być okresowo aktualizowane na podstawie informacji znajdujących się w systemie zewnętrznym.

26. Podsumowanie #

Mechanizm importów w bs4 core pozwala konfigurować powtarzalne procesy wprowadzania oraz aktualizowania danych.

Import może korzystać między innymi z:

• plików CSV,
• plików XLSX,
• zewnętrznych baz SQL,
• plików znajdujących się na serwerze,
• danych tekstowych.

Kluczowym etapem konfiguracji jest przypisanie kolumn źródłowych do odpowiednich pól bs4 core oraz określenie działania dla każdego z nich.

Za pomocą opcji Użyj do szukania można rozpoznawać rekordy już istniejące w bazie, a następnie zdecydować, które dane powinny być:

• tylko dodawane,
• tylko aktualizowane,
• zarówno dodawane, jak i aktualizowane.

Po przygotowaniu konfiguracji import może być wykorzystywany wielokrotnie i uruchamiany:

• ręcznie,
• z triggerów,
• automatycznie w ramach prac cyklicznych.

Dzięki temu ten sam mechanizm może służyć zarówno do jednorazowej migracji danych, jak i do regularnego aktualizowania informacji w bs4 core.