Standard Formularza ePUAP

Departament Informatyzacji

Standard Formularza elektronicznej Platformy Usług Administracji Publicznej

Wersja 1.01

Warszawa, 2014

Standard Formularza ePUAP

Wersja 1.01

2 / 38

Spis treści

Słownik pojęć i skrótów ............................................................................................ 4

Podstawa prawna ...................................................................................................... 7

Wstęp ......................................................................................................................... 8

1. Główne założenia .................................................................................................. 9

2. Struktura formularza ePUAP .............................................................................. 10

2.1. Struktura formularza XForms .......................................................................... 10

2.1.1. Definicja węzła głównego ............................................................................... 10

2.1.2. Wskazanie wzoru dokumentu elektronicznego ............................................... 11

2.1.3. Deklarowanie przestrzeni nazw ...................................................................... 13

2.1.4. Określenie domyślnej skrytki adresata dokumentu ......................................... 14

2.2. Struktura formularza Adobe ............................................................................ 14

2.2.1. Definicja węzła głównego ............................................................................... 15

2.2.2. Wskazanie wzoru dokumentu elektronicznego ............................................... 15

2.2.3. Deklarowanie przestrzeni nazw ...................................................................... 18

2.2.4. Określenie domyślnej skrytki adresata dokumentu ......................................... 18

3. Dane dostępne dla formularza ePUAP .............................................................. 20

3.1. Dana o stanie dokumentu elektronicznego ..................................................... 20

3.2. Dana podmiotu lub użytkownika ..................................................................... 20

3.2.1. Pobieranie danych o podmiocie i użytkowniku do formularza zbudowanego w XForms ................................................................................ 20

3.2.2. Pobieranie danych o podmiocie i użytkowniku do formularza zbudowanego w Adobe .................................................................................. 21

4. Opcjonalne funkcjonalności formularza ePUAP .............................................. 23

4.1. Dołączanie do dokumentu elektronicznego załączników ................................ 23

4.1.1. Załączniki w technologii XForms .................................................................... 23

4.1.2. Załączniki w technologii Adobe ...................................................................... 24

4.2. Podpisywanie części dokumentu elektronicznego .......................................... 25

4.3. Komunikacja ze słownikami ............................................................................ 26

4.3.1. Definiowanie słowników dla XForms .............................................................. 26

4.3.2. Definiowanie słowników w Adobe .................................................................. 27

4.4. Wysyłanie z formularza danych na skrytkę ePUAP......................................... 29

4.5. Akcje „Odpowiedz” .......................................................................................... 30


Wersja 1.01

3 / 38

4.6. Akcja „Opłać” .................................................................................................. 31

4.7. Triggery ........................................................................................................... 32

5. Elementy automatycznie dodawane do dokumentu elektronicznego ............ 33

5.1. Identyfikator formularza ................................................................................... 33

5.2. Identyfikator korelacji ...................................................................................... 34

5.3. Elektroniczne Poświadczenie Opłaty .............................................................. 34

5.4. Podpis elektroniczny ....................................................................................... 35

6. Adresowanie i zapis dokumentu elektronicznego ........................................... 36

6.1. Adresowanie dokumentu ................................................................................. 36

6.2. Zapis dokumentu............................................................................................. 37

Załączniki ................................................................................................................. 38


Wersja 1.01

4 / 38

Słownik pojęć i skrótów

Pojęcie lub skrót Opis

akcja Element formularza ePUAP definiujący działanie na dokumencie, między innymi pozwalający na zdefiniowanie operacji dla dokumentu danego formularza, z której odbiorca dokumentu może skorzystać.

aplikacja Pakiet oprogramowania zdefiniowany z pomocą języka XML realizujący określoną funkcjonalność na platformie ePUAP.

CID Identyfikator korelacji (CID, ang. Correlation Identifier).

CRWDE Centralne Repozytorium Wzorów Dokumentów Elektronicznych.

Czynność Postępowanie mające na celu wykonanie określonej operacji.

Elektroniczna Skrzynka Podawcza

Dostępny publicznie środek komunikacji elektronicznej służący do przekazywania dokumentu elektronicznego do i z podmiotu publicznego przy wykorzystaniu powszechnie dostępnego systemu teleinformatycznego.

EPO Elektroniczne Poświadczenie Opłaty.

ePUAP elektroniczna Platforma Usług Administracji Publicznej - platforma teleinformatyczna, umożliwiająca podmiotom publicznym świadczenie usług opartych na elektronicznych kanałach komunikacji poprzez punkt dostępowy w Internecie.

ESP Elektroniczna Skrzynka Podawcza.

formatka Element na ekranie monitora do prezentowania i wprowadzania danych.

formularz Formularz elektroniczny to graficzny interfejs użytkownika wystawiany przez odpowiednie oprogramowanie służący do przygotowania i wygenerowania dokumentu elektronicznego, zgodnego z odpowiadającym mu wzorem dokumentu elektronicznego opublikowanym w CRDWE

GUI Graficzny interfejs użytkownika, może zawierać elementy takie jak przyciski lub okna, za pomocą nich użytkownik wprowadza dane do systemu.

kliknięcie Jednorazowe naciśnięcie przycisku myszy na wskazanym polu.

mapowanie Element formularza ePUAP, pozwalający na wybranie formularza nadrzędnego dla dokumentów tworzonych przy użyciu tworzonego formularza.

Minister Minister właściwy do spraw informatyzacji.


Wersja 1.01

5 / 38


podmiot Osoba fizyczna, jednostka organizacyjna posiadająca osobowość prawną lub jej nieposiadająca, która w wyniku swego działania może powodować zmiany stanu systemu przetwarzania danych.

POST Metoda przekazywania danych w sieci Internet za pomocą protokółu HTTP oraz HTTPS. W tej metodzie w zapisie URI nie są jawnie podane parametry przekazywania danych. Parametry znajdują się w globalnej tablicy $_POST. Można się do parametrów znajdujących się w tablicy wielokrotnie odwoływać z dowolnego miejsca skryptu, bez ujawnienia parametrów w przeglądarce. Dlatego POST stosuje głównie się dla akcji niebezpiecznych.

proces Zestaw instrukcji, jakie będą wykonane przez system pozwalające na zrealizowanie określonego zadania.

przestrzeń nazw Zbiór podschematów danych, do których można się odwoływać ze schematu danych. Jeśli schemat danych korzysta z innych schematów danych to musi zostać umieszczone w przestrzeni nazw, przykład odwołania do przestrzeni nazw:

http://crd.gov.pl/xml/schematy/meta/2009/11/16/, http://crd.gov.pl/wzor/2011/06/08/599/.

przycisk (radiobutton) Przycisk umożliwia wybór jednej z wielu opcji formatki.

ŚBA Środowisko Budowy Aplikacji.

UPO Urzędowe Poświadczenie Odbioru to dane elektroniczne powiązane z dokumentem elektronicznym doręczonym podmiotowi publicznemu lub przez niego doręczanym w sposób zapewniający rozpoznawalność późniejszych zmian dokonanych w tych danych.

URI Standard internetowy umożliwiający łatwą identyfikację zasobów w sieci (URI, ang. Uniform Resource Identifier).

URL Szczególny przypadek URI, który oprócz identyfikacji zasobu wskazuje również sposób dostępu do niego (URL, ang. Uniform Resource Locator).

URN Ujednolicony format nazw zasobów, składa się z identyfikatora przestrzeni nazw (URN, ang. Uniform Resource Name).

Urzędowe Poświadczenie Odbioru

UPO - Dane elektroniczne dołączone do dokumentu elektronicznego doręczonego podmiotowi lub połączone z tym dokumentem w taki sposób, że jakakolwiek późniejsza zmiana dokonana w tym dokumencie jest rozpoznawalna (na podstawie art. 3 pkt 20 [1]).

Ustawa Ustawa z dnia 17 lutego 2005 r. o informatyzacji działalności podmiotów realizujących zadania publiczne (Dz. U. z 2013 r. poz. 235, Dz. U. z 2014 r. poz. 183).

wyróżnik Opis wzoru dokumentu elektronicznego zapisany w formie pliku XML umieszczony w CRWDE.

wyzwalacz (trigger) Element formularza ePUAP, pozwalający na automatyczne wywołanie akcji danego formularza.

http://crd.gov.pl/xml/schematy/meta/2009/11/16/

http://crd.gov.pl/wzor/2011/06/08/599/

http://pl.wikipedia.org/wiki/J%C4%99zyk_angielski


http://pl.wikipedia.org/wiki/Format

