2023.1

Metadata

REST API allows you to get metadata about the applications and their components, such as workflows, steps and form fields. Those endpoints require metadata permissions that can be set in Designer Studio for specific application. All endpoints use the same pattern, except for the formlayout one, which will be discussed later. The most general endpoints allow you to get list of specified objects, for example /api/data/v5.0/db/{dbId}/applications returns an array of all WEBCON BPS applications that the user has permissions for. Each array object has its own ID, GUID and name listed, as well as the links to related resources. Those objects list endpoints are listed below along with the required scops (Here you can read more about scopes). They all follow the standard ID/GUID principle, which is further described here.

  • GET /api/data/v5.0/db/{dbId}/applications [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] – mentioned above, returns applications
  • GET /api/data/v5.0/db/{dbId}/applications/{idguid}/processes [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] – returns all processes defined under the selected application as well as linked processes
  • GET /api/data/v5.0/db/{dbId}/processes/{idguid}/workflows [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] – returns selected process workflows metadata
  • GET /api/data/v5.0/db/{dbId}/processes/{idguid}/formtypes [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] – returns selected process form types metada
  • GET /api/data/v5.0/db/{dbId}/workflows/{idguid}/steps [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] – returns list of steps for specific workflow
  • GET /api/data/v5.0/db/{dbId}/steps/{idguid}/paths [Scopes: App.Metadata.Read; App.Metadata.ReadWrite] – returns avaliable paths for selected step

Each object returned from any of those endpoints has link to itself in the links section, here is example links property for a sample application:

"links": [
        {
          "href": "/api/data/v5.0/db/1/applications/06642e39-8577-9541-bbde-77879e4d7564",
          "method": "GET",
          "rel": "self"
        }
      ]

The second category are endpoints that return detailed metadata for a single resource. Those are the same endpoints that we got in the self-links above. They will contain the same properties as the previous methods, i.e. ID, GUID, name, links as well as extended properties specific for each resource. Usually it will be the description, in case of application it will also be the parent group name.

Here are all available endpoints and required scopes:

  • GET /api/data/v5.0/db/{dbId}/applications/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]
  • GET /api/data/v5.0/db/{dbId}/process/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]
  • GET /api/data/v5.0/db/{dbId}/workflows/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]
  • GET /api/data/v5.0/db/{dbId}/formtypes/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]
  • GET /api/data/v5.0/db/{dbId}/steps/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]
  • GET /api/data/v5.0/db/{dbId}/paths/{idguid} [Scopes: App.Metadata.Read; App.Metadata.ReadWrite]

If resource has child resources, the links array will contain address to that child. For applications it will be a list of processes, for a process it will be a list of workflows and list of form types, and so on. Here is example links section for a workflow:

"links": [
    {
      "href": "/api/data/v5.0/db/1/workflows/12/steps",
      "method": "GET",
      "rel": "steps"
    }
  ]

Form Layout

The form layout endpoint does not fall in any of the above categories. It allows you to get all the necessary layout metadata for a specific step and form type. Here is example formlayout request, query parameters :

curl -X GET "http://dev20/WEBCONBPS/api/data/v5.0/db/1/formlayout?step=43&formType=9" 
-H "accept: application/json" 
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn (…) eyJiYWWqrZ6FdBI"

The response contains three main properties: fields, itemLists and paths. Let’s take a look at each property:

  • paths – collection of paths available for selected step. Each path has ID, GUID, name, description and visibility enum. Visibility has three possible values: Visible, Hidden and Conditional. Last one means that path visibility is based on dynamic rules, and can vary depending on user or field values.
  • fields – collection of all fields (excluding item lists) that can be configured in the Designer Studio field matrix for a specified step and form type, it including field grouping elements like tabs and groups. Each field has ID, GUID, name, type (one of field types described here), requiredness, visibility, position and parentId.
    • requiredness can have one of three values: Mandatory, Optional, and Conditional – for fields whose requiredness is dynamically modified by business rules
    • visibility have the same values as paths.visiblity, so it can be visible, hidden and conditional for dynamic rules
    • position has two properties: an order that returns an int value that specifies the order of the field in the layout and a placeholder that specifies which panel the field is in
    • parentId is id of a parent form field, for example group field
  • itemLists – is similar to fields, but contains only item list fields. Each item list has all properties that standard field has, as well as the columns property
    • columns contains list of that item list’s columns, each column has ID, GUID, name, type, requiredness and visibility

Links

Almost every metadata endpoint, as well as tasks and reports endpoints have links section in response. Those are standard HATEOS links to related resources. Links is an array property, that can be found on single resource. Each link has three properties:

  • href – is a relative url to another api endpoint for specific related resource or operation
  • method – describes HTTP method for href endpoint
  • rel – describes relation to that resource, for example, ‘self’ means that endpoint will return more data for selected resource and ‘next’ will return another portion data
← Attachment operationsError responses →