Dokumenty > Eksport/Import danych w formacie XML

Drukuj

Eksport/Import danych w formacie XML

W programie Kadry i Płace istotne dane mogą być eksportowane oraz importo­wane w formacie XML, który jest powszechnie akceptowanym standardem przesyła­nia danych w postaci tekstowej. W chwili obecnej można w ten sposób przesyłać następujące rodzaje danych:

Definicje elementów kartotek.

Wystąpienia zdarzeń.

Dane kadrowo-płacowe.

Dane płacowe dla miesięcy i lat.

Eksport w formacie 2009 (w.2009).

 

Eksport oraz import danych w formacie XML jest przydatny podczas wdrażania programu Kadry i Płace u klienta. Pozwala na stworzenie biblioteki standardowych definicji, które mogą być wielokrotnie używane w kolejnych wdrożeniach. Ułatwia również migrację danych z programów innych producentów do programu Kadry i Płace.

 

Przy pomocy eksportu/importu danych kadrowych i zdarzeń można synchronizować informacje wprowadzane w różnych oddziałach firmy. Możliwe też jest importowanie danych wygenerowanych przez programy innych producentów.

 

Eksport oraz import definicji elementów kartotek

Przydatnym narzędziem ułatwiającym wdrożenia programu Kadry i Płace są raporty uaktualniające. Pozwalają one w zautomatyzowany sposób wypełnić kartoteki definicjami standardowych zdarzeń, składników wynagrodzeń, schema­tów księgowań itp. Posługiwanie się raportami uaktualniającymi przyspiesza wdrożenia i pozwala unikać błędów, które są zwykle popełniane podczas wykonywania żmudnych czynności.

 

Raporty uaktualniające zawierają definicje rekordów kartotek w formacie XML. Poniżej przedstawiono szablon raportu uaktualniającego:

#include "upgrade.sci"

Zasoby:

 

<?xml version="1.0" encoding="windows-1250"?>

<db-document>

 

<!-- Tutaj należy dodać definicje rekordów kartotek. -->

 

</db-document>

<!-- end -->

 

Powyższy fragment kodu prezentuje stałe elementy raportu uaktualniającego tj. te, które muszą w nim zawsze wystąpić. We wskazanym miejscu należy wstawić definicje rekordów, które w wyniku wykonania raportu mają być dodane do odpowiednich kartotek. Definicje te są generowane automatycznie przez program Kadry i Płace.

 

Automatyczne generowanie definicji rekordów kartotek jest dostępne tylko dla tych użytkowników, którzy mają nadane prawo Wdrażanie programu Kadry i Płace.

 

W celu wygenerowania definicji rekordu kartoteki w formacie XML, należy wskazać ten rekord a następnie z menu kontekstowego wybrać polecenie Kopiuj definicje do schowka. Jak łatwo zgadnąć, po wykonaniu tych czynności, nowo utworzona definicja w formacie XML będzie znajdowała się w schowku systemu Windows. Teraz wystarczy ją po prostu wkleić do raportu uaktualniającego.

Możliwe jest generowanie wielu definicji na raz. W tym celu, przed wydaniem polecenia Kopiuj definicje do schowka, należy zaznaczyć wszystkie interesujące nas rekordy kartoteki.

Mechanizm automatycznego generowania definicji rekordów w formacie XML jest dostępny w następujących kartotekach:

Składniki wynagrodzeń

Formuły

Zestawy elementów

Zdarzenia

Schematy księgowań

Schematy przelewów

 

Jak już wspomniano, import definicji rekordów do odpowiednich kartotek odbywa się poprzez wykonanie raportu uaktualniającego. Czynność tę należy wykonać na samym początku wdrożenia tzn. jeszcze przed ręcznym dodaniem rekordów specyficznych dla danej firmy. Dzięki temu unikniemy ewentualnych konfliktów, które mają miejsce wtedy, gdy dwa różne rekordy kartoteki mają ten sam identyfikator. Ręczne dodawanie rekordów powoduje, że system bazy danych nadaje im unikalne identyfikatory (z puli wolnych identyfikatorów). Mogą one kolidować z identyfikatora­mi zadeklarowanymi w raportach, o ile te nie zostały wczytane wcześniej.

 

Poniżej przedstawiono przykładową definicję rekordu wyeksportowanego z kartoteki zestawy elementów.

<insert base="ZESTAWY" test="1">

 <id>9882</id>

 <id_zestawu>7801</id_zestawu>

 <element>33091</element>

 <atrybut>0</atrybut>

 <numer>8</numer>

 <typ>0</typ>

 <flagi>0</flagi>

</insert>

 

Warto zwrócić uwagę na atrybut test polecenia insert. Przy pomocy tego atrybutu można sterować sposobem reagowania na ewentualne konflikty identyfikatorów, występujące podczas wykonywania raportu uaktualniającego. Gdy test=”0” i w kartotece istnieje już rekord o takim samym identyfikatorze, wówczas definicja w raporcie zostanie pominięta. Jeśli test=”1”, to definicja w raporcie nadpisze rekord istniejący w kartotece. Jeżeli test=”2”, wówczas wykonywanie raportu zostanie natychmiast przerwane. Brak atrybutu test spowoduje, że w razie wystąpienia konfliktu, definicja w raporcie zostanie pominięta i, dodatkowo, wyświe­tlony zostanie komunikat o błędzie.

 

Eksport oraz import danych kadrowych

Dane kadrowe pracownika można wyeksportować na zakładce Dane Kadrowe formatki Pracownik, wybierając z menu konteksto­we­go polecenie Eksportuj wartości kadrowe. W tym wypadku zostaną wyeksportowane dane zawarte w wybranym zestawie kadrowym.

 

