BPS Web API

Getting Started

BPS Web API enables the external systems to perform operation on workflow elements and their attachments. The accessible attribute elements and operations on the elements correspond to capabilities of a regular system user.

Web API is a SOAP based web service, hosted in SharePoint. It runs by default on the basis of NTLM authentication. The Web service can be consumed by any technology, whilst creating a client for it is particularly easy thanks to the WSDL file with contract description being shared by the web service.

Main concepts

Calling the web service

In order to use Web API comfortably, it is best to generate an object proxy in the code to consume the methods of the web service. The API contracts are made of a few objects associated with each other and it is much easier to use object representation rather than directly create and parse XML/SOAP messages.

Depending on the technology and tools used to create applications, object proxy can be generated directly from the web service endpoint or from the shared WSDL file.

Most operations of the web service work in a similar manner. They are based on the three steps interaction concept.

  1. Firstly, the method returning the object containing an element from the BPS system with the filled initial data shall be executed.
    When starting a new element, the object is filled with the default values. For the existing element it contains its current state in the database.
  2. Then, the field values and possibly the attachments’ values on the object received shall be filled.
  3. The supplemented object must be passed to the method which will perform an entry of the element in the system or a transition to the next step of the workflow.

Once the third step has been performed, the element shall be modified in the BPS system. In order to make interaction easier, those methods return the objects which include the operation status information and possible messages simplifying error diagnosis.

Available operations

Operations available in Web API

  • Creating a new element in the BPS system
  • Editing an existing element
  • Moving an element to the next step
  • Deleting an element
  • Adding a new attachment
  • Retrieving an element’s attachments
  • Deleting an attachment
  • Adding and deleting a substitution definition

Most of those operations require performing a retrieve-fill-execute sequence but there are also operations performed by triggering an individual method such as deleting operations or operations on substitutions.

Hello World Example Download

A frequent example of the BPS Web API usage is creating a new element in the system, adding an attachment to it or starting a workflow using a designated path.

The example of Hello World below simulates the scenario of making a complaint by a dedicated WWW page and creating a new complaint in the BPS system using the Web API from the code level of that webpage. In the WWW application, the client enters his contact details, the details of the product concerned in the complaint and can also attach a picture presenting the reason for the complaint.
This entered data is used to create a new element in the BPS complaint workflow, whilst the pictures are added to the element as attachments. Integration between the two systems takes place through the Web API which is executed from the code level of the WWW application.

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

Also for code transparency it is possible to list the identifiers of workflow, document type, and start path in complaint handling flow.

In order to operate on the Web API methods, a web service client instance needs to be created.

The first stage of creating a new element in BPS involves invoking the API method: GetNewElement for retrieving the new element to run.

Then, the element received shall be filled with data. In order to add an attachment, an appropriate type of object must be created for it and filled with the attachment’s binary metadata.

As the last step, the method starting a new workflow shall be triggered. Apart from the data of the element to be started, a list of attachments for association with that element may be provided. A path within the workflow for starting the element must also be selected.

Having performed the StartWorkFlow method correctly, the element will be created in the system. It will be located in the step to which the selected path leads. It will have the tasks assigned in accordance with the process configuration.