Instrukcja tworzenia źródeł danych w systemie - http://192.168.1.52:8081/confluence/pages/viewpage.action?pageId=13272439

Wtyczka zawiera implementację źródeł danych operujących na RESTful API.

Za pomocą opisywanych źródeł danych można odczytywać i przekazywać dane pomiędzy systemem PlusWorkflow a zewnętrznym API z wykorzystaniem metod protokołu HTTP (GET, POST itd.).

Istnieje również możliwość komunikacji z wewnętrznym API systemu. W takim przypadku w adresie URL należy użyć domeny "localhost"

 

Opis konfiguracji:

Nazwa parametruOpis parametruWymagalność
AutoryzacjaSchemat autoryzacji żądania. Jeśli żądany endpoint nie wymaga autoryzacji pole należy zostawić puste. Opis definiowania szablonów autoryzacji znajduje się TUTAJ.Opcjonalny
Dodatkowe nagłówkiParametr pozwala na dodanie dodatkowych nagłówków do żądania. Parametr można wykorzystać np. do wymuszenia odpowiedzi z API w formacie JSON (jeśli wywoływane API posiada taką możliwość). W takim wypadku należy dodać wiersz w opisywanym parametrze i w polu "Nagłówek" podać wartość "Accept", natomiast w polu "Wartość" podać "application/json".


Poprawnie skonfigurowane API na żądanie z powyższym nagłówkiem powinno zwrócić dane w formacie JSON lub odpowiedzieć błędem w przypadku, gdy na to żądanie nie można odpowiedzieć w formacie JSON.		Opcjonalny
Metoda HTTPLista metod protokołu HTTP. Dostępne metody: GET, HEAD, POST, PUT, DELETE, PATCH. Należy wybrać wymaganą metodę żądania zgodnie z dokumentacją API.Wymagany
URLAdres URL endpointu, do którego wysłane zostanie żądanie. W przypadku wywołania akcję z API tego samego systemu PlusWorkflow, w którym skonfigurowane jest źródło adres URL musi zawierać domenę "localhost".Wymagany
Content-Type

Parametr pozwala na zdefiniowanie formatu danych przekazywanych w ciele żądania. Parametr jest stosowany tylko, gdy wśród parametrów wejściowych znajdują się parametry typu "Parametr Body". W pozostałych przypadkach wartość tego parametru nie ma znaczenia.

Jeśli chcemy skorzystać z innej niż domyślne wartości, należy użyć opcji "Dodatkowe nagłówki" podając "Content-Type" jako nazwa oraz własną, poprawną wartość dla tego nagłówka.

Wymagany
Typ zwracanej odpowiedziOkreśla format odpowiedzi, w którym wywoływane API zwraca wynik zapytania.Wymagany
Parametry wejściowe
Id parametrów wejściowychNazwy parametrów wejściowychTypy parametrów wejściowychjsonPath

Określa id parametrów wejściowych.

  • W przypadku parametru typu "Parametr URL" należy podstawić zdefiniowane id do adresu URL żądania w formacie {id} np. http://localhost/{parametr}
  • W przypadku parametru typu "Parametr Body" oraz w przypadku gdy parametr "Szablon" jest pusty - zdefiniowane id zostanie użyte jako klucz przekazywanych danych w ciele żądania; w przypadku gdy parametr "Szablon" nie jest pusty - zdefiniowane id zostanie użyte jako wartość elementu w szablonie JSON
  • W przypadku parametru typu "Parametr Header" należy podstawić zdefiniowane id jako wartość klucza w nagłówku wysyłanego żądania
Określa wyświetlaną nazwę parametrów wejściowych

Parametr URL - parametr zostanie przekazany w adresie URL.

Parametr Body - parametr zostanie przekazany w ciele żądania.

Parametr Header - parametr zostanie przekazany w nagłówku żądania.

Parametr autoryzacji - parametr zostanie przekazany do wybranego schematu autoryzacji.

Parametrów typu "Parametr Body" nie należy dodawać do żądań typu "GET"!

Ścieżka w formacie jsonPath określająca docelowy element tablicowy struktury JSON, w którym zostaną powielone lub rozpakowane wartości wejściowych parametrów tabelarycznych.

Opcjonalny
Parametry wyjściowe
Id parametrów wyjściowychNazwy parametrów wyjściowychPath/KeyNazwa elementuŻródło
Określa id parametrów wyjściowych używane w mappinguOkreśla wyświetlaną nazwę parametrów wyjściowych