Dane kadrowe kilku pracowników na raz można wyeksportować na formatce Pracownicy. Wystarczy wskazać interesujących nas pracowników a następnie z menu kontekstowego wybrać polecenie Eksport danych kadrowych znajdujące się w podmenu Operacje zbiorcze.

 

Dane kadrowe można zaimportować z pliku w formacie XML do programu Kadry i Płace wybierając z menu głównego Firma polecenie Import danych kadrowych.

 

Ogólna struktura dokumentu

Poniżej przedstawiono szablon dokumentu w formacie XML, zawierającego dane kadrowe wyeksportowane z programu Kadry i Płace. Dla uproszczenia opisu, wszystkie wiersze w tym oraz innych przykładach zostały ponumerowane. W rzeczywistym dokumencie XML numery wierszy należy pominąć.

1        <?xml version="1.0" encoding="windows-1250"?>

2        <hr-document date="2001-12-01" user="Konto administratora">

3                <dictionary>

4                        <!-- definicje importowanych danych -->

5                </dictionary>

6                <data>

7                        <!-- wartości importowanych danych -->

8                </data>

9        </hr-document>

 

W wierszu [1] znajduje się standardowy nagłówek każdego dokumentu w formacie XML. Zawiera on informacje o wersji języka XML, oraz o zastosowanym kodowaniu znaków narodowych.

Tag <hr-document> w wierszu [2] jest początkiem właściwego dokumentu, zawierającego gotowe do importu dane kadrowe. Tag ten posiada dwa atrybuty: date oraz user. Atrybut date przechowuje datę eksportu danych. Atrybut user przechowuje nazwę użytkownika, który wyeksportował dane. Koniec dokumentu wyznacza tag </hr-document> w wierszu [9].

Pomiędzy tagami <dictionary> a </dictionary> znajduje się słownik, zawierający definicje importowanych wartości kadrowych oraz ich atrybutów. Struktura słownika jest szczegółowo opisana w podrozdziale Słownik. Pomiędzy tagami <data> a </data> znajdują się importowane wartości kadrowe. Struktura tej sekcji jest opisana w podrozdziale Dane.

 

Słownik

Słownik zawarty jest pomiędzy tagami <dictionary> a </dictionary>. Słownik zawiera definicje importowanych wartości kadrowych oraz ich atrybutów. Dzięki tym definicjom program Kadry i Płace jest w stanie jednoznacznie skojarzyć wartości kadrowe zawarte w dokumencie XML z odpowiednimi elementami kadrowymi, których wartości przechowywane są w bazie danych.

Słownik zawiera kilka rodzajów definicji. Są to definicje kalendarzy (pracowników, wzorców i firmy), zdarzeń, elementów kadrowych oraz ich atrybutów. Poszczególne definicje są powiązane z importowanymi danymi przy pomocy identyfikatorów definicji przechowywa­nych w obowiązkowym atrybucie id.

 

Kalendarz

Definicje kalendarzy służą do jednoznacznego identyfikowania pracowników, wzorców oraz firmy. Definicja kalendarza zawarta jest pomiędzy tagiem <calendar> a tagiem </calendar>. Z każdą definicją związany jest identyfikator definicji oraz typ kalendarza. Identyfikator definicji jest wykorzystywany do powiązania tej definicji z importowanymi danymi, dzięki czemu wiadomo, do którego kalendarza należy wpisywać wartości. Typ kalendarza określa, czy mamy do czynienia z pracownikiem (employee), wzorcem (template) czy też kalendarzem firmy (global).

1        <calendar id="1" type="employee">

2                <surname>Słodowy</surname>

3                <name>Adam</name>

4                <pesel>50050199999</pesel>

5                <nip>111-111-11-11</nip>

6                <birthday>1950-05-01</birthday>

7                <guid>{2099071C-84E5-4AAF-AA70-57D2D40AFFFA}</guid>

8        </calendar>

 

Powyższy przykład prezentuje sposób definiowania kalendarza. Tag <calendar> rozpoczyna­jący definicję w wierszu [1] ma dwa atrybuty: identyfikator definicji id oraz typ kalendarza type. Pola w wierszach od [2] do [7] opisują pracownika. Są to pola opcjonalne tzn. nie jest wymagane używanie ich wszystkich jednocześnie – można zastosować dowolny podzbiór jednoznacznie identyfikujący pracownika. W większości przypadków wystarczają pola <surname> (nazwisko), <name> (imię) oraz <birthday> (data urodzenia). Pole <guid> zawiera generowany programowo globalnie unikalny identyfikator i może być wykorzystane podczas integracji programu Kadry i Płace z programami firm trzecich.

 

Element kadrowy

Definicja elementu kadrowego zawarta jest pomiędzy tagami <component> oraz </component>. Każdy element kadrowy można jednoznacznie zidentyfikować przy pomocy jego nazwy, którą umieszczamy w polu <name>. W pliku zawierającym dane w formacie XML element kadrowy jest wskazywany przy pomocy identyfikatora zadeklarowanego w atrybucie id.

1        <component id="1">

2                <name>Umowa o dzieło</name>

3        </component>

 

Atrybut elementu kadrowego

Elementy kadrowe dzielimy na zwykłe oraz zgrupowane. Element zwykły przechowuje historię zmian prostej wartości kadrowej (atrybutu), która jest prezentowana w jednej kolumnie. Nazwa tej kolumny jest taka sama jak nazwa elementu kadrowego. Element zgrupowany przechowuje historię zmian wartości kadrowej będącej agregacją kilku wartości prostych (atrybutów). Taka złożona wartość jest prezentowana w kilku kolumnach. W programie Kadry i Płace każda kolumna jest zdefiniowana przy pomocy atrybutu elementu kadrowego.

 

