BPS SOAP API

Getting Started

BPS SOAP 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.

BPS SOAP 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 service

In order to use SOAP 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 SOAP 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 SOAP 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 SOAP 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 SOAP 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.

// Form field identifiers in the process configuration
// Form field that contains complaint issuer's name
private const int ClientNameFormFieldID = 12;  
// Form field that contains complaint issuer's address         
private const int ClientAddressFormFieldID = 21;
// Form field that contains complaint issuer's zip code        
private const int ClientZipCodeFormFieldID = 22;   
// Form field that contains complaint issuer's city     
private const int ClientCityFormFieldID = 24; 
// Form field that contains date of purchase of a product          
private const int PurchaseDateFormFieldID = 18;      
// Form field that contains complaint description and explanation   
private const int ComplaintDescriptionFormFieldID = 3;

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

// object identifiers in BPS Complaint Process
// complaint document type ID
const int docTypeID = 2;   
// complaint workflow     
const int workFlowID = 2;  
// path id to start a new complaint workflow     
const int startPathID = 11;

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

// create BPS SOAP API proxy client
var client = new BPSWebserviceClient("BasicHttpBinding_BPSWebservice");
client.ClientCredentials.Windows.ClientCredential = System.Net.CredentialCache.DefaultNetworkCredentials;
client.ClientCredentials.Windows.AllowedImpersonationLevel = System.Security.Principal.TokenImpersonationLevel.Impersonation;

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

 // Step 1 - get new empty element prefilled with defaults
GetNewElementParams getNewElementParams = new GetNewElementParams()
{
    DocTypeId = docTypeID,
    WorkFlowId = workFlowID
};
NewElement element = client.GetNewElement(getNewElementParams);

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.

// Step 2 - fill form field values
element.TextAttributes.First(x => x.Id == ClientNameFormFieldID).Value = formData.ClientName;
element.TextAttributes.First(x => x.Id == ClientAddressFormFieldID).Value = formData.ClientAddress;
element.TextAttributes.First(x =>; x.Id == ClientZipCodeFormFieldID).Value = formData.ClientZipCode;
element.TextAttributes.First(x => x.Id == ClientCityFormFieldID).Value = formData.ClientCity;
element.DateTimeAttributes.First(x => x.Id == PurchaseDateFormFieldID).Value = formData.PurchaseDate;
element.TextAttributes.First(x => x.Id == ComplaintDescriptionFormFieldID).Value = formData.ComplaintDescription;
// Create attachment object
var attachment = new Attachment()
{
    FileName = "image.jpg",
    Description = "Photo",
    FileType = ".jpg",
    Content = FileResolver.GetStubFileBytes()
};

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.

// Step 3 - start new complaint workflow
StartWorkFlowParams startWorkFlowParams = new StartWorkFlowParams
{
    Element = element,
    AttachmentsToAdd = new[] { attachment },
    PathId = startPathID
};
ExistingElement result = client.StartWorkFlow(startWorkFlowParams);

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.