Listy przewozowe DHL - generowanie z systemu

Autor: Adam Siemiątkowski, SoftwareStudio Group Sp. z o.o.

Co system robi, a czego nie

Zanim przejdziemy do konfiguracji, warto jasno rozgraniczyć zakres odpowiedzialności - to oszczędza rozczarowań na etapie wdrożenia. Generowanie listów przewozowych DHL z poziomu systemu magazynowego oznacza w praktyce przygotowanie kompletu poprawnych danych w formacie, który rozumie aplikacja przewoźnika.

Taki podział ról ma konkretne uzasadnienie. Numer przesyłki i format etykiety należą do przewoźnika i zmieniają się wraz z jego regulaminem - system magazynowy nie powinien ich odtwarzać. Odpowiada natomiast za to, na czym zna się najlepiej: za poprawność danych adresowych i parametrów przesyłki, które i tak są już w bazie.

Zysk jest wymierny wszędzie tam, gdzie dziennie powstaje kilkadziesiąt wydań z magazynu. Znika przepisywanie adresu z dokumentu do formularza przewoźnika, a wraz z nim najczęstsze źródło błędów w dostawie: literówka w kodzie pocztowym albo pominięty numer telefonu do awizacji.

Jak przebiega generowanie

Cały mechanizm sprowadza się do czterech kroków wykonywanych w momencie kliknięcia przycisku w rejestrze dokumentów.

Wynikowy plik udostępniany jest przyciskiem pobrania, który otwiera go w nowym oknie. Aby zapisać plik na dysku zamiast go otwierać, wystarczy kliknąć przycisk prawym przyciskiem myszy i wybrać polecenie zapisania pliku.

Transakcja i jej parametry

Za eksport odpowiada transakcja role_sys/dhl2xml.aspx, należąca do zbioru transakcji uniwersalnych opisanych w materiale o architekturze transakcji. Do poprawnego działania wymaga dwóch parametrów przekazanych w wywołaniu:

• typ - identyfikator pozycji skorowidza XML, czyli wskazanie, która definicja zapytania ma zostać użyta.
• refno - identyfikator dokumentu, dla którego tworzony jest list przewozowy.

Rozdzielenie tych dwóch parametrów daje elastyczność, która przydaje się w praktyce. Jedna definicja zapytania obsługuje wszystkie dokumenty tego samego rodzaju, a jednocześnie nic nie stoi na przeszkodzie, by przygotować kilka definicji - osobną dla przesyłek krajowych i osobną dla zagranicznych, różniących się kodem usługi.

Warto dodać, że mechanizm jest niezależny od tego, skąd pochodzą dane wyjściowe. Firmy pracujące równolegle na systemie ERP - Comarch, SAP czy innym - często zadają pytanie, czy listy przewozowe da się wystawiać z ich środowiska. Odpowiedź sprowadza się do jednego warunku: dane muszą znaleźć się w bazie SQL, do której sięga zapytanie. Jeśli dokumenty sprzedaży lub wydania trafiają do StudioSystem przez integrację, eksport dla przewoźnika działa dokładnie tak samo, bo transakcja nie wie i nie musi wiedzieć, jaki system był pierwotnym źródłem rekordu.

Skorowidz XML - definicja zapytania

Ustawienia eksportu zapisane są w skorowidzu o prefiksie XML. To tam definiuje się, skąd pobrać dane i jak je nazwać. Konfiguracja opiera się na trzech elementach:

Zapytanie budowane jest dynamicznie z tych trzech części, a zmienna @REFNO podstawiana jest z parametru refno przekazanego przy uruchomieniu transakcji. W efekcie powstaje polecenie odczytujące dane kontrahenta, dla którego wystawiono dokument magazynowy o wskazanym numerze referencyjnym:

SELECT TOP(1)
  NRIDODN AS RECEIVER_ID,
  SKROCO AS RECEIVER_NAME,
  KODPOCZTOWY AS RECEIVER_POSTCODE,
  MIEJSCOWOSC AS RECEIVER_CITY,
  ULICA AS RECEIVER_STREET,
  TELEFON AS RECEIVER_TEL,
  EMAIL AS PRE_REC_EMAIL
FROM KNKON
WHERE NRIDODN=(SELECT TOP(1) NRIDODN FROM DPMAG WHERE REFNO=@REFNO)

Ponieważ zapytanie jest w pełni konfigurowalne, listy przewozowe da się tworzyć na podstawie różnych dokumentów i kartotek. Wymaga to jednak znajomości struktury tabel opisanej w materiale o bazie danych platformy, a w przypadku wydań magazynowych - rejestru dokumentów DPMAG.

Kolumny wymagane przez e-case

