Dokumentacja Użytkownika Systemu

Transkrypt

1 Dokumentacja Użytkownika Systemu Importy z plików XML Wersja 7.2

2 Spis treści 1 CO TO JEST XML INFORMACJE OGÓLNE NA TEMAT STRUKTURY PLIKÓW XML IMPORT KONTRAHENTÓW IMPORT KONTRAHENTÓW STRUKTURA PLIKU XML LEGENDA SZCZEGÓŁOWY OPIS STRUKTURY IMPORT SUBSKRYBENTÓW IMPORT SUBSKRYBENTÓW STRUKTURA PLIKU XML LEGENDA SZCZEGÓŁOWY OPIS STRUKTURY POMOC!...14 Importy z plików XML 2 v.7.2

3 1 Co to jest XML Eksport i import danych w Comarch ERP e-sklep odbywa się za pośrednictwem plików w formacie XML dzięki temu zostały spełnione założenia projektowe dotyczące łatwości implementacji w różnych systemach (również programach firm trzecich) oraz elastyczności w zakresie ewentualnych zmian danych z zachowaniem kompatybilności z poprzednimi wersjami. XML (skrót od extensible Markup Language - rozszerzalny język znaczników) to otwarty standard opracowany przez W3C. XML nie jest kolejnym językiem do przechowywania konkretnych danych, jak np. język HTML opisujący wygląd stron sieciowych. XML to język opisujący dane, czyli metajęzyk. W uproszczeniu można powiedzieć, że XML służy do tworzenia innych języków (aplikacji XML) służących do przechowywania informacji. Jeśli mamy potrzebę zapisywania określonych danych o określonej strukturze, XML okaże się najlepszym narzędziem, bez względu, jakie by te dane nie były. W przeciwieństwie do np. HTML, XML nie ma ograniczonej liczby znaczników, bo pozwala przechowywać dowolne dane i to w jak najbardziej wygodny dla nas sposób, bo sami go określamy. Sami określamy strukturę danych, która może być tabelaryczna, ale może także tworzyć drzewo. W ten sposób nie jesteśmy, jako twórcy baz danych XML w żaden sposób ograniczeni. Na tym właśnie polega wyższość XML nad innymi formatami zapisu danych. Potrzeba uniwersalnego i czytelnego formatu danych widoczna była od dawna, a w czasach gwałtownego powiększania się sieci stała się koniecznością. Wreszcie pojawił się format pozwalający na łatwe przechowywanie dowolnych danych. Dzięki oddzieleniu treści od formy (czego nie umożliwia HTML) łatwo skupić się na samych danych. Programy mogą dzięki formatowi XML łatwiej wymieniać dane i je przetwarzać. Prosty przykład wykorzystania formatu XML:  <ludzie> <człowiek> <imie>jan</imie> <nazwisko>kowalski</nazwisko> <poczta>jan.kowalski@comarch.pl</poczta> <web> </człowiek> <człowiek> <imie>józef</imie> <nazwisko>nowak</nazwisko> <poczta>jozef.nowak@comarch.pl</poczta> <web> </człowiek> </ludzie> Importy z plików XML 3 v.7.2

4 2 Informacje ogólne na temat struktury plików XML Tworząc struktury plików importowych należy wziąć pod uwagę następujące informacje: 1. Dane zawarte w pliku XML są pogrupowane w tzw. węzły. 2. Główny węzeł jest zawsze jeden i do niego podpinane są kolejne podwęzły odpowiedzialne za poszczególne grupy importowanych informacji. 3. Nie ma obowiązku umieszczania wszystkich podwęzłów w pliku importowym. Jeśli jakaś grupa danych nie podlega importowi, to odpowiedni podwęzeł nie jest wymagany. 4. Węzeł lub podwęzeł, jako taki sam nie zawiera danych są one rozmieszczone w podpiętej do niego strukturze pól (znaczników, etykiet, tagów). 5. Dane są umieszczone, jako wartości pól, a nie atrybuty pól, czyli jest zawsze: <Phone> </Phone> a nie: <Phone value= ></Phone> 6. W przypadku występowania w pliku XML braku wartości lub wartości pustych, dane nie są importowane do bazy danych sklepu. 7. Podwęzły dzielimy na grupujące dane oraz tworzące listy danych. 8. W strukturze plików XML wszystkie wartości są tekstami, ale dla potrzeb poprawnego importu do Comarch ERP e-sklep wartości poszczególnych etykiet muszą mieć określony format. W tym celu w opisie przy każdej z nich umieszczono informacje o wymaganym formacie: STRING znaki alfanumeryczne (cyfry i litery). Podawane w nawiasach ograniczenie w ilości znaków, które można wprowadzić do Tagu, dotyczy ilości, która zostanie zaimportowana, a nie ilości wyeksportowanej. Przykładowo określenie STRING(20) oznacza, że program zaimportuje pierwszych 20 znaków z podanego ciągu znaków, a ciąg ten może być w rzeczywistości dużo dłuższy. INTEGER wartości liczbowe nie zawierające części dziesiętnych. Importy z plików XML 4 v.7.2

