User Defined API (Definicja API)

WEBCON Redaktor Dodatki,Narzędzia
Facebooktwitterpinterestlinkedinmail
Dotyczy wersji: 2025 R2 i powyżej; autor: Jacek Język

 

Dokumentacja powiązana

 

User Defined API (Definicja API) w WEBCON BPS – Nowy Wymiar Integracji

 

Wprowadzenie

W świecie nowoczesnych procesów biznesowych integracja różnych systemów stała się kluczowym elementem efektywnego działania organizacji. WEBCON BPS od lat dostarcza zaawansowane możliwości w tym zakresie poprzez swoje standardowe, publiczne REST API. Jednak w odpowiedzi na potrzeby bardziej elastycznych i szybciej wdrażanych integracji, udostępniliśmy User Defined API – funkcjonalność, która pozwala użytkownikom definiować własne, dedykowane endpointy REST API w kontekście konkretnej aplikacji i procesu. Dzięki temu zewnętrzne systemy mogą w prosty sposób komunikować się z WEBCON BPS.

 

Zalety korzystania z User Defined API

W porównaniu do klasycznego, publicznego API, User Defined API oferuje szereg istotnych cech, które znacząco ułatwiają codzienną pracę.

Przede wszystkim ogromną zaletą jest prostota tworzenia. W kilka minut, bez znajomości programowania, konfigurator procesu może zbudować własny, w pełni funkcjonalny endpoint. Wszystko odbywa się w przyjaznym interfejsie WEBCON BPS Designer Studio, bez potrzeby wdrażania dodatkowych serwisów czy pisania kodu.

Równie ważna jest szybkość działania – zamiast planować i rozwijać długotrwałe projekty integracyjne, możemy natychmiastowo reagować na potrzeby biznesowe i udostępniać dane lub operacje na żądanie.

User Defined API wyróżnia się także wysokim poziomem bezpieczeństwa. Dzięki ścisłej kontroli dostępu, dwóm trybom uwierzytelnienia i możliwości definiowania własnych reguł ograniczających, mamy pełną kontrolę nad tym, kto i w jakich warunkach może korzystać z API.

Elastyczność rozwiązania sprawia, że jest ono idealne zarówno do prostych odczytów danych, jak i do bardziej zaawansowanych scenariuszy, gdzie potrzebne są działania takie jak rejestracja nowych elementów, aktualizacje, czy przesuwanie workflow do kolejnego kroku.

Nie można też pominąć faktu, że User Defined API nie wymaga modyfikowania backendu WEBCON BPS ani dodawania nowych mechanizmów do systemu. Wszystko opiera się na istniejącej architekturze platformy, co zapewnia łatwość utrzymania i kompatybilność w kolejnych wersjach systemu.

Wreszcie, dostępna automatyczna dokumentacja OpenAPI upraszcza udostępnianie i testowanie interfejsów, co znacząco przyspiesza czas dostarczania pełnych rozwiązań integracyjnych.

 

Kiedy korzystać z publicznego REST API zamiast User Defined API?

Chociaż User Defined API w WEBCON BPS jest niezwykle wygodnym narzędziem do tworzenia szybkich i prostych integracji, są sytuacje, w których lepszym wyborem będzie skorzystanie z klasycznego, publicznego REST API platformy.

Publiczne REST API sprawdzi się przede wszystkim tam, gdzie potrzeba pełnej kontroli nad operacjami wykonywanymi na elementach, aplikacjach czy strukturze systemu. Jeśli integracja wymaga zaawansowanych operacji, takich jak zarządzanie użytkownikami, konfiguracjami aplikacji, tworzeniem lub edytowaniem struktur procesów, należy skorzystać z publicznego REST API. User Defined API po prostu nie posiada takiej funkcjonalności. Publiczne REST API daje dostęp do znacznie szerszego zestawu operacji administracyjnych i deweloperskich.

Kiedy mamy do czynienia z bardzo skomplikowanym przepływem danych, wymagającym wieloetapowych procesów, transakcyjności, obsługi wielu typów obiektów naraz lub konieczności wykonywania skomplikowanych zapytań i modyfikacji, wtedy publiczne REST API, z jego większą elastycznością i możliwością pisania własnych rozszerzeń, będzie bardziej odpowiednim rozwiązaniem.

Warto też pamiętać, że publiczne REST API jest stworzone z myślą o sytuacjach, gdzie nie wystarczy tylko wywołać jedną automatyzację czy pobrać dane z konkretnego źródła lub rekordu. Jeśli system zewnętrzny ma np. monitorować zmiany stanu wielu elementów, synchronizować dane w czasie rzeczywistym na dużą skalę, a także reagować na zdarzenia systemowe, to wtedy funkcje publicznego REST API okażą się niezbędne.

