Import dokumentów z plików XML część II

Transkrypt

1 Import dokumentów z plików XML część II (wersja 1.0) Soneta Sp z o.o. ul. Wadowicka 8a, wejście B Kraków tel./fax +48 (12) handel@enova.pl 1

2 Spis treści 1 Wstęp Import cech Cechy z nazwami wieloczłonowymi Import cech referencyjnych Import zapłat Import wpłaty gotówkowej Identyfikacja raportu i podmiotu Import rozliczenia Rozliczenie części kwoty Uruchamianie importu z kodu Podsumowanie

3 1 Wstęp W poprzednim artykule dotyczącym importów z plików XML omówione zostały podstawowe zasady budowy plików XML wykorzystywanych do importu danych do systemu enova. Zapoznaliśmy się w nim z ogólną strukturą plików importowych, znaczeniem atrybutu business, sposobem tworzenia najprostszych dokumentów, podstawianiem danych relacyjnych, dodawaniem podlist (np. listy pozycji czy listy płatności dokumentu) oraz dodawaniem kolejnych pól do pliku. W bieżącym artykule zajmiemy się zagadnieniami: Importu cech Importu wpłat i rozliczeo Uruchamiania importu z poziomu zewnętrznych dodatków 2 Import cech Przeanalizujmy możliwośd importu kartoteki towarowej z przypisanymi cechami. Ponieważ dla kartoteki towarowej wymagane są kod i nazwa, najprostszy plik XML do zaimportowania kartoteki towarowej, będzie wyglądał jak poniżej (atrybut key jest użyty w celu zabezpieczenie przed duplikacją o tym była mowa w poprzednim artykule): <session xmlns=" business="true"> <Towar key="kod=row_td_scout_24"> <Kod>ROW_TD_SCOUT_24</Kod> <Nazwa>Rower turystyczny damski Scout 24"</Nazwa> </Towar> Chcemy teraz dodad do pliku cechy Kolor oraz Typ, które w organizatorze listy są widoczne jako Features.Kolor i Features.Typ. Zgodnie więc z logiką rozszerzania pliku XML do importu, po uzupełnieniu o cechy będzie on wyglądał tak (uwaga tu występuje pewne odstępstwo od ogólnej reguły tag features ma nazwę pisaną z małej litery): <session xmlns=" business="true"> <Towar key="kod=row_td_scout_24"> <Kod>ROW_TD_SCOUT_24</Kod> <Nazwa>Rower turystyczny damski Scout 24"</Nazwa> <Kolor>niebieski</Kolor> <Typ>turystyczny</Typ> </Towar> 3

4 2.1 Cechy z nazwami wieloczłonowymi Problem pojawia się, gdy cecha posiada nazwę wieloczłonową. Np. zamiast cechy Typ będzie zdefiniowana cecha Typ modelu. Tag importujący cechy nie może wyglądad w ten sposób: <Kolor>niebieski</Kolor> <Typ modelu>turystyczny</typ modelu> bo nie będzie to wówczas poprawny plik XML. W takim wypadku stosuje się inną notację gdzie nazwa cechy jest atrybutem: <feature name="kolor">czerwony</feature> <feature name="typ modelu">turystyczny</feature> W ten sposób jest możliwośd importowania cech do dowolnych obiektów w enova. 2.2 Import cech referencyjnych Szczególnym rodzajem cech są cechy referencyjne. Dodajmy do towaru kolejną cechę Drugi dostawca, typu referencyjnego, tabela danych referencyjnych Kontrahenci. W tym wypadku możliwe jest przekazanie wartości takiej cechy wyłącznie przez GUID lub przez ID. W przypadku identyfikacji przez GUID taki zapis będzie wyglądał następująco: <feature name="drugi dostawca">kontrahent:ba66f d7-9ab c951c8</feature> Lub w uproszczeniu: <feature name="drugi dostawca">ba66f d7-9ab c951c8</feature> W przypadku identyfikacji przez ID, musi ono byd poprzedzone znakiem #: <feature name="drugi dostawca">kontrahent:#3</feature> Lub w uproszczeniu: <feature name="drugi dostawca">#3</feature> 4