5 3 Import kontrahentów 3.1 Import kontrahentów W Comarch ERP e-sklep w obszarze Panel administracyjny/kontrahenci/import kontrahentów jest możliwość wgrania pliku XML z danymi kontrahentami. Uwaga: Struktura wgrywanego pliku XML przy impo rcie kontrahentów musi być zgodna z daną wersją sklepu. Wersja 2.0 plików XML dla kontrahentów jest wymagana od wersji 5.4 Comarch ERP e-sklep. Import kontrahentów składa się z dwóch obszarów: Import z pliku XML oraz Lista ostatnich logów. W obszarze Import kontrahentów po kliknięciu na Dokumentacja / struktura pliku znajduje się schemat, co powinien zawierać plik XML dla importu kontrahentów. Aby wgrać plik XML należy kliknąć na, następnie po wybraniu odpowiedniego pliku należy przycisnąć. Uwaga: Wszystkie pola z wyjątkiem REGON (pole może pozostać puste) w importowanym pliku XML są wymagane. Brak wypełnionego któregokolwiek z pól może spowodować błędy importu kontrahentów. Przy imporcie kontrahentów odpowiednie dane kontrahentów są pobierane ze wskazanego wcześniej pliku XML. W przypadku, gdy wczytywany plik jest błędy administrator sklepu otrzyma odpowiedni komunikat informacyjny: Komunikat ten może się pojawić, gdy: Dany kontrahent w pliku XML nie ma wszystkich danych wtedy też pozostali kontrahenci zawarci w pliku XML nie zostaną zaimportowani, gdyż struktura pliku XML nie jest poprawna. W pliku XML nie są wypełnione wszystkie pola nawet te, które są z danymi do faktury. Został zdublowany adres kontrahenta kolejny kontrahent o takim samym adresie nie zostanie dodany do listy kontrahentów, jednak inni kontrahenci, którzy jeszcze nie są w bazie sklepu zostaną zaimportowani. Podany adres dla danego kontrahenta nie jest poprawny w tym przypadku pozostali kontrahenci nie zostaną zaimportowani. Importy z plików XML 5 v.7.2

6 Po poprawnym imporcie do kontrahentów, którzy byli importowani z pliku XML jest wysyłany Konto utworzone w e-sklep przez Administratora, który zawiera odpowiednie informacje o utworzonym koncie w sklepie. Nowo zaimportowani kontrahenci są również aktywni tak, więc mogą zalogować się do sklepu na otrzymane dane oraz dokonać zakupu. W obszarze Lista ostatnich 10 logów znajdują się informacje o błędach w wysłanym pliku XML wraz z datą jego wgrania. 3.2 Struktura pliku XML Legenda kolor brązowy węzeł główny zbioru XML kolor czerwony podwęzeł węzła głównego zawierający dane danego kontrahenta kolor niebieski subwęzły podpięte pod węzeł z danymi kontrahenta kolor czarny informacje zapisane w ramach węzła lub subwęzła 3.3 Szczegółowy opis struktury - <Customers> Plik zawsze zawiera tylko jeden węzeł na najwyższym poziomie, o nazwie Customers. Węzeł ten posiada atrybut o nazwie Version i wartości liczbowej (INTEGER) równej 2: Version="2" - <Customer> Węzeł <Customer> zawiera dane 1 kontrahenta. Węzeł ten posiada atrybuty o nazwie company i invoice, przyjmują one wartości liczbowe (INTEGER) 0 lub 1, oraz type, który przyjmuje wartości 1,2,3: company= 1 kontrahent firma company= 0 kontrahent osoba prywatna invoice= 1 z fakturą invoice= 0 bez faktury type= 1 -kontrahent krajowy type= 2 -kontrahent wewnątrzunijny type= 3 -kontrahent pozaunijny Jeżeli company= 1, invoice musi mieć wartość 1 - < > STRING(192) Adres kontrahenta: - maksymalna długość: 192 znaki - minimalna długość: 5 znaków < >test@comarch.pl</ >. Importy z plików XML 6 v.7.2