http://pl.wikipedia.org/wiki/Przestrze%C5%84_nazw



Wersja 1.01

6 / 38


wzór dokumentu elektronicznego

Wzór dokumentu elektronicznego zdefiniowany za pomocą języka XML i opublikowany w Repozytorium Wzorów Dokumentów Elektronicznych.

XForms Standard definicji formularzy. Formularze tworzone są za pomocą edytora formularzy w ŚBA lub mogą być tworzone w narzędziach zewnętrznych, a następnie importowane do ŚBA. Więcej informacji znajduje się na stronie http://www.w3.org/TR/xforms/.

XML Uniwersalny język formalny przeznaczony do reprezentowania różnych danych w strukturalizowany sposób.

XPath XML Path Language – język służący do adresowania części dokumentu zdefiniowanego przy pomocy języka XML. Do wskazania, w XPath węzła lub zbioru węzłów, używa się ścieżki lokalizacji.

XSD (Schemat) Schemat wzoru dokumentu elektronicznego opisany w pliku XSD, definiuje strukturę i zawartość dokumentu. Opis w postaci dokumentu XML zrealizowany w standardzie opracowanym przez organizację standaryzującą W3C. Na podstawie pliku XSD można weryfikować poprawność dokumentu elektronicznego.

XSL (Styl) Plik XSL opisuje styl, sposób wizualizacji dokumentu elektronicznego, wizualizowany dokument powinien posiadać postać zbliżoną do wersji papierowej.

http://www.w3.org/TR/xforms/


Wersja 1.01

7 / 38

Uwarunkowania prawne

[1] USTAWA z dnia 17 lutego 2005 r. o informatyzacji działalności podmiotów realizujących zadania publiczne (Dz. U. z 2013 r. poz. 235, Dz. U. z 2014 r. poz. 183);

[2] USTAWA z dnia 14 czerwca 1960 r. Kodeks postępowania administracyjnego (Dz. U. z 2013 r. poz. 267, Dz. U. z 2014 r., poz. 183);

[3] ROZPORZĄDZENIE PREZESA RADY MINISTRÓW z dnia 14 września 2011 r. w sprawie sporządzania pism w formie dokumentów elektronicznych, doręczania dokumentów elektronicznych oraz udostępniania formularzy, wzorów i kopii dokumentów elektronicznych (Dz.U. z 2011 r. Nr 206, poz. 1216);

[4] ROZPORZĄDZENIE RADY MINISTRÓW z dnia 12 kwietnia 2012 r. w sprawie Krajowych Ram Interoperacyjności, minimalnych wymagań dla rejestrów publicznych i wymiany informacji w postaci elektronicznej oraz minimalnych wymagań dla systemów teleinformatycznych (Dz.U. z 2012 r. poz. 526);

[5] Ustawa z dnia 10 stycznia 2014 r. o zmianie ustawy o informatyzacji działalności podmiotów realizujących zadania publiczne oraz niektórych innych ustaw (Dz. U. z 2014 r. poz. 183).


Wersja 1.01

8 / 38

Wstęp

Standard Formularza elektronicznej Platformy Usług Administracji Publicznej, stanowi opis charakterystycznych elementów, jakie powinien lub może posiadać formularz używany przez podmioty publiczne na platformie ePUAP.

Podstawę do zdefiniowania Standardu Formularza jest Art. 16a, ust. 3 Ustawy, który między innymi stanowi: Formularz elektroniczny udostępniony na ePUAP spełnia standardy określone i opublikowane na ePUAP przez ministra właściwego do spraw informatyzacji.

Formularz elektroniczny, w skrócie formularz jest aplikacją zdefiniowaną za pomocą języka XML. Formularz umożliwia utworzenie dokumentu elektronicznego, zgodnego z odpowiadającym mu wzorem dokumentu elektronicznego opublikowanym w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych.

Podmioty publiczne udostępniające na platformie ePUAP usługi mogą tworzyć Formularze za pomocą jednej z dwóch technologii. Pierwszą z nich jest XForms za pomocą, której można tworzyć formularze bezpośrednio w Środowisku Budowy Aplikacji. Drugą jest graficzny interfejs Adobe LiveCycle Designer umożliwiający szybkie projektowanie Formularzy.

Opis podstawowych elementów Formularza wykonanego w technologii XForms charakterystycznych dla ePUAP został zawarty w pliku o nazwie: formularz.xsd, stanowiący załącznik tego dokumentu. Plik formularz.xsd stanowi podstawę do jednego ze sposobów weryfikacji Formularzy instalowanych na ePUAP.

W przypadku tworzenia Formularzy w narzędziu Adobe LiveCycle Designer niezbędne jest pobranie specjalnego “template” ze stron ePUAP przed przystąpieniem do prac implementacyjnych. Powodem takiego rozwiązania jest fakt, iż część funkcji dostępnych na platformie ePUAP zaszyta jest w skryptach przygotowanego szablonu. Dlatego zalecane jest korzystanie właśnie z tego konkretnego rozwiązania. Gotowy szablon o nazwie Szablon_formularza.xdp dostępny jest na stronach ePUAP w sekcji pomoc, na stronie:

Jesteś w: Strona główna > Podmioty publiczne > Licencje na formularze PDF > Zasady korzystania z licencji >

http://epuap.gov.pl/wps/portal/E2_StronaGlowna

http://epuap.gov.pl/wps/portal/!ut/p/a1/04_Sj9CPykssy0xPLMnMz0vMAfGjzOINLY1MDI2CDbwswlycDDzDQoJCvN3CjNzdDfQLsh0VAQ9kQO8!/?1dmy&current=true&urile=wcm%3apath%3a/epuap2/ePUAP2/PL/Podmioty+publiczne&current=true

http://epuap.gov.pl/wps/portal/!ut/p/a1/04_Sj9CPykssy0xPLMnMz0vMAfGjzOINLY1MDI2CDbwswlycDDzDQoJCvN3CjNzdDfQLsh0VAQ9kQO8!/?1dmy&current=true&urile=wcm%3apath%3a/epuap2/ePUAP2/PL/Podmioty+publiczne/Licencje+na+formularze+PDF&current=true


Wersja 1.01

9 / 38

1. Główne założenia

Opis Standardu Formularza ePUAP, określający cechy formularza używanego na ePUAP przez podmioty publiczne, uwzględnia następujące główne założenia wynikające bezpośrednio z przepisów prawa:

1. Formularz elektroniczny udostępniony na ePUAP spełnia standardy określone w repozytorium interoperacyjności (na podstawie art. 16a. ust. 3. [5]);

2. Podmiot publiczny udostępnia na ePUAP formularz elektroniczny umożliwiający wygenerowanie dokumentu elektronicznego w celu złożenia pisma za pomocą środków komunikacji elektronicznej (na podstawie art. 16a. ust. 1. pkt 3 [5]);

3. Minister właściwy do spraw informatyzacji może wezwać podmiot publiczny do dostosowania, we wskazanym terminie, formularza elektronicznego udostępnionego na ePUAP do określonych standardów (na podstawie art. 16a. ust. 4. [5]);

4. W przypadku niedostosowania, we wskazanym terminie, formularza elektronicznego udostępnionego na ePUAP do określonych standardów, minister właściwy do spraw informatyzacji może usunąć formularz elektroniczny z ePUAP (na podstawie art. 16a. ust. 5. [5]);

5. Formularz elektroniczny wpisuje do każdego dokumentu elektronicznego niepowtarzalny identyfikator wzoru na podstawie, którego dokument został stworzony (na podstawie § 24 [3]);

6. Lokalne repozytoria zawierają wyłącznie wzory dokumentów elektronicznych, które uprzednio zostały umieszczone w centralnym repozytorium (na podstawie § 26 [3]).


Wersja 1.01

10 / 38

2. Struktura formularza ePUAP

2.1. Struktura formularza XForms

W skład struktury formularza ePUAP wchodzą charakterystyczne dla platformy ePUAP następujące elementy:

1. Definicja węzła głównego;

2. Wskazanie wzoru dokumentu elektronicznego;

3. Deklarowanie przestrzeni nazw;

4. Określenie domyślnej skrytki adresata dokumentu.

2.1.1. Definicja węzła głównego

Poniżej przedstawiona jest przykładowa definicja węzła głównego formularza będącego aplikacją XForms na platformie ePUAP:

Element <Formularz> z przestrzeni nazw http://www.epuap.gov.pl/Formularz może zawierać atrybuty:

domyslnaNazwaAdresata - służy do określenia adresata za pomocą wyrażenia XPath. W chwili obecnej atrybut nie jest wykorzystywany przez system ePUAP,