Definicja atrybutu elementu kadrowego zawarta jest pomiędzy tagami <attribute> oraz </attribute>. Każdy atrybut można jednoznacznie zidentyfikować przy pomocy jego nazwy, którą umieszczamy w polu <name>. W pliku zawierającym dane w formacie XML, atrybut elementu kadrowego jest wskazywany przy pomocy identyfikatora id.

1        <attribute id="1">

2                <name>Kwota</name>

3        </attribute>

 

Zdarzenie

Definicja zdarzenia zawarta jest pomiędzy tagami <event> oraz </event>. Każde zdarzenie można jednoznacznie zidentyfikować przy pomocy jego nazwy, którą umieszczamy w polu <name>. W pliku zawierającym dane w formacie XML, zdarzenie jest wskazywane przy pomocy identyfikatora zadeklarowanego w atrybucie id.

1        <event id="1">

2                <name>Umowa o dzieło bez ubezpieczeń</name>

3        </event>

 

Dane

W dokumencie XML dane kadrowe zawarte są pomiędzy tagami <data> oraz </data>. Dane te są pogrupo­wane według kalendarzy. Zestaw danych przyporządkowanych do danego kalendarza umieszczony jest pomiędzy tagami <unit> oraz </unit>.

1        <data>

2                <unit calendar="1" begin="2000-01-01" end="2000-05-01" >

3                        <!-- dane kadrowe pracownika o identyfikatorze 1 -->

4                </unit>

5                <unit calendar="2" begin="2000-01-01" end="2000-05-01" >

6                        <!-- dane kadrowe pracownika o identyfikatorze 2 -->

7                </unit>

8        </data>

 

Kalendarz jest wskazywany przez atrybut calendar. Zadeklarowany przy jego pomocy numer odpowiada identyfikatorowi definicji kalendarza, którą można znaleźć w słowniku. Atrybuty begin (początek) oraz end (koniec) definiują przedział czasu, do którego wchodzą dane wyeksportowane z programu Kadry i Płace. Atrybuty te mają charakter informacyjny, są opcjonalne i można je pominąć.

 

Elementy kadrowe

Dane skojarzone z wybranym pracownikiem mogą zawierać wartości jednego lub więcej elementów kadrowych. Wartości poszczególnych elementów kadrowych umieszczane są pomiędzy tagami <component> oraz </component>. Każdy element kadrowy ma atrybut id, który wskazuje na definicję tego elementu umieszczoną w słowniku.

1        <unit calendar="1" begin="2000-01-01" >

2                <component id="1">

3                        <!-- wartości elementu kadrowego o identyfikatorze 1 -->

4                </component>

5                <component id="2">

6                        <!-- wartości elementu kadrowego o identyfikatorze 2 -->

7                </component>

8        </unit>

 

Historia zmian wartości

Wartości kadrowe mogą się zmieniać w czasie. Elementy kadrowe w programie Kadry i Płace przechowują historię zmian swoich wartości. W dokumencie XML historia zmian wartości kadrowych zawarta jest pomiędzy tagami <history> oraz </history>.

1        <component id="1">

2                <history>

3                        <value id="3" begin="2001-02-01" end="2001-02-28">7</value>

4                        <value id="3" begin="2001-03-01">13</value>

5                </history>

6        </component>

 

W powyższym przykładzie pokazano, jak zmieniały się wartości elementu kadrowego o identyfikatorze 1. Historia zawiera dwa wystąpienia wartości. Od 2001-02-01 do 2001-02-28 obowiązuje wartość "7", natomiast od 2001-03-01 obowiązuje wartość "13".

 

Elementy kadrowe zwykłe

Elementy kadrowe zwykłe przechowują historię zmian prostych wartości kadrowych, którą można prezentować w jednej kolumnie.

1        <history>

2                <value id="1" begin="2001-02-01" end="2001-02-28">7</value>

3                <value id="1" begin="2001-03-01">13</value>

4        </history>

 

Każda wartość zawarta jest pomiędzy tagami <value> oraz </value>. Identyfikator id wskazuje na definicję wartości w słowniku. W przypadku elementów kadrowych zwykłych definicja wartości jest tożsama z definicją jej jedynego atrybutu. Okres obowiązywania wartości deklaruje się przy pomocy atrybutów begin (początek) oraz end (koniec).

 

Jeżeli chcemy zadeklarować, że w jakimś przedziale czasu mamy do czynienia z nieokreśloną wartością kadrową, wówczas używamy uproszczonej notacji, której przykład zaprezentowano w wierszu [3] poniższego fragmentu kodu. Zaimportowanie tego kodu spowoduje dodanie pustego rzędu danych z okresem obowiązywania od 2001-03-01.

1        <history>

2                <value id="1" begin="2001-02-01" end="2001-02-28">7</value>

3                <value id="1" begin="2001-03-01" />

4        </history>

 

Elementy kadrowe zgrupowane

Elementy kadrowe zgrupowane przechowują historię zmian złożonych wartości kadrowych, które są prezentowane w kilku kolumnach. Każda taka wartość jest agregacją kilku wartości prostych (atrybutów).

1        <component id="2">

2                <history>

3                        <tuple begin="2001-02-01" end="2001-04-30">

4                                <value id="3">400.00</value>

5                                <value id="4">400.00</value>

6                                <value id="4" flags=”FIXED”>400.00</value>

7                        </tuple>

8                </history>

9        </component>

 

