Get Entities Using Schema

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

Overview

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

This method receives two inputs: One XML schema having the name of the Entity for which we want to look up its values and any business information filtering, and a second one with an XML schema to define which business information we want to retrieve (data model fields).

 

If you do not wish to use a schema, or if you don't need a great level of depth in this query's information (data contained in relations), then you may also use the getEntitiesAsString or getEntities methods.

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

 

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

For the getEntitiesUsingSchemaAsString 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>

 

For the second parameter called schema, the expected XSD needs to correspond to the expected structured defined by Bizagi.

For further information about this, refer to Bizagi's data model XML schemas.

 

Input Parameters

For the first parameter called entitiesInfo, it is necessary to consider:

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 identifier 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 IDs of entities related to the metadata of the forms.

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

For further information about the CDATA element use, refer to the SOA Layer Considerations article.

 

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 getEntitiesUsingSchema

<entitiesInfo>

 <BizAgiWSParam>

         <EntityData>

                 <EntityName>Applicant</EntityName>

                 <Filters>

                         <![CDATA[BuroScore < 100]]>

                 </Filters>

         </EntityData>

 </BizAgiWSParam>

</entitiesInfo>

<schema>

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

         <xs:element name="Applicant">

                 <xs:complexType>

                         <xs:sequence>

                                 <xs:element minOccurs="0" maxOccurs="1" name="DocumentNumber"/>

                                 <xs:element minOccurs="0" maxOccurs="1" name="BuroScore" />

                                 <xs:element minOccurs="0" maxOccurs="1" name="ExceptionObservation" />

                         </xs:sequence>

                 </xs:complexType>

         </xs:element>

 </xs:schema>

</schema>

 

Method getEntitiesUsingSchemaAsString

<entitiesInfo>

 <![CDATA[<BizAgiWSParam>

         <EntityData>

                 <EntityName>Applicant</EntityName>

                 <Filters>

                         BuroScore &lt; 100

                 </Filters>

         </EntityData>

 </BizAgiWSParam>]]>

</entitiesInfo>

<schema>

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

         <xs:element name="Applicant">

                 <xs:complexType>

                         <xs:sequence>

                                 <xs:element minOccurs="0" maxOccurs="1" name="DocumentNumber"/>

                                 <xs:element minOccurs="0" maxOccurs="1" name="BuroScore" />

                                 <xs:element minOccurs="0" maxOccurs="1" name="ExceptionObservation" />

                         </xs:sequence>

                 </xs:complexType>

         </xs:element>

 </xs:schema>]]>

</schema>

 

 

Other filters examples for the first parameter 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 unlike the Get Entities method, attributes having NULL values are returned by this invocation (because they are explicitly included in the schema defined as input parameter).

 

Method getEntitiesUsingSchema

 

GetEntitiesUsingSchema_Image004

 

Method getEntitiesUsingSchemaAsString

 

GetEntitiesUsingSchemaAsString_01

 

Related Web methods

If you wish to query information for an Entity and its immediately related Entities information at most, you may use as well the getEntitiesAsString or getEntities methods.

For further information refer to the Get Entities article.

 

It is also possible that you may want to first retrieve the schema for the Entity to use in this method. In this scenario and to do this dynamically, use the getEntitySchemaStr or getEntitySchema methods.

For further information, refer to the Get Entity Schema article.