Innym scenariuszem jest budowanie rozbudowanych aplikacji klienckich lub portalów zewnętrznych, które intensywnie wykorzystują dane z WEBCON BPS i wymagają stałej, bezpośredniej komunikacji z wieloma obiektami i strukturami. W takich przypadkach publiczne REST API zapewnia większą niezależność i bardziej precyzyjne sterowanie procesami, a także większe możliwości filtrowania, paginacji czy pracy na dużych zbiorach danych.

Podsumowując: jeśli potrzeby integracyjne dotyczą głównie rejestracji danych, odczytu informacji, czy prostych operacji w kontekście pojedynczych procesów lub aplikacji, User Defined API jest rozwiązaniem idealnym. Natomiast, gdy integracja wymaga dostępu do szerszych zasobów systemu, kompleksowej obsługi wielu typów operacji administracyjnych, czy pracy z dużymi i dynamicznie zmieniającymi się zbiorami danych – wtedy warto postawić na klasyczne, publiczne REST API WEBCON BPS.

 

Jak działa i jak skonfigurować User Defined API?

Tworzenie User Defined API w WEBCON BPS rozpoczyna się od zdefiniowania podstawowych informacji: nazwy, opisu oraz trybu działania. Możemy zdecydować, czy API ma umożliwiać wywołanie automatyzacji, pobierać dane z istniejącego źródła danych, czy może zwracać informacje o konkretnym elemencie obiegu. W zależności od wybranego trybu, dalsza konfiguracja będzie nieco inna.

W przypadku automatyzacji na odpowiedniej zakładce budujemy sekwencję akcji, które zostaną wykonane po wywołaniu API. Możemy rejestrować nowe elementy, aktualizować istniejące czy wykonywać inne operacje, a dane wejściowe do tych operacji przekazujemy w treści żądania lub w query stringu. Wynik działania automatyzacji także zwracany jest w formacie JSON.

Jeśli zdecydujemy się udostępnić dane ze źródła danych, wybieramy odpowiednie źródło i opcjonalnie definiujemy filtr, który pozwoli zawęzić zakres zwracanych informacji. Możliwe jest też dynamiczne filtrowanie wyników poprzez przekazywanie parametrów przy wywołaniu endpointu. Co ważne, jeżeli wykorzystujemy źródło typu BPS, system automatycznie ogranicza dostępne dane do tych, do których użytkownik ma uprawnienia.

Gdy natomiast chcemy udostępnić dane konkretnego elementu obiegu, konfigurujemy mapowanie odpowiednich atrybutów lub list pozycji. Endpoint wymaga wówczas podania ID elementu w adresie URL, dzięki czemu precyzyjnie określamy, którego rekordu dotyczą pobierane dane.

Tworząc endpoint, definiujemy również jego adres URL. Platforma automatycznie buduje jego strukturę, a użytkownik określa ostatni człon adresu, dzięki czemu zachowujemy spójność z resztą aplikacji.

Każdy endpoint można zabezpieczyć, wybierając sposób uwierzytelnienia. Dostępne są dwa tryby: poprzez OAuth2, z wykorzystaniem aplikacji dostępu publicznego lub poprzez sesję cookie, co jest szczególnie przydatne w przypadku wywołań z poziomu Portalu, na przykład z niestandardowych kontrolek HTML.

Warto też wspomnieć, że WEBCON umożliwia precyzyjne ograniczanie dostępu do endpointu za pomocą reguł biznesowych. Możemy np. sprawić, że tylko użytkownicy należący do konkretnej grupy lub spełniający określone warunki będą mogli wywołać określone API.

 

Praktyczny przykład: tworzenie User Defined API do rejestracji zamówienia

Załóżmy, że firma chce umożliwić swoim partnerom biznesowym składanie zamówień bezpośrednio do systemu WEBCON BPS poprzez wywołanie prostego API. Zamiast tworzyć rozbudowane integracje, konfigurator decyduje się wykorzystać User Defined API.

Proces rozpoczyna się od stworzenia nowego endpointu w sekcji Definicje API. Należy wprowadzić nazwę nowej definicji API, na przykład „NewOrderAPI” i wybrać tryb działania Wywołaj automatyzację, ponieważ wywołanie API ma inicjować rejestrację nowego zamówienia w systemie.

 

Kolejnym krokiem jest zdefiniowanie także adresu URL endpointu, ustalając go na przykład jako orders/create. Dzięki temu partnerzy mogą łatwo zapamiętać i zintegrować ten adres w swoich systemach.

