Szablony generatora dokumentów
1. Wstęp
Platforma eTeczki eFOB umożliwia generowanie dokumentów na podstawie szablonów, analogicznie jak to się dzieje w mechanizmach generowania dokumentów opartych na korespondencji seryjnej. Użytkownicy mogą tworzyć własne szablony *.docx korzystając z aplikacji LibreOffice kompatybilnej z MS Word, lub *.html przygotowując plik w kodzie tego języka.
Podczas generowania dokumentów, eFOB przy generacji automatycznie wypełnia pola dokumentów danymi z modułów systemu (np. Pracownicy, Kandydaci, Sprawy) lub danymi z kolumn z załączonego Excel. Dzięki temu mechanizmowi, generowanie dokumentów pracowniczych na podstawie szablonów staje się łatwe i efektywne.
Rekomendujemy zapoznanie się z ograniczeniami generatora dokumentów przed użyciem szablonów.
2. Przygotowanie szablonów
Szablony Word (*.docx)
- Aby wstawić pole do szablonu należy przejść do zakładki “Wstawianie”
- Ustawić kursor w miejscu, w którym chcemy wstawić pole
- W sekcji Tekst wybrać “Szybkie części” oraz następnie “Pole”
- Odszukać na liście MergeField
- W “Nazwa pola” wpisać kod z listy dostępnych pól generatora
Rys 1. Dodawanie pól do szablonu w programie MS Word (krok 3)
Rys 2. Dodawanie pól do szablonu w programie MS Word (krok 4)
Przykładowy tekst z wstawionymi polami MergeField «»
Mam na imię «E.first_name», a na nazwisko «E.last_name».
Szablony HTML (*.html)
Aby przygotować szablon HTML niezbędne jest stworzenie pliku spełniającego poniższe założenia:
- Plik musi mieć rozszerzenie .html.
- Koniecznym jest, by plik zaczynał się od <!DOCTYPE html>(1).
- Plik musi zawierać przynajmniej 3 sekcje:
- <html></html>, wewnątrz której będzie się znajdowała cała reszta kodu(2);
- <head></head>, wewnątrz której będą się znajdowały informacje nt. samego pliku takie jak użyte czcionki czy ewentualne ustawienia graficzne czy zastosowanego kodowania(3);
- <body></body>, wewnątrz której znajdować się będzie właściwa część dokumentu – treść, formatowanie, elementy jak tabele czy ewentualne obrazy (zachęcamy by obrazy były przekazywane w kodzie Base64)(4).
Wszelkie pola do generacji muszą być zawarte w podwójnych nawiasach klamrowych, przykładowo {{ E.first_name }}(5).
3. Konfiguracja szablonu w eTeczce eFOB
W celu użycia szablonu należy podpiąć szablon do istniejącego typu dokumentu lub stworzyć do tego celu nowy typ. Dany typ dokumentu może mieć przydzielony wyłącznie jeden szablon.
1. W aplikacji eFOB przechodzimy do menu Administracja oraz wybieramy moduł Typy dokumentów
Rys 3. Typy dokumentów
2. Wyszukujemy interesujący nas typ dokumentu oraz przechodzimy do widoku edycji 3. W sekcji ‘Szczegóły szablonu naciskamy przycisk Dodaj szablon(1) 4. W zależności od tego, jaki typ szablonu chcemy przekazać, wybieramy Word(2) lub HTML(3) 5. Wybieramy z naszego komputera plik z odpowiednim rozszerzeniem(4) 5. Naciskamy przycisk Weryfikuj(5)
Rys 4. Dodawanie szablonu do typu dokumentu
6. Po chwili pojawi się podgląd wydruku szablonu, gdzie wszystkie wartości pól będą zastąpione przez “…”. Jeśli wszystko się zgadza naciskamy “Zapisz szablon”, co spowoduje jego zapis do platformy eTeczki na danym typie dokumentu.
Rys 5. Akceptacja i zapis szablonu do typu dokumentu
4. Edycja szablonów
Dla obu typów szablonów możliwe jest ich podmienienie w systemie. Aby tego dokonać, konieczne jest:
- Wybranie interesującego nas typu dokumentu i przejście do jego szczegółów.
- Znalezienie konkretny plik szablonu i z rozwijanego menu(1) wybranie opcji Zastąp plik.
- Wybranie typu szablonu(2) w nowym oknie, wskazanie pliku z komputera(3) i jego weryfikacja(4).
Dla szablonów HTML możliwa jest edycja szablonów bezpośrednio w systemie. Aby ją uruchomić należy:
- Przejść do szczegółów typu dokumentu.
- Znaleźć plik szablonu i z rozwijanego menu wybrać opcję Edytuj plik.
Otwarty zostanie edytor, który pozwoli na modyfikację szablonu. Zapewnia on podstawowe narzędzia:
- Pogrubienie(1).
- Kursywa(2).
- Podkreślenie(3).
- Zamieszczenie nagłówków(4).
- Dodanie listy numerowanej(5) i nienumerowanej(6).
- Cofnięcie(7) oraz powrót(8).
Dodatkowo, możliwe jest obejrzenie podglądu(9) stworzonego szablonu, anulowanie(10), bądź zapisanie(11).
5. Lista dostępnych pól generatora dokumentów
KANDYDAT (C)
Uwaga: W wersji 2.27 kod CND został zastąpiony krótszym kodem C, podobnie kody ADR_P, ADR_B, PRJ zastąpiono krótszymi kodami A, AB, PR.
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| first_name | TEXT | T | Imię |
| last_name | TEXT | T | Nazwisko |
| middle_name | TEXT | N | Drugie imię |
| maiden_name | TEXT | N | Nazwisko panieńskie |
| birth_date | DATE | N | Data urodzenia |
| place_of_birth | TEXT | N | Miejsce urodzenia |
| pesel | TEXT(11) | N | Numer PESEL (specyficzny dla Polski) |
| driving_licence | TEXT | N | Numer prawa jazdy |
| personal_email | TEXT | N | Email prywatny |
| personal_phone | TEXT | N | Telefon prywatny |
| A | ENTITY | N | Adres prywatny (z ‘primary_postal_address’) |
| business_email | TEXT | N | Email biznesowy |
| business_phone | TEXT | N | Telefon biznesowy |
| PR | ENTITY | N | Projekt, którego dotyczy Boarding |
| AB | ENTITY | N | Adres pobytu biznesowego (z ‘contact_address’) |
| badr_info | LONGTEXT | N | Adres pobytu biznesowego – extra info (z ‘contact_address_information’) |
| additional_info | LONGTEXT | N | Dodatkowe informacje |
| iban | TEXT | N | Numer IBAN |
| contract_start_date | DATE | N | Data rozpoczęcia umowy |
| contract_end_date | DATE | N | Data zakończenia umowy |
| rating | INT | N | Ocena kandydata |
| rating_comment | LONGTEXT | N | Komentarz do oceny kandydata |
| nationality | TEXT | N | Narodowość |
| mother_name | TEXT | N | Imię matki |
| father_name | TEXT | N | Imię ojca |
| X | ENTITY | N | Dodatkowe pola własne w Kandydaci – patrz opis niżej |
PRACOWNIK (E)
Uwaga: W wersji 2.27 kod EMP został zastąpiony krótszym kodem E, podobnie kody ADR_P, ADR_B, PRJ zastąpiono krótszymi kodami A, AB, PR
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| id | INT | T | Identyfikator pracownika (worker) |
| state | TEXT | T | Jeden ze stanów z listy ‘worker_status’: |
| (0, ‘Prospect’), | |||
| (1, ‘On-Boarding’), | |||
| (2, ‘Hired’), | |||
| (3, ‘Resigning’), | |||
| (4, ‘Off-Boarding’), | |||
| (5, ‘Blocked’), | |||
| first_name | TEXT | T | Imię |
| last_name | TEXT | T | Nazwisko |
| middle_name | TEXT | N | Drugie imię |
| maiden_name | TEXT | N | Nazwisko panieńskie |
| sex | LIST | N | Jedna z wartości: |
| – Mężczyzna | |||
| – Kobieta | |||
| – Pozostałe | |||
| – Nieokreślona | |||
| birth_date | DATE | N | Data urodzenia |
| pesel | TEXT(11) | N | Numer PESEL (specyficzny dla Polski) |
| driving_licence | TEXT | N | Numer prawa jazdy |
| personal_email | TEXT | N | Email prywatny |
| personal_phone | TEXT | N | Telefon prywatny |
| A | ENTITY | N | Personal/Private address (z ‘primary_postal_address’) |
| business_email | TEXT | N | Email biznesowy |
| business_phone | TEXT | N | Telefon biznesowy |
| PR | ENTITY | N | Projekt, którego dotyczy Boarding |
| AB | ENTITY | N | Business address of stay (z ‘contact_address’) |
| badr_info | LONGTEXT | N | Business address extra info (z ‘contact_address_information’) |
| additional_info | LONGTEXT | N | Dodatkowe informacje |
| place_of_birth | TEXT | N | Miejsce urodzenia |
| country_birth | TEXT | N | Kraj urodzenia |
| identity_doc_expiry | DATE | N | Data wygaśnięcia dokumentu tożsamości |
| identity_doc_num | TEXT | N | Numer dokumentu tożsamości |
| identity_doc_type | LIST | N | Typ dokumentu tożsamości, jedna z wartości: |
| – Dowód osobisty | |||
| – Paszport | |||
| – Prawo jazdy | |||
| – Inny | |||
| citizenship | TEXT | N | Obywatelstwo |
| nationality | TEXT | N | Narodowość |
| iban | TEXT | N | Numer IBAN |
| contract_start_date | DATE | N | Data rozpoczęcia umowy |
| contract_end_date | DATE | N | Data zakończenia umowy |
| rating | INT | N | Ocena pracownika |
| rating_comment | LONGTEXT | N | Komentarz do oceny pracownika |
| external_id_1 | INT | N | Zewnętrzne ID 1 |
| external_id_2 | INT | N | Zewnętrzne ID 1 |
| mother_name | TEXT | N | Imię matki |
| father_name | TEXT | N | Imię ojca |
| X | ENTITY | N | Dodatkowe pola własne w Pracownicy – patrz opis niżej |
ADRES (A)
Uwaga: Do wersji 2.26 włącznie obowiązuje kod modułu “ADR” (od 2.27 krótszy “A”).
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| id | INT | T | Identyfikator klienta |
| state | TEXT | T | Jeden ze stanów z listy: |
| (0, ‘Deleted’), | |||
| (1, ‘Active’), | |||
| street | TEXT | N | Ulica |
| street_nb | TEXT | N | Numer domu |
| property_number | TEXT | N | Numer mieszkania |
| zip_code | TEXT | N | Kod pocztowy |
| city | TEXT | N | Miasto |
| region | TEXT | N | Region |
| country | TEXT | N | Kraj (tekstowo) |
| description | TEXT | N | Opis |
BOARDING (B)
Uwaga: Do wersji 2.26 włącznie obowiązuje kod modułu “BRD” (od 2.27 krótszy “B”).
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| id | INT | T | Identyfikator boarding |
| state | TEXT | T | Jeden ze stanów z listy ‘boarding_status’: |
| (0, ‘Prospect’), | |||
| (1, ‘On-Boarding’), | |||
| (2, ‘Waiting’), | |||
| (3, ‘Hired’), | |||
| (4, ‘Changing’), | |||
| (5, ‘Transitioning’), | |||
| (6, ‘Resigning’), | |||
| (7, ‘Off-Boarding’), | |||
| (8, ‘Terminated’), | |||
| (9, ‘Blocked’), | |||
| (10, ‘Historical’), | |||
| onboarding_date | DATE | N | Data onboarding (z Boarding) |
| offboarding_date | DATE | N | Data offboarding (z Boarding) |
| start_date | DATE | T | Data początku |
| finish_date | DATE | N | Data końca |
| contract_start_date | DATE | N | Data początku umowy |
| contract_end_date | DATE | N | Data końca umowy |
| PR | ENTITY | N | Projekt, którego dotyczy Boarding |
| E | ENTITY | T | Pracownik, którego dotyczy Boarding |
PROJEKT (PR)
Uwaga: Do wersji 2.26 włącznie obowiązuje kod modułu “PRJ” (od 2.27 krótszy “PR”).
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| id | INT | T | Identyfikator projektu |
| state | TEXT | T | Jeden ze stanów z listy: |
| ACTIVE = (0, “Active”) | |||
| INACTIVE = (1, “Inactive”) | |||
| DELETED = (2, “Deleted”) | |||
| name | TEXT | T | Nazwa projektu |
| start_date | DATE | N | Data startu projektu |
| end_date | DATE | N | Data końca projektu |
| CL | ENTITY | N | Powiązana encja klienta, do którego należy Projekt |
KLIENT (CL)
Uwaga: Do wersji 2.26 włącznie obowiązuje kod modułu “CLI” (od 2.27 krótszy “CL”).
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| id | INT | T | Identyfikator Klienta |
| state | TEXT | T | Jeden ze stanów z listy: |
| (1, ‘Lead’), | |||
| (2, ‘Opportunity’), | |||
| (3, ‘Contracted’), | |||
| (4, ‘Rejected’), | |||
| (5, ‘Closed’) | |||
| name | TEXT | T | Nazwa klienta |
| code | TEXT | N | Kod klienta |
| ADR | ENTITY | N | Powiązana encja adresu głównego klienta |
FIRMA (CO)
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| CO.name | TEXT | T | Nazwa firmy |
| CO.contact_number1 | TEXT | N | Pierwszy numer telefonu |
| CO.contact_number2 | TEXT | N | Drugi numer telefonu |
| CO.email | TEXT | N | Adres email |
| CO.contact_www | TEXT | N | Adres strony internetowej |
| CO.nip | TEXT | N | NIP |
| CO.KRS | TEXT | N | KRS |
| CO.regon | TEXT | N | REGON |
| CO.street | TEXT | N | Nazwa ulicy |
| CO.street_nb | TEXT | N | Numer ulicy |
| CO.property_number | TEXT | N | Numer budynku |
| CO.zip_code | TEXT | N | Kod pocztowy |
| CO.city | TEXT | N | Miasto |
| CO.region | TEXT | N | Region |
| CO.country | TEXT | N | Kraj (tekstowo) |
| CO.description | TEXT | N | Opis |
| CO.disctrict | TEXT | N | Powiat |
| CO.sub_disctrict | TEXT | N | Gmina |
6. Pola własne
Pola własne w Pracownicy oraz Kandydaci
Na platformie eTeczki eFOB w encjach KANDYDAT (C) oraz PRACOWNIK (E) jest możliwe dodawanie niestandardowych pól własnych. Dostęp do ich wartości jest możliwy poprzez znacznik X.
Przykłady użycia
- E.X.pozycja – wartość pola niestandardowego LIST ‘pozycja’ na pracowniku
- C.X.referencje – wartość pola niestandardowego TEXT ‘referencje’ na kandydacie
Pola własne z Excel w generatorze dokumentów
Przy wykorzystaniu funkcjonalności generowania dokumentów z pliku Excel (opisane m.in. w rozdziale Generowanie dokumentów – eFOB eTeczka) dla generatora dostępne są dowolne pola dodatkowe nazw kolumn pobrane z nagłówka – z pierwszej linii danych załączonego Excel.
UWAGA: nazwy kolumn (nagłówek) powinny mieć jednoznaczne unikalne nazwy, bez spacji i polskich znaków
7. Pola i funkcje specjalne
Funkcja Word IF {}
Celem obsłużenia bardziej złożonych konstrukcji możliwe jest warunkowanie wyświetlania tekstu, jak i innych MERGEFIELDs dzięki użyciu funkcji IF {}. Warunek może zawierać zagnieżdżone pola. Spacje są OBOWIĄZKOWE przed i po operatorze (<, <>, >, <=, >=, =). Wartości najlepiej umieszczać w cudzysłowie. Dla operatorów <> i = obsługiwane są wyrażenia regularne w stylu Microsoft (?, *).
Przykład użycia
- { IF { MERGEFIELD reason } <> “” “Powód zmiany umowy: { MERGEFIELD reason }.” } -> doda paragraf, tylko jeśli pole ‘reason’ będzie niepuste
- { IF { MERGEFIELD podwyzka } = “Tak” “Pracownik otrzyma podwyżkę w wysokości: { MERGEFIELD salary_increase }.” “”} -> doda paragraf i wstawi tekst plus wartość z pola ‘salary_increase’, tylko jeśli pole ‘podwyzka’ będzie ustawione na “Tak”
Obsługa błędu wyświetlania “Unknown”
W niektórych wypadkach np. braku danych pola własnego instrukcje warunkowe zaczynają niepoprawnie wyświetlać tekst “UNKNOWN”. Aktualnie znanym obejściem jest dodanie sprawdzenia przy pomocy dodatkowego warunku IF, który jednocześnie deklaruje zmienną, co zapobiega błędom wyświetlania:
- { IF { MERGEFIELD czasem_puste_pole } = “UNKNOWN” “Brak wartości.” }{ IF { MERGEFIELD czasem_puste_pole }” = “Podwyzka” { MERGEFIELD salary_increase } }
Pola dat generatora dokumentów
Jeśli generator w polach MailMerge generator napotka pola o specyficznych nazwach, to podmieni je wg opisu ich działania.
| ID | Typ | Wymag. | Opis |
|---|---|---|---|
| TODAY | TEXT | N | Data systemowa (“Dziś”) formatowana do tekstu jako RRRR-MM-DD (np. 2025-12-22). |
| DOC_DATE | TEXT | N | „Data wystawienia” pobrana z okna „Generuj dokumenty” formatowana do tekstu jako RRRR-MM-DD |
Funkcja PLN
Funkcja PLN(), pozwala na zwrócenie wartości ‘słownie w złotych polskich’ bazując na podanej wartości.
Składnia
- PLN(pole)
- Jeśli wartość dla pole jest tekstem usuwa spacje, standaryzuje ‘przecinki’ oraz próbuje przekonwertować wartość na liczbę zmiennoprzecinkową (
float) – jeśli to się nie uda (np. niepoprawny format), zwraca pusty string. - W przypadku wartości 0 zwraca “zero złotych 00/100”.
- Rozdziela wartość na złote (część całkowita) i grosze (dwie cyfry po przecinku, zaokrąglone).
- Obsługuje liczby ujemne – dodaje słowo “minus”.
- Część złotowa jest zapisywana słownie po polsku (np. “dwa tysiące pięćset złotych”), maksymalnie obsługiwane są “miliardy”).
- Grosze są zawsze wyświetlane jako liczba dwucyfrowa po ukośniku, np. “45/100”, “00/100”.
- Funkcja dobiera poprawną formę słowa “złoty” w zależności od liczby (złoty, złote, złotych).
- Wynik końcowy to tekst w formacie: “<kwota słownie> <złoty/złote/złotych> <grosze>/100”, np. “trzy złote 02/100”.
Przykłady użycia
- «PLN(E.salary)» -> dla wartości pola E.salary == 9600.50 zwróci wartość ‘dziewięć tysięcy sześćset 50/100’
- «PLN(bonus)» -> dla wartości pola bonus == 15000 zwróci wartość ‘piętnaście tysięcy 00/100’
Funkcja SWITCH
Funkcja SWITCH(), wzorowana na koncepcji znanej z Excel (SWITCH function – Microsoft Support), pozwala na zwrócenie określonej wartości w zależności od wyniku porównania podanego wyrażenia z zestawem warunków. Ułatwia pisanie czytelnych reguł biznesowych do generatora dokumentów.
Składnia
- SWITCH(pole, warunek1, wartość1, warunek2, wartość2, …, [opcjonalne] wartość_domyślna)
- Limit długości pola MergeField wynosi 255 znaków, zatem długość całej funkcji SWITCH musi mieścić się w tym limicie
- Wszystkie pola są rozdzielane przecinkami, zaś sama nazwa funkcji jest pisana z dużej litery z nawiasami SWITCH()
- pole – musi odnosić się do pól wg schematu nazewniczego opisanego wyżej
- warunekX oraz wartośćX – domyślnie zostaje ucięte z obydwu stron ze spacji
- warunekX oraz wartośćX – w polach tych nie można używać znaków ” i ,
- wartość_domyślna – jest polem opcjonalnym
Przykłady użycia
- «SWITCH(E.A.city,Warszawa,Warsaw_,Kraków,Cracow,Inne miasto»_ -> zmieni nazwę miasta z polskiego na angielskie
- «SWITCH(E.X.pozycja,E,Pracownik,MGR,Manager» -> zmieni nazwę pola własnego ‘pozycja’ na odpowiednie
- «SWITCH(E.X.bonus,0,Brak,1,Przyznany,Brak informacji» -> zdekoduje pole własne ‘bonus’ na odpowiednie wartości wraz z wartością domyślną ‘Brak informacji’
Funkcja ER
Funkcja ER().<> pozwala na zwrócenie wartości danego atrybutu konkretnego Pracodawcy, o ile znajduje się on w słowniku Pracodawców, niezależnie od tego, czy ma status ‘Aktywny’ czy nie.
Składnia
- ER(pole).<operacja>
- Jeśli wartość dla pole jest tekstem usuwa spacje oraz normalizuje wielkie i małe litery
- Posługuje się pełną nazwą pracodawcy jako kluczem
- Wykonuje jedną z poniższych operacji:
- A – zwraca adres Pracodawcy
- P – zwraca nazwę Pracodawcy do druku
- S – zwraca krótką nazwę Pracodawcy
- NIP – zwraca numer NIP Pracodawcy
- REGON – zwraca numer REGON Pracodawcy
- KRS – zwraca numer KRS Pracodawcy
- PESEL – zwraca numer PESEL Pracodawcy
- W przypadku błędnej składni bądź braku danego Pracodawcy w bazie danych zwrócony zostanie pusty ciąg znaków
Przykłady użycia
Załóżmy istnienie w bazie danych Pracodawcy o poniższych danych:
-
pełna nazwa: Moja firma
-
adres: ul. Uliczna 1, 00-000, Miasto
-
krótka nazwa: Moja
-
NIP: 1169595501
-
REGON: 553277064
-
KRS: 0000123456
-
PESEL: 17020866246
-
«ER(firma).A» -> dla wartości pola firma == ‘Moja firma’ zwróci wartość ‘ul. Uliczna 1, 00-000, Miasto’
-
«ER(firma).S» -> dla wartości pola firma == ‘MOJA FIRMA’ zwróci wartość ‘Moja’
-
«ER(firma).NIP» -> dla wartości pola firma == ‘moja firma’ zwróci wartość ‘1169595501’
Funkcja ER.ALL
Funkcja ER.ALL.<> pozwala na zwrócenie wartości danego atrybutu wszystkich Pracodawców znajdujących się on w słowniku Pracodawców mających status ‘Aktywny’. Ich dane zostaną wylistowane oddzielone od siebie średnikiem oraz nową linią.
Składnia
- ER.ALL.<operacja>
- Wykonuje jedną z poniższych operacji:
- A – zwraca adresy Pracodawców
- P – zwraca nazwy Pracodawców do druku
- S – zwraca krótkie nazwy Pracodawców
- NIP – zwraca numery NIP Pracodawców
- REGON – zwraca numery REGON Pracodawców
- KRS – zwraca numery KRS Pracodawców
- PESEL – zwraca numery PESEL Pracodawców
- W przypadku błędnej składni bądź braku danych u Pracodawcy w bazie danych zwrócony zostanie pusty ciąg znaków.
Przykłady użycia
Załóżmy istnienie w bazie danych dwóch Pracodawców o poniższych danych:
Pracodawca 1:
- pełna nazwa: Moja firma
- adres: ul. Uliczna 1, 00-000, Miasto
- krótka nazwa: Moja
- NIP: 1169595501
- REGON: 553277064
- KRS: 0000123456
- PESEL: 17020866246
Pracodawca 2:
-
pełna nazwa: Twoja firma
-
adres: ul. Chodnikowa 2, 00-000, Miasto
-
krótka nazwa:
-
NIP:
-
REGON:
-
KRS:
-
PESEL: 58120384647
-
«ER.ALL.A_»_ -> zwróci wartość:
‘ul. Uliczna 1, 00-000, Miasto;
ul. Chodnikowa 2, 00-000, Miasto’
- «ER.ALL.S_»_ -> zwróci wartość:
‘Moja’