Properties and querying options

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > OData services > Basic concepts >

Properties and querying options

Overview

Bizagi features OData services which handles a comprehensive set of resources related to the Experience design, as described at Bizagi API.

For such resources, you may choose to 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, the 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

Shows up once per invocation.

Contains an URL directing to the service's metadata (in XML format), which in turn specifies the types of data and field being queried.

[your_bizagi_project_url]/odata/metadata/$metadata

@odata.count

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

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

50

@odata.id

Shows up per 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 you would use in a next invocation so that you can consider the "following page" of the same set of results (provided that there are next results which 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

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

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

100

 

Filtering results

Whenever fetching multiple results within an invocation response (i.e, typically a collection of values) through an HTTP GET action, you may rely on the use of the standard (based on OData specs) $filter option (URL query param), in order to narrow down those results you want according to some criteria.

 

Some of the most common operators per the OData specs are supported by Bizagi and are described in the table below:

 

TYPE

OPERATOR

DESCRIPTION

Simple

eq

Equals operator to compare (strings) and consider an exact match.

ne

A not equals operator to compare (strings) and consider that it is not an exact match.

Simple but with a function-based notation

Contains

An operator to consider if a substring is held inside of the complete string value.

Complex

any

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

all

An operator to narrow down information while iterating a collection, while considering as a valid result, one where all of its records necessarily meet the criteria.

 

Notice that all response information are strings (as data type), and therefore, operators and values need to go inside of apostrophes (' ' characters).

 

Filtering with simple operators

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

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

 

Consider for its use:

[operator]: You may use eq / ne.

[value]: The value to compare with.

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

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

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

[your_bizagi_project_url]: Corresponds to the URL where end users access the Bizagi Work portal.

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

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

While for Bizagi PaaS 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'), you would use $filter with the following syntax (while similarly being able to chain further filters):

[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]

 

A first example using one simple operator, would be filtering the cases resource, by making sure a specific case by its ID is retrieved:

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

 

OData_Filter1

 

Another example using one simple operator could evaluate what is in an inner collection of case information.

This example filters results so that it fetches only those processes that do not consider a parameter of Xpath type, named exactly as 'Score'.

In other words, those processes which do not demand a score is sent in order to start a new case:

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

 

OData_FilterNE

 

Lastly, an example chaining more than one 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) --filters out those in yellow state:

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

 

OData_Filter3

 

Notice that the above uses the Contains operator, which uses a different notation resembling how you would use a function in most programming languages.

 

Filtering with complex operators

For complex operators such as any, all, you may 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])

 

Consider for its use:

[complex_operator]: You may use any  / all.

[simple_operator]: You may use eq / ne.

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

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

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

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

[your_bizagi_project_url]: Corresponds to the URL where end users access the Bizagi Work portal.

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

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

While for Bizagi PaaS projects, such URL would be:

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

 

A first example 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

 

 

Similarly, to chain more than one filter (i.e, using 'and'/'or'), you would use $filter with the following syntax (while similarly being able to chain further filters):

[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

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

Therefore and to implement a query that handles pagination, use these parameters as described in the table below.

 

PARAMETER

DESCRIPTION

EXAMPLE

$top

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

Its use is set as $top=n where n determines the amount of first results to consider.

The following invocation will fetch only the first 5 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 a fixed amount of  first results, so that returned results start from that point on.

Its use is set as $skip=n where n determines the starting point regarding results.

The following invocation will fetch Stakeholders starting off from the 6th one:

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

 

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

$count

Makes the service include information about the amount of records fetched.

Its use is set as $count=true.

The following invocation will fetch only the first 5 Stakeholders in a project while including the @odata.count property with the number of results in this invocation:

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

 

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

The following is a sample response when querying Stakeholders as per the URL in the examples above, and while using 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

Acknowledge the following URL which returns a list of n results:

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

 

Consider for its use:

[odata_service]: The name of the OData service which is 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]: Corresponds to the URL where end users access the Bizagi Work portal.

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

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

While for Bizagi PaaS projects, such 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 may best handle large amount of results.

For instance and while using the same URL specified above, this newer invocation fetches 50 results, parting from the result number 1001:

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

 

note_pin

Note that as with standard URLs and services, query parameters are appended to the base URL followed by the ? sign.

And, multiple parameters are separated by means of the & sign.

 

Expanding results

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

Therefore and to implement a query that retrieves such information into the same invocation, use these parameters as described below.

 

This means that you may use $expand with the following syntax:

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

 

$expand example

Let's part from 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 given stakeholder (queried by its ID) does not include by default information from the Doctor's My Stuff, as shown below:

 

OData_Expand1

 

Notice that for the simplicity of the example, we don't highlight contexts information given that it is not as relevant.

 

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

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

 

OData_Expand2

 

Then, we could rely on the $expand option to fetch the My Stuff information at once when querying information from the Doctor stakeholder, as done initially.

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

 

OData_Expand3