5 3 Import zapłat Może zdarzyd się, że wraz z dokumentem handlowym chcemy zaimportowad również wpłatę do tego dokumentu. Przykładowo chcemy aby import paragonu z pliku XML wprowadził również zapłatę za paragon i powiązał tą wpłatę z należnością. 3.1 Import wpłaty gotówkowej W pierwszej kolejności musimy zaimportowad wpłatę. Dokumenty wpłat mogą byd wprowadzane w enova na różne sposoby (przez Dokumenty, Raporty lub Ewidencję). W przykładzie zajmiemy się wprowadzaniem przez Dokumenty, czyli tak, jak w standardowej kasie gotówkowej. Podstawowy plik dla takiego importu wygląda tak: <session xmlns=" business="true"> <DokKasowyBase class="soneta.kasa.dokumentwplata,soneta.kasa" raport="4334ca3e- 25e e70-607d93e87d8e"> <Kasa> </Kasa> <Definicja> </Definicja> <Data> </Data> <Zaplata class="soneta.kasa.wplata,soneta.kasa"> <Podmiot>Kontrahent: </Podmiot> <Kwota> PLN</Kwota> <Opis>Zapłata za paragon</opis> </Zaplata> <Bufor>False</Bufor> </DokKasowyBase> Niestety taki plik ma zasadniczą wadę, polegającą na posługiwaniu się GUID-ami. O ile w przypadku tagów Kasa i Definicja możemy się łatwo pozbyd GUID-ów, wykorzystując atrybut where, o tyle w przypadku Raport i Podmiot nie będzie to takie łatwe. Wynika to stąd, że: Raport występuje w konstruktorze klasy DokumentWplata, musi byd więc wprowadzony jako atrybut (a nie jako tag). A nie możemy zastosowad atrybutu dla atrybutu. Podmiot w przypadku zapłaty może byd kontrahentem, pracownikiem, bankiem itp. Musi byd więc określony jego typ. Przy takiej konstrukcji możemy się posłużyd jedynie GUID-em lub ID Identyfikacja raportu i podmiotu Rozwiązaniem powyższego problemu jest wprowadzenie do pliku XML raportu oraz podmiotu (kontrahenta) jako zupełnie odrębnych tagów. Zostaną one zidentyfikowane za pomocą atrybutu key (po polu unikalnym dla kontrahenta będzie to kod, a dla raportu numer), a na zapłacie zostaną podstawione za pomocą wewnętrznych identyfikatorów (o użyciu atrybutu key, oraz o wewnętrznych identyfikatorach była mowa w poprzednim artykule). <session business="true" xmlns=" <RaportESP id="raport_1" key="numer.pelny=rk/kasa/2011/07/0012"></raportesp> <Kontrahent id="podmiot_1" key="kod=zefir"></kontrahent> <DokKasowyBase class="soneta.kasa.dokumentwplata,soneta.kasa" Raport="Raport_1"> <Kasa where="symbol=kasa" /> <Definicja where="symbol=kp" /> 5

6 <Kierunek>Przychod</Kierunek> <Data> </Data> <Bufor>True</Bufor> <Zaplata class="soneta.kasa.wplata,soneta.kasa"> <Podmiot>Podmiot_1</Podmiot> <Kwota> PLN</Kwota> <Opis>Zapłata za paragon</opis> </Zaplata> </DokKasowyBase> Proszę zwrócid uwagę, że np. kontrahent ma tag, który dzięki atrybutowi key spowoduje wyszukanie kontrahenta w bazie danych, a za pomocą wewnętrznego identyfikatora (id="podmiot_1") zostanie potem podstawiony na dokumencie wpłaty. Oczywiście, taka zawartośd pliku XML zakłada, że zarówno kontrahent jak i raport kasowy istnieją w bazie danych. 3.2 Import rozliczenia Teraz pozostaje połączenie pliku zawierającego paragon z plikiem zawierającym wpłatę oraz dodanie rozliczenia pomiędzy płatnością paragonu i wpłatą. W tym celu tagi płatnośd i i wpłata otrzymają wewnętrzne identyfikatory (odpowiednio Platnosc_1 i Zaplata_1), którymi posłużymy się w tagu importującym rozliczenie. Dodanie wewnętrznego identyfikatora do płatności: <Platnosc class="soneta.kasa.naleznosc,soneta.kasa" id="platnosc_1"> [...] </Platnosc> Dodanie wewnętrznego identyfikatora do wpłaty: <Zaplata class="soneta.kasa.wplata,soneta.kasa" id="zaplata_1"> [...] </Zaplata> I import rozliczenia: <RozliczenieSP id="rozliczeniesp_1" dokument="platnosc_1" zapłata="zaplata_1"> </RozliczenieSP> Cały plik będzie wyglądał następująco: <session business="true" xmlns=" <RaportESP id="raport_1" key="numer.pelny=rk/kasa/2011/07/0012"></raportesp> <Kontrahent id="podmiot_1" key="kod=zefir"></kontrahent> <DokumentHandlowy id="dokument_1"> <Definicja where="symbol=par" /> <Magazyn where="symbol=f" /> <Data> </Data> <Kontrahent>Podniot_1</Kontrahent> <Platnosci> <Platnosc class="soneta.kasa.naleznosc,soneta.kasa" id="platnosc_1"> <SposobZaplaty where="nazwa=gotówka"/> <Kwota> PLN</Kwota> 6

