BPS REST API

Getting Started

BPS REST API is available by the following URL:

<BPS Portal URL>/api/data

Where BPS Portal URL is the base URL of the BPS Portal in your network environment. For example, you have your company’s server www.mycompany.com, and BPS Portal configured to be accessible by www.mycompany.com/webconbps.

/api/data is the context path for the BPS REST API.

For the sample base URL above, REST API URL is:

https://www.mycomapny.com/webconbps/api/data

BPS REST API is available in all types of installations since BPS 2019, and enables external systems to perform operations on workflow instances and their attachments.

BPS REST API is RESTFull Web service, hosted in BPS Portal. It uses JSON Web Token (JWT) authentication method. The Web service can be employed by any technology that can use HTTP requests.

Main concepts

Calling service

To call WEBCON BPS REST API, your application must acquire an access token, which contains information about your application and the permissions it has. To call any method, you attach the access token as a Bearer token to the authorization header in an HTTP request, and send that request to selected endpoint.

The API supports the following HTTP methods:

• GET – read data from a resource
• POST – create resource or perform an action
• PATCH – update a resource with new values

Available operations:

• Creating new instances in the WEBCON BPS system
• Editing an existing instance
• Moving an instance to the next step
• Adding new attachments
• Retrieving an instance’s attachments

Hello World Example

-Download

A frequent example of the WEBCON BPS Web API usage is creating a new instance 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 WEBCON BPS system using the REST API from the code level of that webpage. In the WWW application, the client enters his contact details, the details of the product relevant to the complaint, and can also attach a picture to supplement the complaint. This data is then used to create a new instance in the WEBCON BPS complaint workflow, whilst the pictures are added to the instance as attachments. Integration between the two systems takes place through the REST API which is executed from the code level of the WWW application.

For transparency, we named parameters that will be passed to REST API. We will also set sample values that can be changed to match those in your environment.

// form field identifiers in the BPS Complaint Process
ClientNameFormFieldID = 136;    // form field that contains complaint issuer's name
ClientAddressFormFieldID = 137; // form field that contains complaint issuer's address
ClientZipCodeFormFieldID = 138; // form field that contains complaint issuer's zip code
ClientCityFormFieldID = 139;    // form field that contains complaint issuer's city
PurchaseDateFormFieldID = 140;  // form field that contains date of purchase of a product
ComplaintDescriptionFormFieldID = 141;  // form field that contains complaint description and explanation
ClientName = "Tom Green";
ClientAddress = "Babinskiego 69";
ClientZipCode = "30-393";
ClientCity = "Krakow";
PurchaseDate = "19-03-2019";
ComplaintDescription = "Description...";
// object identifiers in the BPS Complaint Process
workflowID = 22;  // complaint workflow ID
docTypeID = 24;   // complaint document type ID
startPathID = 121;    // path id to start a new complaint workflow
dbId = 1; // content database ID where the complaint process is stored

In order to make calls to BPS REST API, first we need to get an authorization token. Only registered applications can get token. Global admins can manage applications from the admin panel, which is available at /adminpanel. The following screenshot shows a sample web application registration.

Now that we have a registered application and we’ve generated client id and secret, we can get the authorization token by calling the /api/login method with client id and client secret as body parameters. Then we add received token as a Bearer token to the authorization header.

POST /api/login HTTP/1.1
{
    "clientId": "639fa26f-5bb8-4f11-b8e9-9c585bfd08bb",
    "clientSecret": "6630e3b2-f9a6-499c-883e-70c799494e35"
}

{
    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJodHRwOi8vc2NoZW1hcy54bWx..."
}

Token truncated for readability

Now we can create new element in BPS by calling the API method at endpoint

 /api/data/v5.0/db/{dbid}/elements?pathId={strartPathId}

In the body we will pass workflow id, document type id and fields that we want to fill. Below are examples for request and response.

POST /api/data/v5.0/db/1/elements?pathId=121 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs(...)vQ0v7__8P-DmWQY
{
    "workflow": {
        "id": workflowID
    }, 
    "formType": {
        "id": docTypeID
    },
    "formFields": [
        {
            "id": ClientNameFormFieldID,
            "value": "ClientName"
        },
        {
            "id": ClientAddressFormFieldID,
            "value": "ClientAddress"
        },
        {
            "id": ClientZipCodeFormFieldID,
            "value": "ClientZipCode"
        },
        {
            "id": ClientCityFormFieldID,
            "value": "ClientCity"
        },
        {
            "id": PurchaseDateFormFieldID,
            "value": "PurchaseDate.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)"
        },
        {
            "id": ComplaintDescriptionFormFieldID, 
            "svalue": "ComplaintDescription"
        }
    ]          
}

{
    "id": 29,
    "instanceNumber": "Api/2019/03/00010",
    "status": "MovedToNextStep"
}

Having performed the start workflow method correctly, the instance will be created in the system. It will be located in the step to which the selected start path leads. It will have the tasks assigned in accordance with the process configuration in WEBCON BPS Designer Studio.