Properties and querying options

<< Click to Display Table of Contents >>

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

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.

http://[your_company].bizagi.com/[your_project]/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.

http://[your_company].bizagi.com/[your_project]/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)

http://[your_company].bizagi.com/[your_project]/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

 

Pagination of results

Whenever fetching results through an HTTP GET action, you may rely on the use of the standard $top and $skip querying options 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:

https://[your_company].bizagi.com/[your_project]/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:

https://[your_company].bizagi.com/[your_project]/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:

https://[your_company].bizagi.com/[your_project]/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": "http://[your_company].bizagi.com/[your_project]/odata/metadata/$metadata#stakeholders",

 "@odata.totalCount": 16,

 "value": [

   {

     "@odata.id": "http://[your_company].bizagi.com/[your_project]/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": "http://[your_company].bizagi.com/[your_project]/odata/metadata/stakeholders?$top=1&$skip=1"

}

 

 

$top and $skip example

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

https://[your_company].bizagi.com/[your_project]/odata/[odata_service]/[odata_resource]

 

Consider for its use:

[your_company]: The name of your company.

[your_project]: The name of your Bizagi project. Recall that for environments other than the production environment, the project includes a suffix referencing the given environment.

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

 

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:

https://[your_company].bizagi.com/[your_project]/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.