Integracja systemu e-Doręczenia z platformą WEBCON BPS na potrzeby obsługi procesu „Korespondencja przychodząca”

WEBCON Redaktor Bez kategorii
Facebooktwitterpinterestlinkedinmail
Dotyczy wersji: 2023.1.1 i powyżej, autor: Michał Puchalski

 

Wprowadzenie

e-Doręczenia to cyfrowy odpowiednik listu poleconego z potwierdzeniem odbioru. Usługa ta umożliwia instytucjom publicznym, obywatelom i firmom korzystanie z wygodnych i bezpiecznych doręczeń elektronicznych, które mają taką samą moc prawną, jak tradycyjne przesyłki polecone z potwierdzeniem odbioru. W procesie biorą udział trzy strony: nadawca, odbiorca i Operator Wyznaczony, tj. podmiot, który odpowiada za realizację usług e-Doręczeń. Gdy nadawca wysyła wiadomość za pośrednictwem systemu  e-Doręczeń, odbiorca otrzymuje powiadomienie o nowej wiadomości od Operatora Wyznaczonego. Operator Wyznaczony jednocześnie dostarcza nadawcy dowód wysłania wiadomości. Po odczytaniu wiadomości przez odbiorcę Operator Wyznaczony przekazuje nadawcy dowód jej odebrania.

