Query Entities

<< Click to Display Table of Contents >>

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

Query Entities

Overview

This Web method is used to obtain records information at any of Bizagi's data model Entities.

You do not need to create an entity query form in order to rely on Bizagi queries engine to fetch reports.

 

This method receives mainly: The end user running the Query, filtering criteria for the specific attribute values in that Entity (i.e business information), and parameters to handle the results (how many matches to return, number of pages, etc).

 

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

For the queryEntitiesAsString 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 targetNamespace="http://tempuri.org/XMLSchema.xsd"
    elementFormDefault="qualified"
    xmlns="http://tempuri.org/XMLSchema.xsd"
    xmlns:mstns="http://tempuri.org/XMLSchema.xsd"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="BizagiWSParam">
    <xs:complexType>
        <xs:sequence>
          <xs:element name="QueryParams" maxOccurs="1">
              <xs:complexType>
                <xs:sequence>
                    <xs:element name="XPaths" maxOccurs="1">
                      <xs:complexType>
                          <xs:sequence>
                            <xs:element name="XPath" maxOccurs="unbounded" >
                                <xs:complexType>
                                  <xs:attribute name="Path" type="xs:string" use="required"/>
                                  <xs:attribute name="Include" type="xs:boolean" use="optional" default="false"/>
                                  <xs:attribute name="Sort" type="xs:string" use="optional" default="Asc"/>
                                </xs:complexType>
                            </xs:element>
                          </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                </xs:sequence>
              </xs:complexType>
          </xs:element>
          <xs:element name="Parameter" maxOccurs="unbounded">
              <xs:complexType>
                <xs:attribute name="Name" type="xs:string" use="required"/>
              </xs:complexType>
          </xs:element>
        </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

 

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

 

Input Parameters

BizAgiWSParam: This is the root node, containing all the necessary information to execute the query. Contains the "domain", "userName", "QueryParams", and "Parameters" nodes.

domain: Here goes the name of the domain for the Bizagi user who executes the query.

userName: Name of the user who executes the query.

QueryParams: Contains all the necessary information to search and filter the query results. Contains the "Xpaths" node.

Xpaths: Contains 1 or more nodes of the type "XPath", which are used to specify filtering information related to data model's query controls (business data).

XPath: Specifies in its "Path" attribute, the XPath for the attribute in the data model for filtering information. The XPath uses the dot character (.) as separator. The filtering value goes as the Value of the node and it is case sensitive. Only when specifying a range of values (for example for a Date) it would be necessary to include a "<From>" and/or "<To>" node to contain the range limit values. This element uses additional attributes such as:

"Include": Can be set to true in order to include the results for the attribute. It is mandatory to use this property (you can set it to false).

"Approx": Can be set to true to perform an approximate search on string-type attributes.

"Sort": Can be set as "Desc" (descending) or "Asc" (ascending) to order the results according to the attribute's value. When no ordering is specified, by default the sorting takes the RadNumber in an ascending way.

Take into account that the XPath for entity level query forms, will start off at the source entity.

Parameters: Contains 1 or more nodes of the type "Parameter", which are used to specify all the necessary information to handle the query execution results.

Parameter: Specifies in its "Name" attribute, options to handle the query form results. The filtering value goes as the Value of the node and it is case sensitive. The possible values for the attribute "Name" are:

"idEnt": A mandatory parameter. Indicates the id of the Entity.

"PageSize": defines a number for the size of the cases in each page

"page": defines a number for the page number from which the results cases will be read

"Culture": defines a global culture for multi-language supported results, e.g "en-us", "en-gb".

 

Input Example

With the following example, we will obtain records from an Entity:

 

Method QueryEntities

<BizAgiWSParam>
  <domain>domain</domain>
  <userName>admon</userName>
      <QueryParams>
          <XPaths>
              <XPath Path="OpeningDate" Include="true"/>
              <XPath Path="SLA" Include="true"/>
              <XPath Path="Subject" Include="true"/>
              <XPath Path="TicketDescription" Include="true"/>
          </XPaths>
      </QueryParams>
      <Parameters>
          <Parameter Name="idEnt">10384</Parameter>
          <Parameter Name="page">3</Parameter>
          <Parameter Name="PageSize">10</Parameter>
          <Parameter Name="Culture">en-US</Parameter>
      </Parameters>
</BizAgiWSParam>

 

Method QueryEntitiesAsString

