Form fields and item lists

Resources identificators

There are two ways to specify resources in the API – by ID and by GUID. They can be used interchangeably, but in most cases we recommend using GUIDs because they are unchanged. You can be sure that the application will refer to the same resources after migrating processes between different environments. The exception are objects that are not transferred between environments – workflow instances and attachments (they are identified only by IDs). GUID of each object can be found in the WEBCON BPS Designer Studio. Where can we find this option? It is available under the button next to the field containing the ID.

The screen below shows the location of the button for the workflow:

Form fields

It is possible to set form fields values of API – you can use one of the dedicated endpoints:

• PATCH /api/data/v5.0/db/{dbId}/elements/{id} to edit existing element or
• POST /api/data/v5.0/db/{dbId}/elements to start new element with desired values.

Values of form fields can be sent in two different ways – by string representation using to svalue property and by a strongly typed object (depending on the type, using value attribute). API supports 26 different types of form fields. Their type can be found in the WEBCON BPS Designer Studio, or using API by either getting an existing element (described here) or getting form layout (/api/data/v5.0/db/{dbId}/formlayout).

As example we will use a people picker field. Here is data that we get from an element:

{
  "value": [
    {
      "id": "t.green@webcon.pl",
      "name": "Thomas Green"
    }
  ],
  "id": 392,
  "guid": "3238dbbd-3aff-4985-a531-cc5753fc6b59",
  "type": "People",
  "svalue": "t.green@webcon.pl#Thomas Green",
  "name": "Employee"
}

Of course, the get method returns additional metadata that doesn’t need to be sent to set the field value, i.e. the name and type are returned only to make the contract easier to read by humans. ID and GUID are used for field identification. GUID is main property, so if you provide both system will use GUID. In the case of a people picker, the strongly typed value is an object consisting of two parts, BPS ID of user and it’s display name. The text value, on the other hand, takes the format id#name. Both of these properties set the field value in the same way, the choice of one of them depends on the user’s preferences. if you provide both system will use tybed value.

Here is example API call that updates our example field and save workflow instance:

curl -X PATCH "http://dev20/WEBCONBPS/api/data/v5.0/db/1/elements/1393" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI"  
-H "Content-Type: application/json " 
-d "{\"formFields\":[{\"value\":{\"id\":\"s.lee@webcon.pl\",\"name\":\"Stan Lee\"},\"guid\":\"3238dbbd-3aff-4985-a531-cc5753fc6b59\"}]}"

Each field value can be cleared by sending either empty string in svalue or null in value. Below is a list of supported field models. In addition, all models for a given version are available in the swagger documentation at [your portal address]/api.

Single line of text (Standard field)

type: SingleLine
value: string

example:

 "value": "Sample singleline value"

Single line of text (Hyperlink field)

type: HyperLink
value: object
{
"url": string,
"name": string
}

example:

  "value": { "url": "http://support.webcon.pl/webconbps", "name": "Support" }

Single line of text (Image field)

type: ImageLink
value: object
{
"url": string,
"name": string
}

example:

   "value": { "url": "http://intranet.company.com/employee/123/picture", "name": "Thomas Green" }

Multiple lines of text

type: Multiline
value: string,

example:

   "value": "Sample multiline value. \n Second line."

Multiple lines of text with append mode

type: Comments
value: object
{
"newComment": string
"existingEntries": array of readonly comments
[
"commentEntry": object
{
"author": string,
"comment": string,
"date": string ($date-time iso format)
}
]
}

example:

   "value": { "newComment": "This is my new comment" }

Integer number

type: Int
value: integer ($int32)

example:

   "value": 5

Floating-point number

type: Decimal
value: number ($double)

example:

   "value": 3.14

Date and time

type: Date
value: string ($date-time – dd-MM-yyyy format) ,

example:

   "value": "24.01.2010"

Date and time with enabled time selection

type: DateTime
value: string ($date-time – iso format)

example:

   "value": "2020-01-21T21:32:49Z"

Yes/No choice

type: Boolean
value: boolean

example:

   "value": true

Email

type: Email
value: string

example:

   "value": "t.green@webcon.pl"

Rating scale

type: RatingScale
value: integer ($int32)

example:

   "value": 5

Picture

type: Picture
value: string ($base64)

example:

   "value": "RXhhbXBsZQ=="

Handwritten signature

type: HandwrittenSignature
value: string ($base64) 

example:

   "value": "RXhhbXBsZQ=="

Google map with generation base on coordinates

type: CooridnatesMap
value: object
{
"longtitude": number ($double),
"latitude": number ($double)
}

example:

   "value": {
"longtitude": 50,061106,
"latitude": 19,937782
}

Google map with generation base on address

type: AddressMap
value: string

example:

"value": "Cracow, Market Square 20"

Model shared by all the following fields