W ramach powyższego tematu przygotowaliśmy dwa artykuły prezentujące możliwy sposób integracji pomiędzy platformą WEBCON BPS a systemem e-Doręczeń. Pierwszy artykuł opisuje konfigurację procesu „Korespondencja Przychodząca”, natomiast drugi – konfigurację procesu „Korespondencja Wychodząca” (link do artykułu: XYZ). Rozwiązanie to umożliwi zarządzanie całą korespondencją w ramach jednej platformy. W tym celu konieczne jest przygotowanie kilku dodatków SDK, rozbudowanie konfiguracji o wymagane atrybuty oraz spełnienie kilku wymagań:

  • posiadanie platformy WEBCON BPS w wersji min. 2023;
  • złożenie wniosku przez Klienta o ADE (Adres do e-Doręczeń);
  • rejestracja systemu w skrzynce e-Doręczeń przy użyciu certyfikatu pozwalającego na integrację systemu.
    Certyfikat musi być kwalifikowany, a jego wydawca znajdować się na liście NC Certu (https://www.nccert.pl/tsl/PL_TSL.xml) https://www.nccert.pl/tsl/PL_TSL.xml). Dodatkowo musi on przejść walidację za pomocą narzędzia udostępnionego przez Komisję Europejską, które jest dostępne pod adresem: https://ec.europa.eu/digital-building-blocks/DSS/webapp-demo/certificate-validation.
  • Zalecane jest użycie usługi Azure Key Vault do przechowywania klucza. W przypadku obsługi wielu spółek – niezależnie od wersji BPS – usługa Azure Key Vault będzie wymagana.

Na potrzeby artykułu utworzono prosty proces obsługi korespondencji przychodzącej. W ramach jego założeń korespondencja dotychczasowo rejestrowana była ręcznie w systemie WEBCON BPS. W tym celu po odebraniu listu przez kancelarię konieczne było ręczne uzupełnienie przez nią formularza, zeskanowanie dokumentu i przyporządkowanie odbiorcy. Proces pozwalał potwierdzić odbiór korespondencji, po czym była ona przekazywana do Archiwum.

 

Rys. 1. Obieg „Korespondencja przychodząca”

 

W ramach integracji z systemem e-Doręczeń aplikacja będzie regularnie sprawdzała firmową „skrzynkę”, a następnie pobierze nowe wiadomości.

 

Konfiguracja

Modyfikację należy rozpocząć od utworzenia atrybutów, które będą wykorzystywane w rozszerzeniu e-Doręczeń. Utwórz pola, do których po pobraniu wiadomości przepisany zostanie  jej temat i treść.

 

Rys. 2. Widok fragmentu formularza startowego z danymi podstawowymi

 

W sekcji Szczegóły odbioru do słownika z formami doręczenia dodaj nową wartość e-Doręczenia oraz pola wskazujące daty nadania i otrzymania wiadomości.

 

Rys. 3. Widok fragmentu formularza startowego ze szczegółami odbioru

 

Utwórz nową grupę atrybutów zawierającą podstawowe informacje o nadawcy pobrane z systemu e-doręczeń, takie jak nazwa firmy, adres, czy adres skrzynki e-Doręczeń.

 

Rys. 4. Widok fragmentu formularza startowego z danymi wysyłki

 

Ponadto należy uwzględnić atrybuty techniczne. Zostaną one użyte w systemie e-Doręczeń do jednoznacznej identyfikacji i śledzenia wiadomości oraz ich powiązań, sygnalizowania problemów, a także wspierania użytkowników w nawigowaniu i zarządzaniu wiadomościami w interfejsie aplikacji. Dodaj pola pomagające w identyfikacji wiadomości, jak pokazano na poniższym rysunku. Należy zwrócić uwagę na atrybut „_IDwiadomościPicker”, który jest polem wyboru mającym na celu uzyskanie ID wiadomości w formacie ID#ID. Jako źródło danych zastosowano stałe wartości z pustymi wpisami.

 

Rys. 5. Atrybuty techniczne zawierające podstawowe dane niezbędne do identyfikacji

 

Rys. 6. Przykładowe źródło danych dla atrybutu technicznego „IDwiadomościPicker”

 

Następnie dodaj trzy listy pozycji. Pierwsza wyświetla informacje o ewentualnych błędach, które wystąpiły podczas pobierania wiadomości, druga uwzględnia dane o wszystkich załącznikach dołączonych do wiadomości, a trzecia przechowuje informacje o dowodach związanych z wiadomością, takich jak potwierdzenia doręczenia, odczytu i wysłania.

 

Rys. 7.  Atrybuty techniczne „Lista błędów”, „Lista załączników” i „Lista dowodów”

 

Poniżej znajduje się pełny widok formularza z zaznaczonymi wcześniej wspomnianymi atrybutami.

 

Rys. 8. Formularz wejściowy

 

Kolejnym krokiem w konfiguracji jest zdefiniowane odpowiednich źródeł danych.

Pierwsze źródło odpowiada za integrację aplikacji z system e-Doręczeń. W zakładce Źródła danych skonfiguruj połączenie REST Web Service:

  • nazwa: [eDoręczenia] Agent;
  • URL serwisu autoryzującego: https://int-ow.edoreczenia.gov.pl;
  • URL bazowej instancji serwisu: https://uaapi-int-ow.poczta-polska.pl;
  • Client Secret: w przypadku jednej spółki w wersjach BPS 2023 i 2024 można wkleić wielowierszowy klucz uzyskany w procesie rejestracji systemu. Zaleca się przechowywanie klucza w usłudze Azure Key Vault. Natomiast w przypadku wielu spółek – niezależnie od wersji BPS – usługa Azure Key Vault będzie niezbędna. Klucz zostanie pobrany poprzez dodatki, a w dalszej części artykułu zaprezentowana zostanie konfiguracja.

 

Rys. 9. Konfiguracja źródła danych skrzynki e-Doręczeń w wersjach BPS 2023 i 2024

 

Drugie źródło danych stosowane do synchronizacji wiadomości należy utworzyć w źródłach BPS. Nadaj swoją nazwę, a w konfiguracji wybierz proces „Korespondencja przychodząca” z wszystkimi dostępnymi krokami. Następnie dodaj kolumny „ID”, „Sygnatura”, „_IDwiadomości”
 i „_IDspółki”.

 

Rys. 10. Dodawanie źródła danych BPS

 

Źródło powinno zwracać dane z ograniczonego przedziału czasu, np. z ostatniego miesiąca. Za pomocą filtra SQL można ograniczyć wyniki, aby synchronizowane były wyłącznie wiadomości z wybranego okresu.

 

Rys. 11. Zastosowanie filtra SQL w celu określenia przedziału czasu

 

W przypadku wielu spółek konieczne jest zastosowanie trzeciego źródła do mapowania ID spółki na adres skrzynki e-Doręczeń. Źródło powinno zwracać w pierwszej kolumnie ID spółki, a w drugiej adres skrzynki e-Doręczeń. W poniższym przykładzie zastosowano typ źródła MSSQL, który odczytuje wartości ze słownika.

 

Rys. 12.  Źródło danych do mapowania ID spółki na adres skrzynki e-Doręczeń

 

Zaleca się zwrócenie uwagi na nazwę pierwszej kolumny, aby była zgodna ze zmienną wprowadzoną w konfiguracji dodatku, który zostanie omówiony w dalszej części artykułu.

 

Rys. 13. Nazwa kolumny z ID spółki w maperze

 

W celu konfiguracji rozszerzenia przygotowano paczkę dodatków SDK (istnieje możliwość ich zamówienia):

  • SyncMessages – synchronizuje wiadomości ze skrzynką e-Doręczeń i pobiera dane do tabeli TemporaryEntities;
  • StartDocumentsForMessages ­– uruchamia ścieżkę startową na podstawie wpisów w tabeli TemporaryEntities;
  • GetMessage – pobiera wiadomość ze skrzynki e-Doręczeń;
  • GetAttachments – pobiera załączniki wiadomości ze skrzynki e-Doręczeń;
  • GetEvidences – pobiera wszystkie dowody dotyczące wiadomości ze skrzynki e-Doręczeń;
  • DeleteMessage – usuwa wiadomość ze skrzynki e-Doręczeń.

Pierwszym etapem konfiguracji akcji SDK jest przygotowanie dodatku do synchronizacji danych ze skrzynką e-Doręczeń. W globalnej konfiguracji procesu dodaj cykl, w ramach którego wstawiona zostanie akcja dodatku SDK SyncMessages. W ustawieniach akcji cyklicznej określ nazwę, interwał czasowy, liczbę dopuszczalnych prób oraz datę pierwszego uruchomienia. Natomiast w akcji dodatku SDK uzupełnij nazwę i wybierz odpowiedni dodatek.

 

Rys. 14. Tworzenie cyklicznej akcji z wykorzystaniem dodatku SDK

 

W konfiguracji należy uzupełnić poszczególne sekcje:

  1. a) Konfiguracja połączenia – ustaw połączenie dodatków SDK ze skrzynką e-Doręczeń. Wszystkie akcje będą mieć taką samą konfigurację połączenia;
  • Połączenie do serwisu – wybierz utworzone wcześniej połączenie z serwisem e-Doręczenia – w omawianym przypadku jest to „[eDORECZENIA] Agent”;
  • Identyfikator systemu – nadany podczas rejestracji systemu w e-Doręczeniach;
  • Źródło adresów – wybierz utworzone wcześniej źródło, które służy do mapowania ID spółki na adres skrzynki e-Doręczeń;
  • Opcjonalne połączenia do Azure Key Vault – połączenie używane do pobrania klucza prywatnego z AKV;
  • Nazwa wpisu tajnego – wymagane przy użyciu Azure Key Vault;
  • Reużywaj klucza – po pierwszym pobraniu klucz będzie przechowywany w pamięci. Włączenie tej opcji ogranicza liczbę pobrań klucza z Azure Key Vault;
  • Czas ważności tokena – czas ważności tokena w sekundach, na INT i PROD: 300 s;

 