Wartość elementu zgrupowanego zawarta jest pomiędzy tagami <tuple> oraz </tuple>. Okres obowiązywania tej wartości deklaruje się przy pomocy atrybutów begin (początek) oraz end (koniec). Wartości poszczególnych atrybutów zawarte są pomiędzy tagami <value> oraz </value>. Identyfikator id wskazuje na definicję atrybutu w słowniku. Wartość może też posiadać flagi, definiuje się je przy pomocy atrybutu flags. W obecnej wersji jest uwzględniona flaga dla elementów inicjalizowanych. Jeżeli są one zmodyfikowane przez użytkownika otrzymują wartość FIXED i element nie będzie przeliczany (wyświetlany z zieloną ramką lub zielona flagą).

 

Elementy kadrowe wielowartościowe

W programie Kadry i Płace, w oknie definiowania składników wynagrodzeń, na zakładce Atrybuty można ustawić flagę "Dopuszczalne wiele wartości dziennie". Oznacza ona, że dany element kadrowy może mieć kilka wartości, których okresy obowiązywania nakładają się na siebie. Przykładowo, element Potomstwo może zawierać dane kilkorga dzieci pracownika. W dokumencie XML dane poszczególnych dzieci będą widoczne jako oddzielne historie. Jeżeli będą one importowane kilkukrotnie w celu uaktualnienia, wówczas konieczne jest rozróżnienie, która historia dotyczy danego dziecka. Jest to możliwe dzięki dołączeniu do każdej z nich innego globalnie unikalnego identyfikatora, w skrócie GUID.

 

Poniżej zaprezentowano przykładowe dane dzieci pracownika. Wiersze [3-26] zawierają słownik. Definiuje on pracownika [4-10], element kadrowy Potomstwo [11-13] oraz atrybuty tego elementu [14-25]. Dalej, w wierszach [27-54] znajdują się właściwe dane. Wartości dotyczące poszczególnych dzieci umieszczone zostały pomiędzy tagami <history> oraz </history>. Proszę zwrócić uwagę na atrybut guid. Jego użycie nie jest obowiązkowe.  Powinien być stosowany tylko wtedy, gdy dany element kadrowy wielowartościowy będzie importowany wielokrotnie. Jeżeli w tagu <history> jest atrybut guid i jego wartość można dopasować do identyfikatora istniejącej historii, wówczas importowane dane posłużą do jej uaktualnienia. Nowa historia zostanie utworzona tylko wtedy, gdy w tagu <history> nie ma atrybutu guid lub, gdy w bazie danych nie znaleziono historii o identycznej wartości identyfikatora.

1        <?xml version="1.0" encoding="windows-1250"?>

2        <hr-document date="2001-12-07" user="Konto administratora">

3                <dictionary>

4                        <calendar id="1" type="employee">

5                                <surname>Słodowy</surname>

6                                <name>Adam</name>

7                                <pesel>50050199999</pesel>

8                                <nip>111-111-11-11</nip>

9                                <birthday>1950-05-01</birthday>

10                        </calendar>

11                        <component id="1">

12                                <name>Potomstwo</name>

13                        </component>

14                        <attribute id="1">

15                                <name>imię</name>

16                        </attribute>

17                        <attribute id="2">

18                                <name>nazwisko</name>

19                        </attribute>

20                        <attribute id="3">

21                                <name>data urodzenia</name>

22                        </attribute>

23                        <attribute id="4">

24                                <name>miejscowość</name>

25                        </attribute>

26                </dictionary>

27                <data>

28                        <unit calendar="1" begin="2000-01-01">

29                                <component id="1">

30                                        <history guid="{FAC23730-EB2E-11D5-9ED9-005004032889}">

31                                                <tuple begin="2001-02-01">

32                                                        <value id="1">Piotr</value>

33                                                        <value id="2">Słodowy</value>

34                                                        <value id="3">1970-05-23</value>

35                                                        <value id="4">Warszawa</value>

36                                                </tuple>

37                                        </history>

38                                        <history guid="{FAC23731-EB2E-11D5-9ED9-005004032889}">

39                                                <tuple begin="2001-02-01" end="2001-05-31">

40                                                        <value id="1">Agata</value>

41                                                        <value id="2">Słodowa</value>

42                                                        <value id="3">1968-03-07</value>

43                                                        <value id="4">Warszawa</value>

44                                                </tuple>

45                                                <tuple begin="2001-06-01">

46                                                        <value id="1">Agata</value>

47                                                        <value id="2">Piaseczna</value>

48                                                        <value id="3">1968-03-07</value>

49                                                        <value id="4">Warszawa</value>

50                                                </tuple>

51                                        </history>

52                                </component>

53                        </unit>

54                </data>

55        </hr-document>

 

Transakcje i rozliczenia

Transakcje, podobnie jak elementy kadrowe wielowartościowe, mogą występować w tym samym czasie. W dokumencie XML poszczególne transakcje umieszczane są w oddzielnych historiach, pomiędzy tagami <history> oraz </history>. W skład transakcji wchodzi (obowiązkowo) rozpoczęcie transakcji oraz (opcjonalnie) kilka rozliczeń.

 

Rozpoczęcie transakcji objęte jest tagami <transaction> oraz </transaction>. Atrybut event wskazuje na zdarzenie zdefiniowane w słowniku, które w sposób jednoznaczny określa typ transakcji. Data rozpoczęcia transakcji deklarowana jest przy pomocy atrybutu begin. Z kolei atrybut guid pozwala zidentyfikować transakcję, której dane mają być uaktualnione podczas kolejnych operacji importu.

 

Rozliczenie transakcji umieszczone jest pomiędzy tagami <payment> oraz </payment>. Data rozliczenia deklarowana jest przy pomocy atrybutu date. Analogicznie jak w przypadku rozpoczęcia transakcji, atrybut guid pozwala zidentyfikować rozliczenie, którego dane mają być uaktualnione podczas kolejnych operacji importu.