należy wprowadzić wartość "";

<?xml version="1.0" encoding="UTF-8"?> <Formularz

domyslnaNazwaAdresata="" domyslnaSkrytkaAdresata="" nazwa="Pismo ogolne" prywatny="false" typFormularza="xforms" xmlns="http://www.epuap.gov.pl/Formularz">

<xforms> … … … </xforms>

</Formularz>

http://www.epuap.gov.pl/Formularz


Wersja 1.01

11 / 38

domyslnaSkrytkaAdresata - ustawia domyślną skrytkę dla danego formularza. W chwili obecnej atrybut nie jest wykorzystywany przez system ePUAP, należy

wprowadzić wartość "";

nazwa - nazwa pod jaką będzie funkcjonował w systemie formularz;

prywatny - należy wprowadzić true lub false. Jeżeli zostanie wprowadzona wartość true to dostęp do formularza będzie miał jedynie ten podmiot, który jest jego właścicielem, czyli tylko ten podmiotu, który go zainstalował. Inne podmioty nie będą miały do niego dostępu. Jeżeli zostanie wprowadzona wartość false formularz będzie publiczny, czyli każdy podmiot będzie mógł korzystać z tego formularza;

typFormularza – należy wprowadzić xdp lub XForms, służy do określenia typu formularza.

2.1.2. Wskazanie wzoru dokumentu elektronicznego

Formularz odnosi się do wzoru dokumentu elektronicznego opublikowanego w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych (CRWDE) lub w lokalnym repozytorium, przy czym należy pamiętać, iż lokalne repozytoria zawierają wyłącznie wzory dokumentów elektronicznych, które uprzednio zostały umieszczone w CRWDE. W obu przypadkach należy podać URL wzoru.

Podanie prawidłowego adresu URL jest ważne, gdyż na jego podstawie formularz wiązany jest z danym wzorem i wówczas nie tylko możliwa jest walidacja takiego dokumentu ze schematem XSD, ale również jego wizualizacja.

Odwołanie do wzoru dokumentu należy umieścić w sekcji (tagu) <head>.

Przykład:

Odwołanie do wzoru dokumentu elektronicznego opublikowanego w CRWDE:

Gdzie:

http://crd.gov.pl/ - nazwa serwera;

wzor – obszar wzorów dokumentów elektronicznych;

2011/06/08/599/ – nazwa wzoru.

<meta property="markUrl">

http://crd.gov.pl/wzor/2011/06/08/599/ </meta>

http://crd.gov.pl/



Wersja 1.01

12 / 38

W przypadku korzystania z CRWDE użytkownik musi wprowadzić ścieżkę do istniejącego wzoru dokumentu elektronicznego w postaci:

W środowisku testowym odwołanie ma postać:

http://test.crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/

W środowisku produkcyjnym odwołanie ma postać:

http://crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/

Gdzie:

http://test.crd.gov.pl/ lub http://crd.gov.pl/ - adres serwera;


rok/miesiąc/dzień/numer_wzoru/ - jest nazwą wzoru dokumentu elektronicznego, pod jakim został opublikowany schemat, styl, wyróżnik: rok – reprezentuje czterocyfrowa liczba, miesiąc – reprezentuje dwucyfrowa liczba, dzień - reprezentuje dwucyfrowa liczba, numer_wzoru – trzycyfrowa liczba.

Przykład:

Odwołanie do CRWDE, do wzoru o nazwie 2010/09/27/442/ w środowisku produkcyjnym wygląda następująco:


W przypadku korzystania ze wzoru lokalnego użytkownik musi wprowadzić ścieżkę do istniejącego wzoru lokalnego:


http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/


http://epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/

Gdzie:

http://test.crd.gov.pl/FeResourceServlet/ lub http://epuap.gov.pl/FeResourceServlet/ - adres serwera;

wzor_lokalny/id_podmiotu/ – obszar lokalnych wzorów dokumentów elektronicznych podmiotu o identyfikatorze id_podmiotu;

nazwa_wzoru/ - reprezentuje nazwę podmiotu oraz nazwę wzoru.

http://test.crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/

http://crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/

http://test.crd.gov.pl/

http://crd.gov.pl/


http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/

http://epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/

http://test.crd.gov.pl/FeResourceServlet/

http://epuap.gov.pl/FeResourceServlet/


Wersja 1.01

13 / 38

Przykład:

Odwołanie do obszaru /wzor_lokalny/ lokalnych wzorów dokumentów elektronicznych podmiotu /UMCZ/, do wzoru o nazwie ZgloszenieImprez w środowisku produkcyjnym wygląda następująco:

http://epuap.gov.pl/FeResourceServlet/wzor_lokalny/UMCZ/ZgloszenieImprez/

2.1.3. Deklarowanie przestrzeni nazw

W formularzu należy zadeklarować przestrzenie nazw zawierające używane schematy atomowe stosowane w dokumencie elektronicznym. Schematy atomowe znajdują się w CRWDE. Do sprawdzenia poprawności działania formularza w środowisku testowym, w formularzu mogą być odwołania do CRWDE znajdującym się w środowisku produkcyjnym.

Zaleca się, aby element główny dokumentu był oznaczony wnio:Dokument, gdzie prefiks „wnio” oznacza przestrzeń nazw danego dokumentu elektronicznego.

Przykład:

W formularzu można zadeklarować wiele odwołań do przestrzeni nazw, co dla przykładu przedstawiono poniżej:

<html xmlns=http://www.w3.org/1999/xhtml

…

…

xmlns:adr="http://crd.gov.pl/xml/schematy/adres/2009/11/09/"

xmlns:adrs="http://crd.gov.pl/xml/schematy/adres/2008/05/09/"

xmlns:inst="http://crd.gov.pl/xml/schematy/instytucja/2009/11/16/"

xmlns:insts="http://crd.gov.pl/xml/schematy/instytucja/2008/05/09/"

xmlns:meta="http://crd.gov.pl/xml/schematy/meta/2009/11/16/"

xmlns:metas="http://crd.gov.pl/xml/schematy/meta/2008/05/09/"

xmlns:oso="http://crd.gov.pl/xml/schematy/osoba/2009/11/16/"

xmlns:osos="http://crd.gov.pl/xml/schematy/osoba/2008/05/09/"

xmlns:str="http://crd.gov.pl/xml/schematy/struktura/2009/11/16/"

xmlns:strs="http://crd.gov.pl/xml/schematy/struktura/2008/05/09/"

…

…

</html>

http://epuap.gov.pl/FeResourceServlet/wzor_lokalny/UMCZ/ZgloszenieImprez/

http://www.w3.org/1999/xhtml


Wersja 1.01

14 / 38

2.1.4. Określenie domyślnej skrytki adresata dokumentu

W formularzu należy umieścić adres skrytki, na który domyślnie adresowane będą dokumenty utworzone przy pomocy tego formularza. Aby to zrobić należy umieścić następujący element w sekcji „head” formularza:

Elementy „meta” są niezgodne z XHTML-em, element meta w XHTML-u jest elementem traktowany, jako pusty, tj. <meta atrybuty />.

Elementy ePUAP-owe „meta” zostaną usunięte przez środowisko uruchomieniowe i nie będą wpływały na jego poprawność i wygląd.

2.2. Struktura formularza Adobe

W skład struktury formularza Adobe dla ePUAP wchodzą podobne jak dla formularza XForms następujące elementy:

1. Definicja węzła głównego;

2. Wskazanie wzoru dokumentu elektronicznego;

3. Przestrzenie nazw zawarte w podanym schemacie;

4. Określenie domyślnej skrytki adresata dokumentu.

<head> … …

<meta property="adresSkrytki">/id_podmiotu/nazwa_adresu_skrytki</meta> … … </head>


Wersja 1.01

15 / 38

2.2.1. Definicja węzła głównego

Poniżej przedstawiona jest przykładowa definicja węzła głównego formularza Adobe na platformie ePUAP:

Charakterystyczną cechą formularzy tworzonych w narzędziu Adobe LiveCycle Designer jest typ XDP (XML Data Package). Jest to XML’owy format plików stworzony przez Adobe Systems w 2003r. Zamiarem firmy było stworzenie połączenia dwóch formatów: PDF i XML. Rozwiązanie, które zaproponowała firma Adobe, pozwoliło na to, żeby zawartość PDF była umieszczona w „body” pliku XML.

W przypadku umieszczania formularza XDP na platformie ePUAP użytkownik musi zwrócić uwagę na atrybut typFormularza. Musi być on ustawiony na „xdp”.

