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.
|
To consult file attributes, refer to the methods get Case Data Using XPaths and get Case Data Using Schema. Take into account that both methods only retrieve data from open cases and activities. |
•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.
•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 |
< |
> |
Greater-than sign |
> |
" |
Double quotation mark |
" |
' |
Single quotation mark (or apostrophe) |
' |
& |
Ampersand |
& |
Input Example
In the following example, we obtain information for Applicants which have a BuroScore less than 100.
GetEntitiesUsingSchema Method Input
<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>
GetEntitiesUsingSchemaAsString Method Input
<entitiesInfo>
<![CDATA[<BizAgiWSParam>
<EntityData>
<EntityName>Applicant</EntityName>
<Filters>
BuroScore < 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).
GetEntitiesUsingSchema Method Output
GetEntitiesUsingSchemaAsString Method Output
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.
Last Updated 1/6/2022 5:13:01 PM