Basic operations

WEBCON API uses the HTTP method on your request to determinate what action should be performed. The API supports following methods:

• GET – read data from a resource without its modification
• POST – create new resource or perform an action
• PATCH – update a resource with new values For the method GET no request body is required
• DELETE – delete single resource

The POST and PATCH methods require a request body specified in JSON format, that contains additional information. To perform the operation using the Rest API, you must have the appropriate permissions in BPS (https://howto.webcon.com/privileges-in-webcon-bps-2019/)

The Rest application account is treated in the same way as a regular user and can be granted permissions in BPS Designer Studio. In addition, remember that data permissions and the ability to perform operations in the Rest API are similar to those in the user interface, which means that you cannot get data from invisible fields or move to next step by invisible path.

Here is the list of basics operations on instances that can be done with API:

Starting new instance

POST /api/data/v5.0/db/{dbId}/elements?path={path}

Operation that starts new instance of a workflow. It supports setting fields and item lists values and adding attachments at the start step. Endpoint uses standard user privileges, so application or impersonated user should have launching instances permissions in order to use it. When starting new instance, you must provide:

• dbId – (query) describes which content database should be used in order to start instance
• path – (query) the transition path that will be used by started instance. Can be specified by three different values ID, guid or key word default
• workflow – (body) identifies the workflow within which a new instance will be created, can be specified by either guid or id
• formType – (body) identifies the form type that will be used for new instance

Below is example request that can be used to start empty element:

{
  "workflow": {
    "id": 21
  },
  "formType": {
    "guid": "64148798-6847-49e0-8450-52969c6db3f3"
  }
}

curl -X POST "http://dev20/WEBCONBPS/api/data/v5.0/db/1/elements?path=default" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI" 
-H "Content-Type: application/json" 
-d "{\"workflow\":{\"id\":21},\"formType\":{\"guid\":\"64148798-6847-49e0-8450-52969c6db3f3\"}}"

Getting metadata of existing instance

GET /api/data/v3.0/db/{dbId}/elements/{id}

Operation that returns existing instance metadata. In order to use that method, application or impersonated user needs instances access permissions.

Example request for getting instance data:

curl -X GET "http://dev20/WEBCONBPS/api/data/v5.0/db/1/elements/1393" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI"

Updating and moving existing instances

PATH /api/data/v5.0/db/{dbId}/elements/{id}

Operation that updates or moves selected instance. Requires user to have edit permissions in order to execute this method. The default behavior of the method is to save the workflow instance. In order to move instance to next step you must provide query parameter path. There are four different sections that can be edited via this endpoint: form fields, item lists, comments and attachments. You can provide either or none of them. Specific models for each group are described in workflow instances acticle.

Example request that edits field value and moves element to next step:

curl -X PATCH "http://dev20/WEBCONBPS/api/data/v5.0/db/1/elements/1393?path=1eabf644-5df1-48e8-a1ed-9b4950f8064f" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI" 
-H "Content-Type: application/json" 
-d "{\"formFields\":[{\"svalue\":\"t.green@webcon.pl#Thomas Green\",\"guid\":\"3238dbbd-3aff-4985-a531-cc5753fc6b59\"}]}"

Deleting instances

DELETE /api/data/v5.0/db/{dbId}/elements/{id}

Operation that is used to delete selected instance. Requires application or impersonated user to have instances delete permissions.

Example request:

curl -X DELETE "http://dev20/WEBCONBPS/api/data/v5.0/db/1/elements/1393" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI"