BPS SDK

BPS SDK is a plugin mechanism enabling the creation of own extensions in the BPS system. The SDK libraries consist of two parts. One is the base class set used in individual types of plugins. The latter is the object model and tool class set for performing selected operations in the system. The specifics of the plugins is that they are executed within the system and some of them have the ability to plug into the internal logic of document workflow processing. Owing to that, they provide great possibilities when integrating or extending the system.

SDK overview

The plugin mechanism is executed within the system. That is why, it requires plugins to be implemented in NET Framework (examples in C# language below).
Implementing a plugin consists in inheriting a class from an appropriate base class and then overriding relevant methods and finally including the logic of the plugin within them. Each plugin type has its own base class and a set of virtual methods.

Plugins are divided into three groups. Those creating and presenting own user interface, executing own logic without an additional interface and only responsible for operating on the data. All of those groups have access to the data entered by the user in the standard form fields.
SDK plugin types

Plugins with own user interface

The plugins creating own interface or modifying the look of existing controls include: custom controls, field customizations, custom item list controls and item list customizations. They are responsible for creating the user interface part. The data collected within them can be saved in BPS system fields as well as in external repositories.

Plugins extending the system’s logic

The plugins without own interface include custom actions and flow control classes. Custom actions enable execution of own logic during the system workflow and they are the most frequently used type of plugins. They also have the biggest capability in conjunction with the system’s standard functions.

Plugs operating on data

Plugins which operate on data are custom data sources and custom label printout templates. Custom data sources allow for the presentation and usage of external data in the system. It is also quite a frequently used type of plugin.

Hello World Example download_xs

It is best to start the creation of own plugins with writing the custom action. It is a relatively simple plugin which provides very big possibilities at the same time. A frequent example of applying own custom action is calling the web service exposed by the external system.

The Hello World Example puts the information about an employee’s vacation to the HR system (external system) through the web service exposed by that system. This illustrates the scenario where submission and acceptance of vacation applications is executed in the BPS system, whilst every vacation application must create an appropriate entry about the employee’s vacation in the HR system.
In such case, the custom action passes the data from the BPS element to the HR system and is triggered when the element in the BPS system follows the Accept path, marking the acceptance of the vacation by the superior.

In the example, the action retrieves the data concerning the vacation dates and the employee from the element within the PBS. Those are the Start date, End date and Requestor fields. After the vacation is registered in the HR system, the HR system returns the ID in response. The action stores this ID received in the VacationID field.

Creating and executing an extension requires a few steps. A library with plugins need to be created, an action needs to be implemented within it and then deployed and registered in the system. There is a description of the action code below.

For the convenience and code transparency, the const fields which store the identifiers of the used form fields from BPS are listed in the action.

The URL address referring to the web service to call can be prepared in the plugin as a configuration property. Then, it will be possible to set different value in the test environment and in the production one. For that purpose, the property WebServiceUrl must be decorated with an appropriate attribute.

Next, you should override the Run method from the base class and place the web service execution within it along with forwarding appropriate parameters and storing the vacation identifier received from the web service in the form field.

Preparing a client class to the web service is out of the range of this example, thus it has been omitted here. It can be prepared in any way – using the WSDL tool or by creating a service reference in Visual Studio.

In the Run method it is necessary to create a client object to the web service, provide it with the URL to connect to and finally invoke the RegisterVacation method. As parameters, it requires the vacation start and end dates as well as the details of the person whose vacation is requested. As a result, the web service returns the ID assigned to this vacation in the HR system.

The instance of a RunCustomActionParams class passed as a parameter to the Run method allows for labelling the action as executed incorrectly by setting HasErrors property to true. This results in the termination of workflow processing and going through the whole path to which the action is attached fails in such a situation.
Apart from the error indication, appropriate messages for users can be set using property Message. Furthermore, additional information can be logged in LogMessage. It will be accessible to the process administrator but inaccessible to regular users.