Rys. 15. Konfiguracja połączenia

 

  1. b) Konfiguracja synchronizacji
  • Data pierwszej synchronizacji – data, od której mają być synchronizowane wiadomości podczas pierwszego uruchomienia. Jeśli nie zostanie podana, zostanie użyta bieżąca data. Można wprowadzić datę wcześniejszą, aby zsynchronizować zaległe wiadomości. W przypadku błędu synchronizacji, np. z powodu wygaśnięcia certyfikatu, i potrzeby pobrania zaległych wiadomości warto wyczyścić tabele SDKTemporaryEntities;
  • Maksymalny czas wykonania – maksymalny czas wykonania akcji w sekundach.

 

Rys. 16. Konfiguracja synchronizacji w „SyncMessages”

 

Dodaj osobną akcję cykliczną, która będzie uruchamiać ścieżkę startową pobierającą zsynchronizowane wiadomości. Skorzystaj z dodatku SDK StartDocumentsForMessages. Poniżej objaśniono istotne elementy w konfiguracji.

 

Rys. 17. Cykliczna akcja uruchamiająca pobieranie wiadomości

 

  1. Konfiguracja synchronizacji
  • Źródło z pobranymi wiadomościami – źródło zwracające dwie kolumny, pierwsza z ID wiadomości e-Doręczenia i druga z ID spółki. Powinno ono zwracać dane z ograniczonego przedziału czasu, np. z ostatniego miesiąca. Wybierz wcześniej utworzone źródło „{eDOR} Źródło do Sync”;
  • Nazwa kolumny z id wiadomości – z atrybutów formularza wybierz nazwę pola w bazie „_Idwiadomości”;
  • Nazwa kolumny z id spółki – z atrybutów formularza wybierz nazwę pola w bazie „_Idspółki”.

 