1        <?xml version="1.0" encoding="windows-1250"?>

2        <hr-document date="2001-12-06" user="Konto administratora">

3                <dictionary>

4                        <calendar id="1" type="employee">

5                                <surname>Słodowy</surname>

6                                <name>Adam</name>

7                                <birthday>1950-05-01</birthday>

8                        </calendar>

9                        <event id="1">

10                        <name>Umowa o dzieło bez ubezpieczeń</name></event>

11                        <component id="1"><name>Umowa o dzieło</name></component>

12                        <attribute id="1"><name>kwota</name></attribute>

13                        <attribute id="2"><name>do rozliczenia</name></attribute>

14                        <attribute id="3"><name>zaległości</name></attribute>

15                        <attribute id="4">

16                                <name>domyślna wartość rozliczenia</name>

17                        </attribute>

18                        <attribute id="5"><name>miejscowość</name></attribute>

19                        <attribute id="6"><name>data</name></attribute>

20                        <attribute id="7"><name>nr umowy</name></attribute >

21                        <attribute id="8">

22                                <name>data zawarcia umowy</name>

23                        </attribute>

24                        <attribute id="9"><name>data rozpoczęcia</name></attribute>

25                        <attribute id="10"><name>rozliczenie</name></attribute >

26                </dictionary>

27                <data>

28                        <unit calendar="1" begin="2000-01-01">

29                                <component id="1">

30                                        <history>

31                                                <transaction begin="2001-05-01" event="1"

32                                                        guid="{D9207AB0-DFF4-11D5-9ED3-005004032889}">

33                                                        <value id="1">10 000.00 zł</value>

34                                                        <value id="2">9 000.00 zł</value>

36                                                        <value id="3">0.00 zł</value>

37                                                        <value id="4">1 000.00 zł</value>

38                                                        <value id="5">Warszawa</value>

39                                                        <value id="6">2001-05-01</value>

40                                                        <value id="7">1/2001</value>

41                                                        <value id="8">2001-05-01</value>

42                                                        <value id="9">2001-05-01</value>

43                                                </transaction>

44                                                <payment date="2001-05-25"

45                                                        guid="{D9207AB1-DFF4-11D5-9ED3-005004032889}">

46                                                        <value id="10">1 000.00 zł</value>

47                                                </payment>

48                                        </history>

49                                </component>

50                        </unit>

51                </data>

52        </hr-document>

 

Uwagi dotyczące identyfikatorów GUID

Podczas importu danych kadrowych, program Kadry i Płace musi mieć możliwość odróżniania sytuacji, w których intencją użytkownika jest dodanie nowych wartości, od sytuacji, w których użytkownik oczekuje, że uaktualnione zostaną wartości danych już istniejących (zaimportowanych wcześniej). W tym celu, podczas eksportu, do danych kadrowych dodawane są unikalne w czasie i przestrzeni identyfikatory GUID. Dana kadrowa, do której przyporządkowano GUID, będzie miała ten sam identyfikator we wszystkich systemach, do których zostanie przesłana. Dzięki temu, podczas kolejnych operacji eksportu/importu, będzie można uaktualnić jej wartość, gdyż zostanie ona jednoznacznie skojarzona z odpowiednimi danymi w importowanym pliku XML.

Podczas eksportu danych kadrowych, program Kadry i Płace automatycznie generuje identyfikatory GUID i dołącza je do odpowiednich zestawów danych. Jeżeli dane są importowane z innych systemów, wówczas to na nie spada odpowiedzialność za poprawne wygenerowanie identyfikatorów i przyporządkowanie ich do odpowiednich zestawów danych kadrowych, zgodnie ze specyfikacją daną w tym dokumencie. Ogólna zasada jest następująca. Jeżeli dana ma być przesłana dokładnie jeden raz, wówczas identyfikator GUID można pominąć. Jeżeli jednak dopuszczamy sytuację, w której ta sama dana może być przesyłana wielokrotnie, w celu aktualizacji, wówczas należy do niej dołączać identyfikator GUID.

Poniżej przedstawiamy kilka typowych scenariuszy eksportu i importu danych kadrowych, ze szczególnym uwzględnieniem zastosowania (lub nie) identyfikatorów GUID.

hmtoggle_plus1Scenariusz 1: Migracja danych
hmtoggle_plus1Scenariusz 2: Synchronizacja danych w środowisku rozproszonym
hmtoggle_plus1Scenariusz 3: Import danych z wyspecjalizowanych modułów

 

Eksport oraz import zdarzeń

Eksport oraz import zdarzeń w programie Kadry i Płace odbywa się podobnie do importu oraz eksportu danych kadrowych.

Zdarzenia można wyeksportować w Dzienniku Zdarzeń. W tym celu wystarczy wskazać na liście interesujące nas zdarzenia i z menu kontekstowego wybrać polecenie Eksportuj zdarzenia.

Zdarzenia można zaimportować z pliku w formacie XML do programu Kadry i Płace wybierając z menu głównego Firma polecenie Import zdarzeń.

Poniżej przedstawiono przykładowy plik zawierający dane o zdarzeniu Nadgodziny. Po zaimportowaniu tego pliku w kalendarzu pracownika pojawi się nowe zdarzenie.

<?xml version="1.0" encoding="windows-1250" standalone="yes"?>

<ev-document date="2005-02-08" user="Konto administratora">

 <dictionary>

         <calendar id="1" type="employee">

                 <surname>Arciszewski</surname>

                 <name>Zbigniew</name>

                 <birthday>1970-09-02</birthday>

         </calendar>

         <event id="1">

                 <name>Nadgodziny</name>

         </event>

 </dictionary>

 <data>

         <event id="1" calendar="1" begin="2004-11-03" end="2004-11-03"

                                 start="16:00:0" stop="18:00:0"/>

 </data>

