Skip to main content
Version: 2021.1

BPS SDK

WEBCON BPS SDK is a set of libraries which make it possible to create plugins that allow complete customization of the WEBCON BPS system to meet all business needs. The extensions are run within the WEBCON BPS system, so they have to be implemented in Microsoft .NET Framework technology, e.g. using the C# language. After registering within the system, they can be used in any process. The SDK infrastructure is an integrated part of WEBCON BPS and is available immediately after installation. You can use all plugins provided by WEBCON or partner companies. To develop and use your own plugins, you may need an additional SDK license (it depends on your type of installation and owned licenses).

SDK overview​

Implementing a plugin consists of 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 as well as properties. SDK plugins can be divided into two parts – one associated with the logical part of the control or logical operation (e.g. transferring data to an external system), and second associated with displaying the user interface of the control in a specific environment. There is no requirement to create the user interface for your plugins. Running the logical part of the plugin is independent from the UI part. Both parts can be run separately depending on your needs.

The SDK consists of two libraries:

WebCon.WorkFlow.SDK.SP which contains base classes for controls displayed in the classic SharePoint interface. These classes allow creating and presenting customized user interface.

WebCon.Workflow.SDK which contains base classes for the logical parts of plugins, containers for data, configuration attributes, exceptions, and SDK tool classes. These classes allow manipulating, converting data and executing own logic without an additional interface.

Plugins templates​

The process of creating the SDK plugin is very simple. You can create your projects manually using Class Library for the logical part, and SharePoint Project for the UI part, but you can also make use of provided templates that make this operation even more effortless.

Types of plugins with examples of use cases​

Custom actions​

  • Validation
  • Communicating with external system
  • Changing form field values
  • Generating custom signature
  • Assigning tasks

Custom business rules​

  • Validation
  • Implementing complicated logic and calculations
  • Changing form appearance
  • Changing form behavior

Custom data sources​

  • Loading data from external sources that can’t be handled by built-in data providers

Item list extensions​

  • Item list validation
  • Modify the appearance and operations of the item list control

Form field extensions​

  • Changing default form field appearance
  • Making user interface appearance dependent on various factors
  • Providing custom logic

Custom controls​

  • Displaying additional data such as reports and charts
  • Displaying data from and saving to external systems

Custom label printing templates​

  • Creating custom label (stickers for marking documents) appearance
  • Handling printouts by an external system

Hello World Example​

-Download

To begin creating your own plugins, it is best to start off with writing a custom action. It is a relatively simple plugin which provides very big possibilities at the same time. An example of a custom action used very frequently in many business scenarios 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 a scenario where the submission and acceptance of vacation applications is executed within the WEBCON BPS system, and then every approved vacation application creates a corresponding entry about the employee’s vacation in the HR system. In such case, the custom action passes the data from the WEBCON BPS instance to the HR system and is triggered when the instance in a WEBCON workflow traverses along the ‘Accept’ path, marking the acceptance of the vacation by the employee’s superior. In the example, the action retrieves the data concerning the vacation dates and the employee from the instance within the WEBCON BPS database. This data includes the Start date, End date, and Requestor fields. After the vacation is registered in the HR system, the HR system then returns the ID of this entry in response. The action stores this ID in the VacationID field of the original workflow instance. For convenience and code transparency, the const fields which store the identifiers of the form fields from the WEBCON BPS system are listed in the action.

// Form fields identifiers in the process configuration
// Form field that contains start date of a vacation request
private const int StartDateFormFieldID  = 14;  
// Form field that contains end date of a vacation request  
private const int EndDateFormFieldID    = 15;
// Form field that contains requestor login of a vacation request    
private const int RequestorFormFieldID  = 16;    
// Form field to store the identifier that registered vacation obtained in HR external system
private const int VacationIDFormFieldID = 17;

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

// Configurable properties - properties that can be configured 
// in Designer Studio in the action configuration form
[ConfigEditableText(DisplayName = "WebserviceURL", Description = "URL of vacation webservice", IsRequired = true)]
// URL to Vacation webservice
public string WebServiceUrl { get; set; }

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 scope 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 being requested. As a result, the web service returns the ID assigned to this vacation in the HR system.

public override void Run(RunCustomActionParams args)
{
    try
    {
        // create web service client
        var client = new VacationWebServiceClient(WebServiceUrl);
        // prepare input parameters - read them from the Form Fields
        var registerVacationParams = new RegisterVacationParams
        {
            StartDate = args.Context.CurrentDocument.DateTimeFields.GetByID(StartDateFormFieldID).Value.Value,
            EndDate = args.Context.CurrentDocument.DateTimeFields.GetByID(EndDateFormFieldID).Value.Value,
            Requestor = args.Context.CurrentDocument.PeopleFields.GetByID(RequestorFormFieldID).Values.First().BpsID
        };
        // call web service method
        var result = client.RegisterVacation(registerVacationParams);
        // store the result in the Form Field
        args.Context.CurrentDocument.TextFields.GetByID(VacationIDFormFieldID).Value = result.VacationID;
    }
    catch (Exception ex)
    {
        // when something goes wrong you can stop the workflow
        args.HasErrors = true;                  // Mark that there was error in the action
        args.Message = "Error: " + ex.Message;  // Prepare the message for end users
        args.LogMessage = ex.ToString();        // Prepare log entry
    }
}

The instance of a RunCustomActionParams class passed as a parameter to the Run method allows the action to be labelled as executed incorrectly – by setting HasErrors property to true. This results in the termination of workflow processing, and the path transition 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.