getEntitiesAsString

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

getEntitiesAsString

Overview

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

 

This method is specially 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.

 

note_pin

The description provided in this article applies too for the getEntities web method available in Bizagi .NET edition.

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.

 

 

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

 

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

 

 

 

Input Example

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

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

<BizAgiWSParam>

 <EntityData>

         <EntityName>Applicant</EntityName>

         <Filters>

                 <![CDATA[BuroScore < 100]]>

         </Filters>

 </EntityData>

</BizAgiWSParam>

 

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' ]]>

 

 

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:

GetEntities_Image003

 

Notice that attributes having NULL values will not be returned by this invocation.

 

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 getEntitiesUsingSchemaAsString article.