W momencie zaimportowania formularza XDP do aplikacji w module Środowiska Budowy Aplikacji typ powinien ustawić się automatycznie na xdp (importowane formularze rozróżniane są po typach plików).

2.2.2. Wskazanie wzoru dokumentu elektronicznego

Tworzony formularz, aby poprawnie działał w środowisku ePUAP, musi odnosić się do wzoru dokumentu elektronicznego opublikowanego w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych (CRWDE) lub w lokalnym repozytorium wzorów (wzory lokalne w ŚBA).

<?xml version="1.0" encoding="UTF-8"?>

<Formularz

domyslnaNazwaAdresata=""

domyslnaSkrytkaAdresata=""

nazwa="template_TEST_moj_formularz.xdp"

prywatny="false"

typFormularza="xdp"

xmlns="http://www.epuap.gov.pl/Formularz">

<formularzXdp>

<xdp:xdp>

<template>

.......................

</template>

.......................

</xdp:xdp>

</formularzXdp>

</Formularz>


Wersja 1.01

16 / 38

Dodanie wzoru do formularza w aplikacji LiveCycle Designer odbywa się poprzez opcję New Data Connection -> XML Schema. Można wówczas wskazać schemat bezpośrednio z dysku lub poprzez wpisanie pełnego url do wzoru, np. http://crd.gov.pl/wzor/2013/10/09/1526/schemat.xsd. Ostatnim krokiem będzie wyznaczenie „root’a”.

Jeżeli chcemy, aby podany schemat był umieszczony w środku formularza, należy zaznaczyć opcję Embed XML Schema.

Na podstawie schematu, do formularza wprowadzane są dwa elementy:

1. Datasets – zestaw danych, gdzie miedzy innymi jest wskazany URL do wzoru, np. http://test.crd.gov.pl/wzor/2013/10/10/1527/:

2. Connectionset – zestaw połączeń, gdzie wskazane jest uri oraz root do wzoru:

lub w przypadku umieszczenia schematu w środku formularza:

<connectionSet xmlns="http://www.xfa.org/schema/xfa-connection-set/2.1/">

<xsdConnection name="DataConnection" dataDescription="Dokument">

<uri>\wzor1527\schemat.xsd</uri>

<rootElement>Dokument</rootElement>

</xsdConnection>

</connectionSet>

<connectionSet xmlns="http://www.xfa.org/schema/xfa-connection-set/2.1/">

<?originalXFAVersion http://www.xfa.org/schema/xfa-connection-set/2.8/?>

<xsdConnection name="DataConnection" dataDescription="Dokument">

<uri>http://test.crd.gov.pl/wzor/2013/10/10/1527/schemat.xsd/</uri>

<rootElement>Dokument</rootElement>

</xsdConnection>

</connectionSet>

<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<dd:dataDescription xmlns:dd="http://ns.adobe.com/data-description/" dd:name="Dokument">

<wnio:Dokument xmlns:wnio="http://test.crd.gov.pl/wzor/2013/10/10/1527/">

........

........

</wnio:Dokument>

</dd:dataDescription>

</xfa:datasets>

http://crd.gov.pl/wzor/2013/10/09/1526/schemat.xsd

http://test.crd.gov.pl/wzor/2013/10/10/1527/


Wersja 1.01

17 / 38

Podanie prawidłowego adresu URL jest ważne z dwóch powodów. Po pierwsze Adobe bez poprawnej ścieżki nie odnajdzie schematu. Po drugie na podstawie schematu, formularz wiązany jest z danym wzorem i wówczas możliwa jest zarówno walidacja, jaki i wizualizacja takiego dokumentu ze wskazanym schematem XSD i stylem XSL.

W przypadku korzystania z CRWDE użytkownik musi wprowadzić ścieżkę do istniejącego schematu (w konsekwencji wzoru dokumentu elektronicznego) w postaci:


http://test.crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/nazwa_schematu,

np. http://test.crd.gov.pl/wzor/2013/10/09/1526/schemat.xsd


http://crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/nazwa_schematu,

np. http://crd.gov.pl/wzor/2013/11/09/3526/schemat.xsd

Gdzie:

http://test.crd.gov.pl/ lub http://crd.gov.pl/ - adres serwera;


rok/miesiąc/dzień/numer_wzoru/ - jest nazwą wzoru dokumentu elektronicznego, pod jakim został opublikowany schemat, styl, wyróżnik: rok – reprezentuje czterocyfrowa liczba, miesiąc – reprezentuje dwucyfrowa liczba, dzień - reprezentuje dwucyfrowa liczba, numer_wzoru –kilkucyfrowa liczba;

nazwa schematu – najczęściej jest to zwrot „schemat.xsd” w przypadku CRWDE, ale w przypadku wzorów lokalnych nazwa może być dowolna.

W przypadku korzystania ze wzoru lokalnego użytkownik musi wprowadzić ścieżkę do istniejącego wzoru lokalnego:


http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/nazwa_schematu,

np. http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/ludzik/ZmianaLicencji/schemat.xsd

http://test.crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/nazwa_schematu

http://test.crd.gov.pl/wzor/2013/10/09/1526/schemat.xsd

http://crd.gov.pl/wzor/rok/miesiąc/dzień/numer_wzoru/nazwa_schematu

http://crd.gov.pl/wzor/2013/11/09/3526/schemat.xsd

http://test.crd.gov.pl/

http://crd.gov.pl/

http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/nazwa_schematu

http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/ludzik/ZmianaLicencji/schemat.xsd


Wersja 1.01

18 / 38


http://epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/nazwa_schematu,

np. http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/Sopel/Drzewo/schemat_nowy.xsd

Gdzie:

http://test.crd.gov.pl/FeResourceServlet/ lub http://epuap.gov.pl/FeResourceServlet/ - adres serwera oraz katalogu dla wzorów lokalnych;

wzor_lokalny/id_podmiotu/ – obszar lokalnych wzorów dokumentów elektronicznych podmiotu o identyfikatorze id_podmiotu;

nazwa_wzoru/ - reprezentuje nazwę podmiotu oraz nazwę wzoru;

nazwa schematu – nazwa wczytywanego schematu na podstawie, którego będzie tworzony formularz.

2.2.3. Deklarowanie przestrzeni nazw

Deklarowanie przestrzeni nazw w przypadku formularzy Adobe jest niepotrzebne (powołujemy się na schemat z CRWDE lub z wzorów lokalnych, który istnieje i jest już gotowy do użycia).

W przypadku formularzy XForms mieliśmy sytuację odwrotną. Deklaracje przestrzeni nazw były potrzebne, ponieważ na podstawie tych deklaracji tworzony był schemat w Środowisku Budowy Aplikacji.

2.2.4. Określenie domyślnej skrytki adresata dokumentu

Jeżeli chcemy, aby formularz po uruchomieniu w środowisku ePUAP zawierał odbiorcę, to należy umieścić adres skrytki, na który domyślnie adresowane będą dokumenty utworzone przy pomocy tego formularza. Aby to zrobić należy umieścić następujący element w sekcji „head” formularza:

<head> …

<meta property="adresSkrytki">/id_podmiotu/nazwa_adresu_skrytki</meta> … </head>

http://epuap.gov.pl/FeResourceServlet/wzor_lokalny/id_podmiotu/nazwa_wzoru/nazwa_schematu

http://test.epuap.gov.pl/FeResourceServlet/wzor_lokalny/Sopel/Drzewo/schemat_nowy.xsd

http://test.crd.gov.pl/FeResourceServlet/

http://epuap.gov.pl/FeResourceServlet/


Wersja 1.01

19 / 38

Przykład:

Elementy „meta” są niezgodne z XHTML-em, element meta w XHTML-u jest elementem traktowanym, jako pusty, tj. <meta atrybuty />.

Elementy ePUAP-owe „meta” zostaną usunięte przez środowisko uruchomieniowe i nie będą wpływały na jego poprawność i wygląd.

Najprostszym rozwiązaniem w celu dodania sekcji head z adresem skrytki w meta

jest:

1. Zaimportowanie formularza do podsystemu ŚBA;

2. Wyeksportowanie zaimportowanego formularza do XML;

3. Wprowadzenie sekcji HEAD wraz z adresem skrytki za pomocą edytora XML, np. NotePad++, XMLSpy do wyeksportowanego pliku;

4. Usunięcie starego formularza i zaimportowanie nowego z wprowadzonymi zmianami dotyczącymi adresata;

5. Zainstalowanie aplikacji poprzez Testy otwarte lub Uaktualnienie aplikacji.