<sxml>
      <![CDATA[<BizAgiWSParam>
          <domain>domain</domain>
          <userName>admon</userName>
              <QueryParams>
                  <XPaths>
                      <XPath Path="OpeningDate" Include="true"/>
                      <XPath Path="SLA" Include="true"/>
                      <XPath Path="Subject" Include="true"/>
                      <XPath Path="TicketDescription" Include="true"/>
                  </XPaths>
              </QueryParams>
              <Parameters>
                  <Parameter Name="idEnt">10384</Parameter>
                  <Parameter Name="page">3</Parameter>
                  <Parameter Name="PageSize">10</Parameter>
                  <Parameter Name="Culture">en-US</Parameter>
              </Parameters>
      </BizAgiWSParam>]]>
</sxml>

 

Output

 

Output Schema

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

 

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema targetNamespace="http://tempuri.org/XMLSchema.xsd" elementFormDefault="qualified"
    xmlns="http://tempuri.org/XMLSchema.xsd" xmlns:mstns="http://tempuri.org/XMLSchema.xsd"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="BizagiWSParam">
    <xs:complexType>
      <xs:sequence>
          <xs:element name="Results" maxOccurs="1">
              <xs:complexType>
                  <xs:sequence>
                      <xs:element name="RowsCount" minOccurs="1" maxOccurs="1"/>
                      <xs:element name="PageCount" minOccurs="1" maxOccurs="1"/>
                      <xs:element name="Tables" maxOccurs="1">
                          <xs:complexType>
                              <xs:sequence>
                                  <xs:element name="ResponseTable" maxOccurs="1">
                                      <xs:complexType>
                                          <xs:sequence>
                                              <xs:element name="Columns" maxOccurs="1">
                                                  <xs:complexType>
                                                      <xs:sequence>
                                                          <xs:element name="Column" maxOccurs="unbounded">
                                                              <xs:attribute name="Name" type="xs:string" use="required"/>
                                                              <xs:attribute name="Type" type="xs:string" use="required"/>
                                                          </xs:element>
                                                      </xs:sequence>
                                                  </xs:complexType>
                                              </xs:element>
                                              <xs:element name="Rows" maxOccurs="1">
                                                  <xs:complexType>
                                                      <xs:sequence>
                                                          <xs:element name="Row" maxOccurs="unbounded">
                                                              <xs:complexType>
                                                                  <xs:sequence>
                                                                      <xs:element name="Column" maxOccurs="unbounded">
                                                                          <xs:complexType>
                                                                              <xs:attribute name="Name" type="xs:string"/>
                                                                          </xs:complexType>    
                                                                      </xs:element>    
                                                                  </xs:sequence>
                                                                  <xs:attribute name="Id" type="xs:integer"/>
                                                              </xs:complexType>
                                                          </xs:element>
                                                      </xs:sequence>
                                                  </xs:complexType>
                                              </xs:element>
                                          </xs:sequence>
                                      </xs:complexType>
                                  </xs:element>
                              </xs:sequence>
                          </xs:complexType>
                      </xs:element>
                  </xs:sequence>
              </xs:complexType>
          </xs:element>
          <xs:element name="Parameters" maxOccurs="1">
              <xs:complexType>
                  <xs:sequence>
                      <xs:element name="Parameter" maxOccurs="unbounded">
                          <xs:complexType>
                              <xs:attribute name="Name" type="xs:string"/>
                          </xs:complexType>
                      </xs:element>
                  </xs:sequence>
              </xs:complexType>
          </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

 

Output Parameters

BizAgiWSResponse: This is the root node, containing all the feedback information of the query execution. Contains the "Results", and "Parameters" nodes.

Results: Contains the "RowsCount", "PageCount" and "Tables" node with the returned information of the cases.

RowsCount: Number of total records (cases) returned by the query execution.

PageCount: Number of total pages returned by the query execution.

Tables: Contains the "CaseTable" and "TaskTable" nodes.

ResponseTable: Contains one "Columns" node and undefined occurrences of "Rows" (one for each case from the result).

Nodes inside the ResponseTable will contain information of the attributes of the given entity.

Parameters: Contains one or more nodes of the type "Parameter", which contain what specified as input for the query execution results.

Parameter: Specifies in its "Name" attribute, the options used in the input to handle the query form results.

 

Output Example

With the following sample returned XML-structured response from Bizagi SOA layer, we can see how is the information returned.

 

Method QueryEntities

 

queryEntities_output

 

Method QueryEntitiesAsString

 

queryEntities_output_2

 

Related Web methods

If you wish to obtain information from specific types of Entities such as Parameter Entities, you may use the getEntitiesAsString or getEntities Web method available in the EntityManagerSOA Web service.

For further information refer to the EntityManagerSOA Web methods article.