</ev-document>

 

Program Kadry i Płace pozwala wyeksportować dowolne zdarzenia. Natomiast w przypadku importu istnieje jedno ograniczenie. Nie można importować zdarzeń dotyczących rozpoczęcia lub rozliczenia transakcji. Zdarzenia tego typu zostaną pominięte podczas importu. Dane o transakcjach można zaimportować przy pomocy opisanego wcześniej importu danych kadrowych.

 

Export oraz import danych płacowych

Program Kadry i Płace umożliwia eksport oraz import danych płacowych firmy lub pracowników, naliczonych dla miesięcy i lat. Odbywa się on podobnie do importu oraz eksportu danych kadrowych.

Eksport danych płacowych można wykonać na dwa sposoby:

z kartoteki pracowników,

z formatki pracownika lub firmy.

 

Eksport danych płacowych z kartoteki pracowników można wykonać dla jednego lub grupy pracowników wykonując polecenie Eksport danych płacowych z menu podręcznego. Po wybraniu polecenia pojawia się okno Eksport danych płacowych do XML, w którym należy określić parametry eksportowanych danych:

zakres dat okresów eksportowanych danych

typ eksportowanych okresów (wszystkie, bazowy, ZUS, podatkowy)

czy eksportować wartości dla roku

zestaw elementów, dla których mają być eksportowane wartości

 

Po kliknięciu przycisku Zapisz pojawia się okno gdzie należy wskazać nazwę pliku do zapisu.

 

Eksport danych płacowych z formatki pracownika lub formatki firmy dostępny jest na zakładce Miesiące – lata z menu podręcznego Eksport danych płacowych. W tym przypadku nie pojawia się okno z parametrami danych eksportu, gdyż eksportowane są dane aktualnie prezentowane na widoku.

 

Import danych płacowych wykonuje się poleceniem z menu Firma > Import danych > płacowych. Następnie należy wskazać plik XML zawierający dane do importu. Poprawna operacja importu kończy się bez żadnych komunikatów.

 

Struktura dokumentu XML dla danych płacowych

Poniżej przedstawiono przykładowy dokument w formacie XML, zawierający dane płacowe wyeksportowane z programu Kadry i Płace.

<?xml version="1.0" encoding="windows-1250" standalone="yes"?>

<mypv-document date="2005-03-07" user="Konto administratora">

 <dictionary>

         <calendar id="1" type="employee">

                 <surname>Arciszewski</surname>

                 <name>Zbigniew</name>

                 <birthday>1970-09-02</birthday>

         </calendar>

         <component id="1">

                 <name>Informacja o kosztach uzyskania przychodów</name>

         </component>

         <component id="2">

                 <name>PIT 11/8B(2005) poz.34 PIT 40(2005) poz.35</name>

         </component>

 </dictionary>

 <data>

         <calendar id="1">

                 <period date="2004-01-01" type="3">

                         <component id="1" group="7">

                                 <flags>0</flags>

                                 <count>1</count>

                                 <value>1</value>

                                 <string>od jednego zakładu pracy</string>

                         </component>

                         <component id="2" group="1">

                                 <flags>1</flags>

                                 <count>1</count>

                                 <value>1999</value>

                                 <string>1 999,00 zł</string>

                         </component>

                 </period>

                 <period date="2004-01-01" type="6">

                 </period>

         </calendar>

 </data>

</mypv-document>

 

W pierwszej linijce dokumentu występuje standardowy nagłówek XML. W drugiej linijce zawarty jest tag mypv-document rozpoczynający sekcję danych płacowych dla miesięcy i lat. Tag ten zawiera atrybuty date oraz user z informacją o dacie eksportu oraz użytkowniku, który go wykonał. Dane płacowe zapisane są w strukturze znanej z danych kadrowych, na którą składają się sekcje słownika oraz właściwych danych.

Pomiędzy tagami <dictionary> a </dictionary> znajduje się słownik, zawierający definicje pracowników oraz elementów, dla których zapisane są wartości płacowe. Struktura słownika jest identyczna z danymi kadrowymi i jest szczegółowo opisana w rozdziale 3.2 Słownik.

Pomiędzy tagami <data> a </data> znajdują się importowane wartości płacowe, zapisane w kaskadowej strukturze kolejnych tagów. Pomiędzy tagami <calendar> a </calendar> znajdują się dane dla jednego pracownika, określonego atrybutem id, odpowiadającym id pracownika zdefiniowanego w słowniku. Kolejny tag <period> określa okres z jakiego pochodzą dane. Tag ten zawiera dwa atrybuty date oraz type. Atrybut date określa datę okresu tj. rok i miesiąc, dzień powinien zawsze być pierwszym dniem miesiąca lub roku. Atrybut type określa typ okresu.

Atrybut type może przybrać następujące wartości:

1 – okres miesiąc bazowy

2 – okres miesiąc ZUS

3 – okres miesiąc podatkowy

4 – okres rok bazowy

5 – okres rok ZUS

6 – okres rok podatkowy

 

Kolejnym tagiem w strukturze jest <component> odpowiadający elementowi płacowemu. Atrybut id określa definicję elementu ze słownika, natomiast atrybut group określa typ grupowania wartości. Mogą istnieć różne wartości dla tego samego elementu, ale dla różnych grupowań.

 

Atrybut group może przybrać następujące wartości:

1 - suma wartości

2 - wartość średnia wszystkich wartości

3 - wartość średnia wartości niezerowych

4 - pierwsza wartość

5 - pierwsza niezerowa wartość

6 - ostatnia wartość

7 - ostatnia niezerowa wartość

8 - minimalna wartość