<?xml version="1.0" encoding="UTF-8"?>

<Formularz

domyslnaNazwaAdresata=""

domyslnaSkrytkaAdresata=""

nazwa="Formularz_testowy.xdp"

prywatny="false"

typFormularza="xdp"

xmlns="http://www.epuap.gov.pl/Formularz">

<formularzXdp>

<xdp:xdp timeStamp="2013-11-27T11:28:41Z"

uuid="0b083727-5646-42ea-81aa-0f5240d05463"

xmlns:xdp="http://ns.adobe.com/xdp/">

<head>

<meta property="adresSkrytki">/SzkolaWyzszaLublin/skrytka</meta>

</head>

<template xmlns="http://www.xfa.org/schema/xfa-template/2.4/">

.......................

</template>

.......................

</xdp:xdp>

</formularzXdp>

</Formularz>


Wersja 1.01

20 / 38

3. Dane dostępne dla formularza ePUAP

W chwili otwierania dokumentu do edycji przy użyciu danego formularza do tego formularza dodawane są automatycznie charakterystyczne dla platformy ePUAP instancje.

Poniżej zostaną opisane te instancje, ich przeznaczenie i sposób utworzenia.

3.1. Dana o stanie dokumentu elektronicznego

Działanie formularz można uzależnić od tego czy dokument już zapisany został otworzony przez formularz, czy dokument nie był jeszcze zapisany i jest na etapie tworzenia przy pomocy formularza.

Ustalenie staniu dokumentu umożliwia instancja „first-load”, która przyjmuje wartość „Yes”, gdy dokument jest na etapie tworzenia, a wartość „No”, gdy dokument został już zapisany.

Przykład instancji:

3.2. Dana podmiotu lub użytkownika

3.2.1. Pobieranie danych o podmiocie i użytkowniku do formularza zbudowanego w XForms

Aktualnie dane zalogowanego podmiotu dostępne są w instancji „init-data”. Jej treść w zależności od rodzaju podmiotu będzie zawierała element „oso:Osoba” lub „inst:Instytucja”.

<head> … … <xf:instance id="first-load"> <isFirstLoad>Yes</isFirstLoad> </xf:instance> … … </head>


Wersja 1.01

21 / 38

Dla przykładu dane z instancji „init-data” można użyć we wstępnej fazie tworzenia dokumentu przy obsłudze zdarzenia „XForms-model-construct-done” w celu wypełnienia dokumentu danymi wnioskującego. Przykład instancji „init-data”:

3.2.2. Pobieranie danych o podmiocie i użytkowniku do formularza zbudowanego w Adobe

Podczas otwierania dokumentu do edycji przy użyciu danego formularza można wymusić od systemu ePUAP, aby pobrał automatycznie część danych dostępnych w ramach systemu i wstawił je do formularza. Przykładowo można z chwilą uruchomienia formularza wstawić do niego dane na temat zalogowanego użytkownika lub dane na temat jego podmiotu.

Dane zalogowanego użytkownika i jego podmiotu mogą być automatycznie pobierane po uruchomieniu formularza. W tym celu podczas budowy formularza należy dodać pola/kontrolki i jako wartość domyślną kontrolki wpisać jedną z poniższych wartości:

Dane zalogowanego użytkownika:

#ImieUzytkownika

#NazwiskoUzytkownika

#DrugieImieUzytkownika

#EmailUzytkownika

<head> … …

<xf:instance id="init-data"> <init-data/>

</xf:instance> …

… </head>


Wersja 1.01

22 / 38

Dane podmiotu, na który zalogował się użytkownik:

Osoba fizyczna, osoba fizyczna prowadząca

działalność gospodarczą

Osoba prawna, jednostka

organizacyjna niemająca osobowości

prawnej

Wartości wspólne dla osoby prawnej, osoby fizycznej prowadzącej działalność gospodarczą, jednostki

organizacyjnej niemającej osobowości prawnej

#Imie #NazwaInst #KodPocztowy

#Nazwisko #KRS #Poczta

#PESEL #NIPInst #Miejscowosc

#NIPOsoby #REGON #Ulica

#KodPocztowyOsoby #KodPocztowyInst #Budynek

#PocztaOsoby #PocztaInst #Lokal

#MiejscowoscOsoby #MiejscowoscInst #Wojewodztwo

#UlicaOsoby #UlicaInst #Gmina

#BudynekOsoby #BudynekInst #Kontakt

#LokalOsoby #LokalInst #Powiat

#WojewodztwoOsoby #WojewodztwoInst #RodzajPodmiotu

#GminaOsoby #GminaInst

#KontaktOsoby #KontaktInst

#PowiatOsoby #PowiatInst

#FormaWlasnosci

#FormaPrawna

Aby to zrobić należy przejść do danego pola/kontrolki, wybrać zakładkę Value i wpisać dowolną wartość z listy w pole Default, np. #ImieUzytkownika, #WojewodztwoInst.


Wersja 1.01

23 / 38

4. Opcjonalne funkcjonalności formularza ePUAP

Formularz ePUAP składa się z podstawowej funkcjonalności zawierającej definicję pól umożliwiających edycję dokumentu elektronicznego oraz z wielu funkcjonalności charakterystycznych dla przyjętych rozwiązań na platformie ePUAP, do tych funkcjonalności zalicza się:

1. Dołączanie do dokumentu elektronicznego załączników – formularz może umożliwiać dołączanie wskazanych plików, jako załączniki,

2. Podpisywanie części dokumentu elektronicznego – możliwość podpisania określonych części edytowanego dokumentu,

3. Komunikacja ze słownikami – pola dokumentu mogą przyjmować wartości występujące w słowniku wcześniej zdefiniowanym na ePUAP,

4. Wysyłanie z formularza danych do ESP ePUAP – stosuje się w przypadku potrzeby wysłania bezpośrednio z formularza do ESP danych,

5. Akcja „odeślij” – stosuje się ją do definiowania automatycznej odpowiedzi przez podmiot publiczny. Można ją również wykorzystać do przekazania dokumentu „dalej” np. do innego podmiotu. Akcja odeślij nie jest widoczna na formularzu w momencie jego wypełniania. Dopiero po wysłaniu dokumentu przez użytkownika, usługodawca w folderze Odebrane widzi akcje odeślij jako przycisk,

6. Akcja „opłać” wykorzystywana w przypadku składania dokumentu elektronicznego do podmiotu publicznego, który wymaga wniesienia opłaty,

7. Triggery –stosowane w przypadku konieczności wywołania akcji na formularzu. W zależności od typu triggera podpięta pod niego akcja jest wykonywana w momencie wysłania dokumentu lub odebrania dokumentu.

4.1. Dołączanie do dokumentu elektronicznego załączników

4.1.1. Załączniki w technologii XForms

Jeżeli chcemy udostępnić w formularzu możliwość dodania plików ze wskazanego zasobu: dysku lub składu dokumentów, to należy utworzyć element XForms upload o identyfikatorze oraz referencji.

Przykład:

<xf:upload id="identyfikatorKontrolki" ref="sciezka/do/str:DaneZalacznika">

<xf:filename ref="../@nazwaPliku"/> </xf:upload>


Wersja 1.01

24 / 38

Jeżeli do załącznika chcemy dodać opis, dobrą praktyką jest zdefiniowanie elementu:

Należy oznaczyć dane załącznika (w zależności od kodowania załącznika: odpowiednio base64 lub URI) za pomocą elementów xf:bind.

Plik jest dołączony do formularza w formie załącznika w formacie base64 w przypadku załączników (str:Zalacznik) o kodowaniu „base64” lub w postaci odnośnika do pliku zewnętrznego w przypadku załączników o kodowaniu „URI” (patrz: typ str:ZalacznikKodowanieTyp). W przypadku kodowania „URI” (funkcjonalność „Duże załączniki”) system może wykorzystać pole str:OpisZalacznika do przechowywania wartości funkcji skrótu (ang. hash) wskazywanego pliku.

Kontrolki upload utworzone w powyższy sposób związane z danymi zgodnymi ze schematami atomowymi przewidzianymi dla załączników (str:Zalacznik itd.) powinny zostać rozszerzone przez środowisko uruchomieniowe do ePUAP-owej kontrolki załącznika, umożliwiającej poza pobraniem z dysku także na pobranie ze składu.

4.1.2. Załączniki w technologii Adobe