Ścieżka (JsonPath lub XPath - w zależności od formatu odpowiedzi zwrotnej z API) służąca do wyodrębnienia danych z odpowiedzi.

Dokumentacja korzystania z JsonPath - https://github.com/json-path/JsonPath

Bardzo przydatną stroną gdzie można odczytać ścieżkę z podanego JSON'a jest: https://jsonpathfinder.com/

W przypadku źródła typu "Parametr Header", w polu podajemy nazwę klucza z nagłówka odpowiedzi.

W przypadku źródła typu "Parametr Cookie", w polu podajemy nazwę cookie z odpowiedzi. Jeśli została podana gwiazdka: * to zostaną odczytane wszystkie cookie z odpowiedzi.

Nazwa elementu z podanej ścieżki XPath lub JsonPath z której zostanie pobrana wartość. W przypadku gdy wskazanego elementu nie ma, zostanie zwrócona wartość pusta.

 

Parametr nie może wskazywać na element, który zawiera w sobie kolejnego node'a z elementami.

  • Parametr Body - wartość zostanie pobrana z "ciała" wiadomości odpowiedzi według podanej ścieżki i nazwy elementu (parametry: "Path/Klucz" oraz "Nazwa elementu");
  • Parametr Header - wartość zostanie pobrana z nagłówka wiadomości odpowiedzi według podanego klucza (parametr "Path/Klucz");
  • Parametr Cookie - wartość zostanie pobrana z cookie odpowiedzi według podanego klucza (parametr "Path/Klucz");

 

W przypadku wyboru "Parametr Body" w polu "Path/Klucz" należy podać ścieżkę do parametru w odpowiednim formacie (JsonPath lub XPath).

Aby pobrać wszystkie cookie w formacie "nazwa1=wartosc1;nazwa2=wartosc2" należy w polu klucz podać gwiazdkę: *

Opcjonalny
Szablon

Szablon wejściowy w formacie JSON, który zostanie przekazany w treści wiadomości wysyłanej. Wartości parametrów podanych w klamrach, np.: "{param1}" zostaną zastąpione wartościami parametrów wejściowych o danym id (w tym przypadku: param1).

Jeżeli parametr podany w klamrach znajduje się w obiekcie (JSON object) w strukturze listy w szablonie JSON oraz został dla niego określony element tablicowy w definicji parametru wejściowego (parametr jsonPath) a także jeśli parametr wejściowy jest typu tabelarycznego to obiekt do którego należy parametr w klamrach w szablonie JSON zostanie powielony tyle razy ile wynosi długość przekazanej tablicy parametru wejściowego.

Jeżeli parametr podany w klamrach znajduje się w tablicy(JSON array) w strukturze listy w szablonie JSON oraz został dla niego określony element tablicowy w definicji parametru wejściowego (parametr jsonPath) a także jeśli parametr wejściowy jest typu tabelarycznego to tablica do której należy parametr w klamrach w szablonie JSON zostanie wypełniona wartościami z tablicy parametru wejściowego.

 

Jeśli szablon pozostanie pusty to jako treść wiadomości wysyłanej zostanie wygenerowany prosty schemat JSON w formacie: "{"{param1}":"param1_wartość"}" zgodnie z przekazanymi parametrami wejściowymi.

Opcjonalny
Separator zmiennych tabelarycznych

Znak tekstowy określający separator danych w tabelarycznych parametrach wejściowych.

Wartość domyślna: ";"

Wymagany
Timeout połączenia [s]Parametr określający limit czasu dla połączenia ze wskazaną usługą REST. Domyślna wartość parametru to 60 sekund.Wymagany

Komponent umożliwia wyświetlenie podglądu danych nieprzetworzonych (wygenerowany schemat JSON, odpowiedź z API, nagłówki odpowiedzi z API). W celu wyświetlenia podglądu należy użyćprzycisku "Pokaż dane nieprzetworzone" znajdującego się na samym dole okna konfiguracji, następnie opcjonalnie uzupełnić parametry wejściowe źródła i finalnie użyć przycisku "Wywołaj źródło".

 

Przykładowe okno z podglądem danych nieprzetworzonych:

Przykłady konfiguracji:

Przykładowa konfiguracja, wykorzystująca publiczne API https://api.publicapis.org/:

