Skip to main content
Version: 2025 R2

API Definitions

This functionality allows you to create a simple REST API definition, through which you can integrate an external system with WEBCON BPS in the context of a selected process.

API Definition

1. Basic information​

The Name field allows you to enter name for this API definition. In the Documentation field, you can optionally enter description of the API definition, which will be available in the generated process documentation. ID is an automatically generated API definition identifier and is not filled in by the configuring user.

2. Running mode​

Allows you to specify the behavior that will be launched after the endpoint defined here is called. The following options are available:

  • Execute automation – the API made available from the external application level will enable you to launch automation, the definition of which should be created in the Automation tab. The POST type calls are supported.

  • Get data from the data source – API will allow you to retrieve values ​​from the specified source. The configuration of the source and filters for this source are available on the Data source tab. The GET type calls are supported.

  • Get data from an element instance – API will allow you to retrieve values ​​from the specified workflow instance. The scope and type of data returned after calling this type of endpoint is defined in the Element data tab. To indicate which instance data should be returned when calling this type of API, at the end of the call path, provide the instance ID, e.g., https://webcon.bps/api/udef/db/1/MyEndpoint/123 The GET type calls are supported.

3. Active​

Select this checkbox to make the configured endpoint available to the external system calling it. Unchecking it results in saving the configuration, but the endpoint is not be available to the system calling it.

4. Endpoint URL​

Allows you to specify the address used for calling the API definition by an external system. The address is partially generated automatically and will have the following form: https://{BPS_Portal}/api/udef/db/{dbId}/MyEndpoint. Under this configuration, define the last part of the address MyEndpoint. The variables {BPS_Portal} and {dbId} are filled in automatically. A fully generated address is displayed under the address configuration control.

The endpoint address can consist of several subdirectories separated by the / character. The name of each of them can contain digits, but names consisting only of digits are prohibited.

Example

The address configuration: MyData/v1/invoices results in making the API available under the https://webconbps.com/api/udef/db/1/MyData/v1/invoices address.

In the case of the Get data from an element instance mode, the API call requires a reference to a workflow instance. In this case, a segment containing the workflow instance ID should be added to the API call path.

Example

https://webconbps.com/api/udef/db/1/MyEndpoint/123

5. Authentication mode​

Prior to calling the API, authentication of the calling system in WEBCON BPS is required. Authentication can be done in two ways:

  • API Application authentication (OAuth2) – authentication is done using a token based on the defined public-access application. The description of the REST public-access application configuration is included in the chapter Applications with API access.

When configuring REST application, you can use the Application Context and/or the User Context. In order for the endpoint to be called in the context of a defined user, it is necessary to assign the respective scope of permissions in the REST application configuration.

For Application Context, the following permission scopes apply: App.UserDefAPI.Read.All – reading data sources and instance data in all applications App.UserDefAPI.ReadWrite.All – reading data sources and instance data, using automation and operations on the instance in the selected application

For User Context, the following permission scopes apply: User.UserDefAPI.Read.All – reading data sources and instance data in all applications User.UserDefAPI.ReadWrite.All – reading data sources and instance data, using automation and operations on the instance in all applications User.UserDefAPI.Read.<AppGuid> – reading data sources and instance data in the selected application User.UserDefAPI.ReadWrite.<AppGuid> – reading data sources and instance data, using automation and operations on the instance in the selected application

  • User authentication in BPS Portal (Cookie) – authentication is done using cookies at the WEBCON BPS Portal level. This mode does not require additional configuration. It can be useful when calling an endpoint via Java Script code from a custom HTML control embedded within a form or application dashboard to retrieve or set specific data using the API. Access to application and process data is limited according to the permissions of the logged-in user within whose context the endpoint is called.

Regardless of the authentication method, the user under whose context the endpoint is called must have at least the Application access permission to have access to the defined endpoints. Additionally, if the called API performs operations on process instances, user must also have the respective permissions for the given process or instance (e.g., to register a new instance or modify an existing one). It is worth emphasizing that holding permissions to instances only at the process level, without application permissions, prevents the endpoint from being called.

6. Access restrictions​

The rule allows you to define additional conditions under which the endpoint is available or not. If no rule has been defined and the field is left empty, calling the API definition depends on the user's permissions to the application or the respective scopes of permissions.

If user has the respective permissions to the application, and the defined rule returns the value POSITIVE, TRUE or 1, access to the endpoint will be granted. If the rule returns other values, the API request will be blocked and an attempt to call the endpoint will return the 403 error.

The access restriction rule should be used for the authentication mode User authentication in BPS Portal (Cookie). In this mode, any user logged into the Portal is able to call the endpoint. Permissions to perform a specific operation (e.g., reading instance data or performing an action) are verified during its implementation. However, when the operation applies to global data (i.e., the data not related to a specific instance), it is worth limiting access to the endpoint to a specific group of users.

OpenAPI Endpoint Documentation​

For the main node API Definitions in the navigation tree, there is a toolbar with a button that allows you to generate and download definitions of created APIs in the OpenAPI format. This format allows for easy sharing, documenting, and testing of APIs, ensuring consistency and compliance with the best system integration practices.

OpenAPI