Tak jak było wspominane wcześniej do poprawnej pracy formularzy XDP w środowisku ePUAP niezbędne jest zbudowanie formularza w oparciu o szablon „template.xdp”. W szablonie tym zawarte są funkcje JavaScript, które wykorzystywane są do integracji formularzy XDP z systemem ePUAP. Między innymi zawierają logikę pozwalającą na dołączanie załączników zakodowanych w formacie BASE64 do wynikowego dokumentu XML.

Załączanie załączników zadziała tylko wtedy, gdy w schemacie XSD, na

podstawie, którego tworzony jest formularz zdefiniowane są załączniki, tzn. istnieje węzeł Zalaczniki oraz DaneZalacznika.

Funkcje dostępne w ramach szablonu XDP dotyczące załączników to:

function attachmentsChanged() – sprawdza, czy aktualna lista załączników została zmieniona, lista załączników porównywana jest z listą zapisaną w zmiennej attachmentsList;

function getAttachments() – zwraca tablicę zawierającą aktualną listę załączników;

function checkAttachmentsSize(maxSize) – sprawdza, czy sumaryczny rozmiar załączników nie przekracza wartości podanej w parametrze maxSize;

function removeAttachmentsFromData() – usuwa załączniki z dokumentu (węzły Zalacznik znajdujące wewnątrz węzła Zalaczniki w xfa.data);

<xf:textarea id="identyfikatorKontrolki2" ref="sciezka/do/str:OpisZalacznika">


Wersja 1.01

25 / 38

function addNode(where, what) – dodaje węzeł podany w parametrze what do węzła where, jeśli węzeł where nie zawiera już węzła o podanej nazwie i przestrzeni nazw;

function addAttachment(fileAttachment) – dodaje nowy załącznik do dokumentu, w tym celu dodawany jest węzeł Zalacznik do węzła Zalaczniki w dokumencie, zawartość załącznika konwertowana jest do formatu BASE64 i zapisywana w węźle DaneZalacznika, dodatkowo ustawiane są atrybuty załącznika (nazwa, kodowanie itp.);

function addAttachmentsToDataXml() – usuwa załączniki z dokumentu i dodaje aktualną listę załączników do dokumentu;

function addZalacznikiNodeFromSchema() – przeszukuje schemat dokumentu w poszukiwaniu węzła Zalaczniki i dodaje go do dokumentu wynikowego (xfa.data) pod taką ścieżką jak w schemacie, jeśli schemat nie zawiera węzła Zalaczniki zwracana jest wartość false, w przeciwnym wypadku true.

Szczegółowy kod każdej zdefiniowanej funkcji użytkownik może podejrzeć po załadowaniu pliku template.xdp do środowiska LiveCycle Designer i przejściu do Hierarchy-> Dokument ->Variables -> Messaging.

4.2. Podpisywanie części dokumentu elektronicznego

Platforma ePUAP umożliwia podpisywanie poszczególnych elementów, węzłów formularza. W tym celu należy określić id węzłów, które mają być podpisane.

Przykład:

W dokumencie, który zawiera 4 pola: imię, nazwisko, adres, data urodzenia. Chcemy, aby pola imię, nazwisko po uzupełnieniu były podpisane przez osobę 1. Dane adres i data urodzenia po uzupełnieniu mają być podpisane przez osobę 2. Tworzymy dwa identyczne formularze, różniące się poniżej przedstawionymi elementami:

Formularz 1 Formularz 2

<idWezlowDoPodpisu>

<idWezla>podpis1</idWezla>


</idWezlowDoPodpisu>

<idWezlowDoPodpisu>



</idWezlowDoPodpisu>

Następnie w xf:model, w dokumencie, na którym operuje formularz należy

zdefiniować elementy i przypisać im odpowiednie id np.: <wnio:Imie id="podpis1" />

<wnio:Nazwisko id="podpis2" />

<wnio:Adres id="podpis3" />

<wnio:DataUrodzenia id="podpis4" />


Wersja 1.01

26 / 38

4.3. Komunikacja ze słownikami

4.3.1. Definiowanie słowników dla XForms

Formularz może posiadać pola, których wartości są przyjmowane ze słownika. Na platformie ePUAP został udostępniony podsystem Słowników Referencyjnych w postaci usługi sieciowej SOAP. Słowniki referencyjne mogą być definiowane na platformie ePUAP przez osobę posiadającą odpowiednie uprawnienia. Do powszechnego użycia są aktualnie dostępne słowniki wymienione w poniższej tabeli.

Aby umożliwić komunikację z tą usługą z poziomu silnika formularzy utworzono usługę o nazwie wsservlet, w obsługiwanym przez silnik formularzy stylu REST.

Z istniejących słowników na platformie ePUAP można korzystać w formularzu poprzez usługę wsservlet oraz element XForms „submission”.

Usługa wsservlet, obsługująca zapytania do słowników, ma następujące parametry:

mode - sposób zwracania wyników, wartość domyślna to "list", parametr nie jest wymagany, możliwe są dwie wartości:

"list" - zwraca większy plik XML z dodatkowymi wartościami poza nazwą;

"edit_box" - w jednym elemencie XML wypisuje tylko same nazwy pozycji ze słownika;

słownik - kod słownika, z którego chcemy pobierać wartości. Wartość parametru zależy od wczytanych słowników np. "WOJ", "POWIATY", itd. Parametr jest wymagany;

Kod słownika Nazwa słownika

PKD_2004 Klasyfikacja PKD 2004


KRAJE Słownik krajów

WOJ Słownik województw

POWIATY Słownik powiatów

GMINY Słownik gmin

MIEJSCOWOSCI Słownik miejscowości

ULICE Słownik ulic


Wersja 1.01

27 / 38

referencja - wartością tego parametru jest nazwą wykorzystywaną przy budowaniu odpowiedzi w XML. Główny element XML ma w nazwie wartość tego parametru. Parametr jest wymagany;

referencja_nadrzedna - parametr jest wykorzystywany przy ograniczaniu pobieranych pozycji ze słownika na podstawie wartości z nadrzędnego słownika. Wartość tego elementu oznacza nazwę kolejnego parametru w wywołaniu. Dla przykładu, gdy wartością tego parametru jest "elem", to w wywołaniu powinien pojawić się jeszcze parametr elem z wartością równą wybranej ze słownika nadrzędnego (wymagana wartość numeryczna, a nie nazwa pozycji). Parametr opcjonalny dla ograniczenia pobieranych wartości ze słownika.

Przykłady:

W środowisku testowym odwołanie bez wartości nadrzędnej:

http://test.epuap.gov.pl/portal/wsservlet?slownik=WOJ&referencja=ref

W środowisku testowym odwołanie do słownika powiatów z wartością nadrzędną, czyli wartością województwa nadrzędnego:

http://test.epuap.gov.pl/portal/wsservlet?slownik=POWIATY&referencja=ref&referencja_nadrzedna=elem&elem=06

http://test.epuap.gov.pl/portal/wsservlet?slownik=WOJ&referencja=ref&referencja=ref

W tym przypadku dodawane są dwa powiązane ze sobą parametry: referencja_nadrzedna=elem&elem=06

Gdzie: elem - to prosty identyfikator, parametr o tej nazwie musi mieć wartość numeryczną określającą pozycję nadrzędnego słownika, np. 06 (nie nazwę).

W środowisku produkcyjnym adres jest:

http://epuap.gov.pl/portal/wsservlet?

4.3.2. Definiowanie słowników w Adobe

Tworząc formularz niejednokrotnie zastanawiamy się, czy przypadkiem danych wartości nie możemy pobrać z jakiegoś słownika i tym samym uprościć wprowadzanie danych potencjalnemu użytkownikowi formularza. Ponieważ w systemie ePUAP udostępniony jest podsystem Słowników Referencyjnych warto czasami wykorzystać ten element podczas budowy formularza XDP. Słowniki referencyjne może wczytać do Systemu ePUAP osoba posiadająca odpowiednie uprawnienia, natomiast korzystać już z istniejących słowników może każdy. Do powszechnego użycia są dostępne słowniki wymienione w poniższej tabeli.

http://test.epuap.gov.pl/portal/wsservlet?slownik=WOJ&referencja=ref

http://test.epuap.gov.pl/portal/wsservlet?slownik=POWIATY&referencja=ref&referencja_nadrzedna=elem&elem=06

http://test.epuap.gov.pl/portal/wsservlet?slownik=WOJ&referencja=ref&referencja=ref

http://epuap.gov.pl/portal/wsservlet


Wersja 1.01

28 / 38

Kod słownika Nazwa słownika



KRAJE Słownik krajów

WOJ Słownik województw

POWIATY Słownik powiatów

GMINY Słownik gmin

MIEJSCOWOSCI Słownik miejscowości

