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.

1. Basic information

The Name field allows you to enter a name for this API definition. In the Documentation field, optionally enter a 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 on the Automation tab. 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 is available on the Data source tab. GET type calls are supported.

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

3. Activating the endpoint

This option should be checked so that the configured endpoint is available to the external system calling it. Unchecking saves the configuration, but the endpoint will not be available to the system calling it.

4. Endpoint URL

Allows you to specify the address where the API definition will be available for invocation by an external system. The address is partially generated automatically and will look like this: https://{BPS_Portal}/api/udef/db/{dbId}/MyEndpoint. In this configuration point, you should define the last part of the address MyEndpoint. The variables {BPS_Portal} and {dbId} will be filled in automatically. The full 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

Configuring the address as MyData/v1/invoices will make the API available at https://webconbps.com/api/udef/db/1/MyData/v1/invoices

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

Example

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

5. Authentication mode

Before 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 will be 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 a REST application, you can use both the Application Context and the User Context. In order for the endpoint to be called in the context of the defined user in the REST application configuration, it is necessary to grant the appropriate scope of permissions.

In the case of Application Context these are the scopes of permissions: App.UserDefAPI.Read.All - reading data sources and element data in all applications App.UserDefAPI.ReadWrite.All - reading data sources and element data, using automation and operations on the element in the selected application

In the case of User Context these are the scopes of permissions: User.UserDefAPI.Read.All - reading data sources and element data in all applications User.UserDefAPI.ReadWrite.All - reading data sources and element data, using automation and operations on the element in all applications User.UserDefAPI.Read.<AppGuid> - reading data sources and element data in the selected application User.UserDefAPI.ReadWrite.<AppGuid> - reading data sources and element data, using automation and operations on the element in the selected application

• User authentication in BPS Portal (Cookie) – authentication will be performed using cookies from 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 in a form or application dashboard to retrieve or set some data using the API. Access to application and process data will be limited according to the permissions of the logged-in user in whose context the endpoint is called.

Regardless of the authentication method, the user in 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 elements, the user must also have the appropriate permissions for the given process or element (e.g. to register a new element or modify an existing one). It is worth emphasizing that having permissions to elements 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 will be available or not. If the rule has not been defined and the field is left empty, calling the API definition depends on the user's permissions to the application or the appropriate scopes of permissions.

If the user has the appropriate 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 a 403 error.

The access restriction rule should be used in the case of the authentication mode: User authentication in BPS Portal (Cookie). In this mode, any user logged into the Portal will be able to call the endpoint. Permissions to perform a specific operation (e.g. reading element data or performing an action) are verified at the stage of its implementation. However, when the operation concerns global data (i.e. not related to a specific element), 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 best practices in system integration.