Informacje wstępne #
Wymiana dokumentów w ramach e-Doręczeń nie jest częścią standardowej instalacji Navigatora365. Razem z systemem dostarczany jest serwis pośredniczący, który pozwala na komunikację poprzez REST API z użyciem standardowych akcji takich jak Call REST Api, Utwórz dokument czy Zmień wartość pola. Projektant systemu sam decyduje w jakiej formie przygotować integrację. Niniejszy artykuł opisuje jeden z możliwych scenariuszy przygotowania takiej integracji.
Opis serwisu znajduje się w osobnym artykule.
Przygotowanie formularzy #
e-Doręczenia dotyczą pism przychodzących i wychodzących zatem najlepiej integrację przeprowadzić w ramach aplikacji Kancelaria. Dlatego założymy że w systemie jest zainstalowana standardowa aplikacja Kancelaria z formularzami Pisma przychodzące oraz Pisma wychodzące. Nasze prace będą polegać na dostosowaniu tych formularzy do potrzeb e-Doręczeń oraz dodaniu elementów pomocnych w integracji takich jak formularz konfiguracyjny czy procesy pobierania i wysyłania dokumentów.
Formularz konfiguracyjny #
W systemie powinno być miejsce gdzie przechowujemy dane konfiguracyjne. Mowa tu o takich danych jak dane firmy, informacje do autoryzacji w serwisach itp.. Może to być formularz konfiguracyjny z aplikacji systemowej (System) udostępniony innym aplikacjom lub dedykowany formularz w aplikacji Kancelaria. Wybór miejsca podpięcia formularza konfiguracyjnego zostawiamy projektantom. My przyjmiemy, że jest on częścią aplikacji Kancelaria. Jeżeli nie masz jeszcze przygotowanego formularza konfiguracyjnego w aplikacji do przetwarzania pism to dobrym pomysłem jest przygotowanie takiego formularza. Poniżej prezentujemy przykład takiego formularza
Formularz pisma #
System e-Doręczeń nie przesyła zbyt wielu informacji więc ewentualna rozbudowa formularza nie jest zbyt pracochłonna. Poniżej prezentujemy przykładową sekcję pól na potrzeby e-Doręczeń.
Większość pól to pola tekstowe które wypełniamy w procesie pobierania wiadomości. Dla procesowania pism istotne są pola ID wątku i ID wiadomości, których będziemy używać przy przygotowaniu odpowiedzi na pisma oraz przy przypisywaniu dokumentu do sprawy. Obok wartości pobieranych z e-Doręczeń mamy pola techniczne takie jak znacznik Przeczytane, data przeczytania czy kontrahent – pole wyliczane na podstawie skrzynki e-Doręczeń nadawcy.
Pobieranie dokumentów #
Wraz z systemem Navigator dostarczany jest serwis pośredniczący który służy do komunikacji z systemem e-Doręczeń. Serwis upraszcza komunikację i dostarcza standardowych metod opartych o REST API oraz format json. Dlatego w procesie użyjemy właśnie tych akcji do pobierania wiadomości. Proces może być uruchamiany ręcznie lub za pomocą harmonogramu, np. co 30 minut.
W procesie definiujemy jedną zmienną – to json w którym będziemy przechowywać zwrócone dane.
Sam proces jest bardzo prosty, składa się z zaledwie kilku akcji.
W pierwszej akcji potrzebujemy pobrać wszystkie dokumenty.
Na przykładzie powyżej widać konfigurację akcji Wywołaj REST API. Jako parametry podajemy skrzynkę adresata oraz daty. Dodatkowym parametrem jest read=false co oznacza że pobieramy same nagłówki wiadomości. Dzięki temu w systemie e-Doręczeń taki dokument jest oznaczony jako nieprzeczytany. To ważne, jeżeli potrzebujemy dotrzymać terminów urzędowych. Wynik zapytania składujemy w zmiennej procesowej.
W przykładzie data podana jest wprost, to dobry pomysł do pierwszego zasilenia systemy ale potem warto gdzieś przechowywać datę ostatniego pobrania dokumentów, np. w dokumencie konfiguracyjnym, i używać tej daty w wywołaniu akcji.
W konfiguracji potrzebne jest jeszcze określenie sposobu autoryzacji. W naszym serwisie użīwamy ApiKey który jest zapisany w dokumencie konfiguracyjnym
Pobrane dokumenty są dostarczane w tablicy json więc do ich dalszej obróbki musimy użyć pętli. Konfiguracja jest prosta, w Źródle danych wskazujemy zmienną json, którą użyliśmy do przechowania zwracanego rezultatu REST API.
Wewnątrz pętli jest standardowa akcja tworzenia dokumentu w której wypełniamy pola danymi z e-Doręczeń. Wybieramy pole na formularzu, wskazujemy pętlę jako źródło danych i wybieramy konkretny klucz z jsona do wstawienia danych.
W systemie, po wywołanie tego procesu pojawią się nowe dokumenty typu Pismo przychodzące.
Odczytanie pisma #
Tak jak opisaliśmy wyżej, użycie warunku read=false powoduje, że pobrane pismo jest niekompletne – nie ma treści ani załączników. W systemie e-Doręczeń jest opisane jako nieprzeczytane czyli nie biegną jeszcze żadne terminu urzędowe. Użytkownik aplikacji Kancelaria może zdecydować, kiedy przeczytać taki dokument. Od strony technicznej możemy to zrobić w ramach procesu obiegu dokumentu lub jako niezależny proces uruchamiany przyciskiem na formularzu. Pierwszy sposób wydaje się lepszy bo jesteśmy w stanie kontrolować terminowość wykonywania czynności oraz raportować dokumenty które zbyt długo nie są przeczytane. Niezależnie od wybranej metody warto zrobić osobny proces do odczytania dokumentu.
Proces składa się tak naprawdę z dwóch kroków. Widoczna na przykładzie bramka jest tylko zabezpieczeniem, by nie wywoływać REST API w sytuacji gdy nie mamy ID wiadomości gdyż spowoduje to wyświetlenie komunikatu błędu.
W pierwszym kroku procesu wywołujemy endpoint serwisu odpowiedzialny za odczytanie wiadomości. Konfiguracja tego endpointu jest analogiczna, jak endpointu do pobierania wiadomości. Jedyne różnica jest taka, że zamiast daty podajemy ID wiadomości, którą chcemy odczytać.
Konfiguracja autentykacji oraz format jsona jest identyczny jak w akcji pobierania wiadomości. W jsonie dostajemy oczywiście tylko jeden dokumentgdyż o ten konkretny dokument odpytujemy serwis jednak struktura pól wewnątrz obiektu jest identyczne. Dlatego nie potrzebujemy tu użyć akcji pętla ale akca uzupełniania pisma wychodzącego jest analogiczna jak tworzenia dokumentu. Możemy użyć tych samych pól w obu akcjach.
Na koniec warto zauważyć, że możemy wielokrotnie odczytywać wiadomość, za każdym razem będzie pobierana treść oraz załączniki dokumentów. System e-Doręczeń odnotuje pierwsze odczytanie jako datę odczytania i od tej daty będą biegły terminy urzędowe.