7 <ShippingData> <Name1> Tagi zawierające pola adres dostawy kontrahenta. Po zaimportowaniu pliku dane pojawią się w sklepie w panelu administracyjnym w Kontrahenci/Lista kontrahentów/edycja danego kontrahenta/ zakładka Adresy. STRING(50) Nazwa kontrahenta - (pierwsza linia): - maksymalna długość: 50 znaków <Name1>Jan Kowalski</Name1> <Name2> Nazwa kontrahenta - (druga linia): <Name2>Firma test</name2> <City> STRING(50) Miasto kontrahenta: - maksymalna długość: 50 znaków <City>Kraków</City> <PostCode> STRING(20) Kod pocztowy kontrahenta: - maksymalna długość: 20 znaków <PostCode>32-222</PostCode> <Street> STRING(50) Ulica kontrahenta: - maksymalna długość: 50 znaków <Street>ul.Testowa 4</Street> Importy z plików XML 7 v.7.2

8 <HouseNo> <FlatNo> STRING(20) STRING(20) W przypadku braku numeru mieszkania należy podać -. <State> STRING(50) Województwo kontrahenta: - maksymalna długość: 50 znaków <State>małopolskie</State> <Country> Państwo kontrahenta: - należy wybrać skrót danego Państwa z dostępnej listy w Dokumentacja/Struktura pliku dostępnej w panelu administracyjnym - skróty brane są z kodów ISO skróty należy pisać z dużych liter <Country>PL</Country> Poniżej przykłady skróty Państw: PL - Polska FR - Francja DE - Niemcy GB - Wielka Brytania US - Stany Zjednoczone UA Ukraina <Phone> STRING(50) Telefon kontrahenta: - maksymalna długość: 50 znaków <Phone> </Phone> <Phone>(22) </Phone> <Phone> </Phone> Importy z plików XML 8 v.7.2

9 <InvoiceData> <Name1> <Name2> <City> <PostCode> <Street> <HouseNo> <FlatNo> <State> <Country> <Phone> <NIP> Tagi zawierające pola dane do faktury kontrahenta. Po zaimportowaniu pliku dane pojawią się w sklepie w panelu administracyjnym w Kontrahenci/Lista kontrahentów/edycja danego kontrahenta/ zakładka Dane ogólne. Pole nie jest wymagane! STRING(20) NIP kontrahenta: - maksymalna długość: 20 znaków <NIP> </NIP> <NIP> </NIP> <Regon> Pole jest wymagane. STRING(20) Regon kontrahenta: - maksymalna długość: 20 znaków <Regon> </Regon> Pole nie jest wymagane. Importy z plików XML 9 v.7.2

10 Przykładowy plik xml - Kontrahenci <?xml version="1.0" encoding="utf-8"?> <Customers Version="2"> <Customer Company="1" Invoice="1" Type="1"> < >test@comarch.pl</ > <ShippingData> <Name1>Jan Kowalski</Name1> <Name2>Firma test</name2> <City>Kraków</City> <PostCode>32-222</PostCode> <Street>Testowa</Street> <HouseNo>34a</HouseNo> <FlatNo>5</FlatNo> <State>małopolskie</State> <Country>PL</Country> <Phone> </Phone> </ShippingData> <InvoiceData> <Name1>Jan Kowalski</Name1> <Name2>Firma test Sp. z o.o.</name2> <City>Warszawa</City> <PostCode>32-008</PostCode> <Street>Firmowa</Street> <HouseNo>44</HouseNo> <FlatNo>8</FlatNo> <State>mazowieckie</State> <Country>PL</Country> <Phone> </Phone> <NIP> </NIP> <Regon> </Regon> </InvoiceData> </Customer> <Customer Company="0" Invoice="0" Type="2"> < >test1@comarch.pl</ > <ShippingData> <Name1>Andrzej Nowak</Name1> <Name2>Wewnątrzunijny test1</name2> <City>Shwaz</City> <PostCode>3222</PostCode> <Street>Mein</Street> <HouseNo>88</HouseNo> <FlatNo>4</FlatNo> <State>Tirol</State> <Country>AT</Country> <Phone> </Phone> </ShippingData> </Customer> </Customers> Importy z plików XML 10 v.7.2

