Skip to main content

Konfiguracja ustawień systemowych dla CallRest

Aktualizacja

Cel i zakres

Ten poradnik pokazuje, jak przygotować konfigurację systemową potrzebną do używania funkcji CallRest w regułach biznesowych. Celem konfiguracji jest zdefiniowanie serwisu REST, sposobu autoryzacji oraz nazwanych endpointów, z których reguła będzie mogła korzystać później przez wywołania takie jak CallRest("NazwaSerwisu", "NazwaEndpointu", ...).

Wymagania wstępne

  • Musisz mieć uprawnienia administratora do Ustawień systemowych.
  • Musisz znać:
    • bazowy adres zewnętrznego API,
    • sposób autoryzacji wymagany przez to API,
    • adresy endpointów, które chcesz wywoływać,
    • metody HTTP dla poszczególnych endpointów,
    • format danych wysyłanych do API, jeżeli wywołanie ma body.
  • Do pracy z CallRest przydaje się podstawowa znajomość HTTP: metody, nagłówki, body, MIME type i schematy uwierzytelniania.

Jak CallRest odwołuje się do konfiguracji

CallRest korzysta z konfiguracji zapisanej w parametrach systemowych z prefiksem external.rest.. W praktyce:

  • pierwszy argument funkcji wskazuje nazwę serwisu,
  • drugi argument funkcji wskazuje nazwę endpointu w tym serwisie,
  • kolejne argumenty są dostępne w szablonach jako placeholdery.

Trzymaj jedno, spójne nazewnictwo serwisu i endpointów w konfiguracji oraz w regule. Funkcja buduje nazwy parametrów na podstawie przekazanych argumentów, więc literówka albo inna konwencja nazewnicza spowoduje, że konfiguracja nie zostanie odnaleziona.

Instrukcja krok po kroku

Krok 1. Utwórz integrację typu CallRest

  1. Przejdź do Ustawień systemowych i otwórz obszar zdefiniowanych integracji.
  2. Dodaj nową integrację.
  3. Jako typ integracji wybierz CallRest.
  4. Wpisz techniczną nazwę serwisu, na przykład TestAPI.

Ta nazwa będzie później używana jako pierwszy argument funkcji:

json = CallRest("TestAPI", "GetInvoice")

Najlepiej używać krótkiej, technicznej nazwy bez spacji i bez zmieniania jej później między konfiguracją a regułami.

Krok 2. Skonfiguruj parametry ogólne serwisu

Po utworzeniu integracji uzupełnij co najmniej parametry ogólne serwisu.

Parametr Kiedy jest potrzebny Uwagi
Url zawsze Bazowy adres API, na przykład https://api.example.com.
AuthorizationType zwykle zawsze Dostępne warianty: BASIC, TOKEN, BEARER, NOAUTH, CUSTOM, NTLM, JWT.
Login BASIC, TOKEN Login używany przy wybranym typie autoryzacji.
Password BASIC Hasło do autoryzacji Basic.
APIToken TOKEN, BEARER, CUSTOM Token API lub inna wartość autoryzacyjna.
AuthorizationHeaderParam CUSTOM Nazwa nagłówka, do którego ma trafić token.

Jak działają typy autoryzacji

  • BASIC: system wysyła nagłówek Authorization: Basic ... z Login i Password.
  • TOKEN: system również wysyła Basic, ale jako dane wykorzystuje Login i APIToken.
  • BEARER: system wysyła nagłówek Authorization: Bearer TOKEN, gdzie TOKEN pochodzi z APIToken.
  • CUSTOM: system wysyła wartość APIToken w nagłówku wskazanym przez AuthorizationHeaderParam.
  • NOAUTH: system nie dodaje nagłówka autoryzacji.
  • NTLM: wariant techniczny dla środowisk, które tego wymagają.
  • JWT: scenariusz zaawansowany, wymagający dodatkowych parametrów OAuth.*.

Jeżeli wybierzesz CUSTOM, ale nie ustawisz AuthorizationHeaderParam, wywołanie zakończy się błędem.

Krok 3. Dodaj endpoint dostępny z reguły

Sama integracja nie wystarczy. CallRest potrzebuje jeszcze nazwanej metody, czyli endpointu, który później podasz jako drugi argument funkcji.

  1. Wejdź w szczegóły integracji.
  2. Dodaj endpoint, na przykład GetInvoice.
  3. Uzupełnij dla niego przynajmniej:
    • Endpoint,
    • RequestType.
  4. W razie potrzeby dodaj też:
    • ContentType,
    • RequestBody,
    • SOAPAction,
    • ResultType.

