How to get the structure of related entities

<< Click to Display Table of Contents >>

Navigation:  Application integration > Bizagi RESTful API > Basic concepts > Lookup services >

How to get the structure of related entities


To use HTTP POST-based services, you may need to first look up certain data structures or input parameters.


The following section describes how to query values of a related entity, such as one typically displayed as a drop-down list, so you can send out an appropriate value when starting a new process, completing a workitem or triggering an action.


Scope of the resource

The related entities resource uses via an HTTP GET, and is defined as relatedEntity.

It lets you see which referenced entities are used by a process (attributes of the type Entity); in a start form when creating a new case, or an activity form when completing a workitem, or as input for when triggering an action.




Resource URL

Querying values for related entities is supported for these resources:











The following image illustrates how you can send an HTTP GET for this resource, by using the following:




[ID_process]: Corresponds to the GUID of the process as returned when querying [your_bizagi_project_url]/odata/data/processes




Returned results consider multiple values, one per each of the related entities used by that process, activity or action (typically via a drop-down list).

Inside of the value element, you will find:

Name: The name of the attribute as a referenced entity. The unique URL to access that specific reference.

Id: A string-based GUID representing the URI of that specific reference.

Xpath: The Xpath to that attribute parting from the process entity.



In addition, for every set of results returned by OData services, the successful response includes a set of standard properties which are preceded by the @ sign. These properties are described at Properties and querying options.


Through the property, you can obtain the specific record's detail only, instead of a full list. For example, use:



Parting from the above invocation, you should navigate into the specific values that are possible for the given related entity.

For example, use:





Returned results contain multiple values, one for each of the possible values of an existing record for that entity.

Inside the value element, the following properties may be useful:

label: The display name or general label for that record.

value: The unique identifier for that record.

When the entity has a business key definition, which is composed by a single attribute, then this returned value matches the value held by the business key attribute.

Otherwise, if the business key is a compound definition (more than one attribute) or if there is no business key explicitly defined for that entity, this value will be a GUID.

You can send this value, whether or not it is a GUID as an input parameter to start a new process, complete a pending activity or event (workitem), or trigger an action.


The example above shows a GUID. The example below shows a returned value when an entity has a business key definition bound to a single attribute: