# Jeden importer plików XML obsługuje kilka formatów, ale nowy format wymaga kodu > Importer plików XML przenosi plik do archiwum, a pozycje zapisuje jako zlecenie wydania w buforze. Konfiguracja zmienia katalog, ale nowy format wymaga kodu. Adres strony: https://magazyn.softwarestudio.com.pl/import-komunikatow-xml-jeden-mechanizm-kilka-formatow/ --- W opisywanym wdrożeniu jeden importer obsługuje kilka formatów komunikatów, bo wspólny jest cały przebieg: katalog z plikami, archiwum, rozpoznanie wersji, rozpłaszczenie do wierszy i zapis przez zapytanie z konfiguracji. Konfiguracja zmienia katalog, zapytanie i procedurę, ale nowy format wymaga nowych klas w kodzie. Plik XML od partnera wchodzi do WMS inną drogą niż zlecenie wpisane w formularzu. W opisywanym wdrożeniu przechodzi przez importer, który obsługuje kilka formatów komunikatów i zawsze kończy ten sam przebieg: pozycje plików trafiają do zlecenia wydania w buforze, do uzupełnienia i zatwierdzenia przez magazyn. Ten opis przygotowaliśmy dla działu IT i kierownika projektu. Rozdzielamy w nim to, co ustawia konfiguracja, od tego, co opisuje kod, a przykłady są wymyślone. Inne kanały wymiany danych opisują strony o [wymianie plików CSV z ERP](/integracja-wms-erp-sftp-csv/) i o [integracji EDI z WMS](/integracja-edi-wms-sftp/), a zlecenia składane w portalu przez klienta artykuł o [portalu klienta w czterech wariantach](https://system.wms.net.pl/portal-klienta-wms-cztery-modele-wspolpracy-i-odciecie-danych/). ## Import startuje z menu i czyta pliki z katalogu Import uruchamia pozycja menu magazynu. Jej adres niesie cztery parametry: typ komunikatu, źródło pliku, identyfikator zapytania zapisującego i identyfikator zapytania zwracającego katalog. Nic nie startuje automatycznie: strona pokazuje komunikat o oczekiwaniu, a po zakończeniu tekst wyniku. W menu są aktywne dwie pozycje importu: awizo wysyłki i dokument sprzedaży. Dokument sprzedaży występuje w dwóch generacjach formatu, a obie obsługuje ta sama pozycja menu. Katalog z plikami zwraca zapytanie z konfiguracji, a ścieżka jest względem katalogu aplikacji na serwerze. Importer czyta pliki z tego katalogu i nie pobiera ich ze zdalnego serwera, więc pliki muszą tam trafić z zewnątrz. Za dostarczenie ich odpowiada więc proces poza WMS, a sam importer zaczyna pracę dopiero po kliknięciu pozycji menu. Pliki zamiast dokumentu wpisanego w formularzu to nie jedyna droga wejścia danych: z etykiet dostawcy powstaje na przykład PZ opisane w artykule o [PZ z danych etykiet dostawcy](https://system.wms.net.pl/pz-z-danych-etykiet-dostawcy-cztery-kontrole/). ## Plik trafia do archiwum, zanim zostanie sparsowany Jedno uruchomienie przetwarza pliki z katalogu po kolei. Dla każdego pliku importer robi kopię w katalogu roboczym aplikacji, z numerem przebiegu w nazwie, i przenosi oryginał do równoległego katalogu archiwum o takiej samej strukturze jak katalog wejściowy. Archiwizacja następuje przed parsowaniem. Błąd struktury pliku kończy przebieg. System zapisuje go w rejestrze błędów i pokazuje „Struktura pliku XML jest błędna, nie udało się sparsować.”. Kolejnych plików nie przetwarza do następnego uruchomienia, a plik z błędem leży już wtedy w archiwum. Przykład (wymyślony): w katalogu czekają trzy pliki, a drugi ma uszkodzoną strukturę. Pierwszy zostaje zaimportowany i trafia do archiwum. Drugi trafia do archiwum, ale parsowanie kończy się błędem i komunikatem. Trzeci zostaje w katalogu wejściowym do następnego uruchomienia importu. Bez błędu importer bierze kolejne pliki, aż katalog się opróżni, a wynik kończy się zdaniem „Nie znaleziono więcej plików do importu.”. Dziennik zdarzeń dostaje wpisy „Pobrano plik do importu, rozpoczynam parsowanie.” i „Parsowanie zakończone sukcesem.”. ## Wersję dokumentu importer rozpoznaje po treści pliku Dla dokumentu sprzedaży importer rozpoznaje wersję po treści pliku. Obecność znacznika głównego starszego formatu oznacza wersję starszą, a jego brak wersję nowszą. Potem plik jest deserializowany do klas właściwych dla typu. Wersji nie wskazuje więc osobna pozycja menu. Obie generacje formatu przechodzą przez tę samą pozycję, a o dalszej drodze pliku rozstrzyga to, co w nim zapisano. ## Każda pozycja towarowa przechodzi przez szablon zapytania Komunikat rozpłaszcza się do tabeli wierszy: jeden wiersz to jedna pozycja towarowa, a dane nagłówka są powielone w każdym wierszu. Dla każdego wiersza importer bierze szablon zapytania zapisującego z tabeli kodów i podstawia wartości pól oraz pięć zmiennych globalnych: numer przebiegu, login, nazwę pliku, numer pliku i identyfikator dokumentu. Wszystkie formaty kończą jako zlecenie wydania w buforze, do uzupełnienia i zatwierdzenia przez magazyn. Numer pliku staje się numerem referencyjnym zlecenia, więc jeden plik daje jedno zlecenie. Pozycje wiążą się z kartoteką po kodzie EAN w kartotece właściciela towaru. Plik nie wskazuje właściciela towaru, a magazyn i oddział także ustala procedura zapisu. O tym, czyj to towar, decyduje więc wybór procedury, a kolejny klient wymaga osobnej procedury. Dla działu IT jest to ważna granica: pomyłka w doborze procedury zmienia właściciela całego zlecenia. Komunikat końcowy dla awiza wysyłki brzmi „Import zakończony powodzeniem.”, a dla dokumentu sprzedaży „Import zakończony powodzeniem. Ilość zaimportowanych pozycji X z Y.”. Dokumenty, które powstają przy wysyłce po zrealizowaniu zlecenia, opisuje artykuł o [WZ, packing liście i liście przewozowym](https://system.wms.net.pl/wz-packing-list-i-list-przewozowy-ktory-dokument-do-czego/). ## Konfiguracja nie zastępuje kodu przy nowym formacie Konfiguracja ustawia cztery rzeczy: typ komunikatu, katalog, zapytanie zapisujące i procedurę docelową. Kod opisuje klasy ze strukturą XML każdego formatu oraz metodę przepisującą pola do tabeli wierszy, osobną dla każdego typu. Od typu zapisanego w kodzie zależy też nazwa katalogu archiwum. | Element importu | Gdzie się go ustawia | Czy zmiana wymaga programowania | | --- | --- | --- | | Typ komunikatu | parametr adresu pozycji menu | Nie, dopóki typ istnieje w kodzie | | Katalog z plikami | zapytanie z konfiguracji | Nie | | Zapytanie zapisujące | tabela kodów z szablonami zapytań | Nie, to wiersz konfiguracji | | Procedura docelowa | konfiguracja; osobna dla każdego klienta | Wskazanie nie, ale nowa procedura dla kolejnego klienta tak | | Klasy opisujące strukturę XML | kod aplikacji | Tak | | Przepisywanie pól do wierszy | kod aplikacji, osobna metoda dla każdego typu | Tak | > Nowy format pliku XML oznacza nowy kod. Konfiguracja obejmuje cztery rzeczy: typ komunikatu, katalog, zapytanie i procedurę. Z nowym formatem przychodzi więc nowy kod oraz nowa procedura wraz z wierszami konfiguracji. Zmiana katalogu albo szablonu zapytania mieści się w konfiguracji, ale nowa struktura pliku wymaga klas i metody przepisującej pola. W planie projektu rozdzielamy więc zmianę konfiguracji od zmiany kodu. ## Potwierdzenie wysyłki wraca do partnera jako plik XML Eksport potwierdzenia wysyłki uruchamia przycisk w rejestrze zleceń wydania. Przycisk działa, gdy zlecenie ma już zrealizowaną ilość, a w przeciwnym razie system pokazuje stronę z komunikatem. Strona wykonuje zapytanie z konfiguracji i buduje jeden komunikat zamówienia. Nagłówek ma pięć danych: identyfikator dokumentu, znacznik czasu, nadawcę, odbiorcę i typ. Dalej idą dane zamówienia z adresem dostawy i liczbą linii oraz same linie. Linia ma sześć danych: kod artykułu (EAN), ilość zamówioną, ilość dostarczoną, numer linii z zamówienia, partię i pole SSCC. Ilości są zaokrąglane w górę do całości, a do pola SSCC trafia numer palety zapisany przy realizacji. Plik powstaje w katalogu wyjściowym na serwerze aplikacji, a jego nazwa zawiera datę i unikalny numer przebiegu. Po wygenerowaniu zlecenie zostaje oznaczone jako wykonane. Ekran pokazuje „Wyeksportowano plik o nazwie: ...”, a gdy zapytanie nie zwróci wierszy, „Nie znaleziono zleceń gotowych do eksportu, które nie zostały dotychczas wysłane.”. Przesłanie pliku odbiorcy odbywa się poza tą stroną. Zadania uruchamiane z formularza WMS opisuje strona o [zadaniu integracyjnym uruchamianym z formularza](/zadanie-integracyjne-uruchamiane-z-formularza-wms/). Szerszy kontekst operatora z wieloma właścicielami towaru przedstawia tekst [WMS dla operatora 3PL](https://www.programmagazyn.pl/wms-dla-operatora-3pl/). Importowi plików towarzyszą cztery pytania do klienta. Odpowiedzi ustalają, kto odpowiada za pliki i co dzieje się po błędzie. - Dostarczenie pliku: kto i jak umieszcza pliki w katalogu wejściowym, skoro importer sam ich nie pobiera. - Błąd struktury: co robimy z plikiem, który po błędzie leży już w archiwum, i z plikami czekającymi do następnego uruchomienia. - Właściciel towaru: czy kolejny klient ma dostać własną procedurę, bo plik nie wskazuje właściciela. - Nowy format: kto napisze klasy i metodę przepisującą pola oraz kiedy powstanie nowa procedura. ## Pytania i odpowiedzi o imporcie plików XML do WMS ## Słownik pojęć o imporcie plików XML Terminy używane przez dział IT i kierownika projektu, gdy WMS przyjmuje komunikaty w plikach XML.