ULICE Słownik ulic

Korzystanie ze słowników referencyjnych z poziomu formularza XDP sprowadza się do wywołania usługi sieciowej Słowników Referencyjnych. Aby to zrobić należy wybrać opcję File->New Data Connection->WSD File a następnie wskazać plik WSDL znajdujący się:

w środowisku testowym pod adresem:

http://test.epuap.gov.pl/sr_external_ws/services/SlownikiReferencyjnePublic?wsdl

a w środowisku produkcyjnym pod adresem:

http://ws.epuap.gov.pl/sr_external_ws/services/SlownikiReferencyjnePublic?wsdl

Po utworzeniu nowego połączenia (New Data Connection) w sekcji Data View (tam gdzie wczytywaliśmy poprzednio schemat) powinien pojawić się nowy wpis o nazwie WSDLSlownik.

Dalszy sposób pracy z usługą udostępniania danych słownikowych zależy od sposobu ich wykorzystania na formularzu. W najprostszym przypadku można zaprezentować użytkownikowi kontrolki służące do wpisania parametrów wywołania i tabelę z wynikami.

Aby to zrobić należy przeciągnąć na formularz odpowiednie elementy z widoku „Data view” na obszar roboczy Design View, np. Kod Słownika, Kod Pozycji Słownika, etc. Dodatkowo należy dodać przycisk (Buton), w którego opcjach należy wybrać wywołanie dodanej przez nas usługi sieciowej (wybieramy opcję Execute i wskazujemy nasz Connection).

Więcej informacji na temat Słowników Referencyjnych (znaczenia parametrów) użytkownik znajdzie w instrukcji dla integratorów „Współpraca z systemami zewnętrznymi” dostępnej w sekcji pomoc dla integratorów na stronach ePUAP.

http://test.epuap.gov.pl/sr_external_ws/services/SlownikiReferencyjnePublic?wsdl

http://ws.epuap.gov.pl/sr_external_ws/services/SlownikiReferencyjnePublic?wsdl


Wersja 1.01

29 / 38

4.4. Wysyłanie z formularza danych na skrytkę ePUAP

Jednym z podstawowych rodzajów pracy na ePUAP jest edycja dokumentu za pomocą formularza, a następnie jego zapis, zaadresowanie w podsystemie Moje Dokumenty i wysłanie za pomocą Podsystemu Komunikacyjnego (PK).

Jednak może wystąpić potrzeba wysłania danych z instancji formularza XForms bezpośrednio na skrytkę.

Podsystem Komunikacyjny dostępny jest, jako usługa sieciowa SOAP, aby z niej skorzystać z poziomu formularza dostępny jest pośrednik w postaci usługi w stylu REST, na którą można wysłać dane za pomocą elementu XForms „submission”.

Usługa „XMLServlet”, obsługującego wysyłanie danych z formularza na skrytkę, ma następujące parametry:

depositeBoxAddress - parametr określający adres skrytki na ePUAP, na którą ma być wysłany dany XML. Parametr jest wymagany;

tgsid - parametr określający identyfikator sesji (token bezpieczeństwa). Jest przydzielany dopiero po zalogowaniu. Parametr jest wymagany. Aby uzyskać jego wartość i móc ją przekazać do wywołania usługi XMLServlet należy odczytać wartość parametru „tgsid”, z którym wywołany jest silnik formularza. W tym celu należy skorzystać z dodatkowej funkcji XPath udostępnionej w ramach silnika: xxforms:get-request-parameter(‘tgsid’). Pełna dokumentacja znajduje się pod adresem:

http://wiki.orbeon.com/forms/doc/developer-guide/xforms-xpath-functions

Z funkcji tej można skorzystać tylko w odpowiedzi na zdarzenia xforms-ready lub xformsmodel-construct-done, więc należy ją odczytać na początku działania formularza i pamiętać do momentu wywołania usługi w tymczasowej instancji danych;

instance - nazwa instancji XML wysyłanego na odpowiednią skrytkę. Służy do utworzenia odpowiedzi już dla samego formularza. Parametr jest wymagany.

responseAddress - adres odpowiedzi, adres skrytki nadawcy, na którą ma być dostarczona odpowiedz; podmiot odbierający odpowiedź musi mieć przydzielone uprawnienia do skrytki związanej z tym adresem;

czyProbne - próbne zlecenie doręczenia, przyjmuje wartość True i False, domyślnia wartość False. Przy zleceniu próbnym True dokument nie jest przekazywany dalej, sprawdzana jest tylko poprawność parametrów i skrytki odbiorcy.

Przykłady:


http://test.epuap.gov.pl/portal/xmlservlet?instance=in&depositeBoxAddress=/ID_Podmiotu/adres_skrytki&tgsid=wartosc_tgsid_odczytana_wczesniej

W środowisku produkcyjnym adres jest:

http://epuap.gov.pl/portal/xmlservlet?

http://wiki.orbeon.com/forms/doc/developer-guide/xforms-xpath-functions



http://epuap.gov.pl/portal/xmlservlet


Wersja 1.01

30 / 38

4.5. Akcje „Odpowiedz”

Jeżeli chcemy udostępnić w formularzu możliwość automatycznej odpowiedzi lub przekazania dokumentu do innej instytucji publicznej to należy utworzyć w węźle głównym dokumentu (<formularz>) sekcje (tag) <akcja>. Sekcja <akcja> powinna zawierać atrybuty:

nazwa – nazwa akcji, na formularzu będzie to nazwa przycisku;

typ – odeslij, definiuje typ akcji.

Następnie należy zdefiniować sekcje parametr z atrybutami nazwa, gdzie wartości atrybutu definiują parametry akcji odeślij:

adres – adres odbiorcy, można podać adres skrytki w postaci /identyfikator_podmiotu/nazwa_adresu_skryki lub ciag znaków „autor” lub „nadawca”. Gdzie autor to użytkownik wysyłający formularz jako pierwszy a nadawca to użytkownik, który wysłał formularz jako ostatni do nas;

xslt - powinien zawierać transformatę dla odsyłanego dokumentu. Jeżeli transformata nie zostanie wskazana to system prześle „dalej” odebrany dokument. Transformata powinna być umieszczona w sekcji <wartość>;

warunek_wyswietlania - powinien zawierać wyrażenie XPath, określający, w jakim przypadku akcja powinna być wyświetlona.

Przykład:

<akcja nazwa="Odpowiedz" typ="odeslij"> <parametr nazwa="adres"> <wartosc>nadawca</wartosc> </parametr> <parametr nazwa="xslt"> <wartosc> <xsl:stylesheet version="1.0"

… </wartosc> </parametr> <parametr nazwa="warunek_wyswietlania"> <wartosc/> </parametr> </akcja>


Wersja 1.01

31 / 38

4.6. Akcja „Opłać”

Jeżeli chcemy udostępnić w formularzu płatność elektroniczną to należy utworzyć w węźle głównym dokumentu (<formularz>) sekcje (tag) <akcja>. Sekcja <akcja> powinna zawierać atrybuty:

nazwa – nazwa akcji, na formularzu będzie to nazwa przycisku;

typ – oplac, definiuje typ akcji.

Następnie należy zdefiniować sekcje parametr z atrybutami nazwa, gdzie wartości atrybutu nazwa definiują parametry akcji opłać:

tytul_oplaty - należy wprowadzić wyrażenie XPath pozwalające na określenie tytułu opłaty;

wysokosc_oplaty – należy wprowadzić wyrażenie XPath pozwalające na określenie kwoty należności;.

numer_rachunku - należy wprowadzić numer rachunku bankowego, na jakie będzie realizowana płatność;

czy_modyfikowac – należy wprowadzić true lub false;

warunek_wyswietlania - powinien zawierać wyrażenie XPath, określający, w jakim przypadku akcja powinna być wyświetlona.

Przykład:

<akcja nazwa="Opłać" typ="oplac"> <parametr nazwa="tytul_oplaty"> <wartosc> </wartosc> </parametr> <parametr nazwa="wysokosc_oplaty"> <wartosc>//*[local-name()='Dokument']/*[local-name()='TrescDokumentu']/*

