$(document).ready(function(){highlight();});

Properties and querying options

<< Click to Display Table of Contents >>

Navigation:  Bizagi API > Basic concepts >

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:

 

PROPERTY

OCCURRENCE

DESCRIPTION

EXAMPLE OF ITS VALUE

@odata.context

Once per invocation.

Contains a URL for the service's metadata (in XML format), which specifies the types of data and field being queried.

[your_bizagi_project_url]/odata/metadata/$metadata

@odata.count

Once per invocation and applies when using Pagination of results while querying a resource which represents a collection.

Specifies the number of records fetched (an integer), while using $count=true in the URL.

50

@odata.id

For each element of a collection.

Contains an URL of each element in case you want to navigate into its detail.

[your_bizagi_project_url]/odata/metadata/stakeholders(f83b2142-e0c2-4d70-8da6-f987f86ff38d)

@odata.nextLink

Shows up once per invocation and applies when using Pagination of results.

Specifies the URL for the "following page" of the same set of results (applies for all pages except the last one).

[your_bizagi_project_url]/odata/metadata/stakeholders(e6e38460-2f33-4804-bddf-46058843c314)/relevants?$skip=4&$top=3

@odata.totalCount

Once per invocation and applies when using Pagination of results.

This property is not standard, and specifies the number of results for the resource (an integer), regardless of the number fetched in the current invocation (due to pagination).

100

 

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:

 

TYPE

OPERATOR

DESCRIPTION

Simple

eq

An equals operator to compare strings to find exact matches.

ne

A not equals operator to compare strings to find matches that are not exact.

Simple but with a function-based notation

Contains

An operator to consider whether a substring is part of the complete string value.

Complex

any

An operator to narrow down information while iterating over a collection; a valid result is, one where any of the records meet the criteria.

all

An operator to narrow down information while iterating over a collection; a valid result is one where all of records meet the criteria.

 

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'

 

OData_Filter1

 

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'

 

OData_FilterNE

 

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')

 

OData_Filter3

 

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')

 

OData_FilterComplex

 

 

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:

 

PARAMETER

DESCRIPTION

EXAMPLE

$top

Only returns a fixed amount of first results, and disregards the rest.

It returns $top=n where n determines the number of first results starting from the top of the list.

This invocation will fetch only the first five Stakeholders in a project:

[your_bizagi_project_url]/odata/metadata/stakeholders?$top=5

 

For a more detailed example, refer to the section below.

$skip

Disregards number of results, so the returned results start from that point on.

Use as $skip=n where n determines how many re-sults to skip, starting from the top.

This invocation fetches Stakeholders starting from the sixth one:

[your_bizagi_project_url]/odata/metadata/stakeholders?$skip=5

 

For a more detailed example, refer to the section below.

$count

The service includes information about the number of records fetched.

Use as $count=true.

This invocation fetches only the first five Stakeholders in a project while including the @odata.count property with the number of results returned in this invocation:

[your_bizagi_project_url]/odata/metadata/stakeholders?$top=5&$count=true

 

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

 

note_pin

As with standard URLs and services append query parameters to the base URL after a question mark and separate multiple parameters with ampersand (&).

 

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:

 

OData_Expand0

 

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:

 

OData_Expand1

 

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:

 

OData_Expand2

 

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:

 

OData_Expand3