9 - minimalna niezerowa wartość

10 - maksymalna wartość

 

W tym miejscu struktury dokumentu znajdują się cztery tagi bez atrybutów określające wartość elementu:

Pomiędzy tagami <flags> </flags> znajdują się flagi wartości (obecnie mogą to być: 1 – wartość zafiksowana  2 – wartość zaimportowana).

Pomiędzy tagami <count> </count> zawarta jest liczba naturalna określająca liczbę wartości z ilu dana wartość została zgrupowana.

Pomiędzy tagami <value> </value> znajduje się wartość elementu w postaci liczbowej.

Pomiędzy tagami <string> </string> znajduje się wartość elementu w postaci tekstowej.

 

Format  XML (w.2009)

Format Eksport XML (w.2009) ten jest nowszą wersją eksportu XML, zorientowaną obiektami biznesowymi.

 

Wcześniejsze rozwiązania eksportu danych (kadrowych, płacowych zdarzeń) charakteryzowały tym, że:

eksport różnych danych dla pracownika (dane kadrowe, zdarzenia, dane płacowe) odbywał się z różnych miejsc programu.

plik XML miał strukturę złożoną:

osekcja definicji dictionary

osekcja danych data (zależna od dictionary)

operacja importu polegała na tym, że trzeba było wybrać jaki rodzaj danych się importuje i Dane Kadrowe – i wybrać plik. Konstrukcja taka zakładała, że użytkownik wie (lub pamięta) jakie dane są w pliku XML i wtedy wykonuje operację importu.

 

Format eksportu XML (w. 2009) zakłada, że:

eksport obiektu biznesowego będzie odbywał się w jednym miejscu, użytkownik wskaże na formatce eksportu w. 2009 dla danego obiektu biznesowego (np. pracownika) – jakie dane będzie eksportował i dane te zostaną zapisane do jednego pliku.

plik XML będzie miał strukturę prostą – sekcja z danymi dla pracownika będzie kompletna (nie będzie już sekcji dictionary), co umożliwi na przykład wydzielenie z pliku XML danych dla wybranego (lub wybranych) pracownika (pracowników).

Operacja importu będzie odbywała się z jednego miejsca w programie, użytkownik najpierw wybierze, jakie dane będzie chciał zaimportować z pliku XML, a potem wybierze plik. Program sprawdzi, czy w podanym pliku są wymagane dane i jeśli je znajdzie to zaimportuje je do programu.

 

Interfejs użytkownika

Na oknie Ustawienia w gałęzi Komunikacja > Eksport XML, na formatce w prawej części okna jest nowa zakładka Eksport XML (w.2009). Służy ona do ustawienia sposobu identyfikacji obiektów Pracownika oraz eksportowanych definicji obiekty: Kartoteki i Wzorce. Należy tak ustawić te parametry, aby podczas eksportu weszły do pliku XML te dane, które podczas operacji importu wystarczą do uzyskania jednoznaczności danych. Jeśli eksport i import jest w ramach tej samej bazy i nie służy do zakładania pracowników, to może wystarczyć tylko skrót pracownika, który jest unikalny w zakresie jednej bazy. Jeśli operacja eksportu/importu jest bardziej skomplikowana, potrzebne jest więcej danych o pracowniku – zwłaszcza, jeśli Pracownik będzie zakładany podczas importu do bazy (tzn. nie było go w bazie) – wtedy potrzebne są zawsze Imię i Nazwisko.

 

Eksport

Na oknie Pracownicy w podmenu eksportu danych jest nowa opcja Eksport XML (w.2009).

Otwiera ona okno eksportu danych pracownika gdzie użytkownik może wybrać:

zakres dat eksportowanych danych

oraz dane dla pracownika, które będą eksportowane – tzn:

oprzypisania pracownika do wzorców

oinicjalizacja kalendarza.

Możliwe do wyeksportowania są te dane, do których zalogowany użytkownik posiada uprawnienia.

 

Import

W głównym oknie programu, w menu Firma > Import znajduje się nowa opcja Import (w.2009).

Otwiera ona okno do wyboru danych, jakie będą importowane z pliku XML. Po wyborze danych i pliku XML następuje import.

 

Format pliku XML (w.2009)

Plik XML w.2009 posiada następującą strukturę:

1.Tag: xml-symfonia – z dwiema przestrzeniami nazw: obiekt i dane. Obiektem jest Pracownik. Danymi są:

wzorce – przypisania do wzorców dla pracownika

initkal – Inicjalizacja kalendarza pracownika

2.Tag: kadry-document z atrybutami:

wersja = „2009”  – do rozpoznania eksportu XML (w.2009)

date = „2008-11-24” – data wykonania eksportu

begin = data początkowa eksportowanych danych

end = data końcowa eksportowanych danych

Tag ten musi posiadać atrybut: wersja=”2009” , który służy do identyfikacji pliku do opcji importu.

3.Tag: obiekt:pracownik – Tag obiektu pracownika obejmujący wszystkie dane dla danego pracownika – atrybuty: identyfikujące pracownika, z formatki ustawień. W przykładzie zostały podane wszystkie atrybuty, natomiast do rzeczywistych plików wystarczą tylko te które jednoznacznie identyfikują pracownika w danej bazie. W przykładzie poniżej znajdują się wszystkie opisywane Tagi. Pracownik może posiadać następujące dane:

dane:wzorce – tag danych - przypisania wzorców dla pracownika – Tag ten może być dzieckiem Tagu – Pracownik. Zawiera listę przypisania pracownika do wzorców:

otag: wzorzec – przypisanie pracownika do wzorca w konkretnym zakresie dat. Posiada atrybuty (nazwa lub skrót jest konieczna do identyfikacji):