[local-name()='Wartosc']/*[local-name()='WysokoscOplaty'] </wartosc> </parametr> <parametr nazwa="numer_rachunku"> <wartosc>11111111111111111111111111</wartosc> </parametr> <parametr nazwa="czy_modyfikowac"> <wartosc>true</wartosc> </parametr> <parametr nazwa="warunek_wyswietlania"> <wartosc>true()</wartosc> </parametr> </akcja>


Wersja 1.01

32 / 38

4.7. Triggery

Jeżeli chcemy w formularzu automatycznie wywołać akcję to należy utworzyć w węźle głównym dokumentu (<formularz>) sekcje (tag) <triggery>.

W jednym formularzu można zdefiniować maksymalnie dwa triggery, po jednym z każdego typu: „odeslij”, „oplac”.

Sekcja <triggery> powinna zawierać atrybuty:

akcja – nazwa akcji, jaka akcja powinna być wykonana w przypadku zajścia zdarzenia zdefiniowanego w typie. Na danej liście wyświetlane są akcje dla danego formularza.;

typ – zdarzenie uruchamiające trigger, można podać jeden z dwóch typów: wyślij lub odbierz;

warunek_wyswietlania - powinien zawierać wyrażenie XPATH, określający, w jakim przypadku trigger powinien być wykonany.

Przykład:

<triggery>

<trigger akcja="Odpowiedz" typ="wyslij" warunek="true()"/> </triggery>


Wersja 1.01

33 / 38

5. Elementy automatycznie dodawane do dokumentu elektronicznego

Do tworzonego dokumentu elektronicznego są automatycznie dodawane elementy charakterystyczne dla platformy ePUAP. Poniżej zostaną przedstawione te elementy, ich przeznaczenie i sposób utworzenia.

5.1. Identyfikator formularza

Identyfikator formularza służy do wskazania formularza, który umożliwił utworzenie dokumentu elektronicznego.

Identyfikator formularza jest dodawany przez podsystem „Moje Dokumenty” poza silnikiem formularza w czasie zapisu dokumentu w zbiorze dokumentów. Identyfikator składa się z identyfikatora podmiotu „id_podmiotu” oraz z nazwy formularza „nazwa_formularza”.

Identyfikator formularza umieszczany jest w dokumencie elektronicznym, w elemencie <meta:Wartosc> znajdującym się wewnątrz elementu <meta:Identyfikator> stanowiącego część elementu <wnio:OpisDokumentu>, co przedstawiono poniżej:

Wymagane jest zdefiniowanie prefiksu „meta” na poziomie głównego elementu wzoru dokumentu elektronicznego, stanowiącego odwołanie do aktualnej przestrzeni nazw, zawierającej definicje meta danych, co przedstawiono poniżej:

<wnio:Dokument> …

xmlns:meta="http://crd.gov.pl/xml/schematy/meta/2009/11/16/" … </wnio:Dokument>

<wnio:OpisDokumentu> … …

<xsl:for-each select="wnio:OpisDokumentu/meta:Identyfikator"> <meta:Identyfikator typIdentyfikatora="{@typIdentyfikatora}"> <meta:Wartosc> <xsl:value-of select="meta:Wartosc"/> </meta:Wartosc> </meta:Identyfikator>

</xsl:for-each> … … </wnio:OpisDokumentu>


Wersja 1.01

34 / 38

5.2. Identyfikator korelacji

Identyfikator korelacji służy do budowy relacji zachodzącej pomiędzy dokumentami elektronicznymi. W szczególnych przypadkach w jednym dokumencie może być więcej niż jeden identyfikator korelacyjny. Dla przykładu, relacja może określać zależności dokumentów przetwarzanych w trybie asynchronicznym lub relacja określa przypisanie dokumentów do jednej sprawy. W formularzu identyfikator korelacji powinien być oznaczony za pomocą skrótu CID (ang. Correlation Identifier).

Identyfikator korelacji CID jest dodawany przez podsystem „Moje Dokumenty” poza silnikiem formularza w czasie zapisu dokumentu do zbioru dokumentów.

System doda element CID do elementu <wnio:OpisDokumentu>, co przedstawiono poniżej:

5.3. Elektroniczne Poświadczenie Opłaty

Złożenie dokumentu elektronicznego do podmiotu publicznego może wymagać wniesienia opłaty. Fakt wniesienia opłaty jest potwierdzany dokumentem elektronicznym o nazwie Elektroniczne Poświadczenie Opłaty (EPO).

Elektroniczne Poświadczenie Opłaty posiada określoną strukturę, w której między innymi występują następujące informacje: tytuł wniesienia opłaty, numer rachunku, wysokość kwoty wniesionej na rachunek oraz poświadczenie podpisem elektronicznym.

W formularzu można zdefiniować akcję „Opłać”, która umożliwi dokonanie opłaty, a do dokumentu elektronicznego zostanie dołączone, jako załącznik EPO.

Ponadto w takim przypadku, w formularzu musi być zdefiniowana sekcja powtarzalna umożliwiająca dołączanie załączników.

<wnio:OpisDokumentu> … … <xsl:for-each select="wnio:OpisDokumentu/str:CID"> <str:CID> <xsl:value-of select="."/> </str:CID> </xsl:for-each> … … </wnio:OpisDokumentu>


Wersja 1.01

35 / 38

5.4. Podpis elektroniczny

Podpis elektroniczny powinien zawierać referencje do całej treści poświadczenia oraz referencje do wszystkich obiektów wchodzących w skład dokumentu, którego dotyczy poświadczenie. W przypadku, gdy dokument składa sie z 4 plików to powinny być one objęte podpisem poprzez referencje.

Podpis powinien być tak skonstruowany, że umieszczenie poświadczenia razem z plikami, których dotyczy w jednym katalogu powinno umożliwić weryfikację podpisu, weryfikacja może być pozytywna lub negatywna.

Podpisy dodawane przez system ePUAP są elementami <ds:Signature> umieszczonymi, jako ostatnie elementy potomne głównego elementu.

Dodawanie elementów podpisu przeprowadzane jest poza silnikiem formularzy.


Wersja 1.01

36 / 38

6. Adresowanie i zapis dokumentu elektronicznego

6.1. Adresowanie dokumentu

Dokument może być zaadresowany w czasie działania formularza w tym celu należy wywołać odpowiedni kod JavaScript.

Przykład kodu obsługującego zdarzenie polegające na naciśnięciu przyciski „Adresuj dokument” przedstawiono poniżej:

Gdzie:

id1 – identyfikator kontrolki zawierającej adres skrytki (może być niewidoczna i związana z polem wyliczalnym);

id2 – identyfikator kontrolki zawierającej nazwę adresata (może być niewidoczna i związana z polem wyliczalnym).

W przypadku nie podania nazwy adresata zostanie ona uzupełniona danymi z profilu podmiotu widniejącego w adresie skrytki. Kluczowym jest wywołanie funkcji setReceiverFromForm().

<body> … … <xf:trigger> <xf:label>Adresuj dokument</xf:label> <xxforms:script ev:event="DOMActivate">

if (parent.setReceiverFromForm) {

var boxValue = ORBEON.xforms.Document.getValue('id1'); var nameValue = ORBEON.xforms.Document.getValue('id2'); parent.setReceiverFromForm(boxValue, nameValue);

} else {

alert('Błąd: brak funkcji adresowania!'); }

</xxforms:script> </xf:trigger> … … </body>


Wersja 1.01

37 / 38

6.2. Zapis dokumentu

Zapis dokumentu do bazy danych nie musi być implementowany w formularzu środowisko uruchomieniowe automatycznie doda element XForms „submission” odpowiedzialny za tę operację. Należy pamiętać, że:

Pierwszy model danych powinien się nazywać „main-model”;

Zapisowi podlega instancja danych o identyfikatorze „main”, powinna być to pierwsza instancja danych pierwszego modelu;

Submisja jest typu replace=”instance” i treść dokumentu po zapisie trafi z powrotem do instancji danych, z których została pobrana (uzupełniona o elementy dodawane automatycznie poza silnikiem formularza), należy się liczyć z możliwością wyzwolenia zdarzeń xforms-value-changed;

Po wykonaniu submisji wywoływane jest zdarzenie xforms-ready (na potrzeby formularzy utworzonych za pomocą Edytora Formularzy ŚBA), a następnie wywoływane operacje xf:rebuild, xf:recalculate, xf:revalidate, xf:refresh;

Wartość głównego elementu instancji o identyfikatorze „first-load” przyjmuje wartość „No”.


Wersja 1.01

38 / 38

Załączniki

Do opisu Standardu Formularza ePUAP zostały załączone dwa podstawowe pliki stanowiące pomoc przy opracowaniu własnego formularza:

Formularz.xsd – stanowi podstawę weryfikacji instalowanych Formularzy na ePUAP wykonanych w technologii XForms;

Szablon_formularza.xdp – niezbędny przy budowie Formularzy ePUAP w technologii Adobe.

Documents

Standard Formularza ePUAP