Rys. 18. Konfiguracja synchronizacji w „StartDocumentsForMessages”

 

  1. Konfiguracja startowania dokumentu
    • ID ścieżki startowej – wybierz ścieżkę „_NoweEdoręczenie”, na której znajdują się dodatki pobierające wiadomość, załączniki i dowody. (Opisano w dalszej części artykułu);
    • ID pola na ID wiadomości – w tym polu dodatek zapisuje ID wiadomości pobranej ze skrzynki e-Doręczeń. Z atrybutów formularza wskaż to pole, które wybrano powyżej w konfiguracji synchronizacji, przy czym tym razem użyj kolumny ID „_IDwiadomości”;
    • ID pola na ręczne ID spółki – w tym polu dodatek zapisuje ID spółki na podstawie tabeli ID spółki i adresu ADE. Spośród atrybutów formularza wybierz to samo pole, które zostało użyte wcześniej w konfiguracji synchronizacji, ale tym razem wskaż kolumnę ID „_IDspółki”.

 

Rys. 19. Konfiguracja startowania dokumentu w „StartDocumentsForMessages”

 

Przed konfiguracją kolejnych dodatków SDK, dodaj nową ścieżkę przejścia, która pobierze wiadomości, załączniki i dowody ze skrzynki e-Doręczeń. Przykładowo nazwij ją „_NoweEdoręczenie”. Tworzenie zadania przypisz opiekunom aplikacji. Po dodaniu nowej ścieżki należy również dodać odpowiednie akcje, które obsłużą te operacje, takie jak pobieranie wiadomości, przetwarzanie załączników oraz weryfikacja dowodów.

 

Rys. 20.  Ścieżka przejścia, która pobiera wiadomości ze skrzynki e-Doręczeń

 

Opis każdej akcji zaprezentowano poniżej.

  • ID wiadomości picker dla SDK – akcja zmienia wartość pola „_IDwiadomościPicker” (używanego w dodatku GetMessage) na wartość z pola „_IDwiadomości”.

 

Rys. 21. Konfiguracja akcji zmień wartość pola „_IDwiadomościPicker”

 

  • Forma dostarczenia – akcja zmienia wartość pola „Forma dostarczenia” na wartość „e-Doręczenie”.

 

Rys. 22. Konfiguracja akcji zmień wartość pola „Forma dostarczenia”

 

  • Pobieranie wiadomości e-Doręczenie – akcja, która pobiera wiadomość ze skrzynki e-Doręczeń, korzystając z dodatku SDK

W sekcji Konfiguracja połączenia należy wpisać te same dane, które wstawiono w poprzednich dodatkach SDK. Na samej górze znajduje się dodatkowe pole Identyfikator spółki, na podstawie którego zostanie dopasowany adres skrzynki e-Doręczeń. O tej zmiennej wspomniano już wcześniej – musi ona pasować do nazwy pierwszej kolumny tabeli Źródło adresów.

 

Rys. 23. Konfiguracja połączenia w dodatku GetMessage

 

W sekcji Konfiguracja odpowiedzi należy wskazać miejsca do zapisywania informacji o załącznikach oraz błędach.

 

Rys. 24. Konfiguracja odpowiedzi w dodatku GetMessage

 

Następnie przypisz atrybuty do pól z podstawowymi informacjami wiadomości zgodnie z poniższą instrukcją, aby dane te zostały uzupełnione po pobraniu wiadomości. Na końcu w sekcji Konfiguracja dodatku uzupełnij Pole z identyfikatorem wiadomości tym samym atrybutem, który został zastosowany w pierwszej akcji na obecnej ścieżce.

 

Rys. 25. Konfiguracja odpowiedzi w pobieraniu wiadomości ze skrzynki e-Doręczeń cd.

 

Na ścieżce dodaj warunek „Czy są załączniki do pobrania?”

 

Rys. 26. Akcja „Pobieranie załączników z e-Doręczeń” na ścieżce

 

Rys. 27. Warunek „Czy są załączniki do pobrania?”

 

  • Pobieranie załączników z e-Doręczeń – akcja, która pobiera załączniki wiadomości za pomocą dodatku GetAttachments. Załączniki są pobierane na podstawie zapisanych informacji w polu listy załączników. W konfiguracji akcji uzupełnij pole ID kategorii załączników identyfikatorem kategorii do której zostaną przypisane pobrane załączniki.

 

Rys. 28. Fragment konfiguracji dodatku GetAttachments

 

  • {e-Doręczenia} Pobieranie dowodów – akcja, która pobiera dowody wiadomości za pomocą dodatku GetEvidences.

Sekcje Konfiguracja połączenia i  Konfiguracja dodatku uzupełnij w taki sam sposób, jak w poprzednich akcjach. W sekcji Konfiguracja pliku możliwe jest przypisanie pobranych dowodów do konkretnej kategorii załączników. Można także pobrać je jako archiwum w formacie ZIP lub jako pojedyncze pliki XML i załadować na formularz.

 

Rys. 29. Konfiguracja pliku w konfiguracji dodatku GetEvidences

 

W sekcji Lista dowodów zaznaczenie pola wyboru przy opcji Pobieraj listę dowodów umożliwi pobranie oddzielnej listy.

 

Rys. 30. Lista dowodów w konfiguracji dodatku GetEvidences

 

  • MessageID – akcja zmienia wartość pola „_IDwiadomości” na wartość z pola „_IDwiadomościPicker”.

 

Rys. 31. Konfiguracja akcji zmień wartość pola „_IDwiadomości”

 

  • Kontrahent – akcja uzupełnia pole „Kontrahent” na podstawie numeru NIP pobranego z wiadomości w systemie e-Doręczeń.

 

Rys. 32.  Konfiguracja akcji zmień wartość pola „Kontrahent”

 

  • Spółka – w przypadku wielu spółek można dodać akcję, która automatycznie uzupełni pole odpowiednią wartością spółki.

 

Rys. 33.  Konfiguracja akcji zmień wartość pola „Spółka”

 

Opisaną powyżej ścieżkę „_NoweEdoręczenie” można traktować jako techniczną (nie musi być ona widoczna dla użytkownika). System uruchomi ją automatycznie, pod warunkiem że konto serwisowe posiada odpowiednie uprawnienia – szczególnie na poziomie danego obiegu.

 

Rys. 34. Nadanie uprawnień uruchomienia elementu dla konta serwisowego

 

W końcowym kroku, gdzie archiwizowane są pobrane wiadomości, można dodać przycisk z akcją umożliwiającą usuwanie wiadomości ze skrzynki e-Doręczeń, aby zapobiec jej zapełnieniu. Do utworzenia tej akcji użyj dodatku SDK DeleteMessage, uzupełniając sekcje Konfiguracja połączenia i sekcje Konfiguracja dodatku analogicznie jak we wcześniejszych akcjach SDK.

 

Rys. 35. Przycisk menu do usuwania wiadomości ze skrzynki e-Doręczeń

 

Na koniec warto opisać, w jaki sposób korzystać z aplikacji. Po wykryciu przez akcję cykliczną nowej wiadomości w skrzynce e-Doręczeń system uruchamia ścieżkę do pobierania wiadomości, załączników oraz dowodów. Odbiorca wiadomości znajdzie odpowiednio wypełniony formularz na liście swoich zadań lub w raporcie korespondencji przychodzącej.

Poniżej zaprezentowano widok wspomnianego formularza. Po lewej stronie uzupełnione są pola „Temat” i „Treść”. Po prawej stronie w zakładce Dane z e-Doręczenia znajduje się pole „ADE Nadawcy”. W szczegółach odbioru uzupełnione jest również pole „Data nadania”. Proces można kontynuować jak w przypadku standardowej korespondencji, uzupełniając sprawę, przypisując właściciela i przekazując dokument do wybranej osoby.

 

Rys. 36. Formularz wejściowy wyświetlany po wykonaniu akcji cyklicznej pobierania wiadomości ze skrzynki e-Doręczeń

 

Podsumowanie

System e-Doręczenia umożliwia użytkownikom bezpieczne odbieranie wiadomości elektronicznych. Powyżej opisany proces zapewnia bezpieczne, przejrzyste i efektywne zarządzanie komunikacją elektroniczną, umożliwiając użytkownikom łatwe odbieranie i przeglądanie wiadomości oraz ich załączników, a także zarządzanie nimi.