Related entities values

<< Click to Display Table of Contents >>

Navigation:  Bizagi API > Basic concepts > Common lookup services >

Related entities values

Overview

Bizagi features OData services, which handle a comprehensive set of resources, some which enable you to do an HTTP POST to start a new process, complete a pending activity or event (workitem), or to trigger an action.

In order to use these 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 that you can send out an adequate value when starting a new process, completing a workitem or triggering an action.

 

Scope of the resource

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

It allows you to obtain which referenced entities are used by a process (those attributes of the type Entity), either used in a start form -when wanting to create a new case, or used in an activity form -when wanting to complete a workitem, or used as input for an action -when wanting to trigger one.

 

OData_Related1

 

Resource URL

The possibility to query values for related entities is supported for all of these resources:

[your_bizagi_project_url]/odata/data/processes([ID_process])/relatedEntities

[your_bizagi_project_url]/odata/data/processes([ID_process])/cases([ID_case])/workitems([ID_workitem])/relatedEntities

[your_bizagi_project_url]/odata/data/cases([ID_case])/workitems([ID_workitem])/relatedEntities

[your_bizagi_project_url]/odata/data/stuff([ID_stuff])/values([ID_value])/actions([ID_action])/relatedEntities

[your_bizagi_project_url]/odata/data/searches([ID_search])/actions([ID_action])/relatedEntities

[your_bizagi_project_url]/odata/data/searches([ID_search])/results([ID_result])/actions([ID_action])/relatedEntities

[your_bizagi_project_url]/odata/data/relevants([ID_relevant])/relatedEntities

[your_bizagi_project_url]/odata/data/relevants([ID_relevant])/actions([ID_action])/relatedEntities

 

Example

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

[your_bizagi_project_url]/odata/data/processes([ID_process])/relatedEntities

 

Consider:

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

 

OData_Related2

 

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.

@odata.id: 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.

 

note_pin

In addition to the above, 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. Such properties are described at Properties and querying options.

 

Through the @odata.id property, you can obtain that specific record's detail only, instead of a full list. For example using:

[your_bizagi_project_url]/odata/data/processes([ID_process])/relatedEntities([ID_related])

 

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

For example using:

[your_bizagi_project_url]/odata/data/processes([ID_process])/relatedEntities([ID_related])/values

 

OData_Related3

 

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

Inside of the value element, you should consider as relevant the following information:

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

value: The unique identifier for that record.

Whenever 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, either 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.

Such value, regardless of being a GUID or not, is the one to send out as input parameters for any of the above scenario (start a new process, complete a pending activity or event (workitem), or trigger an action).

 

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

 

OData_Related4