Konfiguracja źródłaOdpowiedź APIOpis
{
  message: "user was created"
}
Źródło dodaje użytkownika do API example.com i w odpowiedzi wyświetla wiadomość zwrotną oraz pliki cookie.
Konfiguracja źródłaOdpowiedź APIOpis 
{
  data: [
    {
      ...,
      userName: "admin",
      ...
    },
    {
      ...,
      userName: "administrator",
      ...
    }
  ],
  total: 2
}

Źródło zwraca listę nazw użytkowników systemu PlusWorkflow, zawierających wartość przekazaną w parametrze "filter" oraz liczbę wszystkich zwróconych wyników przy każdej zwróconej nazwie użytkownika.


(Wywołanie dla filter="admin")
 

Instructions for creating data sources in the system - http://192.168.1.52:8081/confluence/pages/viewpage.action?pageId=13272439

The plugin contains the implementation of datasources operating on the RESTful API.

Described data sources allow for read and transfer data between the PlusWorkflow system and an external API using the HTTP protocol methods (GET, POST, etc.).

It is also possible to communicate with the PWFL system's internal API. In this case, use "localhost" in the URL

 

Configuration description:

Name of the parameter
Description
Optionality
AuthorizationRequest authorization scheme. If the requested endpoint does not require authorization, leave the field blank. Description of defining authorization templates is HERE.Optional
Additional headersThe parameter allows adding additional headers to the request. The parameter can be used, for example, to force a response from the API in JSON format. In this case, add a row in the described parameter and enter "Accept" in the "Header" field, and "application/json" in the "Value" field.


A properly configured API should return data in JSON format on request with the above header or reply with an error in case this request cannot be answered in JSON format.		Optional
HTTP methodList of HTTP protocol methods. Available methods: GET, HEAD, POST, PUT, DELETE, PATCH. Choose the required request method according to the API documentation.Required
URLEndpoint URL to which the request will be sent. If you call an action from the API of the same PlusWorkflow system in which the datasource is configured, the URL must contain the domain "localhost".Required
Content-Type

The parameter allows defining the format of the data transferred in the body of the request. The parameter is used only if the "Parameters Body" type parameters are among the input parameters. In other cases the value of this parameter does not matter.

Should use custom header? Use "Additional headers" to set "Content-Type" with your own proper value.

Required
Response Content-TypeParameter specifies data format of incoming API response.Required
Input parameters
Input parameters id
Input parameters names
Input parameters types
JsonPath

Specifies the id of the input parameters.

Specifies the display name of the input parameters

URL param - the parameter will be passed in the URL

Body param - the parameter will be passed in the request body

Header param - parameter will be passed as a header value.

Auth param - parameter will be passed to selected authorization schema.

Parameters of type "Body param" should not be added to requests of type "GET"!

JsonPath formatted value for JSON array where array-like input values will be duplicated/unpacked.

Optional
Output parameters
Output parameters id
Output parameters names
Path/Key
Child node nameSource
Specifies the id of the output parameters used in mappingSpecifies the display name of the output parameters

A path (JsonPath or  XPath) used to extract data from the resulting JSON.

Documentation for using JsonPath - https://github.com/json-path/JsonPath

In case of "Header param" type - fill in with response header key name.

In case of "Cookie param" type - fill in cookie name for single cookie or star * for all cookies in key=value pairs.

XPath or JsonPath child node name from where the value will be obtained. In case of non existing element - empty value will be returned.

  • Body param - value obtained from response body according to given JsonPath/XPath;
  • Header Param - value obtained from response header with given name;
  • Cookie param - value obtained from response cookies;
Optional
Connection timeout [s]Timeout parameter for connection to the REST service. The default parameter value is 60 seconds.Required

Component allows displaying raw data preview (generated JSON schema, API response, API response headers). To use raw data preview feature please use "Show raw data" button (the very bottom of data source configuration window) then fill in required input parameters and finally click the "Execute datasource" button.

 

Sample raw data preview window:

 

Configuration samples:

 

Datasource configuration
API response
Description
{
  message: "user was created"
}
The source adds the user to the example.com API and responds with a message from the server and reads all cookies values.
Datasource configuration
API response
Description
{
  data: [
    {
      ...,
      userName: "admin",
      ...
    },
    {
      ...,
      userName: "administrator",
      ...
    }
  ],
  total: 2
}

The datasource returns a list of PlusWorkflow system user names, containing the value passed in the "filter" parameter and the number of all results returned for each returned username.

 

(executed with following query param: filter="admin")