Columns in collections

<< Click to Display Table of Contents >>

Navigation:  Bizagi API > Basic concepts > Common lookup services >

Columns in collections

Overview

Bizagi features OData services, which handle a comprehensive set of resources, some which let you use an HTTP POST to start a new process, complete a pending activity or event (workitem), or trigger an action.

To use these HTTP POST-based  services, you may first need to determine which is the data structure or input parameter you need for a collection.

 

The following section describes how to interpret the columns set up in a form using a collection, so you can send out correct values when starting a new process, completing a workitem or triggering an action, that require information related to the collection.

 

Scope of the resource

Information about columns in a collection is retrieved by default when you query a process (attributes of the type Entity) in a start form when creating a new case, in an activity form when completing a workitem, or as input when triggering an action.

 

Resource URL

Information about columns used by collections is available for these resources, whenever any resource returns information about an Xpath of the type Collection:

[your_bizagi_project_url]/odata/data/processes([ID_process])

[your_bizagi_project_url]/odata/data/processes([ID_process])/cases([ID_case])/workitems([ID_workitem])

[your_bizagi_project_url]/odata/data/cases([ID_case])/workitems([ID_workitem])

[your_bizagi_project_url]/odata/data/stuff([ID_stuff])/values([ID_value])/actions([ID_action])

[your_bizagi_project_url]/odata/data/searches([ID_search])/actions([ID_action])

[your_bizagi_project_url]/odata/data/searches([ID_search])/results([ID_result])/actions([ID_action])

[your_bizagi_project_url]/odata/data/relevants([ID_relevant])

[your_bizagi_project_url]/odata/data/relevants([ID_relevant])/actions([ID_action])

 

 

Example

The following image illustrates how you can send an HTTP GET for this resource:

 

OData_CollectionDataType

 

Returned results include multiple values inside of a Collection-type Xpath, one for each of the columns in that form (typically in a table control).

The columns element, contains:

Name: The unique name of the attribute as a column.

Id: A string-based GUID representing the URI of that specific reference.

Xpath: The Xpath to that attribute from the collection entity.

Type: The type of data of the attribute. For a list of possible values of data types in Bizagi, refer to Types of data.

 

Based on the column information, and to send out input parameters for a collection, build the following structure for this specific Xpath:

 

{

    "startParameters": [

        {

            "xpath": "MyProcessEntity.MyCollection",

            "type": "collection",

            "rows": [

                         {

                    "columns": [

                         {

                            "xpath": "FullName",

                            "value": "Juliette Leroy"

                        },

                        {

                            "xpath": "Income",

                            "value": "300000"

                        }

                    ]

                },

                {

                    "columns": [

                         {

                            "xpath": "FullName",

                            "value": "Piotr Blanter"

                        },

                        {

                            "xpath": "Income",

                            "value": "300000"

                        }

                    ]

                }

            ]

        }

    ]

}

 

The example above, sends out two new rows for the MyCollection collection, while filling out two columns: FullName and Income.

The image below shows another example, and the response you receive when creating a new case for a given process:

 

OData_SendCollection

 

 

Edit Records of a collection

To edit a record in your collection, you must implement a business key in your entity. Afterward, if you send an existing key inside the "columns" section, along with the attributes you want to edit, the current record updates its information.

 

For example, let's assume that in the previously shown case, you set the FullName as the business key.

 

If you send the following startParameter JSON:

{
    "startParameters": [
        {
            "xpath": "MyProcessEntity.MyCollection",
            "type": "collection",
            "rows": [
                {
                    "columns": [
                {
                            "xpath": "FullName",
                            "value": "Juliette Leroy"
                        },
                        {
                            "xpath": "Income",
                            "value": "400000"
                        }
                    ]
                }
           ] 
        }
    ]
}

 

Bizagi doesn't create a new record but updates the existing one, increasing Juliette Leroy salary to 400000.

 

note_pin

When you add a business key to an entity, you must be aware of the following considerations:

Some rules or policies might be affected by the use of a business key.

Once you add a business key, you can't go back to not having a business key.

The OData layer must expose your business key, so don't use sensitive information as your key.

To use virtualization and the OData layer you must have permissions to create new records on the database

When you add a business key to your Production environment, if the business key is not well defined some collisions may arise in the deployment

 

Restrictions

Nested collections (collections inside of collections) are not supported by these services.

You can fill a collection with values directly, but you cannot fill out a collection inside of a collection.

You cannot delete rows that are already created in a collection.