Najważniejsza zasada całej konfiguracji brzmi: nazwy zwracanych kolumn muszą dokładnie odpowiadać specyfikacji e-case DHL. Aplikacja przewoźnika rozpoznaje dane po nazwach, nie po kolejności, dlatego w zapytaniu nadaje się aliasy poleceniem AS.

Część pól pochodzi wprost z kartoteki, a część to wartości stałe określające rodzaj usługi i sposób rozliczenia:

• RECEIVER_ID, RECEIVER_NAME - identyfikator i nazwa odbiorcy.
• RECEIVER_POSTCODE, RECEIVER_CITY, RECEIVER_STREET, RECEIVER_HOUSENUMBER - adres dostawy.
• RECEIVER_TEL, PRE_REC_EMAIL - dane kontaktowe wykorzystywane do awizacji przesyłki.
• PRODUCT - kod usługi przewoźnika, podawany jako wartość stała.
• PAYMENT_TYPE, INVOICE_TO - sposób rozliczenia i wskazanie płatnika.
• CASH_ON_DELIVERY, GOODS_VALUE - kwota pobrania i deklarowana wartość towaru.
• DOCUMENT, BLP - znaczniki dodatkowych opcji przesyłki.

Wartości stałe wpisuje się w zapytaniu jako literały w apostrofach, na przykład 'P' AS PAYMENT_TYPE. Warto zwrócić uwagę na drobiazg, który potrafi kosztować godzinę diagnostyki: kopiowanie definicji z edytora tekstu bywa źródłem tak zwanych inteligentnych cudzysłowów zamiast prostych apostrofów, co powoduje błąd zapytania.

Podpięcie przycisku do rejestru

Aby użytkownik mógł wywołać eksport, transakcję podpina się jako polecenie w rejestrze dokumentów - najczęściej w zestawieniu wydań z magazynu. Służy do tego moduł Konfigurator, w którym każda pozycja menu wiąże nazwę transakcji z parametrami jej uruchomienia.

StudioSystem

Transakcja i parametry w jednym formularzu

Pola „Transakcja do uruchomienia" oraz „Parametry transakcji" decydują o tym, co wywoła przycisk. W przykładzie widoczna jest inna transakcja uniwersalna - mechanizm podpięcia pozostaje identyczny.

Po zapisaniu konfiguracji w rejestrze dokumentów pojawia się polecenie uruchamiające eksport. Numer referencyjny zaznaczonego dokumentu przekazywany jest automatycznie, więc użytkownik wykonuje jedną czynność: zaznacza wydanie i klika przycisk.

Gdzie powstaje plik i typowe błędy

Wygenerowane pliki zapisywane są na serwerze w katalogu App_Xml, a ich nazwa ma postać dhl-@REFNO, gdzie @REFNO to wartość parametru refno. Każdy dokument ma więc własny, jednoznacznie nazwany plik, co ułatwia późniejsze odszukanie eksportu dla konkretnej przesyłki.

Jeżeli konfiguracja kolumn jest błędna albo brakuje wymaganych parametrów uruchomienia, plik nie powstanie, a w oknie transakcji wyświetli się komunikat o błędzie. W praktyce wdrożeniowej najczęściej odpowiadają za to trzy przyczyny:

1. Nieprzekazany parametr - najczęściej brak typ przy podpinaniu przycisku do menu.
2. Alias niezgodny ze specyfikacją - literówka w nazwie kolumny docelowej, na przykład RECEIVER_POSTCODE zapisane inaczej.
3. Warunek nietrafiający w rekord - zapytanie wykonuje się poprawnie, ale nie zwraca żadnego wiersza.

Ten sam mechanizm eksportu do XML wykorzystywany jest szerzej w platformie, co opisuje strona o eksporcie danych do XML. Jeśli natomiast interesuje Cię obsługa przesyłek kurierskich po stronie samego magazynu, warto zajrzeć do materiału o transakcji kurierskiej oraz do zestawienia transakcji WMS.

Podsumowanie

Generowanie listów przewozowych DHL w StudioSystem opiera się na prostym założeniu: system dostarcza dane, przewoźnik wystawia dokument. Transakcja dhl2xml.aspx odczytuje ustawienia ze skorowidza XML, wykonuje zapytanie z podstawionym numerem referencyjnym dokumentu i zapisuje plik XML w katalogu App_Xml, skąd trafia on do aplikacji e-case DHL.

Kluczem do poprawnego wdrożenia jest zgodność nazw kolumn ze specyfikacją przewoźnika oraz przemyślany warunek zapytania. Ponieważ całość opiera się na konfigurowalnym zapytaniu SQL, ten sam mechanizm da się wykorzystać dla innych dokumentów i innych formatów wymiany danych.