Camunda - polaczenie procesu z zewnetrznym API (REST)

Najczęściej spotykanym scenariuszem odczytu tasków i uruchamianiem aktywności w zewnątrznych systemach jest budowanie 'listy tasków' na zewnątrz Camundy. Camunda zajmuje się tylko przesyłaniem informacji a rolą zewnętrznych systemów jest odpowiednie reagowanie w zależności od otrzymanego sygnału (czytaj więcej). Czasami jednak chcemy Camundzie zlecić pracę połączenia się z zewnątrznym API, np. serwisem REST by otrzymać lub przekazać dane. Camunda oferuje taką możliwość z wykorzystaniem "service task" i konektora "http-connector".

Poniżej przedstawiamy tutorial jak zbudować diagram BPM, konektor i dokonać właściwych ustawień by proces Camundy łączył się z API.

Budujemy diagram procesu

Ten tutorial bazuje na przykładzie REST Service Task opublikowanym przez Camunde na Github. Z tamtejszego repozytorium możesz pobrać pliki użyte w tym przykładzie. Gotowy diagram to plik invokeRestService.bpmn. Otwórz go w Camunda Modeler.

To bardzo prosty proces który inicjujemy poprzez przeslanie zmiennej "date". Task procesu "Check if date is holiday" łączy się z REST pod adresem https://feiertage-api.de/api i jeśli data jest dniem wolnym od pracy (Niemcy), obierana jest ścieżka "is holiday" a aktywność przenosi się do tasku "Pack for holiday". W innym przypadku aktywowany jest task "Pack for work".

Do przesłania definicji procesu na serwer Camunda używamy programu Postman. Wysyłamy plik invokeRestService.bpmn do REST Camundy metodą "deployment"; http://localhost:8080/engine-rest/deployment/create [Content-type: multipart/form-data, body "upload" i wskazujemy na plik]

Połączenie procesu z REST zewnetrznego API

Task procesu oznaczony "Check if date is holiday" jest tym który łączy się z REST i parsuje otrzymaną odpowiedź przypisując zmiennej "isHoliday" odpowienia wartość. Po wykonaniu tej pracy aktywność przechodzi do następnego tasku w procesie.

W zakładce "Connector" tasku znajdziesz sekcje "Details" i "Output parameters". Details definiuje jaki konektor jest użyty - w tym przypadku "http-connector" a także url, metodę i nagłówki. Wszystkie szczegóły komunikacji. "Output Parameters" definiuje zmienną "isHoliday" która jest zwracana przez task. Jej wartość wynika z rezultatu parsowania odpowiedzi REST za pomocą skryptu "parseHoliday.js" (Java Script).

Plik parsera odpowiedzi (otrzymanej w formacie JSON),  "parseHoliday.js", wrzucamy do katalogu "camunda-bpm-tomcat-X.X.X\server\apache-tomcat-X.X.X\lib". Do parsowania odpowiedzi REST używana jest biblioteka (wrapper) Camunda Spin.

Zawartość tego skryptu to ledwie parę linijek kodu:

// fetch execution variables
var response = connector.getVariable("response");
var date = connector.getVariable("date");

// parse response variable with camunda-spin
var holidays = S(response);

var query = "$..[?(@.datum=='" + date + "')]";

// use camunda-spin jsonPath to test if date is a holiday
!holidays.jsonPath(query).elementList().isEmpty();

"query" spradza czy element "datum" odpowiedzi w formacie JSON zawiera naszą date (zmienna "date") którą wysłaliśmy do procesu inicjując go.

Inicjacja procesu

Proces inicjujemy wyłając z programu Postman zapytanie do REST Camundy, metoda "process-definition" - http://localhost:8080/engine-rest/process-definition/key/holiday/start [Content-type: application/json]

{
  "variables": {
      "date" : {
      "value" : "2014-01-02",
      "type": "String"
    }
  }
}

Scenariusz nr 2

Innym rozwiązaniem jest rozbicie procesu komunikacji Camundy z API na dwa kroki. W pierwszym łączymy się z API i konczymy task, w drugim odbieramy rezultat z API.

Task "Call API" wykonuje połączenie do zewnętrznego API (tak jak to dzieje się w procesie wyżej). Nie zajmuje się przetworzeniem odpowiedzi z API. Proces idzie dalej, do tasku "Wait for signal" (task typu "receive task"). API powinien poinformować proces Camudny używajać metody "Correlate a Message".