W kwestii uwierzytelnienia wybrano metodę OAuth2 . Do uwierzytelnienia użyta zostanie odpowiednio skonfigurowana aplikacja REST. Opis procesu konfiguracji takiej aplikacji znajduje się w dalszej części artykułu.

 

Następnie należy przejść do zakładki Automatyzacja. Aby API było w stanie przyjąć dane o nowym zamówieniu, należy zdefiniować parametry wejściowe, takie jak „CustomerName”, „ProductCode” oraz „Quantity”. Te parametry będą później wykorzystywane do uzupełnienia pól w formularzu zamówienia.

 

Następnie należy zbudować prostą sekwencję akcji. W pierwszym kroku trzeba dodać akcję Uruchom obieg, wskazując odpowiedni proces obsługi zamówień.

 

Akcja w automatyzacji przypisze wartości tych parametrów do odpowiednich pól formularza nowego zamówienia. Po poprawnym utworzeniu elementu, identyfikator zamówienia zostanie zapisany do parametru wyjściowego OrderID, a system zwróci go w odpowiedzi w strukturze JSON.

 

Całość zajmuje kilkanaście minut pracy i nie wymaga pisania ani jednej linijki kodu programistycznego. Partnerzy biznesowi otrzymują prosty, czytelny interfejs do składania zamówień, a wewnętrzny proces rejestracji w WEBCON BPS odbywa się automatycznie, zgodnie z ustalonymi regułami biznesowymi.

Po stronie klienta zewnętrznego, który ma wywołać nasze API, przygotowujemy prostą aplikację w języku C#. Aplikacja ta będzie najpierw uwierzytelniać się w WEBCON BPS za pomocą OAuth2, a następnie wysyłać dane nowego zamówienia.

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
static async Task Main(string[] args)
{
var portalUrl = "https://bps.webcon.com";
var clientId = "your-client-id"; // WEBCON BPS app client ID
var clientSecret = "your-client-secret"; // WEBCON BPS app client secret

var client = await GetAuthenticatedClientAsync(portalUrl, clientId, clientSecret);

var newOrder = new OrderParams()
{
CustomerName = "Firma ABC",
ProductCode = "PRD-00123",
Quantity = 5
};

var endpoint = $"{portalUrl}/api/udef/db/1/orders/create";

try
{
string orderId = await InvokeOrderAutomationAsync(endpoint, newOrder, client);
Console.WriteLine($"Zamówienie zostało zarejestrowane. ID zamówienia: {orderId}");
}
catch (HttpRequestException ex)
{
Console.WriteLine($"Błąd podczas rejestracji zamówienia: {ex.Message}");
}
}

static async Task<HttpClient> GetAuthenticatedClientAsync(string portalUrl, string clientId, string clientSecret)
{
var url = $"{portalUrl}/api/oauth2/token";

var parameters = new Dictionary<string, string>
{
{ "client_id", clientId },
{ "client_secret", clientSecret },
{ "grant_type", "client_credentials" }
};

var authClient = new HttpClient();
var response = await authClient.PostAsync(url, new FormUrlEncodedContent(parameters));
var json = await response.Content.ReadAsStringAsync();
var token = JObject.Parse(json)["access_token"].ToString();

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
return client;
}

static async Task<string> InvokeOrderAutomationAsync(string endpoint, OrderParams order, HttpClient client)
{
var content = new StringContent(JsonConvert.SerializeObject(order));
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

var response = await client.PostAsync(endpoint, content);

if ((int)response.StatusCode >= 400 && (int)response.StatusCode < 500)
{
var error = await response.Content.ReadAsStringAsync();
throw new HttpRequestException($"Błąd klienta ({(int)response.StatusCode}): {error}");
}

response.EnsureSuccessStatusCode();

var jsonResponse = await response.Content.ReadAsStringAsync();
var json = JObject.Parse(jsonResponse);
var orderId = json["Data"]?["OrderID"]?.ToString();

if (string.IsNullOrEmpty(orderId))
{
throw new Exception("Nie udało się pobrać ID zamówienia z odpowiedzi.");
}

return orderId;
}

struct OrderParams
{
public string CustomerName { get; set; }
public string ProductCode { get; set; }
public int Quantity { get; set; }
}
}

 

W tym przykładzie aplikacja działa w bardzo prosty sposób:

Najpierw nawiązywane jest bezpieczne połączenie z WEBCON BPS za pomocą mechanizmu OAuth2. Używamy tu klienta HTTP, który pobiera token dostępu, a następnie ustawia go w nagłówkach kolejnych zapytań.

W powyższym kodzie your-client-id oraz your-client-secret są danymi niezbędnymi do uwierzytelnienia aplikacji w WEBCON BPS.

  • Client ID (your-client-id) to unikalny identyfikator aplikacji, którą należy wcześniej zarejestrować w WEBCON BPS Portal w sekcji Administracja → Integracje → API.
  • Client Secret (your-client-secret) to tajny klucz bezpieczeństwa przypisany do tej aplikacji, służący do potwierdzania tożsamości klienta podczas procesu autoryzacji.

Oba te elementy są nadawane podczas tworzenia aplikacji REST i powinny być bezpiecznie przechowywane, ponieważ umożliwiają autoryzowany dostęp do API. W szczególności, clientSecret nie powinien być udostępniany publicznie ani przechowywany w miejscach niechronionych.

 

Następnie przygotowujemy strukturę danych reprezentującą zamówienie (OrderParams), zawierającą nazwę klienta, kod produktu i zamawianą ilość.

W kolejnym kroku dane są serializowane do formatu JSON i wysyłane metodą POST na wcześniej skonfigurowany endpoint User Defined API. Jeśli operacja przebiegnie pomyślnie, nowy rekord zostaje utworzony w WEBCON BPS, a użytkownik widzi komunikat w konsoli potwierdzający wysłanie zamówienia.

W ten sposób cały proces – od stworzenia API w WEBCON, przez przygotowanie aplikacji klienckiej, aż po automatyczną rejestrację zamówienia – jest realizowany szybko, bez konieczności pisania rozbudowanych integracji serwerowych czy tworzenia dodatkowych usług middleware.

 

Konfiguracja Aplikacji z dostępem do API (Aplikacji REST)

Aby umożliwić zewnętrznej aplikacji uruchamianie automatyzacji, takich jak tworzenie nowych elementów za pomocą User Defined API w WEBCON BPS, należy odpowiednio skonfigurować aplikację REST oraz przypisać jej właściwe uprawnienia.

Rejestracja aplikacji REST

W panelu administracyjnym WEBCON BPS należy przejść do sekcji Administracja → Integracje → API i utworzyć nową aplikację typu App context. Ten typ aplikacji jest przeznaczony do komunikacji między usługami i nie wymaga interakcji użytkownika. Podczas tworzenia aplikacji podaj jej nazwę, unikalny login w formacie UPN oraz adres e-mail. Po zapisaniu aplikacji system wygeneruje Client ID oraz umożliwi wygenerowanie Client Secret, które należy bezpiecznie przechować, ponieważ nie będzie możliwe ich ponowne wyświetlenie.

 

Konfiguracja zakresów uprawnień (scopes)

Aby aplikacja mogła uruchamiać automatyzacje, takie jak tworzenie nowych elementów, należy przypisać jej odpowiednie zakresy uprawnień. Dla operacji związanych z tworzeniem i modyfikacją elementów wymagany jest zakres: App.UserDefAPI.ReadWrite, który umożliwia odczyt źródeł danych i danych elementu, użycie automatyzacji i operacje na elemencie w wybranej aplikacji. Ten zakres należy przypisać aplikacji REST w sekcji Application permissions (scopes).

 

Nadanie uprawnień użytkownikowi aplikacji

Podczas wywoływania endpointu User Defined API z użyciem ClientID oraz ClientSecret skonfigurowanej aplikacji REST, operacja wykonywana jest w kontekście użytkownika, którego dane (nazwa, login, e-mail) zostały określone podczas tworzenia aplikacji. Aby możliwe było zarejestrowanie nowego zamówienia w WEBCON BPS, konieczne jest nadanie temu użytkownikowi odpowiednich uprawnień w WEBCON BPS Designer Studio.

Użytkownik ten musi posiadać uprawnienia do uruchamiania elementów obiegu w odpowiednich procesach. Dodatkowo, aby uzyskać dostęp do zdefiniowanych endpointów, użytkownik wywołujący endpoint musi mieć co najmniej uprawnienie Dostęp do aplikacji nadany dla aplikacji BPS.

 

Brak wymaganych uprawnień spowoduje, że aplikacja integrująca się nie będzie mogła tworzyć nowych elementów, nawet jeśli skonfigurowane zostały odpowiednie zakresy uprawnień.

 

Podsumowanie

User Defined API w WEBCON BPS otwiera nowy rozdział w integracji procesów biznesowych. Dzięki tej funkcjonalności możliwe jest tworzenie szybkich, bezpiecznych i w pełni dostosowanych do potrzeb organizacji połączeń z systemami zewnętrznymi. Narzędzie to nie tylko ułatwia integrację, ale również przyspiesza rozwój aplikacji biznesowych, zwiększając elastyczność i skuteczność działania całej organizacji.