Jeden importer plików XML obsługuje kilka formatów, ale nowy format wymaga kodu

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 i o integracji EDI z WMS, a zlecenia składane w portalu przez klienta artykuł o portalu klienta w czterech wariantach.

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.

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.

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.

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. Szerszy kontekst operatora z wieloma właścicielami towaru przedstawia tekst 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.