Properties and querying options

Overview

Bizagi features OData services to handle a comprehensive set of resources related to the Experience design, as described in the Bizagi API.

For such resources, you can include filters or navigate data returned by the response by relying on standard properties and querying options.

Properties

For every set of results returned by the OData services, a successful response includes a set of standard properties which are preceded by the @ sign.

These properties are:

Filtering results

When you fetch multiple results with an invocation response (typically a collection of values) through an HTTP GET action, you can use the standard (based on OData specs) $filter option (URL query param), to narrow down the results to those that match criteria.

Some of the most common operators per the OData specs are supported by Bizagi:

All response information is in strings (as data type). Operators and values need to go inside of apostrophes (' ' characters).

Filtering with simple operators

For simple operators such as and, or, eq, ne, you can use $filter with the following basic syntax:

[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$filter=[field_resource] [operator] [value]

Customizations:

•[operator]: Use eq / ne.

•[value]: The value to compare with.

•[field_resource]: The particular field within the invocation response which contains multiple results. A typical example in Bizagi would be values.

•[odata_service]: The name of the OData service which, either data or metadata.

•[odata_resource]: The OData resource you are querying which returns multiple results within its response. An example in Bizagi would be querying stakeholders.

•[your_bizagi_project_url]: The URL where end users access the Bizagi Work Portal.

For an on-premise Bizagi project, such URL would be:

https://[your_server]/[your_project]/

For Automation Service projects, such URL would be:

https://[project_environment]-[your_project]-[your_company].bizagi.com/

When chaining more than one filter (i.e, using 'and'/'or'), use $filter with the following syntax (chaining as many further filters as you need):

•[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$filter=[field_resource] [operator_1] [value_1] and [operator_2] [value_2]

•[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$filter=[field_resource] [operator_1] [value_1] or [operator_2] [value_2]

This example uses one simple operator, and filters the cases resource, to retrieve a case by its ID:

.../cases?$filter=caseNumber eq '1169'

This example uses one simple operator to evaluate what is in an inner collection of case information.

This example filters results so to fetch only those processes that do not consider a parameter of Xpath type named 'Score'.

Those processes which do not demand a score are sent to start a new case:

.../processes?$filter=parameters/xpath ne 'Score'

Finally, an example chains several filtering criteria using and / or.

In this case we are fetching all pending activities which are either on time (green state) or expired (red state). The query filters out those in the yellow state:

.../workitems?$filter=Contains(state, 'green') or Contains(state,'red')

The query uses the Contains operator, which uses a different notation that resembles how you would use a function in most programming languages.

Filtering with complex operators

For complex operators such as any and all, you can use $filter with the following basic syntax:

[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$filter=[collection_resource]/[complex_operator](p:p/[attribute_in_collection] [simple_operator] [value])

Customization:

•[complex_operator]: You may use any or all.

•[simple_operator]: You may use eq or ne.

•[value]: The value to compare with (used by the simple_operator).

•[collection_resource]: The collection within the invocation response values, which contains multiple results to iterate over. A typical example in Bizagi would be parameters.

•[odata_service]: User data or metadata.

•[odata_resource]: The OData resource you are querying and which returns multiple results within its response. An example in Bizagi would be querying stakeholders.

•[your_bizagi_project_url]: The URL where end users access your Bizagi Work Portal.

For an on-premise Bizagi project, the URL would be:

https://[your_server]/[your_project]/

For Automation Service projects, the URL would be:

https://[project_environment]-[your_project]-[your_company].bizagi.com/

A search using the any operator would seek processes for which there is at least one parameter of the type 'Collection':

...processes?$filter=parameters/any(p: p/type eq 'Collection')

To chain more than one filter (i.e, using 'and' and 'or'), use $filter with the following syntax (chaining as many filters as you need):

•[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$filter=[collection_resource]/[complex_operator](p:p/[attribute1_in_collection] [simple_operator_1] [value1]

and p/[attribute2_in_collection] [simple_operator_2] [value2)

•[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$filter=[collection_resource]/[complex_operator](p:p/[attribute1_in_collection] [simple_operator_1] [value1]

or p/[attribute2_in_collection] [simple_operator_2] [value2])

Pagination of results

When fetching results through an HTTP GET action, you may use the standard (based on OData specs) $top and $skip options (URL query params), to implement pagination, especially if the service returns a large number of results.

To implement a query that handles pagination, use these parameters:

Bizagi automatically includes in the response the @odata.totalCount and @odata.nextLink properties.

Here is a sample response when you query Stakeholders as per the URL in the examples above, and use pagination of results:

{

 "@odata.context": "[your_bizagi_project_url]/odata/metadata/$metadata#stakeholders",

 "@odata.totalCount": 16,

 "value": [

   {

     "@odata.id": "[your_bizagi_project_url]/odata/metadata/stakeholders(e6e38460-2f33-4804-bddf-46058843c314)",

     "id": "e6e38460-2f33-4804-bddf-46058843c314",

     "name": "Client",

     "displayName": "Client",

     "iconName": "bz-icon-ctg bz-icon-ctg-helicopter"

   }

 ],

 "@odata.nextLink": "[your_bizagi_project_url]/odata/metadata/stakeholders?$top=1&$skip=1"

}

$top and $skip example

The following URL returns a list of n results:

[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]

Customization:

•[odata_service]: Either data or metadata.

•[odata_resource]: The name of the resource (URI) being queried. Examples are: stuff, searches, relevants, processes, stakeholders.

•[your_bizagi_project_url]: The URL where end users access your Bizagi Work Portal.

For an on-premise Bizagi project, the URL would be:

https://[your_server]/[your_project]/oauth2/server/token

For Automation Service projects, the URL would be:

https://[project_environment]-[your_project]-[your_company].bizagi.com/oauth2/server/token

Then, by appending parameters such as $top and $skip, you can handle large number of results.

For instance, while using the same URL specified above, fetch 50 results, starting from result number 1001, with this invocation:

[your_bizagi_project_url]/odata/[odata_service]/[odata_resource]?$top=50&$skip=1000

Expanding results

Whenever you fetch results through an HTTP GET action, you can use the standard (based on OData specs) $expand option (URL query param), to fetch additional information (from child resources), into the same invocation.

To implement a query that retrieves such information into the same invocation, use these parameters:

[your_bizagi_project_url]/odata/[odata_service]/[parent_odata_resource]?$expand=[child_odata_resource]

$expand example

Let's start with the following query that fetches stakeholders' information:

Taking as an example, the information from the Doctor stakeholder as shown above, we notice that fetched details for that stakeholder (queried by its ID) do not include by default information from the Doctor's My Stuff, as shown below:

To keep the example simple, we don't highlight contexts information since it is not as relevant.

However we know we can get My Stuff information, since it is a resource available (/stuff) which is bound to a stakeholder (i.e., the Doctor).

The My Stuff collections for the Doctor in this example consists basically of the Medical equipment, as shown below:

We can rely on the $expand option to fetch the My Stuff information at once when querying information from the Doctor stakeholder, as we did initially.

This would "merge" the stakeholders details with the My Stuff collections in a single response: