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

Transkrypt

1 Import dokumentów z plików XML część I (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 Eksport i import danych z plików XML Ogólna struktura plików importu Atrybut business Atrybuty guid i id Import danych słownikowych Identyfikacja kontrahenta w bazie danych Identyfikacja kontrahenta na dokumencie Identyfikacja po GUID Identyfikacja po polu unikalnym Wewnętrzny identyfikator Importy podlist Pozycje dokumentu handlowego Płatności Najprostszy plik importu Podsumowanie i kontynuacja

3 1 Wstęp Często pojawiają się pytania o możliwośd importu danych w szczególności faktur czy innych dokumentów handlowych do enova. System enova dostarcza kilku mechanizmów importu danych np. importy z arkuszy Microsoft Excel, czy kilka formatów importu danych do ewidencji dokumentów (w księgowości). W niniejszym dokumencie skupimy się nad importem danych z wykorzystaniem plików XML. Ma on na celu przybliżenie zasad budowy plików XML służących do importu danych do systemu enova. Odpowiednio wygenerowany plik XML może służyd np. do importu danych do systemu enova z zewnętrznych programów. 2 Eksport i import danych z plików XML W systemie istnieje funkcja eksportu danych do plików XML dostępna z menu Plik\Eksportuj zapisy. Funkcja ta jest dostępna na większości list i odnosi się do eksportu danych aktualnie wyświetlonych (zaznaczonych) na liście. Kilka słów wyjaśnienia, dlaczego na niektórych listach ta opcja nie jest dostępna do pliku XML można wyeksportowad jedynie kompletne z logicznego punktu widzenia dane. Przykładowo dokument handlowy (np. faktura) łącznie z pozycjami stanowi kompletną paczkę danych. Z drugiej strony, jeżeli otworzymy listę Handel\Dane analityczne\pozycje to lista ta zawiera zestawienie pozycji dokumentów handlowych. Pojedyncza pozycja nie jest kompletną paczką danych pozycja bez nagłówka dokumentu nie może istnied. Dlatego w tym miejscu eksport danych do pliku XML nie jest dostępny. Używając określenia bardziej technicznego, możliwy jest import tylko zapisów guidowanych, czyli posiadających własny GUID. Funkcja lustrzana do eksportu dokumentów jest dostępna z menu Plik\Importuj zapisy\z pliku XML. Funkcja ta pozwala na zaimportowanie danych z uprzednio przygotowanego pliku XML. W odróżnieniu od eksportu, który zapisuje do pliku dokumenty z bieżącej listy, import działa bezkontekstowo tzn. niezależnie od tego na której liście zostanie uruchomiony, importuje wszystkie dane zawarte we wskazanym pliku XML. 3

4 W przypadku eksportu dokumentów handlowych do pliku XML mamy dostępną jeszcze jedną, specjalizowaną funkcję dostępną z menu Czynności\Narzędziowe\Eksport dokumentu\do pliku. Funkcja dostępna jest na liście dokumentów handlowych (lub na formularzu dokumentu handlowego) i tworzy plik XML, który ma nieco inną strukturę od tego, który jest tworzony z funkcji Plik\Eksportuj zapisy, ale może byd importowany tą samą funkcją importu. Podstawowa różnica w strukturze plików generowanych tymi dwoma metodami zostanie omówiona w następnym punkcie. 3 Ogólna struktura plików importu Zobaczmy na układ pliku wygenerowanego funkcją Plik\Eksportuj zapisy (jest to fragment pliku zawierającego dokument handlowy) <session xmlns=" <DokumentHandlowy id="dokumenthandlowy_14" guid="afd216af-1d07-4fc6-a6c2- c8596e60fea9"> <Kategoria>Sprzedaż</Kategoria> <Stan>Zatwierdzony</Stan> <Potwierdzenie>Niepotwierdzony</Potwierdzenie> <Definicja> </Definicja> <Magazyn> </Magazyn> Podstawowa zasada jest taka, że oprócz znacznika XML na początku pliku całośd danych umieszczona jest w tagu session, a dalej znajdują się tagi zawierające poszczególne zapisy. Nazwa tagu DokumentHandlowy odpowiada w tym wypadku typowi importowanych danych, natomiast w ramach dokumentu znajdują się tagi zawierające poszczególne pola z wartościami (Kategoria, Stan itd. są to pola dokumentu). 3.1 Atrybut business Jeżeli popatrzymy na fragment pliku wygenerowanego za pomocą funkcji Czynności\Narzędziowe\Eksport dokumentu\do pliku to wygląda on tak: <DokumentHandlowy guid="afd216af-1d07-4fc6-a6c2-c8596e60fea9"> <Definicja where="symbol=fv" /> <Magazyn where="symbol=f" /> <Data> </Data> Co do ogólnej struktury to wygląda bardzo podobnie do poprzedniego (tagi session, DokumentHandlowy oraz tagi odpowiadające wartościom pól w dokumencie). Proszę natomiast zwrócid uwagę na pozornie drobną różnicę a mianowicie na atrybut business="true" w tagu session. Atrybut ten ma kolosalne znaczenie dla funkcji importu danych z pliku XML: Jeżeli atrybut business ma wartośd true, wówczas import z pliku XML przebiega z wykorzystaniem logiki biznesowej programu czyli w analogiczny sposób, jakby wartości kolejnych pól były ustawiane np. na 4

5 poziomie interfejsu użytkownika (na formularzu dokumentu). Oznacza to w szczególności wykonanie wszelkich obliczeo i weryfikacji podczas dodawania zapisu. Ponadto wszystkie pola które nie zostaną ustawione (czyli te, których nie będzie w pliku XML) zostaną zainicjalizowane tak, jak przy normalnym dodawaniu dokumentu. Jeżeli atrybut business ma wartośd false (albo nie jest ustawiony) wówczas kopiowanie danych odbywa się z pominięciem logiki biznesowej w uproszczeniu można powiedzied, że import odbywa się niejako na poziomie danych zapisywanych do bazy. Oznacza to m.in., że dane nie są weryfikowane pod względem poprawności, żadne dane nie będą zainicjalizowane. Z powyższego wynika, że jeżeli chcemy zewnętrznymi narzędziami przygotowad plik XML do importu, wówczas koniecznie należy stosowad atrybut business="true". Bezpieczne tworzenie plików XML bez tego atrybutu jest możliwe tylko wewnętrznymi mechanizmami systemu enova bo system ma pełną informację o dokumencie i jest w stanie wygenerowad komplet spójnych danych o eksportowanym zapisie. 3.2 Atrybuty guid i id W obu przypadkach tag DokumentHandlowy posiada atrybut guid. Atrybut ten odpowiada właściwości (polu) GUID dokumentu i jest jednoznacznym identyfikatorem tego dokumentu. W przypadku importu zapisów z pliku program zawsze zweryfikuje czy istnieje już zapis (w tym wypadku dokument handlowy) o podanym identyfikatorze GUID, i jeśli tak, to istniejący zapis zostanie nadpisany. W przeciwnym wypadku zostanie dodany nowy zapis. Atrybut guid może nie byd ustawiony w pliku XML w takim wypadku podczas importu zawsze zostanie dodany nowy zapis i zostanie mu nadany nowy identyfikator GUID (tak, jak podczas normalnego dodawania dokumenty w systemie enova). Inaczej jest z atrybutem id. Jest to identyfikator wewnętrzny w ramach pliku XML. Nie ma on znaczenia dla dodawania zapisu do systemu enova, natomiast może mied znaczenie dla powiązania różnych zapisów znajdujących się w pliku XML będzie o tym dalej mowa w punkcie mówiącym o imporcie danych kontrahentów. 4 Import danych słownikowych Jeden plik XML może zawierad wiele danych - może zarówno zawierad wiele dokumentów do zaimportowania, jak i dane różnego rodzaju. Dzięki temu w jednym pliku razem z dokumentem handlowym możemy umieścid np. dane o kontrahencie czy towarach. 4.1 Identyfikacja kontrahenta w bazie danych Poniżej plik zawierający podstawowe dane kontrahenta: <Kontrahent id="kontrahent_2" key="kod=zefir" guid="ba66f d7-9ab c951c8"> <Kod>Zefir</Kod> <Nazwa>ZEFIR J.Nowak i E.Nowak</Nazwa> </Kontrahent> Ponieważ dla kontrahenta wymaganymi danymi są jedynie kod i nazwa, dla uproszczenia plik został ograniczony tylko do tych dwóch wymaganych tagów. Dokładniej omówimy znaczenie atrybutów id, key i guid oraz ich znaczenia do powiązania zapisu z zapisem w bazie danych i z innymi zapisami w pliku XML. 5

6 Jak już wcześniej wspomniano guid jest jednoznacznym identyfikatorem zapisu w bazie danych. Jeżeli atrybut guid jest wypełniony i zostanie znaleziony w bazie kontrahent o takim GUID, to jego dane zostaną podczas importu zaktualizowane. Jeżeli kontrahent o danym GUID nie zostanie znaleziony, wówczas zostanie dodana nowa kartoteka. Zastanówmy się, co się stanie, jeżeli w pliku XML nie określimy żadnego identyfikatora dla kontrahenta i spróbujemy zaimportowad dane: <Kontrahent> <Kod>Zefir</Kod> <Nazwa>ZEFIR J.Nowak i E.Nowak</Nazwa> </Kontrahent> Program w tym wypadku doda nowego kontrahenta, nada mu w enova nowy GUID. Co się jednak stanie jeśli spróbujemy wykonad import z tego pliku po raz drugi (lub jeśli kontrahent Zefir już wcześniej istniał w bazie). Program nie znajdzie kontrahenta po identyfikatorze GUID (bo takiego identyfikatora nie ma), spróbuje dodad nowego kontrahenta i otrzyma błąd duplikacji kodu kontrahenta. Aby z jednej strony nie wymuszad posługiwania się identyfikatorami GUID (co jest niewygodne, a czasami przy przesyłaniu danych pomiędzy różnymi bazami danych wręcz niemożliwe), wprowadzony został atrybut key, który umożliwia zidentyfikowanie zapisu po polu unikalnym innym niż GUID: <Kontrahent key="kod=zefir" > <Kod>Zefir</Kod> <Nazwa>ZEFIR J.Nowak i E.Nowak</Nazwa> </Kontrahent> Taki zapis oznacza, że program spróbuje znaleźd kontrahenta o kodzie Zefir, i jeśli go znajdzie to zaktualizuje jego dane, a jeśli nie znajdzie założy nową kartotekę. 4.2 Identyfikacja kontrahenta na dokumencie Jeżeli przyjrzymy się plikowi zawierającemu wyeksportowany dokument handlowy, wówczas znajdziemy w nim m.in. tag Kontrahent, który wskazuje na kontrahenta, którego należy wstawid na dokumencie. Kontrahent na dokumencie może byd zidentyfikowany na 3 sposoby: Identyfikacja po GUID Jako wartośd tagu Kontrahent podstawiamy po prostu GUID kontrahenta. Aby zastosowad taką metodę konieczna jest znajomośd identyfikatorów GUID a jeśli mówimy o eksporcie/imporcie pomiędzy różnymi bazami danych (czy wręcz różnymi programami) to często taka synchronizacja GUID-ów jest trudna do zapewnienia. Warto zwrócid uwagę, że w takim przypadku dane kontrahenta nie muszą byd zapisane w pliku XML ważne jest, żeby w bazie danych do której importujemy istniał kontrahent o wskazanym GUID. Oczywiście jeżeli w pliku oprócz dokumentu handlowego znajdzie się również tag z danymi kontrahenta, wówczas mamy pewnośd, że w przypadku braku kontrahenta o takim GUID zostanie on zaimportowany. 6

7 <DokumentHandlowy > <Kontrahent> ba66f d7-9ab c951c8</kontrahent> Proszę zwrócid uwagę, że w pierwszym przykładzie podanym na początku w analogiczny sposób było wykonane odwołanie do magazynu czy definicji dokumentu: <Definicja> </Definicja> <Magazyn> </Magazyn> Identyfikacja po polu unikalnym Podobnie, jak identyfikowaliśmy kontrahenta w bazie danych za pomocą atrybutu key, na dokumencie możemy go zidentyfikowad po polu unikalnym wykorzystując atrybut where. Ponieważ dla kontrahenta polem unikalnym jest kod, więc w atrybucie where użyjemy odwołania do kodu kontrahenta. <DokumentHandlowy > <Kontrahent where="kod=zefir" /> Podobnie jak w poprzednim przykładzie dane kontrahenta nie muszą byd umieszczone w pliku XML ważne, żeby w bazie znajdował się kontrahent o podanym kodzie. Proszę zwrócid uwagę, że w drugim przykładzie podanym na początku tego dokumentu w analogiczny sposób było wykonane odwołanie do magazynu czy definicji dokumentu: <Definicja where="symbol=fv" /> <Magazyn where="symbol=f" /> Wewnętrzny identyfikator Trzecim sposobem jest wykorzystanie wewnętrznego identyfikatora atrybutu id. W tym wypadku dane kontrahenta muszą znajdowad się w pliku XML, kontrahent musi posiadad nadany atrybut id, i poprzez ten atrybut odwołujemy się do jego kartoteki, np.: <Kontrahent id="kontrahent_2" key="kod=zefir" > <Kod>Zefir</Kod> <Nazwa>ZEFIR J.Nowak i E.Nowak</Nazwa> </Kontrahent> <DokumentHandlowy > <Kontrahent> kontrahent_2</kontrahent> 7

8 W tym wypadku kontrahentowi nadaliśmy wewnętrzny identyfikator kontrahent_2. Wartośd tego identyfikatora może mied dowolną wartośd alfanumeryczną i nie jest nigdzie zapisywana w bazie danych obowiązuje wyłącznie wewnątrz pliku XML. Do tak nadanego identyfikatora możemy odwoład się ustalając kontrahenta na dokumencie handlowym. 5 Importy podlist 5.1 Pozycje dokumentu handlowego Dokument handlowy zawiera listę pozycji w odróżnieniu od danych wcześniej omawianych w tym wypadku musimy zapewnid możliwośd zapisania nie jednej wartości (jak Kontrahent, Magazyn itp.), ale wielu dla każdej pozycji trzeba określid towar, ilośd, cenę itp. <DokumentHandlowy guid="afd216af-1d07-4fc6-a6c2-c8596e60fea9"> <Definicja where="symbol=fv" /> <Magazyn where="symbol=f" /> <Data> </Data> <Kontrahent where="kod=zefir" /> <Pozycje> <Pozycja> <Towar where="kod=nam_home1" /> <Ilosc>1 szt</ilosc> <Cena>72.00 PLN</Cena> </Pozycja> <Pozycja> <Towar where="kod=spiwor" /> <Ilosc>1 szt</ilosc> <Cena>31.50 PLN</Cena> </Pozycja> </Pozycje> W tym wypadku mamy tag Pozycje, który rozpoczyna listę w ramach której dla każdej pozycji jest oddzielny tag Pozycja. W podanym przykładzie wszystkie dane relacyjne (magazyn, kontrahent, towary) są identyfikowane za pomocą atrybutu where. 5.2 Płatności W przypadku płatności sytuacja wygląda podobnie jak w przypadku pozycji. Są jednak dwie istotne różnice Po pierwsze płatnośd w systemie może byd typu należnośd lub zobowiązanie. Oczywiście jeśli mówimy o fakturze sprzedaży, to wiemy, że chodzi nam o należnośd ale z punktu widzenia konstrukcji pliku XML musi to byd jawnie zadeklarowane stąd atrybut class w tagu Platnosc. Druga sprawa dotyczy edycji płatności. Zastanówmy się, jak działa program podczas edycji dokumentu handlowego (na formularzu) w szczególności podczas dodawania pozycji i płatności na dokument. Jeżeli nie edytujemy ręcznie płatności, to za każdym razem gdy zmieniamy pozycje na dokumencie (np. dodajemy nową pozycję) program automatycznie zmienia wartośd płatności. W tym wypadku płatnośd na dokumencie jest jedna i automatycznie jej wartośd dostosowuje się do wartości dokumentu. Jeżeli natomiast dokonamy zmian na 8

9 zakładce płatności np. rozbijemy płatnośd na dwie raty to wówczas program przestaje dostosowywad wartośd płatności do wartości dokumentu i osoba edytująca płatności musi zadbad o to, żeby ich suma była zgodna z dokumentem. Jeżeli więc podczas importu najpierw dodamy pozycje do dokumentu, to automatycznie program utworzy płatnośd na dokumencie. I jeśli wtedy dodatkowo zaimportowane zostaną płatności z pliku XML, to spowoduje niezgodnośd wartości dokumentu z płatnościami (płatności będą zdublowane). Jeżeli w pliku XML chcemy umieścid płatności (np. informację o rozbiciu na raty), wówczas musimy najpierw zaimportowad te płatności a potem pozycje dokumentu. Aby zachowad taką kolejnośd importowania danych, kolejnośd tagów w pliku XML musi byd z nią zgodna (a więc najpierw płatności, potem pozycje): <DokumentHandlowy> <Definicja where="symbol=fv" /> <Magazyn where="symbol=f" /> <Data> </Data> <Numer>FV/000001/11</Numer> <Kontrahent where="kod=zefir" /> <Platnosci> <Platnosc class="soneta.kasa.naleznosc,soneta.kasa"> <SposobZaplaty where="nazwa=przelew" /> <Kwota> PLN</Kwota> <TerminDni>7</TerminDni> </Platnosc> <Platnosc class="soneta.kasa.naleznosc,soneta.kasa"> <SposobZaplaty where="nazwa=gotówka" /> <Kwota>27.31 PLN</Kwota> <TerminDni>0</TerminDni> </Platnosc> </Platnosci> <Pozycje> </Pozycje> 6 Najprostszy plik importu Bazując na dotychczasowej wiedzy o sposobie inicjalizowania danych oraz identyfikacji danych relacyjnych spróbujmy utworzyd najprostszy możliwy plik, z którego można zaimportowad kompletny dokument faktury sprzedaży. Plik będzie utworzony dla bazy demo a więc zakłada w bazie istnienie określonych kartotek kontrahenta i towaru: <DokumentHandlowy> <Definicja where="symbol=fv" /> <Magazyn where="symbol=f" /> <Kontrahent where="kod=zefir" /> <Pozycje> 9

10 <Pozycja> <Towar where="kod=nam_home1" /> </Pozycja> </Pozycje> Proszę zwrócid uwagę, że w pliku nie ma np. daty zainicjalizowana zostanie data bieżąca. Dla pozycji podany jest wyłącznie towar ilośd, cena i rabat zostaną zainicjalizowane domyślnie (tak, jakbyśmy dodawali nową pozycję do faktury z poziomu formularza). Nie ma również płatności zostanie więc utworzona jedna płatnośd ze sposobem i terminem płatności domyślnym dla wskazanego kontrahenta. Taki uproszczony plik może stad się bazą do dodawania kolejnych informacji do importu np. chcąc w pliku umieścid datę dokumentu (żeby został utworzony ze wskazaną datą a nie domyślnie z datą bieżącą) należy dodad tag Data. Utworzone w ten sposób pliki XML mogą byd wykorzystywane np. do importu danych z zewnętrznego oprogramowania omówione tu zasady można potraktowad jako ogólne zasady tworzenia plików wymiany danych (nie tylko dla dokumentów handlowych). Omawiane przykłady dotyczą bardzo prostych struktur danych są to w większości pliki minimalistyczne. Rozbudowę tych struktur można uzyskad przez dodawanie kolejnych tagów zawierających wartości innych pól dokumentu. Warto zwrócid uwagę, że ponieważ nazwy tagów w pliku XML odpowiadają nazwom właściwości (property, albo mówiąc w uproszczeniu nazwom pól na dokumencie), dla zidentyfikowania jakich nazw tagów można używad warto posłużyd się pomocniczo organizatorem listy: Inne podejście do tworzenia własnych plików XML polega na wyeksportowaniu z enova pełnych danych o interesującym nas zapisie i wzorowanie się na tak przygotowanym pliku. Należy jednak pamiętad, że funkcja Plik\Eksport danych tworzy pliki w trybie niebiznesowym (atrybut business="false" bądź nieustawiony), co oznacza, że struktura pliku będzie nieco inna od tej, która nas interesuje (w trybie biznesowym). 10

11 7 Podsumowanie i kontynuacja Przedstawiony dokument miał na celu zapoznanie z podstawowymi zasadami budowy plików XML wykorzystywanych do importu danych do systemu enova. Wszystkie omawiane przykłady dotyczyły importu dokumentu handlowego, ale ogólne zasady budowy plików XML są uniwersalne dla całego systemu enova. W kolejnym miesiącu w ramach kontynuowania tematu zostaną omówione: Import cech Import innych danych powiązanych (np. zapłaty, zaliczki) Uruchamianie importu z poziomu zewnętrznych dodatków 11