Dotyczy wersji: 2020.1.x i wyższych; autor: Marcin Wołosz
Wersja WEBCON BPS 2019 wprowadziła możliwość korzystania z technologii REST przy tworzeniu rozwiązań integracji programistycznej z systemem. REST API zapewnia pełne wsparcie i możliwość startowania nowych elementów obiegu, przejścia ścieżkami oraz modyfikacji zawartości elementu.
W wersji 2020 dostępne jest API w wersji 2.0, którego użyjemy w poniższych przykładach.
Autentykacja
API korzysta z autentykacji bearer token. W celu uzyskania tokenu, konieczne jest zarejestrowanie aplikacji w panelu administratora, dostępnym tylko dla administratorów domyślnej bazy zawartości. Panel dostępny jest pod adresem: [adres_portalu]/adminPanel
Zarejestrowanie aplikacji wygeneruje dwie informacje: ClientID oraz ClientSecret, które są konieczne do uzyskania wcześniej wspomnianego tokenu. Od wersji 2020 możliwe jest utworzenie wielu ClientSecret.
Bardzo ważne jest zapisanie wygenerowanego klucza secret, ponieważ nie jest on przez nas przechowywany i w razie jego utraty, nie będzie mógł zostać odzyskany.
Mamy też możliwość użycia tzw. Impersonacji, która pozwala nam na wywołanie API w kontekście konkretnego użytkownika.
Przed rozpoczęciem testów konieczne jest nadanie uprawnień do startowania procesu dla nowo utworzonej aplikacji. Wykonuje się dokładnie tak samo jak w przypadku zwykłych użytkowników czy grup.
Użycia API
Do testów używać będziemy narzędzie do weryfikacji API – Postman oraz prostego, dwukrokowego procesu, zawierającego kilka standardowych atrybutów i jedną listę pozycji.
Uzyskanie tokenu – /api/login
W postmanie tworzymy pierwszy REQUEST. Będzie to POST do metody LOGIN. Nie jest wymagana żadna autentykacja.
W nagłówku ustawiamy Content-Type na application/json, a w body przesyłamy JSONem wygenerowane wcześniej ClientID oraz ClientSecret
REQUEST:
URL: https://at03.webcon.pl/api/login
Metoda zwróciła token potrzebny do autentykacji w kolejnych metodach.
RESPONSE:
Postman:
Pobranie elementu – /api/data/v2.0/db/{dbId}/elements/{id}
Pobranie elementu wykonujemy za pomocą REQUESTu GET z parametrami {dbID} (baza zawartości) oraz {id} (wfdid elementu).
W tej metodzie musimy użyć tokenu do autentykacji:
W odpowiedzi otrzymujemy informacje o elemencie:
Startowanie elementu – /api/data/v2.0/db/{dbId}/elements
W tym przypadku używamy z tej samej autentykacji co w poprzednim przykładzie. Zmianą jest to, że korzystamy z REQUESTu POST oraz to, że do dajemy wymagany parametr PATH zawierający ścieżkę którą chcemy przejść.
W body konieczne jest przesłanie takich informacji jak ID/Guid obiegu, ID/Guid spółki, ID/Guid typu formularza. Nie jest konieczne przesłanie wszystkich atrybutów (tak jak to miało miejsce w SOAP API). GUIDy atrybutów można wykorzystać z poprzedniego przykładu.
Przykładowy REQUEST:
URL: https://at03.webcon.pl/api/data/v2.0/db/6/elements?path=15
RESPONSE:
Element zarejestrowany przy pomocy REST API:
Update elementu – /api/data/v2.0/db/{dbId}/elements/{id}
Modyfikacja wymaga REQUESTu PATCH. W najprostszej wersji jest to zapis elementu, można opcjonalnie użyć ścieżki którą ma przejść REST API. W body przesyłamy tylko to co chcemy zmodyfikować. Inne wartości nie muszą być wysłane.
REQUEST:
URL: https://at03.webcon.pl/api/data/v2.0/db/6/elements/21
RESPONSE:
Podsumowanie
Powyższe przykłady to tylko część tego na co pozwala nam REST API – zastosowań jest o wiele więcej. Możemy też między innymi:
- pobierać i modyfikować załączniki,
- usuwać elementy,
- pobierać zadania dla użytkowników,
- pobierać informacje o procesach
- i wiele więcej.
Pełna dokumentacja w formie swaggera dostępna jest na [adres_portalu]/api, a w wersji z SP na [adres_portalu]/webconbps/api.