11 4 Import Subskrybentów 4.1 Import Subskrybentów W Comarch ERP e-sklep w obszarze Panel administracyjny/zarządzanie treścią/newsletter/import subskrybentów jest możliwość wgrania pliku XML z danymi subskrybentów. Import subskrybentów składa się z dwóch obszarów: Import z pliku XML oraz Lista ostatnich logów. W obszarze Import kontrahentów po kliknięciu na Dokumentacja / struktura pliku znajduje się schemat, co powinien zawierać plik XML dla importu kontrahentów. Aby wgrać plik XML należy kliknąć na, następnie po wybraniu odpowiedniego pliku należy przycisnąć. Uwaga: Wszystkie pola w importowanym pliku XML są wymagane. Brak wypełnionego któregokolwiek z pól może spowodować błędy importu subskrybentów. Przy imporcie subskrybentów odpowiednie dane są pobierane ze wskazanego wcześniej pliku XML. W przypadku, gdy wczytywany plik jest błędny administrator sklepu otrzyma odpowiedni komunikat informacyjny: Komunikat ten może się pojawić, gdy: Dany subskrybent w pliku XML nie ma wszystkich danych wtedy też pozostali subskrybenci zawarci w pliku XML nie zostaną zaimportowani, gdyż struktura pliku XML nie jest poprawna. Został zdublowany adres subskrybenta kolejny subskrybenta o takim samym adresie nie zostanie dodany do listy subskrybentów, jednak inni subskrybenci, którzy jeszcze nie są w bazie sklepu zostaną zaimportowani. Podany adres dla danego kontrahenta nie jest poprawny w tym przypadku pozostali subskrybenci nie zostaną zaimportowani. Po poprawnym imporcie do subskrybentów, którzy byli importowani z pliku XML jest wysyłany z linkiem aktywacyjnym wysyłkę newslettera. Do momentu aż dany subskrybent nie aktywuje wysyłki newslettera jest on nie aktywny w sklepie na liście subskrybentów. W obszarze Lista ostatnich 10 logów znajdują się informacje o błędach w wysłanym pliku XML wraz z datą jego wgrania. Importy z plików XML 11 v.7.2

12 Struktura pliku XML Legenda kolor brązowy węzeł główny zbioru XML kolor czerwony podwęzeł węzła głównego zawierający dane subskrybenta kolor czarny subwęzły podpięte pod węzeł z danymi subskrybenta 4.2 Szczegółowy opis struktury - <Subscribers> Plik zawsze zawiera jeden (i tylko jeden) węzeł na najwyższym poziomie, o nazwie Subscribers. - <Subscriber> Węzeł <Subscriber> zawiera dane 1 subskrybenta. - < > STRING(192) Adres kontrahenta: - maksymalna długość: 192 znaki - minimalna długość: 5 znaków < >test@comarch.pl</ >. <Language> Język newslettera. Tag ten przyjmuje wartości 1,2,3,4,5 <Language>1</Language> Wartość: 1 język polski 2 język angielski 3 język niemiecki 4 język ukraiński 5 język francuski Importy z plików XML 12 v.7.2

13 Przykładowy plik xml - Subskrybenci <?xml version="1.0" encoding="utf-8"?> <Subscribers Version="1"> <Subscriber> < >test1@comarch.pl</ > <Language>1</Language> </Subscriber> <Subscriber> < >test2@comarch.com</ > <Language>2</Language> </Subscriber> <Subscriber> < >test3@icomarch24.pl</ > <Language>3</Language> </Subscriber> </Subscribers> Importy z plików XML 13 v.7.2

14 5 Pomoc! Więcej informacji na temat funkcjonalności sklepu internetowego znajdą Państwo na stronie Comarch ERP e-sklep - kliknij tutaj. KONTAKT Dowiedz się więcej o Systemie Obsługi Zgłoszeń >> Telefon do asysty: wew. 2 Importy z plików XML 14 v.7.2