<< Click to Display Table of Contents >> Navigation:  Low-code Process Automation > Studio Cloud - Authoring environment > Bizagi Studio > Bizagi from external applications > Bizagi API > OData RESTful services > 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:

 

 

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

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

 

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

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

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 Personas as per the URL in the examples above, and use pagination of results:

{

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

 "@odata.totalCount": 16,

 "value": [

   {

     "@odata.id": "[your_bizagi_project_url]/odata/metadata/Personas(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/Personas?$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, Personas.

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

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 Personas' information:

 

 

Taking as an example, the information from the Doctor Persona as shown above, we notice that fetched details for that Persona (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 Persona (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 Persona, as we did initially.

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

 

 

Querying options with allusers parameter

When you query results, you can use the parameter allusers to get results for all users. Without this parameter you can only get results for the user that is logged in. There are multiple scenarios where you can use this parameter, which are explained in detail in the following section:

 

You can query all this options through Postman.

 

As a prerequisite, you must first generate a bearer token in the Work Portal and connect to your Bizagi project. The steps to do so are detailed in Bizagi API Authentication.

 

Select the type of method that you are going to excecute (GET, POST, DELETE, etc.). Type the URL of your project and then append the endpoint you are interested in. Send the request and the query result will be returned.

 

Return all cases of a process for all users or a specific case of a process for all users

Endpoint for all processes: /odata/data/processes(ID)/cases?$allUsers=true

Enpoint for a specific process: /odata/data/processes(ID)/cases(ID)?$allUsers=true

 

For this example you must have previously gotten the id of the process you are interested in. You can get the id by querying all the processes. Bear in mind to look for the id and no the processId parameter.

 

Once you have the id, you must replace ID in the endpoint  /odata/data/processes(ID)/cases?$allUsers=true, with the actual id. The URL in Postman must look like this:

•[your_bizagi_project_url]/odata/data/processes(ID)/cases$allUsers=true

 

•[your_bizagi_project_url]/odata/data/processes(ID)/cases(ID)$allUsers=true

 

 

Search by case number for all users

Endpoint: /odata/data/searchByCaseNumber(caseNumber=’caseNumber’)?$allUsers=true

 

The URL in Postman must look like this:

•[your_bizagi_project_url]/odata/data/searchByCaseNumber(caseNumber= case number)?$allUsers=true

 

 

Return all or a specific case for all users

Endpoint for all cases: /odata/data/cases?$allUsers=true

 

To get all the cases for all users, the URL in Postman must look like this:

•[your_bizagi_project_url]/odata/data/cases?$allUsers=true

 

Endpoint for a specific case: /odata/data/cases(ID)?$allUsers=true

 

To get alla specific case for all users, the URL in Postman must look like this:

•[your_bizagi_project_url]/odata/data/cases(ID)?$allUsers=true

 

 

Return all cases with work items or a specific case with work items for all users

 

Endpoint for all cases with work items: /odata/data/casesWithWorkitems?$allUsers=true

 

For this example you must have previously gotten the ids of the process you are interested in. You can get the id by querying all the cases.

Once you have the id, you must replace ID in the endpoint. The URL in Postman must look like this:

•[your_bizagi_project_url]/odata/data/casesWithWorkitems?$allUsers=true

 

 

Endpoint for a specific case with work items: /odata/data/casesWithWorkitems(ID)?$allUsers=true

 

For this example you must too have previously gotten the ids of the process and of the case you are interested in. You can get the id by querying all the cases.

Once you have the id, you must replace ID in the endpoint  /odata/data/processes(ID)/cases?$allUsers=true, with the actual id. The URL in Postman must look like this:

•[your_bizagi_project_url]/odata/data/processes(ID)/cases(ID)?$allUsers=true

 

 

Last Updated 11/28/2023 9:19:15 AM