Nintex zapowiedział tę innowację kilka miesięcy temu podczas koferencji InspireX w Nowym Orelanie (luty tego roku). Podczas swojej prezentacji „Extensibility on the Nintex Workflow Platform” Vadim Tabakam i Brad Orluk, a potem na Blogu Nintex zostały pokazane i opisane pierwsze wrażenia z nowej funkcji.

Aktualnie funkcja dostępna jest wyłącznie w tzw. „Beta preview”. Czym jest? Nintex nazywa to „extensibility framework”. Jest to narzędzie, które pozwala klientom na dodawanie do Nintex Workflow Cloud własnych RESTowych endpointów, które następnie są „zamykane” w gotowe do użycia akcje. Jak to działa?

Nintex Xtensions – podstawy

W 3 krokach:

1. Wgraj plik JSON zawierający definicję, w standardzie Swager, endpointów REST web service’u albo wskaż plik Swagger poprzez podanie do niego adresu URL.
2. Stwórz nowe połączenie („Connection”), jeśli web service wymaga uwierzytelnienia.
3. I już! Teraz możesz używać wszystkich akcji, zbudowanych na podstawie metod opisanych w pliku Swager.

Jak to zrobić, krok po kroku

Chcę zaprezentować teraz jak użyć nowej funkcji. Ten tutorial jest podzielony na dwie sekcje. Pierwsza pokazuje, jak wygenerować plik Swagger, jeśli web service nie posiada takiego. Druga część pokazuje, jak użyć taki plik w Nintex Workflow Cloud. Jeśli chcesz, możesz też od razu przejść na koniec, gdzie pokazane jest działanie Xtension w akcji.

Ostatnia rzecz – na potrzeby prezentacji korzystam z RESTful API portalu Billiving (prosta księgowość dla małych firm).

No to do dzieła.

Co zrobić, gdy nie mam pliku Swagger?

W zasadzie, jeśli web service jest programowany przez Ciebie, w Visual Studio, możesz dodać add-in, który pozwoli Ci na szybkie dokumentowanie metod w standardzie Swagger (przykłady tu i tu). W innym wypadku, możesz też próbować ręcznie stworzyć plik w notatniku, korzystająć z dokumentacji standardu LUB (co polecam) użyć aplikacji przeglądarkowej restunited.com. Zatem – załóż sobie teraz tam bezpłatne konto 😉

Krok 1 – Basic

1. Kliknij „REST API” –> „New REST API wizard”:
   
   
   
2. W otwartym formularzu wypełnij pola Endpoint URL i Base URL. Endpoint określa ścieżkę URL do określonej metody w API, tymczasem Base URL jest adresem URL do root’a metod web service’u.
3. Ustaw „Method Name” – ta wartość będzie potem używana w Nintex Workflow Cloud jako nazwa akcji, zatem lepiej, by była precyzyjna.
4. Określ sposób uwierzytelniania („Authentication”) – wybierz prawidłowy typ i podaj przykładowe dane. Będzie to potem używane przez funkcję „Connections” w NWC, by umożliwić odpytywanie endpointów:

   

Krok 2 – Endpoint Request

Wpisz parametry żądania („Request”) – możesz podać dodatkowe parametry adresu URL i zmienne. Pola będą użyte w konfiguracji akcji w NWC:

