Skip to main content
Version: 2023.1

Workflow instances

A single workflow instance consists of many elements. In this article we will discuss the individual parts that we can get through most basic endpoint that is used to retrieve information about a particular instance – /api/data/v5.0/db/{dbId}/elements/{id}. To use this endpoint, we will need permissions for this element and one of the scopes below. You can read more about scopes in this article.

Required scopes: [App.Elements.Admin.All; App.Elements.Read.All; App.Elements.ReadWrite.All; User.Elements.Admin.All; User.Elements.Admin.<ProcGuid>; User.Elements.Read.All; User.Elements.Read.<ProcGuid>; User.Elements.ReadWrite.All; User.Elements.ReadWrite.<ProcGuid>]

The endpoint response is divided into following sections:

Header – contains element basic metadata such as id, instance number, version, author, step, workflow and form type information.

Here’s example header section:

"header": {
    "id": 240,
    "instanceNumber": "Api/2020/01/00017",
    "version": 5,
    "author": {
      "bpsId": "t.green@webcon.pl",
      "name": "Thomas Green"
    },
    "updatedBy": {
      "bpsId": " t.green@webcon.pl ",
      "name": "Thomas Green"
    },
    "creationDate": "2020-01-16T08:16:03.504Z",
    "modificationDate": "2020-01-16T08:16:03.504Z",
    "finishDate": "2020-01-16T08:16:03.504Z",
    "enterToCurrentStepDate": "2020-01-16T08:16:03.505Z",
    "step": {
      "id": 43,
      "guid": "adb07a18-95f3-40e6-a0f0-a54552fdc88e"
    },
    "workflow": {
      "id": 12,
      "guid": "d1fd2660-669e-4f84-9e1b-88814fef3365"
    },
    "company": {
      "id": 1,
      "guid": "E554D815-F958-463A-B4DD-E2EB29B29FF2"
    },
    "formType": {
      "id": 9,
      "guid": " f1905dde-12fc-46d5-a736-0dc61e838e5b"
    },
    "parentInstanceId": 205
 }

FormFields​

FormFields – contains listed form fields data. Only fields visible on the form are returned. Every field has its id, guid, type, name, value as object and svalue as string representation of a value. A full description of the supported fields along with their models is available in this article.

Here’s example an formFields section:

"formFields": [
    {
      "value": "Holiday request",
      "id": 176,
      "guid": "993c843e-112f-44ac-8c44-e8fb1fc521fa",
      "type": "SingleLine",
      "svalue": "Holiday request",
      "name": "Title"
    },
    {
      "value": [
        {
          "id": "t.green@webcon.pl",
          "name": "Thomas Green"
        }
      ],
      "id": 164,
      "guid": "f4b3024b-9feb-43a1-a6b7-00f2691a9eef",
      "type": "ChoicePicker",
      "svalue": "t.green@webcon.pl#Thomas Green",
      "name": "Superior"
    }
]

ItemLists​

ItemLists – contains metadata of an instance item lists. Similar to fields it has id and guid, additionally each item list has an array of columns, and array of rows, and each row has its id and list of fields.

Here’s example an itemLists section:

"itemLists": [
    {
      "id": 3,
      "guid": "791ef030-2901-4bfb-8212-c2aa1af8aa2f",
      "name": "string",
      "mode": "Incremental",
      "columns": [
        {
          "id": 7,
          "guid": "E554D815-F958-463A-B4DD-E2EB29B29FF2",
          "type": "SingleLine",
          "name": "Invoice number"
        }
      ],
      "rows": [
        {
          "id": 25,
          "delete": false,
          "cells": [
            {
              "value": "INV/2020/01/12"
              "id": 9,
              "guid": "AA80F5F8-4634-4940-9E3D-3265EFDB6EB1",
              "svalue": "INV/2020/01/12"
            }            
          ]
        }
      ]
    }
  ]

Comments​

Comments – list of an instance’s comments. Each comment has author, content and date.

Here’s example comments section:

"comments": {
    "existingEntries": [
      {
        "author": "Thomas Green",
        "comment": "Sample comment",
        "date": "2020-01-16T08:16:03.506Z"
      }
    ],
    "newComment": ""
  }

Attachments​

Attachments – contains list of attachments metadata without their contents.

Here’s example attachments section:

"attachments": [
    {
      "id": 1132,
      "author": {
        "bpsId": "t.green@webcon.pl",
        "name": "Thomas Green"
      },
      "updatedBy": {
        "bpsId": "t.green@webcon.pl",
        "name": "Thomas Green"
      },
      "creationDate": "2019-11-26T11:33:39.87+01:00",
      "modificationDate": "2019-11-26T11:33:39.87+01:00",
      "version": 0,
      "name": "Holiday request.docx",
      "description": "",
      "group": "4#Additional documents"
    }

Tasks​

Tasks – contains list of users tasks and cc tasks with their substitutes for the selected instance.

Here’s example tasks section:

"tasks": {
    "directTasks": [
      {        
        "user": {
          "bpsId": "t.green@webcon.pl",
          "name": "Thomas Green"
        },
        "name": "Standard task",
        "description": "",
        "flag": "None",
        "isFinished": false,
        "isNew": false
      }
    ],
    "ccTasks": []
  }