• Person or group – type: People
• Choice field with dropdown – type: ChoiceList
• Choice field with autocomplete – type: Autocomplete
• Choice field with popup search window – type: ChoicePicker
• Choice tree – type: ChoiceTree

value: array of objects
[
  {
    "id": string,
    "name": string
  }
]

example:

"value": [
  {
    "id": "t.green@webcon.pl",
    "name": "Thomas Green"
  }
]

Item lists

This part describes all the options of editing item lists using REST API. API allows to add, remove and edit a list’s rows, as well as reinitialize it with values configured in WEBCON BPS Designer Studio. Let’s start with a simple example that allows us to add two rows to the list and move workflow instance to next step. We will use standard instance edit endpoint – /api/data/v5.0/db/{dbId}/elements/{id}. It is described in more detail in this article.

Here is a sample Json content request that adds two new rows and sets two columns for each. Column types are single line of text and choice field.

{
"itemLists": [
    {
      "guid": "e7884f6b-2810-452a-b3cb-6711c64eaf9e",
      "rows": [
        {
          "cells": [
            {
              "value": [
                {
                  "id": "t.green@webcon.pl",
                  "name": "Thomas Green"
                }
              ],
              "guid": "fe53f415-ef41-4f03-bf1f-82b3b5e22365"
            },
            {
              "svalue": "Central Europe",
              "guid": "912a4c12-2e0e-4a93-8c11-df0197a072e1"
            },
          ]
        },
        {
          "cells": [
            {
              "value": [
                {
                  "id": "s.lee@webcon.pl",
                  "name": "Stan Lee"
                }
              ]
              "guid": "fe53f415-ef41-4f03-bf1f-82b3b5e22365"
            },
            {
              "svalue": "North Europe",
              "guid": "912a4c12-2e0e-4a93-8c11-df0197a072e1"
            },
          ]
        }
      ]
    }
  ]
}

And here is curl:

curl -X PATCH "http://dev20/WEBCONBPS/api/data/v5.0/db/1/elements/1393?path=default" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI" 
-H "Content-Type: application/json" 
-d "{\"itemLists\": [ { \"guid\": \"e7884f6b-2810-452a-b3cb-6711c64eaf9e\", \"rows\": [ { \"cells\": [ { \"value\": [ { \"id\": \"t.green@webcon.pl\", \"name\": \"Thomas Green\" } ] \"guid\": \"fe53f415-ef41-4f03-bf1f-82b3b5e22365\" }, { \"svalue\": \"Central Europe\", \"guid\": \"912a4c12-2e0e-4a93-8c11-df0197a072e1\" }, ] }, { \"cells\": [ { \"value\": [ { \"id\": \"s.lee@webcon.pl\", \"name\": \"Stan Lee\" } ] \"guid\": \"fe53f415-ef41-4f03-bf1f-82b3b5e22365\" }, { \"svalue\": \"North Europe\", \"guid\": \"912a4c12-2e0e-4a93-8c11-df0197a072e1\" }, ] } ] } ]}"

Let’s take a look at each property:

• itemList is an array of instance’s item list that we want to edit. In example we edited just one list, but it is possible to send multiple list objects
• guid is an item list identifier, there is also an id property that can be used
• rows is an array of item lists’ rows that we want to edit. Example shows how to add new row. To edit exising row, you should send also that row id identifier. To delete existing row just pass that row identifier and flag delete set to true, example: {“rows”: { “id”: 9, “delete”: true }} Row identifier can be obtained using the element get method (/api/data/v3.0/db/{dbId}/elements/{id})
• cells is an array of cells for specific row, you edit then in the same way as you edit form fields. Cell identifier is an ID or guid of corresponding list column. Keep in mind that you don’t need to send each cell data. Cells that have not been sent retain their previous values, or are set to default value in case of new rows.

Advanced item list edit scenario

REST API also allows you to easily edit the list if you want to provide the full list’s status. Simply add the mode parameter to list model with either “Exact” or 1. The difference from the standard mode is that all non-forwarded values will be removed for rows or cleared for values. The behavior for editing or adding rows is the same as for incremental (standard) mode. This means that when the identifier is given, the row will be edited, otherwise a new one will be created. The delete flag does not apply to this mode, because as previously mentioned, all rows that were not passed will be deleted.

List initialization

It is possible to reload the list value in a similar way as you can do it on form in the browser. There is dedicated endpoint to do so – POST /api/data/v5.0/db/{dbId}/elements/{id}/itemlists/{itemlistid}/init. Operation will use the same setting as standard button, so first you should configure Initialization settings in Designer Studio. Also the show reload button option should be check in order to use this endpoint. Reinitialization will clear item list data, then add pre-configured values and save workflow instance.

Example below will reload values of list ID 282 on element ID 1393:

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