Dotyczy wersji: 2025 R2 i powyżej; autor: Kacper Świętek, Lily Adamowicz
Dokumentacja powiązana
Szczegółowy opis akcji, za pomocą których można nanosić na dokumenty podpisy cyfrowe oraz je weryfikować, znajduje się w następujących sekcjach Pomocy WEBCON BPS:
Wpis stanowi rozszerzenie do artykułu Podpisywanie dokumentu usługą Autenti.
Wprowadzenie
W WEBCON BPS obsługa podpisów cyfrowych została zrealizowana za pomocą dedykowanych akcji opartych na Software Development Kit (SDK). Mechanizm ten umożliwia bezpieczne i płynne realizowanie operacji związanych z podpisywaniem dokumentów. Obecnie dostępne są dodatki integracyjne, które umożliwiają współpracę z następującymi zewnętrznymi dostawcami usług podpisu elektronicznego:
Ten artykuł dotyczy integracji z platformą Autenti. Przedstawiono w nim proces podpisywania dokumentów oraz konfigurację przykładowego obiegu, który obejmuje wysłanie dokumentu do podpisu, a następnie pobranie już podpisanego dokumentu.
Wymogi licencyjne
Aby skorzystać z integracji WEBCON BPS z Autenti, należy zakupić odpowiednia licencję integracyjną. Szczegółowe informacje na ten temat można uzyskać bezpośrednio od przedstawiciela Autenti. Komunikacja z platformą Autenti odbywa się za pomocą konta systemowego, z którego wysyłane są dokumenty do podpisu. Osoby podpisujące dokumenty nie muszą posiadać konta w Autenti ani licencji do WEBCON BPS.
Opis procesu
Platforma Autenti udostępnia różne sposoby operowania procesowanymi dokumentami. Są to m.in.:
- tworzenie dokumentu w systemie,
- ładowanie pliku z dokumentem do podpisu,
- sprawdzanie statusu dokumentu,
- wysyłanie e-maila z linkiem do podpisu dokumentu,
- dwuetapowa weryfikacja przy pomocy wiadomości SMS.
Funkcjonalności te umożliwiają realizację poniższego schematu komunikacji (obiegu):
Rys. 1. Schemat działania obiegu
W procesie zdefiniowano dwie akcje:
- wysłanie dokumentu do Autenti,
- wysłanie żądania o zwrot dokumentu wraz ze statusem.
Zastosowano również mechanizm Timera, który automatycznie co godzinę próbuje uruchomić ścieżkę odpowiedzialną za sprawdzenie statusu podpisu dokumentu w Autenti.
Przypadek biznesowy
Na potrzeby prezentacji wykorzystany zostanie uproszczony obieg dokumentu, który obejmuje kilka podstawowych etapów: przygotowanie dokumentu, zaakceptowanie przez menedżera oraz podpisanie dokumentu przez osoby zewnętrzne. Proces rozpoczyna się od kroku Przygotowanie dokumentu, w którym generowany jest szablon dokumentu. Następnie dokument trafia do Akceptacji menedżera, gdzie może zostać zaakceptowany lub odrzucony. Po zatwierdzeniu, dokument przechodzi do kroku Oczekiwanie na podpisy, a system cyklicznie (co godzinę) uruchamia ścieżkę Sprawdź status, weryfikując, czy dokument został podpisany w Autenti. Kiedy podpisy zostaną już złożone, obieg kończy się na kroku Zatwierdzony.
Rys. 2. Obieg podpisu
Na formularzu zdefiniowano atrybuty niezbędne do wywołania akcji podpisu:
Rys. 3. Formularz obiegu podpisu
Lista Osoby podpisujące służy do wskazania wszystkich uczestników procesu podpisywania dokumentu oraz do przypisania im odpowiednich ról i ustawień związanych z autoryzacją. Każdy wiersz na liście odpowiada jednej osobie biorącej udział w procesie.
W kolumnie Osoba (typ atrybutu: Osoba lub grupa) należy wybrać konkretnego użytkownika. Na podstawie wybranej osoby system automatycznie uzupełni adres e-mail, na który zostanie wysłane zaproszenie do podpisania dokumentu.
W kolumnie Rola (typ atrybutu: Pole wyboru) należy wskazać sposób uczestnictwa danego użytkownika w procesie podpisywania. Do wyboru są następujące role zgodne z wymaganiami Autenti:
Rys. 4. Konfiguracja pola wyboru
- SENDER – osoba wysyłająca dokument,
- SIGNER – osoba podpisująca dokument,
- APPROVER – osoba zatwierdzająca dokument (bez składania podpisu),
- REVIEWER – osoba przeglądająca dokument z możliwością komentowania,
- VIEWER – osoba z dostępem wyłącznie do podglądu dokumentu.
W kolumnie Telefon (typ atrybutu: Pojedynczy wiersz tekstu) należy podać numer telefonu osoby podpisującej. Atrybut ten jest wymagany, jeżeli zaznaczono opcję związaną z uwierzytelnianiem poprzez SMS.
W kolumnie Typ podpisu (typ atrybutu: Pole wyboru) należy wskazać wybraną formę podpisu:
- ESIGNATURE – standardowy podpis elektroniczny,
- QUALIFIED_ESIGNATURE – kwalifikowany podpis elektroniczny.
Dodatkowo dostępne są do wyboru dwa pola:
- Uwierzytelnianie SMS – zaznaczenie tej opcji powoduje, że przed złożeniem podpisu użytkownik musi wpisać kod SMS przesłany na wskazany numer telefonu.
- Odblokuj dokument za pomocą SMS-a – po zaznaczeniu tej opcji dokument będzie zaszyfrowany i użytkownik zobaczy jego treść dopiero po wpisaniu kodu SMS.
Należy także dodać jedno techniczne pole tekstowe Document ID from Autenti, które będzie kluczowe dla dalszego przebiegu procesu. Pole to przechowuje identyfikator (GUID) dokumentu nadany przez system Autenti po jego poprawnym zapisaniu w bazie tej platformy.
Zgodnie z dokumentacją Autenti REST API należy upewnić się, że system Autenti zwrócił poprawny identyfikator GUID. Brak tego identyfikatora oznacza, że dokument nie został prawidłowo zarejestrowany, a pole techniczne pozostanie puste. Taka sytuacja wskazuje na problem po stronie integracji i uniemożliwia prawidłowe kontynuowanie procesu podpisywania.
Konfigurację integracji należy rozpocząć od ustawienia połączenia REST z REST API Autenti, aby możliwe było przesyłanie dokumentów do podpisu w formacie PDF.
Rys. 5. Konfiguracja połączenia z API
Należy utworzyć nowe połączenie typu REST Web Service i ustawić typ uwierzytelnienia na Salesforce. Następnie w konfiguracji połączenia należy uzupełnić poniższe dane zgodnie ze zrzutem ekranu:
- Użytkownik – adres e-mail powiązany z kontem Autenti wykorzystanym przy integracji,
- Hasło – hasło do konta Autenti,
- Client ID – wartość uzyskana z Autenti,
- Client Secret – tajny klucz API dostarczony przez Autenti,
- URL serwisu autoryzującego – https://api.accept.autenti.net/api/v2/auth/token,
- URL bazowej instancji serwisu – https://api.accept.autenti.net/api/v2.
Powyższe adresy URL są aktualne na dzień 17.04.2025 i mogą ulec zmianie w przyszłych wersjach platformy Autenti. W związku z tym przed konfiguracją zaleca się ich weryfikację w oficjalnej dokumentacji.
Kolejnym etapem procesu jest konfiguracja akcji wysyłania dokumentu do podpisu. W opisywanym przykładzie akcja została dodana w kroku Akceptacja menedżera. Na ścieżce Approve należy dodać automatyzację, wewnątrz której umieszczona zostanie odpowiednia akcja SDK.
Rys. 6. Podgląd akcji wysłania dokumentu
Rys. 7. Konfiguracja akcji wysłania dokumentu
Poniżej przedstawiono konfigurację poszczególnych sekcji akcji:
Rys. 8. Wybór załącznika
SELECT
ATT_ID
FROM WFDataAttachmets
WHERE
ATT_WFDID = {WFD_ID}
AND dbo.ClearWFElemID(ATT_Attribute1) = 1
AND ATT_IsDeleted = 0
W tym polu należy zdefiniować zapytanie SQL do tabeli WFDataAttachmets, które zwraca identyfikator załącznika przeznaczonego do podpisu. Na potrzeby scenariusza zapytanie zostało ograniczone do aktualnego elementu i zawężone do załączników z kategorii To be signed, które nie zostały usunięte.
Rys. 9. Konfiguracja uwierzytelniania
W sekcji Authenticate należy wybrać wcześniej utworzone połączenie, a następnie ustawić parametr grant_type na uwierzytelnianie hasłem. Kolejnym krokiem jest określenie wartości scope, czyli zakresu uprawnień przyznanych aplikacji. W przykładowej konfiguracji należy ustawić scope na full.
Rys. 10. Konfiguracja zapytania
Poniżej należy zdefiniować kluczowe elementy w sekcji Request body, które określają dane przesyłane do usługi podpisu elektronicznego.
- Title i Description
- Należy wskazać pola z tytułem i opisem dokumentu, który ma zostać przesłany do podpisu.
- Informacje te będą widoczne w treści wiadomości e-mail wysyłanej do osób zaproszonych do podpisania dokumentu.
- Users
- Należy wskazać listę pozycji zawierającą dane osób, które będą podpisywać dokument. Kolumny listy pozycji zostały omówione we wcześniejszej części artykułu. Wypełnienie pól oznaczonych gwiazdką jest obowiązkowe.
- Participation priority
- Pole jest obowiązkowe w przypadku, gdy na liście pozycji Osoby podpisujące przynajmniej jeden wiersz będzie zawierać rolę Approver.
Ostatnia sekcja w konfiguracji akcji SDK to Konfiguracja dodatku, w której ustawienia akcji są powiązane z obiegiem oraz logiką systemu.
Rys. 11. Konfiguracja dodatku
{
"classifiers" : [ "CHALLENGE_CLASSIFIER-UNIQUE_TYPE:ACTION_SELECTION" ],
"attributes" : {
"selectedIds" : ["EVENT_CLASSIFIER-UNIQUE_TYPE:DOCUMENT_SENT"]
}
}
W polu HEADER X-ASSERTION wklejana jest konfiguracja udostępniona po wybraniu pomocy kontekstowej. Z kolei w polu Returned id of document należy wskazać utworzone przez użytkownika pole techniczne, w którym będzie przechowywane zewnętrzne ID dokumentu.
Po skonfigurowaniu akcji można przejść do BPS Portal i przetestować działanie rozwiązania. W tym celu należy utworzyć nowy element, uzupełnić listę osób podpisujących, a następnie przejść ścieżką do kroku Akceptacja menedżera.
Rys. 12. Okno formularza w kroku Przygotowanie dokumentu
Po zatwierdzeniu przez przełożonego dokument zostaje wysłany do podpisu osobom wskazanym na liście pozycji Osoby podpisujące. Osoby te otrzymają następującą wiadomość e-mail:
Rys. 13. Treść e-maila od firmy Autenti
Przycisk Zobacz i podpisz dokument jest jednocześnie hiperłączem prowadzącym do dokumentu przygotowanego do podpisu. Po kliknięciu następuje przekierowanie na stronę autoryzacyjną, gdzie należy wprowadzić kod wysłany za pomocą wiadomości SMS w celu odblokowania dokumentu. Jeżeli opcja Odblokuj dokument za pomocą SMS-a nie została zaznaczona, to dokument do podpisu zostanie wyświetlony natychmiast, z pominięciem kroku autoryzacji.
Rys. 14. Dokument zabezpieczony kodem SMS
Po prawidłowym wprowadzeniu kodu SMS wyświetli się dokument do podpisu wraz z najważniejszymi informacjami. Po zapoznaniu się z treścią dokumentu należy wybrać przycisk Dalej.
Rys. 15. Dokument do podpisu
Po kliknięciu w hiperłącze wyświetlany jest monit z prośbą o potwierdzenie złożenia podpisu poprzez wprowadzenie jednorazowego kodu wysłanego na numer telefonu. Podanie jednorazowego kodu jest wymagane, ponieważ podczas rejestracji elementu w Portalu dla tego użytkownika zaznaczono opcję dodatkowego uwierzytelniania SMS.
Jeśli ta opcja nie zostanie zaznaczona, podpisanie dokumentu nie będzie wymagało dodatkowego potwierdzenia – wystarczy kliknięcie przycisku Podpisz, aby zakończyć proces podpisywania.
Rys. 16. Dokument – potwierdzenie złożenia podpisu
Po wprowadzeniu kodu system wyświetli informację o podpisaniu dokumentu:
Rys. 17. Ekran podpisanego dokumentu
Do wszystkich osób znajdujących się na liście podpisujących zostanie wysłane potwierdzenie o zakończeniu podpisywania dokumentu wraz z kopią podpisanej umowy.
Rys. 18. E-mail zwrotny
Jeżeli dokument podpisano poprawnie, dołączony zostanie do niego certyfikat i pieczęć, które zaświadczają o autentyczności podpisu.
Rys. 19. Certyfikat podpisu firmy Autenti
Podczas podpisywania dokumentu w Autenti element znajduje się na etapie kroku Oczekiwanie na podpisy. W tym czasie dokument pozostaje w systemie Autenti, a jego status nie jest automatycznie aktualizowany w WEBCON BPS. Aby zakończyć proces, konieczne jest skonfigurowanie akcji, która sprawdzi status podpisu i pobierze dokument w chwili zmiany statusu na COMPLETED. Automatyzację tę należy dodać na ścieżce Sprawdź status.
Rys. 20. Podgląd akcji pobierania dokumentu
Ustawienia w sekcji Authenticate są analogiczne, jak w przypadku akcji wysyłania dokumentu. W polu Returned id of document należy podać identyfikator, który zostanie zwrócony po pobraniu dokumentu.
Rys. 21. Konfiguracja akcji pobrania dokumentu
W polu Copy Status to field należy wskazać atrybut, do którego zostanie zapisany status pobranego pliku. Natomiast w polu Category określa się kategorię przeznaczoną dla pobranego dokumentu (w opisywanym przypadku będzie to Signed).
Kolejnym etapem procesu jest konfiguracja kroku warunkowego Czy podpisano?, do którego prowadzi ścieżka Sprawdź status.
Rys. 22. Konfiguracja kroku warunkowego Czy podpisano?
Jeśli w efekcie akcji pobrania dokumentu w atrybut Document status from Autenti zostanie wpisana wartość COMPLETED, to element zostanie przekazany do kroku końcowego. W przeciwnym przypadku element powróci do kroku Oczekiwanie na podpisy. System może zwrócić różne statusy:
- PROCESSING – nie podjęto jeszcze wszystkich decyzji,
- COMPLETED– wszyscy podpisali dokument,
- REJECTED – co najmniej jedna osoba odmówiła podpisu.
W kroku Oczekiwanie na podpisy wymagana jest również konfiguracja funkcji Timera, która co godzinę sprawdza, czy dokument został już podpisany.
Rys. 23. Konfiguracja funkcji Timera
Tryb działania należy ustawić na Przejście ścieżką po wywołaniu akcji. Jeżeli nie zdefiniowano akcji do wykonania, Timer będzie co godzinę próbować przepuścić dokument do następnego kroku.
Po poprawnym wykonaniu akcji w polu Status podpisu z Autenti pojawia się wartość COMPLETED, co oznacza, że proces podpisu został zakończony powodzeniem, tzn. wszystkie osoby podpisały dokument. W efekcie element zostaje przekazany do kroku końcowego, a w kategorii Podpisano pojawia się podpisany dokument.
Rys. 24. Element na kroku końcowym
Podsumowanie
Przedstawiony powyżej obieg stanowi jedynie przykładowe zastosowanie dodatku WEBCON BPS do integracji z Autenti.
Kod źródłowy wszystkich dodatków znajduje się na oficjalnym koncie GitHub: https://github.com/WEBCON-BPS i jest udostępniany na licencji MIT License.