Przykład podstawowej konfiguracji:

Element Wartość
Nazwa serwisu TestAPI
Nazwa endpointu GetInvoice
Url https://api.example.com
GetInvoice.Endpoint /invoices/{{0}}
GetInvoice.RequestType GET
GetInvoice.ContentType application/json

Po takiej konfiguracji reguła może wywołać endpoint tak:

json = CallRest("TestAPI", "GetInvoice", [InvoiceNumber])

W tym przypadku wartość [InvoiceNumber] zostanie podstawiona do placeholdera {{0}}.

Krok 4. Użyj placeholderów tam, gdzie konfiguracja ma być dynamiczna

To jest najważniejszy element łączący konfigurację systemową z regułą. Placeholdery można stosować nie tylko dla argumentów inline, ale również dla pól sprawy i zmiennych z reguły.

Najczęściej używane typy placeholderów:

Typ placeholdera Przykład Znaczenie
Argument funkcji CallRest {{0}}, {{1}} Kolejne opcjonalne argumenty przekazane po nazwie serwisu i endpointu.
Pole na sprawie {{InvoiceNumber}} Wstawia wartość pola ze sprawy.
Pole słownikowe {{Country.value}} Wstawia wybraną wartość z pozycji słownikowej.
Zmienna z reguły {{_customerName}} Wstawia wartość zmiennej z aktualnie wykonywanej reguły.

Placeholderów można używać między innymi w:

  • Url,
  • Endpoint,
  • RequestBody,
  • Password,
  • APIToken,
  • nagłówkach,
  • cookies,
  • parametrach OAuth.*.

Przykład z body opartym o pola sprawy:

Parametr Wartość
CreateOrder.Endpoint /orders
CreateOrder.RequestType POST
CreateOrder.ContentType application/json
CreateOrder.RequestBody { "number": "{{InvoiceNumber}}", "customer": "{{CustomerName}}" }

Przykład z argumentami przekazanymi inline:

Parametr Wartość
CreateOrder.RequestBody { "number": "{{0}}", "customer": "{{1}}" }

Wywołanie reguły:

json = CallRest("TestAPI", "CreateOrder", [OrderNumber], [CustomerCode])

Jeśli budujesz JSON lub XML z placeholderów, zwróć uwagę na typ danych:

  • placeholder dla tekstu powinien być ujęty w cudzysłowy,
  • placeholder dla liczby nie musi być ujmowany w cudzysłowy,
  • brak placeholdera w Endpoint albo RequestBody oznacza, że argument przekazany z reguły nie zostanie nigdzie wykorzystany.

Krok 5. Dobierz poprawny ContentType

Najczęstszy wariant to application/json, ale CallRest obsługuje też inne typy danych. W zależności od integracji możesz wykorzystać:

  • application/json,
  • application/xml,
  • application/x-www-form-urlencoded,
  • multipart/form-data,
  • application/octet-stream,
  • text/xml dla webserwisów typu SOAP.

W praktyce oznacza to:

  • dla application/json i application/xml zwykle uzupełniasz RequestBody,
  • dla application/x-www-form-urlencoded używasz par CustomXWWWFormKeyN i CustomXWWWFormValueN,
  • dla multipart/form-data używasz CustomFormDataParam albo CustomFormDataParamN,
  • dla application/octet-stream w RequestBody wskazujesz załącznik ze sprawy,
  • dla text/xml często potrzebny jest też SOAPAction.

Krok 6. Skonfiguruj opcje zaawansowane tylko wtedy, gdy są potrzebne

Nowe UI ma gotowe pola tylko dla najczęstszych parametrów. Kod obsługuje też kilka opcji zaawansowanych, które mogą wymagać ręcznego dodania jako dodatkowe parametry.

Najważniejsze z nich to:

Parametr Zastosowanie
UseRawJsonBody Wymusza wysyłkę body bez domyślnego formatowania JSON. Przydaje się przy niestandardowych formatach dat albo gotowym surowym body.
ResultType Pozwala zwrócić samo body, same headers albo body+headers.
UseWebProxy Można ustawić na poziomie całego serwisu albo pojedynczego endpointu.
Headers Pozwala zadeklarować wiele dodatkowych nagłówków w jednym parametrze, linia po linii w formacie klucz:wartość.
CustomHeaderKeyN / CustomHeaderValueN Starszy sposób dodawania nagłówków jako osobnych par parametrów.
CustomCookieKeyN / CustomCookieValueN / CustomCookiePathN / CustomCookieDomainN Cookies wysyłane razem z żądaniem HTTP.