nazwa – do identyfikacji wzorca

skrót – do identyfikacji wzorca

begin – datę początkową

end – datę końcową

dane:initkal – tag danych – inicjalizacji kalendarza dla pracownika – Tag ten może być dzieckiem Tagu – Pracownik. Inicjalizacja kalendarza może posiadać atrybuty begin i end. Atrybuty te służą do określenia daty, która może zostać użyta podczas importu do usunięcia poprzedniej inicjalizacji (użyta opcja podczas importu). Jeśli opcja taka jest użyta, to podczas inicjalizacji kalendarza, poprzednie inicjalizacje z zakresu dat podanych w begin i end zostaną usunięte (data „begin” musi być wypełniona – jeśli jest pusta poprzednia inicjalizacja nie jest usuwana). Inicjalizacja kalendarza może obejmować:

odni – inicjalizacja kalendarza wzorcem czasu pracy (inicjalizacja indywidualna)

dzienwzorzec – inicjalizacja Wzorcem Czasu Pracy – systemem okresowym. Atrybuty: do identyfikacji wzorca czasu pracy: Nazwa i skrot. Atrybuty informacyjne: begin (data początkowa), end (data końcowa) prior (priorytet), nrdnia (od 0 do 7) – kolejny numer z listy z formatki Inicjalizacji kalendarza Wzorcem czasu pracy : Pierwszy dzień skojarz z.

dzien – inicjalizacja Wzorcem Czasu pracy- wzorcem Dnia. Atrybuty: do identyfikacji wzorca czasu pracy: Nazwa i skrot. Atrybuty informacyjne: begin (data początkowa), end (data końcowa) prior (priorytet).

odnigodziny – inicjalizacja za pomocą opcji Edycji Harmonogramu – bezpośredniego podawania godzin i minut czasu pracy dla pracownika na kalendarzu dziennym lub tygodniowym.

dzienpracy – informacja o pojedynczym dniu pracy. Atrybuty: do identyfikacji wzorca dnia: Nazwa i skrot (skrót), do określenia dnia: data (dzień) i prior (priorytet).

praca – lista Tagów określających godziny pracy w danym dniu. Atrybuty do identyfikacji Rodzaju Pracy : nazwa i skrot (skrót). Atrybuty godzin : Start, Stop, flagi. Flagi służą do określenia, że praca nie zahacza o następny dzień: flagi="F_CALY" (cała praca jest w dniu następnym czyli np. od 2:00 do 4:00 rano)  flagi="F_KON" (zaczyna się w danym dniu, a kończy się w dniu następnym tzn np. od 22: do 6:00).

 

Przykładowy plik XML w formacie XML w.2009 – zawierający elementy opisane powyżej.

<?xml version="1.0" encoding="windows-1250" standalone="yes"?>

<xml-symfonia xmlns:obiekt="urn:symfonia/kadry/xml" xmlns:dane="urn:symfonia/kadry/xml">

 <kadry-document wersja="2009" date="2008-11-24" begin="2008-01-01" end="2009-01-01">

         <obiekt:pracownik nazwisko="Abacki" imie="Adam" guid="{159AE442-316B-4D89-8394-3089AEA3DEEF}" skrot="Abacki Adam (20000)" pesel="68110832122" nip="1234567890" dataurodz="1970-12-09">

                 <dane:wzorce>

                         <wzorzec nazwa="Pracownik etatowy" skrot="Pracownik etatowy (19001)" begin="2008-10-01"/>

                         <wzorzec nazwa="Wynagrodzenie zasadnicze" skrot="Wynagrodzenie zasadnicze (19004)" begin="2008-10-01"/>

                         <wzorzec nazwa="(Współ)Pracownik" skrot="(Współ)Pracownik (19031)" begin="2008-10-01"/>

                         <wzorzec nazwa="Płatność przelewem (etat)" skrot="Płatność przelewem (etat) (19034)" begin="2008-10-01"/>

                         <wzorzec nazwa="Rozliczenie zasiłku chorobowego" skrot="Rozliczenie zasiłku chorobowego (19064)" begin="2008-10-14" end="2008-10-16"/>

                         <wzorzec nazwa="Potrącenie wynagrodzenia za zasiłki" skrot="Potrącenie wynagrodzenia za zasiłki (19067)" begin="2008-10-14" end="2008-10-16"/>

                         <wzorzec nazwa="Urlop wypoczynkowy" skrot="Urlop wypoczynkowy (19063)" begin="2008-11-18" end="2008-11-20"/>

                 </dane:wzorce>

                 <dane:initkal begin="2008-01-01" end="2009-01-01">

                         <dni>

                                 <dzien nazwa="Dzień roboczy 8.5 godz." skrot="DR 8,5" begin="2008-10-03" end="2008-10-03" prior="1000"/>

                                 <dzienwzorzec nazwa="Brygada B" skrot="Bryg B" begin="2008-10-04" end="2008-10-04" prior="2000" nrdnia="0"/>

                                 <dzienwzorzec nazwa="Brygada A" skrot="Bryg A" begin="2008-10-04" end="2008-10-04" prior="4000" nrdnia="0"/>

                         </dni>

                         <dnigodziny>

                                 <dzienpracy nazwa="Dzień roboczy 8 godz." skrot="DR 8h" data="2008-10-02" prior="1000">

                                         <praca nazwa="Domyślny rodzaj pracy" skrot="PracaD" start="8:00" stop="9:00"/>

                                         <praca nazwa="Domyślny rodzaj pracy" skrot="PracaD" start="9:00" stop="18:30"/>

                                 </dzienpracy>

                         </dnigodziny>

                 </dane:initkal>

         </obiekt:pracownik>

 </kadry-document>

</xml-symfonia>