(gdyby to była metoda POST, wówczas konieczne jest zwykle podanie także przykładowej treści „Body” żądania.

Krok 3 – Endpoint Response

Określ parametry odpowiedzi („Response”). To również bardzo ważne, ponieważ korzystając z tych ustawień, w konfiguracji akcji, w NWC, będzie możliwe określenie zmiennych, do zapisania odpowiedzi:

W moim przypadku odpowiedzią jest obiekt JSON, zawierający kolekcję danych klientów, których mam w systemie. Jeśli masz możliwość skopiować i wkleić przykładową treść odpowiedzi, REST United wygeneruje obiektdla zwracanych danych, dla Ciebie. Super!

Krok 4 – Test & Verify

Teraz podaj wymnagane parametry i sprawdź, czy zapytania wysyłane do opisanego endpointa działają. Jeśli tak, web service powinien zwrócić kod odpowiedzi = 200 (OK):

Krok 5 – Release SDK

Teraz możesz opublikować SDK. Jeśli jednak chcesz dodać więcej endpointów do SDK (czyli dostępnych będzie więcej akcji po stronie NWC), po prostu kliknij pomarańczowy przycisk „Add Endpoint„. Jeśli nie, kliknij „Release SDK„:

Krok 6 – Pobierz plik JSON w formacie Swagger

Gdy REST United wygeneruje SDK (Status zmieni się na „Succeeded”), przejdź do zakładki „Test&Export” i kliknij przycisk „Swagger” a następnie „Export”:

W ten sposób wygenerowany został plik JSON w formacie Swagger. Teraz możemy wrócić do Nintex Workflow Cloud.

Mam już plik Swagger, co mogę z nim zrobić?

Utwórz Xtension

1. Przejdź do menu Xtensions. Kliknij przycisk „+” i wybierz „JSON file”. Wskaż plik z definicją w formacie Swagger:

   
   

2. Potwierdź wybrany rodzaj uwierzytelniania i ustaw nazwę oraz opis, a także logo dla nowego połączenia:

   

Utwórz Connection

Po krótkiej chwili nowa Xtensions będzie utworzona. Przejdź do „Connections” – tutaj możesz skonfigurować zaufane połączenie do web service’u, korzystając z metody określonej we wskazanym Xtension (każdy Xtension tworzy własny Connector). Wybierz Connector odpowiadający stworzonemu Xtension z listy rozwijanej:

Gdy tylko nowe połączenie zostanie utworzone, możesz zaczynać używać akcji w swoich workflowach.

Przykład użycia

Stworzyłem przepływ, który jest uruchamiany poprzez wysłanie formularza:

Celem tego formularza jest zebranie danych od użytkownika, następnie rozwiązanie podanej nazwy kraju na jego ID, pobrane z endpoint „Get Countries” i zapisanie tak przygotowanych danych jako nowego Klienta w aplikacji Billiving. Sam formularz nie powala, jednak Nintex pracuje intensywnie nad „Zink„, także w niedalekiej przyszłości formularze będą bardziej atrakcyjne.

Workflow używa dwóch akcji z Web service Billiving: „Definitions – Get Countries” oraz „Client – Create a client„.

Spójrz, ile nowych akcji pojawiło się w menu. Każda odpowiada innemu endpointowi (metodzie) dostępnej w web service Billinving, które określiłem korzystając z REST United:

Niestety, w NWC nie istnieje operacja na kolekcji pozwalająca na pobranie ID elementu w oparciu o jego WARTOŚĆ, zatem by znaleźć ID podanego w formularzu kraju, muszę przeiterować całą kolekcję, aż natrafię na pasujący kraj. Gdy to nastąpi, pętla jest przerywana.

Nastepnie przygotowuję treść żądania w formacie JSON i używam jej w akcji „Create Client”:

Zapisany formularz uruchamia workflow, który wykonuje się ok. 5 minut (zanim przejdzie całą kolekcję), ale gdy tylko to zrobi, nowy klient zostaje dodany do bazy:

Osobiście uważam tę funkcję za bardzo potrzebną. Pozwala na integrację Nintex Workflow Cloud z każdą, nowoczesną aplikacją, które posiada web service REST i API na nim dostępne. Jednak moim zdaniem możliwości integracji nie kończą się wyłącznie na już istniejących web service’ach, dostarczanych przez firmy trzecie, ale przede wszystkim na wykorzystaniu tego we własnym zakresie organizacji, np. w scenariuszu, w którym konkretna, specjalistyczna aplikacja własna jest hostowana w infrastrukturze Azure i integruje się z przepływami pracy w NWC poprzez REST. Bardzo użyteczne 🙂