16.01.2023 13:54
Please ask a question in the forum, it's the best way to get a quick answer
Applies to version: 2020.1.x; author: Marcin Wołosz
The WEBCON 2019 version introduced the possibility of using REST API technology to create programming integration solutions with the system. The REST API provides full support and allows you to start new workflow instances, transition paths, and modify the content of the instances. WEBCON BPS 2020 has API in version 2.0 which will be used in the examples below.
Authentication
API uses bearer token authentication. How can you get a token? You need to register the application in the admin panel (available only for the administrator of the default content database . The panel is available at: [Portal_address]/adminPanel.
Registering the application will generate two important pieces of information: ClientID and ClientSecret, which are necessary to get this token. Since the launch of the 2020 version, there is a possibility to create multiple ClientSecret.
The most important thing is to save the generated key, because it isn’t stored by us and if you will lose it, it cannot be viewed again.
There is also a possibility of using “Impersonation” which allows you to call API in the context of a specific user.
Before starting your tests, you need to give your newly registered App the privileges to start the process – you can do this in exactly the same way as you would assign privileges to regular users or groups.
For testing we will use the API verification tool – called Postman and a simple, two-step process containing several standard form fields and one item list.
- Obtaining a token – /api/login
In Postman we create the first REQUEST – POST for the LOGIN method. No authentication is required.
In the header we set ‘Content-Type’ to application/json and in the body using JSON we send the previously generated ClientID and ClientSecret.
REQUEST:
URL: https://at03.webcon.pl/api/login
{
"clientId": "61cd212a-ad42-4d14-a547-6a628d6e7485",
"clientSecret": "IenbtQ2POBj03TxLculhZfHmZrFlemvcTvxqI0o0jIE="
}
This method has returned a token needed for authentication in subsequent methods.
RESPONSE:
{
"token":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc
2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L21kZW50aXR5
L2NsYWltcy9uYW1lIjoicmVzdGFwaUB3ZWJjb24ucGwiLCJodHR
wOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L21kZW
50aXR5L2NsYWltcy9uYW1laWRlbnRpZmllciI6InJlc3RhcGlAd
2ViY29uLnBsIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcv
d3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvZ212ZW5uYW1lIjo
icmVzdGFwaUB3ZWJjb24ucGwiLCJyZWdpc3R1cmVkX2FwcCI6Ij
YxY2QyMTJhLWFkNDItNGQxNC1hNTQ3LTZhNjI4ZDZ1NzQ4NSIsI
kFzcE5ldC5JZGVudGl0eS5TZWN1cml0eVN0YW1wIjoiUEhBQ1JS
WUJKR1VBV1pRMkxMSkJQNFRIQIRGU0hJQOsiLCJuYmYiOjE1ODA
0NzMxNjgsImV4cCI6MTU4MDU1OTU2OCwiaXNzIjoiV0VCQ090IF
BvcnRhbCJ9.N_czfz94iYyAnzDDZZ6G5WHSOVwe35ptiFK6WMk5
-qA"
}
Postman:
- Loading instance info - /api/data/v2.0/db/{dbId}/elements/{id}
The instance information is downloaded using GET REQUEST and {dbID}, {id} parameters.
In this method we must use the token for authentication:
In response we receive information about the instance.
{
"header": {
"id": 19,
"instanceNumber": "REST/2020/01/00011",
"version": 3,
"author": {
"bpsId": "RESTAPI@webcon.pl",
"name": "RESTAPI - Registered App"
},
"updatedBy": {
"bpsId": "tom.green@webcon.com",
"name": "Tom Green"
},
"creationDate": "2020-01-31T13:55:49.14+01:00",
"modificationDate": "2020-01-31T14:07:55.8+01:00",
"finishDate": "2020-01-31T13:55:48.91+01:00",
"enterToCurrentStepDate": "2020-01-31T13:55:48.91+01:00",
"step": {
"id": 17,
"guid": "26e671c4-8f52-4aa3-9bd2-7aca5f92828b"
},
"workflow": {
"id": 6,
"guid": "6b65a2d2-79fc-4190-bbb5-e6dd9e352a1f"
},
"company": {
"id": 1,
"guid": "E554D815-F958-463A-B4DD-E2EB29B29FF2"
},
"formType": {
"id": 6,
"guid": "bc6a5791-3c52-4370-9d48-d5df54b8036f"
}
},
"formFields": [
{
"id": 59,
"guid": "db669fb4-81d7-470c-8f51-5287f7f8edb2",
"type": "People",
"svalue": "tom.green@webcon.com#Tom Green",
"name": "Autor",
"value": [
{
"id": "tom.green@webcon.com",
"name": "Tom Green"
}
]
},
{
"id": 60,
"guid": "3cc97cec-bb1d-4f42-82b1-016dd4be7499",
"type": "Multiline",
"svalue": "",
"name": "Opis",
"value": null
},
{
"id": 61,
"guid": "7582b693-c161-417c-a13f-3835b9f60712",
"type": "Date",
"svalue": "2020-01-11",
"name": "Data rejestracji",
"value": "2020-01-11T00:00:00.0000000+01:00"
}
],
"itemLists": [
{
"id": 62,
"guid": "9f3074bf-6342-4090-b31d-a25411f74342",
"name": "Poświęcony czas",
"mode": 0,
"columns": [
{
"id": 9,
"guid": "edc5359d-ca3f-4695-8d9a-bde43342cdba",
"type": "Autocomplete",
"name": "Osoba"
},
{
"id": 10,
"guid": "915da93b-967a-4b5e-b1e0-9d4f2e48f155",
"type": "Date",
"name": "Data"
},
{
"id": 11,
"guid": "34e8eb1b-cb17-4ece-97f8-26aeeb2d2d94",
"type": "Decimal",
"name": "Czas"
}
],
"rows": [
{
"id": 21,
"cells": [
{
"id": 9,
"guid": "edc5359d-ca3f-4695-8d9a-bde43342cdba",
"svalue": "18565#testAPI@webcon.pl",
"value": [
{
"id": "18565",
"name": "testAPI@webcon.pl"
}
]
},
{
"id": 10,
"guid": "915da93b-967a-4b5e-b1e0-9d4f2e48f155",
"svalue": "2020-01-30",
"value": "2020-01-30T00:00:00+01:00"
},
{
"id": 11,
"guid": "34e8eb1b-cb17-4ece-97f8-26aeeb2d2d94",
"svalue": "2.00",
"value": 2.0
}
]
},
{
"id": 22,
"cells": [
{
"id": 9,
"guid": "edc5359d-ca3f-4695-8d9a-bde43342cdba",
"svalue": "18565#testAPI@webcon.pl",
"value": [
{
"id": "18565",
"name": "testAPI@webcon.pl"
}
]
},
{
"id": 10,
"guid": "915da93b-967a-4b5e-b1e0-9d4f2e48f155",
"svalue": "2020-01-31",
"value": "2020-01-31T00:00:00+01:00"
},
{
"id": 11,
"guid": "34e8eb1b-cb17-4ece-97f8-26aeeb2d2d94",
"svalue": "3.00",
"value": 3.0
}
]
}
]
}
],
"comments": {
"existingEntries": [
{
"author": "Tom Green",
"comment": "test",
"date": "2020-01-31T14:07:55+01:00"
}
],
"newComment": ""
},
"attachments": [],
"tasks": {
"directTasks": [],
"ccTasks": []
}
}
- Starting a new instance – /api/data/v2.0/db/{dbId}/elements
In this case we will use the same authentication as in the previous example. The only change is to use POST REQUEST and add required PATH parameter containing the path we want to transition with.
In the body it is necessary to send information such as: workflow ID/GUID, business entity ID/GUID and form type ID/GUID. Sending all form fields is not necessary. The GUIDs of form fields can be used from the previous example.
Example of REQUEST.
URL: https://at03.webcon.pl/api/data/v2.0/db/6/elements?path=15
{
"workflow": {
"id": 6,
"guid": "6b65a2d2-79fc-4190-bbb5-e6dd9e352a1f"
},
"company": {
"id": 1,
"guid": "E554D815-F958-463A-B4DD-E2EB29B29FF2"
},
"formType": {
"id": 6,
"guid": "bc6a5791-3c52-4370-9d48-d5df54b8036f"
},
"formFields": [
{
"id": 59,
"guid": "db669fb4-81d7-470c-8f51-5287f7f8edb2",
"type": "People",
"svalue": "tom.green@webcon.com#Tom Green",
"name": "Autor",
"value": [
{
"id": "tom.green@webcon.com",
"name": "Tom Green"
}
]
},
{
"id": 61,
"guid": "7582b693-c161-417c-a13f-3835b9f60712",
"type": "Date",
"svalue": "2020-01-11",
"name": "Data rejestracji",
"value": "2020-01-11T00:00:00.0000000+01:00"
}
],
"itemLists": [
{
"id": 62,
"guid": "9f3074bf-6342-4090-b31d-a25411f74342",
"name": "Poświęcony czas",
"mode": 0,
"columns": [
{
"id": 9,
"guid": "edc5359d-ca3f-4695-8d9a-bde43342cdba",
"type": "Autocomplete",
"name": "Osoba"
},
{
"id": 10,
"guid": "915da93b-967a-4b5e-b1e0-9d4f2e48f155",
"type": "Date",
"name": "Data"
},
{
"id": 11,
"guid": "34e8eb1b-cb17-4ece-97f8-26aeeb2d2d94",
"type": "Decimal",
"name": "Czas"
}
],
"rows": [
{
"id": 0,
"cells": [
{
"id": 9,
"guid": "edc5359d-ca3f-4695-8d9a-bde43342cdba",
"svalue": "18565#testAPI@webcon.pl",
"value": [
{
"id": "18565",
"name": "testAPI@webcon.pl"
}
]
},
{
"id": 10,
"guid": "915da93b-967a-4b5e-b1e0-9d4f2e48f155",
"svalue": "2020-01-30",
"value": "2020-01-30T00:00:00+01:00"
},
{
"id": 11,
"guid": "34e8eb1b-cb17-4ece-97f8-26aeeb2d2d94",
"svalue": "2.00",
"value": 2.0
}
]
},
{
"id": 0,
"cells": [
{
"id": 9,
"guid": "edc5359d-ca3f-4695-8d9a-bde43342cdba",
"svalue": "18565#testAPI@webcon.pl",
"value": [
{
"id": "18565",
"name": "testAPI@webcon.pl"
}
]
},
{
"id": 10,
"guid": "915da93b-967a-4b5e-b1e0-9d4f2e48f155",
"svalue": "2020-01-31",
"value": "2020-01-31T00:00:00+01:00"
},
{
"id": 11,
"guid": "34e8eb1b-cb17-4ece-97f8-26aeeb2d2d94",
"svalue": "3.00",
"value": 3.0
}
]
}
]
}
]
}
RESPONSE
{
"id": 4,
"instanceNumber": "REST/2020/01/00013",
"status": "MovedToNextStep"
}
The workflow instance registered by using REST API:
- Updating an existing instance – /api/data/v2.0/db/{dbId}/elements/{id}
The modification requires PATCH REQUEST. In the simplest case, it involves saving the workflow instance – you can optionally use a transition path through the REST API. In the body we send only what we want to modify. Other values don’t have to be sent.
REQUEST:
URL: https://at03.webcon.pl/api/data/v2.0/db/6/elements/21
{
"formFields": [
{
"id": 60,
"guid": "3cc97cec-bb1d-4f42-82b1-016dd4be7499",
"type": "Multiline",
"svalue": "TEST",
"name": "Opis",
"value": "TEST"
}
]
}
REPONSE:
{
"id": 4,
"instanceNumber": "REST/2020/01/00013",
"status": "Saved"
}
The above examples are only a small part of what we can do with REST API. We can also use it to:
- Download and modify attachments
- Delete instances
- Download tasks for users
- Download information about processes
- and a lot more
The full documentation in the swagger form is available at: [Portal_address]/api and in the version with SharePoint at: [Portal_address]/webconbps
Comments (2)
Login to add comment
Login
16.01.2023 12:03
Hello,
Could pass example how to add attachment and post action in post action?
I can create case via post, add values to attribiutes but when I added a part with attachment and comment, it does not work.
It works only when i use patch method. I have BPS version: 2021.1.5.307
part Example of my code bellow:
,
"comments": {
"newComment": "TEST"
},
"attachments": [
{
"content": "VEVTVA==",
"name": "Nowy dokument tekstowy.txt",
"description": ""
}
]
Could pass example how to add attachment and post action in post action?
I can create case via post, add values to attribiutes but when I added a part with attachment and comment, it does not work.
It works only when i use patch method. I have BPS version: 2021.1.5.307
part Example of my code bellow:
,
"comments": {
"newComment": "TEST"
},
"attachments": [
{
"content": "VEVTVA==",
"name": "Nowy dokument tekstowy.txt",
"description": ""
}
]
office@webcon.com
+48 12 443 13 90
+48 12 443 13 90