User Defined API (API Definition)

Applies to version: 2025 R2 and above; author: Jacek Język

Related documentation

• API definitions | WEBCON BPS

User Defined API (API Definition) in WEBCON BPS – a new level of integration

Introduction

In the world of modern business processes, the integration of different systems has become a key element for the effective operation of an organization. WEBCON BPS has been providing advanced capabilities in this regard for years through its standard, public REST API. However, in response to the need for more flexible and faster to deploy integrations, we have provided User Defined API – functionality that allows users to define their own dedicated REST API endpoints in the context of a specific application and process. This allows external systems to easily communicate with WEBCON BPS.

Advantages of using the User Defined API

Compared to the classic public API, the User Defined API offers a number of important features that greatly streamline daily operations.

First of all, the simplicity of creation is a huge advantage. In a few minutes, without any programming knowledge, the process configurator can create their own fully functional endpoint. Everything is done in the user-friendly interface of WEBCON BPS Designer Studio, without having to implement additional services or write code.

Equally important is the speed of operation – instead of planning and developing lengthy integration projects, we can react immediately to business needs and provide data or operations on demand.

The User Defined API also provides a high level of security. With strict access control, two authentication modes, and the ability to define our own restrictive rules, we have complete control over who can use the API and under what conditions.

The flexibility of the solution makes it ideal for simple data retrieval as well as more advanced scenarios where actions such as registering new workflow instances, making updates, or taking the workflow to the next step are required.

It is also important to note that the User Defined API does not require modifying the WEBCON BPS backend or adding new mechanisms to the system. Everything is based on the existing platform architecture, which ensures easy maintenance and compatibility in future versions of the system.

Finally, the available automatic OpenAPI documentation simplifies the provisioning and testing of interfaces, which significantly speeds up the delivery of full integration solutions.

When is it advisable to use a public REST API instead of a User Defined API?

Although the User Defined API in WEBCON BPS is an extremely convenient tool for creating quick and easy integrations, there are situations where using the platform's classic public REST API would be a better choice.

The public REST API is particularly well-suited for scenarios where comprehensive control over operations on workflow instances, applications, or system structure is essential. If the integration requires advanced operations, such as managing users, application configurations, creating or editing process structures, use the public REST API. The User Defined API simply does not have this functionality. A public REST API provides access to a much broader set of administrative and development operations.

When dealing with complex data flows that require multi-step processes, transactionality, handling multiple types of objects at once, or performing complex queries and modifications, a public REST API is a more suitable solution due to its greater flexibility and the ability to write your own extensions.

It's also important to note that the public REST API is designed for situations where a single automation or retrieval of data from a specific source or record is insufficient. If an external system is to, for example, monitor changes in the state of multiple workflow instances, synchronize data in real time on a large scale, and respond to system events, then the functions of the public REST API will prove essential.

Another scenario is the development of complex client applications or external portals that make extensive use of data from WEBCON BPS and require constant, direct communication with multiple objects and structures. In such cases, a public REST API offers enhanced autonomy and more precise process control. It also provides greater ability to filter, paginate, and work on large data sets.

In summary, if your integration needs primarily involve data recording, information retrieval, or basic operations within the scope of single processes or applications, the User Defined API is the optimal solution. Conversely, when integration demands access to broader system resources, intricate support for diverse administrative operations, or engagement with voluminous and continually evolving data sets, the tried-and-true public REST API of WEBCON BPS emerges as a reliable choice.

How does the User Defined API work and how to configure it?

Creating a User Defined API in WEBCON BPS starts with defining the basic information: name, description, and mode of operation. We can decide whether the API should enable the triggering of automation, retrieve data from an existing data source or perhaps return information about a specific workflow instance. Depending on the selected mode, the rest of the configuration will be slightly different.

In the case of automation, we create a sequence of actions on the appropriate tab that will be executed when the API is invoked. We can register new workflow instances, update existing ones, or perform other operations, and we pass the input for these operations in the body of the request or in a query string. The result of the automation is also returned in JSON format.

If we choose to share data from a data source, we select the appropriate source and optionally define a filter to narrow the scope of the information returned. It is also possible to dynamically filter the results by passing parameters when invoking the endpoint. Importantly, when we use a BPS internal view data source, the system automatically limits the available data to that for which the user has privileges.

On the other hand, if we want to provide the data of a specific workflow instance, we configure the mapping of the relevant form fields or item lists. The endpoint then requires the instance ID in the URL so that we can determine exactly which record the retrieved data belongs to.

When we create an endpoint, we also define its URL. The platform automatically builds its structure, and the user specifies the last part of the address, so we maintain consistency with the rest of the application.

Each endpoint can be secured by selecting an authentication method. There are two modes: through OAuth2, using a public access application, or through a cookie session, which is particularly useful for Portal calls, for example from custom HTML controls.

It is also worth mentioning that WEBCON makes it possible to precisely restrict access to the endpoint using business rules. For example, we can make it so that only users who belong to a certain group or meet certain conditions can invoke a certain API.

Practical example: Creating a User Defined API for order registration

Let's assume a company wants to enable its business partners to place orders directly in WEBCON BPS by invoking a simple API. Instead of creating a complex integration, the configurator decides to use a User Defined API.

The process starts by creating a new endpoint in the API Definitions section. Enter the name of the new API definition, for example, "NewOrderAPI", and select the Execute automation running mode, since the API call will initiate the registration of a new order in the system.

The next step is to define the Endpoint URL, such as orders/create. This makes it easy for partners to remember and integrate this URL into their systems.

The authentication method chosen is OAuth2. A properly configured REST application is used for authentication. The process of configuring such an application is described later in this article.

Next, select the Automation tab. In order for the API to accept new order data, you need to define input parameters such as “CustomerName”, “ProductCode”, and “Quantity”. These parameters will later be used to populate the fields in the order form.

The next step is to create a simple sequence of actions. In the first step, add a Start a subworkflow action and specify the corresponding order handling process in its configuration.

The action in the automation will assign the values of these parameters to the corresponding fields of the new order form. Once the instance is correctly created, the order ID is written to the “OrderID” output parameter , and the system returns it in a response in a JSON structure.

The whole process takes only a few minutes and does not require writing a single line of code. Business partners get a simple, clear interface to place orders, and the internal registration process in WEBCON BPS takes place automatically according to the established business rules.

On the side of an external client, who will invoke our API, we prepare a simple C# application. This application will first authenticate with WEBCON BPS using OAuth2 and then send the new order data.

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 secret

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

        var newOrder = new OrderParams()
        {
            CustomerName = "Company 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($"Success! Order registered. Order ID: {orderId}");
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"Error while registering order: {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($"Client error ({(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("Failed to get order ID from response.");
        }

        return orderId;
    }

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

In this example the application works in a very simple way:

First, a secure connection to WEBCON BPS is established using the OAuth2 mechanism. Here we use an HTTP client that retrieves an access token and then sets it in the headers of subsequent requests.

In the code above, your-client-id and your-client-secret are the data needed to authenticate the application in WEBCON BPS.

• Client ID (your-client-id) is the unique identifier of the application, which has to be registered in advance in WEBCON BPS Portal under Administration → Integrations → API.
• Client Secret (your-client-secret) is a secret security key assigned to this application, which is used to confirm the identity of the client during the authorization process.

Both are assigned during the development of a REST application and should be stored securely as they allow authorized access to the API. In particular, clientSecret should not be made public or stored in unprotected locations.

Next, we prepare a data structure representing the order (OrderParams), which contains the customer name, product code, and quantity ordered.

Then, the data is serialized into JSON format and sent to the previously configured User Defined API endpoint via the POST method. If the operation is successful, a new record is created in WEBCON BPS and the user sees a message in the console confirming that the order has been sent.

In this way, the entire process – from the creation of the API in WEBCON, through the preparation of the client application, to the automatic registration of the order – is performed quickly, without the need to write extensive server integrations or create additional middleware services.

Configuring an API-enabled application (REST application)

In order to allow an external application to execute automations such as creating new workflow instances using the USER Defined API in WEBCON BPS, you need to properly configure the REST application and assign it the right permissions.

REST application registration

In WEBCON BPS Portal, select Administration → Integrations → API and create a new application of the App context type. This type of application is designed for communication between services and does not require user interaction. When creating the application, specify its name, a unique login in UPN format, and an email address. Once the application is saved, the system will generate a Client ID and allow you to generate a Client Secret, which should be kept safe as it will not be possible to view it again.

Configuration of application permissions (scopes)

In order for the application to execute automations, such as creating new workflow instances, it is necessary to assign appropriate permission scopes. For operations related to creating and modifying workflow instances, the following scope is required: App.UserDefAPI.ReadWrite, which allows reading data sources and workflow instance data, using automations and operations on the workflow instance in the selected application. This scope should be assigned to the REST application in the Application permissions (scopes) section.

Granting privileges to an application user

When the User Defined API endpoint is called using the ClientID and ClientSecret of a configured REST application, the operation is performed in the context of the user whose credentials (name, login, email) were specified when the application was created. To be able to register a new order in WEBCON BPS, it is necessary to give this user the appropriate privileges in WEBCON BPS Designer Studio.

This user must have privileges to start workflow instances in the corresponding processes. In addition, to access defined endpoints, the user calling the endpoint must have at least the Access to the application type privilege granted from the BPS application level.

Without the required privileges, the integrating application will not be able to create new workflow instances, even if the appropriate permission scopes have been configured.

Summary

User Defined API in WEBCON BPS opens a new chapter in business process integration. Thanks to this functionality it is possible to create fast, secure, and fully customized connections to external systems for the organization. This tool not only facilitates integration, but also accelerates the development of business applications, increasing the flexibility and efficiency of the entire organization.