Jeśli korzystasz z JWT, dodatkowo musisz skonfigurować parametry:

  • OAuth.BaseUrl,
  • OAuth.TokenUrl,
  • OAuth.TokenPath,
  • OAuth.Issuer,
  • OAuth.UserId,
  • OAuth.GrantType,
  • OAuth.Scope,
  • OAuth.PrivateKeyPem.

To jest scenariusz zaawansowany. Warto wdrażać go dopiero wtedy, gdy podstawowy wariant integracji działa już poprawnie.

Krok 7. Zapisz konfigurację i sprawdź ją w regule

Po zapisaniu ustawień utwórz lub zaktualizuj regułę, w której wywołasz CallRest.

Najprostszy test:

[ApiResponse] = CallRest("TestAPI", "GetInvoice", [InvoiceNumber])

Jeżeli konfiguracja jest poprawna:

  • funkcja zwróci wynik jako tekst JSON albo XML, zależnie od odpowiedzi serwisu i ustawień,
  • reguła będzie mogła przypisać wynik do zmiennej albo pola,
  • w razie potrzeby będziesz mógł dodatkowo pobrać nagłówki odpowiedzi przez ResultType.

Weryfikacja

Po zapisaniu konfiguracji sprawdź:

  1. Czy nazwa serwisu w Ustawieniach systemowych jest taka sama jak pierwszy argument CallRest.
  2. Czy nazwa endpointu jest taka sama jak drugi argument CallRest.
  3. Czy Endpoint i RequestBody zawierają placeholdery tam, gdzie reguła przekazuje wartości dynamiczne.
  4. Czy wybrany AuthorizationType jest zgodny z wymaganiami zewnętrznego API.
  5. Czy przy CUSTOM uzupełniono AuthorizationHeaderParam.
  6. Czy przy metodach z body ustawiono poprawny ContentType.
  7. Czy dla JWT uzupełniono komplet parametrów OAuth.*.

Typowe problemy

Endpoint nie dostaje argumentów

Najczęstsza przyczyna to brak placeholderów w Endpoint albo RequestBody.

Przykład błędnej konfiguracji:

  • Endpoint = /invoices

Przykład poprawnej konfiguracji:

  • Endpoint = /invoices/{{0}}

Reguła wskazuje inną nazwę serwisu lub endpointu niż konfiguracja

Jeżeli w konfiguracji utworzysz serwis TestAPI, a w regule wywołasz inną nazwę, na przykład CallRest("TestApi", ...), funkcja będzie szukała innego zestawu parametrów i nie odnajdzie oczekiwanej konfiguracji. Dlatego najlepiej trzymaj jedną, niezmienną konwencję zapisu nazw.

Wywołanie kończy się błędem autoryzacji

Najczęstsze przyczyny:

  • wybrano zły AuthorizationType,
  • wpisano token do Password zamiast do APIToken,
  • przy CUSTOM nie ustawiono AuthorizationHeaderParam,
  • przy JWT nie uzupełniono wszystkich wymaganych parametrów OAuth.*.

Reguła dostaje błąd mimo odpowiedzi z API

Jeżeli API zwraca kod spoza listy statusów akceptowanych przez CallRest, funkcja potraktuje to jako błąd. W takiej sytuacji trzeba sprawdzić:

  • czy API zwraca oczekiwany status HTTP,
  • czy potrzebujesz CustomErrorHandling,
  • czy ResultType nie powinien zwracać też nagłówków do dalszej diagnostyki.

Body JSON po podstawieniu ma niepoprawny format

Najczęściej problem wynika z nieprawidłowego połączenia placeholderów i typów danych. Sprawdź, czy:

  • tekstowe placeholdery są ujęte w cudzysłowy,
  • liczbowe placeholdery nie są niepotrzebnie zamieniane na tekst,
  • przy UseRawJsonBody = true nie próbujesz składać kilku fragmentów JSON w sposób, który omija parser szablonów.

Ważne informacje

  • CallRest nie konfiguruje integracji samodzielnie. Reguła korzysta wyłącznie z tego, co administrator zapisze w Ustawieniach systemowych.
  • Technicznie konfiguracja opiera się o parametry systemowe external.rest.<nazwa serwisu>[.<nazwa endpointu>][.<nazwa pomocnicza>].
  • To administrator decyduje, jak nazywają się serwisy i endpointy, dlatego warto od razu przyjąć spójny standard nazewnictwa.
  • Nie wszystkie opcje wspierane przez kod są dostępne jako gotowe pola w UI. Przy bardziej zaawansowanych scenariuszach część parametrów może wymagać ręcznego dodania.