Get Entities

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > SOAP web services > Available SOAP web services > EntityManagerSOA Web methods >

Get Entities

Overview

This Web method is used to query information stored in Entities of Bizagi's data model (from an external application).

 

This method is especially used for Parameter Entities in Bizagi; given that it will return a set of records for that Entity, and such records (lists of values) are never modified from a Process instance.

This method receives a single input having the name of the Entity for which we want to look up its values, and any business information filtering.

 

Note that this method will return information for records at that Entity and information for related attributes (relationships in that Entity) for one depth level. If greater depth level is required, then use the getEntitiesUsingSchemaAsString or getEntitiesUsingSchema methods.

For more information about other methods, refer to the Related Web methods section at the end of this article.

 

For the getEntities method, the request and response XML's are of the native .NET XmlDocument type.

For the getEntitiesAsString method the same XML structure is handled, but this parameter is sent as a string type using CDATA.

 

 

 

Input

 

Input Schema

The following shows a sample XML structure of information to send to Bizagi:

 

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">

 <xs:element name="BizAgiWSParam">

         <xs:complexType>

                 <xs:sequence>

                         <xs:element name="EntityData">

                                 <xs:complexType>

                                         <xs:sequence>

                                                 <xs:choice>

                                                         <xs:element name="EntityName" type="xs:string"/>

                                                         <xs:element name="EntityID" type="xs:integer"/>

                                                 </xs:choice>

                                                 <xs:element name="FilterDisabled" type="xs:boolean" minOccurs="0" />

                                                 <xs:element name="Filters" type="xs:string" nillable="true" minOccurs="0"/>

                                         </xs:sequence>

                                 </xs:complexType>

                         </xs:element>

                 </xs:sequence>

         </xs:complexType>

 </xs:element>

</xs:schema>

 

Input Parameters

BizAgiWSParam: It is the root node.

EntityData: It is the element which contains either EntityName or EntityID.

EntityName: Is the name (not display name) of the given entity to query. If this element is included the next one must not be.

EntityID: Is used instead of the previous method, do not include both. It is the id or key (in the database for the table ENTITY) of the entity that is to be consulted. It is easier to use this element when used in conjunction with other SOA methods, for example the ones from the web service RenderSOA, which are used to replicate Bizagi forms in a user interface of an external system, that return the identifiers of entities related to the metadata of the forms.

FilterDisabled: Used to include within the results, records in Parameter Entities which have been disabled (logical deletion).

To include such records as well, include this element and set its value to false.

Filters: Set the filter for the queried entity. The filter format is specified as a WHERE statement of a basic SQL query (database level).

It is recommended to include filter within the CDATA XML element (to be able to use XML reserved special characters, such as the less-than sign).

You may only narrow down values by including filters for attributes found directly inside of the entity you are querying (not supported for attributes nor relationships which are at other entities).

 

The following table shows valid signs to use for comparisons in filters:

 

Character

Description

=

Equal to

<

Less than

>

Greater than

<>

Different from

!=

Different from

<=

Less than or equal to

>=

Greater than or equal to

 

The following table provides the XML format equivalent to use, for those scenarios where reserved special characters in XML are required(commonly used).

 

Character

Description

XML Format to use

<

Less-than sign

&lt;

>

Greater-than sign

&gt;

"

Double quotation mark

&quot;

'

Single quotation mark (or apostrophe)

&apos;

&

Ampersand

&amp;

 

Input Example

In the following example, we obtain information for Applicants which have a BuroScore less than 100.

 

Method getEntitiesAsString

<BizAgiWSParam>

 <EntityData>

         <EntityName>Applicant</EntityName>

         <Filters>

                 <![CDATA[BuroScore < 100]]>

         </Filters>

 </EntityData>

</BizAgiWSParam>

 

Method getEntitiesAsString

<entitiesInfo>

 <![CDATA[<BizAgiWSParam>

         <EntityData>

                 <EntityName>Applicant</EntityName>

                 <Filters>

                         BuroScore &lt; 100

                 </Filters>

         </EntityData>

 </BizAgiWSParam>]]>

</entitiesInfo>

 

Other filters examples are:

Using a direct String comparison:

 <![CDATA[ Option  = 'Automatic' ]]>

Using an AND condition:
       <![CDATA[ (DocumentType = 1 OR City = 2) AND Approved = true ]]>

Comparing Date information (using the date format at the database):

 <![CDATA[ date1 >= '06/05/2008' ]]>

 

We suggest you use How to start a process in Bizagi from other applications as a guideline to invoke this service.

 

Output

 

Output Schema

The following shows a sample XML structure of information returned by Bizagi:

 

<?xml version="1.0" encoding="utf-8"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

 <xs:element name="BizAgiWSResponse">

         <xs:complexType>

                 <xs:sequence>

                         <xs:element name="Entities" maxOccurs="1">

                                 <xs:complexType />

                         </xs:element>

                 </xs:sequence>

         </xs:complexType>

 </xs:element>

</xs:schema>

 

Within the Entities element, the XML structure for the information returned by Bizagi will correspond to the attributes and relations for that given Entity.

For further information about how is the XML structure returned for a data model in Bizagi, refer to Bizagi's data model XML schemas.

 

Output Parameters

BizAgiWSResponse: It is the root node.

Entities: Within this element, the attributes and relations for that given Entity will be returned with their corresponding values.

Note that this method returns a set of records (one or more rows), and therefore there will be only one occurrence of the Entities element, by possibly many of inner elements.

 

Output Example

In the following example, we illustrate a returned XML-structured sample response from Bizagi SOA layer. Notice that attributes having NULL values will not be returned by this invocation.

 

Method getEntities

 

GetEntities_Image003

 

Method getEntitiesAsString

 

getEntitiesAsString_01

 

Related Web methods

If you wish to query information using an Entity as start point, but with a great depth level for information contained through relations (in other Entities), use the getEntitiesUsingSchemaAsString or getEntitiesUsingSchema methods.

For further information refer to the Get Entities Using Schema article.