getEntitiesUsingSchemaAsString

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

getEntitiesUsingSchemaAsString

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.

 

note_pin

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

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.

 

 

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

 

 

 

Input Example

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

For the first parameter, we use:

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

<BizAgiWSParam>

 <EntityData>

         <EntityName>Applicant</EntityName>

         <Filters>

                 <![CDATA[BuroScore < 100]]>

         </Filters>

 </EntityData>

</BizAgiWSParam>

 

For the second parameter, we use this schema:

GetEntitiesUsingSchema_Image003

 

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

 

 

 

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:

GetEntitiesUsingSchema_Image004

 

Notice that unlike the getEntitiesAsString method, attributes having NULL values are returned by this invocation (because they are explicitly included in the schema defined as input parameter).

 

 

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

For further information refer to the getEntitiesAsString 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 method.

For further information, refer to the getEntitySchemaStr article.