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.). Od wersji wtyczki 1.0.17 dostępna jest również możliwość pobierania plików. |
Od wersji wtyczki 1.0.18 dostępna jest również możliwość wysyłania pliku w zapytaniu. Należy ustawić "ContentType" jako "multipart/form-data" oraz uzupełnić parametry związane z wysyłanymi plikami. |
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 (operacja odczytu):| Nazwa parametru | Opis parametru | Wymagalność |
|---|
| Autoryzacja | Schemat 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łówki | Parametr 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 HTTP | Lista metod protokołu HTTP. Dostępne metody: GET, HEAD, POST, PUT, DELETE, PATCH. Należy wybrać wymaganą metodę żądania zgodnie z dokumentacją API. | Wymagany | | URL | Adres 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 odpowiedzi | Określa format odpowiedzi, w którym wywoływane API zwraca wynik zapytania. | Wymagany | | Nazwa wpisu | Nazwa wpisu w wysyłanym zapytaniu dotyczące danego pliku. Opcja dostępna dla typu "multipart/form-data" w parametrze "Content-Type". |
| | | ID pliku | Plik, który ma zostać wysłany. Opcja dostępna dla typu "multipart/form-data" w parametrze "Content-Type". |
| | | Parametry wejściowe | | Id parametrów wejściowych | Nazwy parametrów wejściowych | Typy parametrów wejściowych | jsonPath |
|---|
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 Path/Klucz - parametr zostanie przekazany w w polu "Path/Klucz", w sekcji parametrów wyjściowych | 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ściowych | Nazwy parametrów wyjściowych | Path/Key | Nazwa elementu | Żródło |
|---|
| Określa id parametrów wyjściowych używane w mappingu | Okreś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: 
|
Opis konfiguracji (operacja pobierania pliku):| Nazwa parametru | Opis parametru | Wymagalność | Uwagi |
|---|
| Autoryzacja | Schemat 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łówki | Parametr 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 HTTP | Lista metod protokołu HTTP. Dostępne metody: GET, HEAD, POST, PUT, DELETE, PATCH. Należy wybrać wymaganą metodę żądania zgodnie z dokumentacją API. | Wymagany | | | URL | Adres 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. |
| | | | 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 | | | 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 | | | Klasa dokumentów | Określa klasę dokumentów, w której zapisany zostanie pobrany plik. | | | | Nazwa pliku | Nazwa, pod którą zapisany zostanie pobrany plik. | | | | Opis pliku | Opis pobranego pliku w archiwum dokumentów. | | | | Wywołaj akcje klasy dokumentów | Wywołuje akcje na klasie dokumentów (typ zdarzenia: "Dodanie nowego dokumentu z poziomu archiwum"). | | | | Dołącz do procesu | Pozwala określić czy i w jaki sposób dodać pobrany dokument do procesu/zadania. Dostępne opcje: | Opcja | Opis |
|---|
| Nie dołączaj do procesu ani do zadania | Dokument jest tylko zapisywany w archiwum | | Dołącz do procesu | Dodawanie do procesu (pojawia się pole "ID procesu") | | Dołącz do procesu i zadania | Dodawanie do procesu oraz do zadania (pojawiają się pola: "ID procesu" oraz "ID zadania") |
| | | | ID procesu | ID procesu, do którego chcemy dołączyć pobrany dokument (dostępne po wyborze odpowiedniej opcji parametru "Dołącz do procesu"). | | ID procesu można znaleźć na pasku adresu przeglądarki internetowej (parametr "processKey"). | | ID zadania | ID zadania, do którego chcemy dołączyć pobrany dokument (dostępne po wyborze odpowiedniej opcji parametru "Dołącz do procesu"). | | ID zadania można znaleźć na pasku adresu przeglądarki internetowej (parametr "activityId"). | | Zapisz jako nowa wersja | Określa czy i w jaki sposób zapisać nową wersję pobranego dokumentu. Dostępne opcje: | Opcja | Opis |
|---|
| Nie | Zapisywanie jako nowy dokument w archiwum | | Tak (bazując na ID pliku) | Zapisuje nową wersja dla podanego ID pliku (pojawia się pole "ID pliku") | | Tak (bazując na indeksach) | Zapisuje nową wersję pliku wykorzystując systemowy mechanizm indeksów |
| | | | ID pliku | ID pliku, dla którego zostanie utworzona nowa wersja dokumentu (dostępne po wyborze odpowiedniej opcji parametru "Zapisz jako nowa wersja"). | | | | Indeks | Nazwa indeksu z klasy dokumentów (możliwość użycia parametru wejściowego, np. {index_name}, gdzie "index_name" to ID parametru wejściowego. | | | | Wartość indeksu | Wartość, która zostanie zapisana w danym indeksie (możliwość użycia parametru wyjściowego, np. { | | | | Parametry wejściowe | | Id parametrów wejściowych | Nazwy parametrów wejściowych | Typy parametrów wejściowych | jsonPath |
|---|
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
- W przypadku parametru typu "Parametr pliku" należy podstawić zdefiniowane id jako wartość w polach: klasa dokumentów, nazwa pliku, opis pliku, ID procesu, ID zadania, ID pliku, indeks
| 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 pliku - parametr zostanie przekazany w polach dotyczących pobieranego dokumentu/archiwum dokumentów. Parametr Path/Klucz - parametr zostanie przekazany w w polu "Path/Klucz", w sekcji parametrów wyjściowych | 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. |
| | | | Parametry wyjściowe | | Id parametrów wyjściowych | Nazwy parametrów wyjściowych | Path/Key | Żródło |
|---|
| Określa id parametrów wyjściowych używane w mappingu | Okreś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. |
- 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");
|
| | |
Przykłady konfiguracji:| Konfiguracja źródła | Odpowiedź API | Opis |
|---|
 | {
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ła | Odpowiedź API | Opis | |
|---|
 | {
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") | |
|