7 <TerminDni>0</TerminDni> </Platnosc> </Platnosci> <Pozycje> <Pozycja> <Towar where="kod=montaz" /> <Ilosc>1 szt</ilosc> <Cena> PLN</Cena> </Pozycja> </Pozycje> <Stan>Zatwierdzony</Stan> </DokumentHandlowy> <DokKasowyBase class="soneta.kasa.dokumentwplata,soneta.kasa" Raport="Raport_1"> <Kasa where="symbol=kasa" /> <Definicja where="symbol=kp" /> <Kierunek>Przychod</Kierunek> <Data> </Data> <Bufor>True</Bufor> <Zaplata class="soneta.kasa.wplata,soneta.kasa" id="zaplata_1"> <Podmiot>Podmiot_1</Podmiot> <Kwota> PLN</Kwota> <Opis>Zapłata za paragon</opis> </Zaplata> </DokKasowyBase> <RozliczenieSP id="rozliczeniesp_1" dokument="platnosc_1" zapłata="zaplata_1"> </RozliczenieSP> Rozliczenie części kwoty Gdyby rozliczenia miała podlegad nie cała kwota, ale tylko jej częśd, wówczas tag RozliczenieSP powinien zawierad dodatkowo informację o tej kwocie: <RozliczenieSP id="rozliczeniesp_1" dokument="platnosc_1" zapłata="zaplata_1"> <KwotaDokumentu> PLN</KwotaDokumentu> </RozliczenieSP> 4 Uruchamianie importu z kodu Czasami w rozwiązaniach dodatkowych dla enova pojawia się potrzeba automatycznego uruchomienia importu danych z pliku XML (z poziomu kodu własnego programu czy serwisu). Za wczytywanie danych z plików XML odpowiada klasa SessionReader. Zakładając, że do zmiennej filename podstawiona zostanie nazwa pliku XML, a w zmiennej login będzie obiekt loginu do enova, samo zaimportowanie danych z pliku zawiera 3 linie kodu: // Soneta.Business.App.Login login; // string filename = "C:\\Folder\\NazwaPliku.XML"; System.Xml.XmlTextReader reader = new System.Xml.XmlTextReader(filename); reader.whitespacehandling = System.Xml.WhitespaceHandling.Significant; new SessionReader(login).Read(reader); 7

8 5 Podsumowanie W dwóch artykułach dotyczących importu danych z plików XML przedstawione zostały podstawowe zasady konstrukcji plików importu. Zawarte w artykułach informacje mogą posłużyd do budowy zewnętrznych mechanizmów wymiany danych pomiędzy oprogramowaniem firm trzecich a systemem enova (przykładowo import zamówieo ze sklepu internetowego za pomocą plików XML). Wszystkie przykłady bazowały na imporcie dokumentów handlowych i powiązanych z nimi danych. Wynika to stąd, że najczęściej pojawia się potrzeba integracji właśnie w tym obszarze. Oczywiście informacje zawarte w artykułach, dotyczące zasad konstrukcji plików, identyfikacji danych, dodawania nowych pól do plików importowych itp. mają charakter ogólny i mogą byd pomocne w budowaniu plików wymiany w innych obszarach. 8