Overview
This Web method is used to obtain Bizagi Processes' cases and both their general detail and business information from an external application.
You do not need to create a 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 Process instances general information (e.g status and dates), filtering criteria oriented to the specific data model of the Processes (i.e business information values), and parameters to handle the results (how many matches to return, number of pages, etc).
•For the queryCases method, the request and response XML's are of the native .NET XmlDocument type.
•For the queryCasesAsString 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 attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="BizAgiWSParam">
<xs:complexType>
<xs:all>
<xs:element name="Domain" type="xs:string" minOccurs="0"/>
<xs:element name="UserName" type="xs:string" minOccurs="0" />
<xs:element name="domain" type="xs:string" minOccurs="0"/>
<xs:element name="userName" type="xs:string" minOccurs="0" />
<xs:element name="QueryParams" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="Internals" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="Internal">
<xs:complexType mixed="true">
<xs:sequence minOccurs="0">
<xs:element name="From" type="xs:string" minOccurs="0"/>
<xs:element name="To" type="xs:string" minOccurs="0" />
</xs:sequence>
<xs:attribute name="Name" type="xs:string" use="required" />
<xs:attribute name="Include" type="xs:boolean" use="optional" />
<xs:attribute name="Sort" type="xs:string" use="optional" />
<xs:attribute name="Approx" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="XPaths" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="XPath">
<xs:complexType mixed="true">
<xs:sequence minOccurs="0">
<xs:element name="From" type="xs:string" minOccurs="0"/>
<xs:element name="To" type="xs:string" minOccurs="0" />
</xs:sequence>
<xs:attribute name="Path" type="xs:string" use="required" />
<xs:attribute name="Include" type="xs:boolean" use="optional" />
<xs:attribute name="Sort" type="xs:string" use="optional" />
<xs:attribute name="Approx" type="xs:boolean" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Parameters">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="Parameter">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="Name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
</xs:schema>
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 "Internals" and "Xpaths" nodes.
•Internals: Contains one or more nodes of the type "Internal", which are used to specify filtering information related to internal renders (Process data).
•Internal: Specifies in its "Name" attribute, the internal control for filtering information. The filtering value goes as the Value of the node and it is case sensitive.
The possible Internal "Name" values are:
oProcessState: Allows filtering a case if it is open ("Running"), closed ("Completed") or was aborted ("Aborted"). "ALL" is used as the default value, in which case there would be no filtering.
oRadNumber: Allows specification of a specific case.
oCreationDate: Allows filtering according to the cases' creation date.
oExpiryDate: Allows filtering according to the cases' expiration date.
oExpiryDays: Allows filtering according to the remaining days for the cases' expiration date.
oUsers: Allows filtering according to the users (by specifying the UserId) which are currently working in the cases.
oCreatorfullname: full name of the case creator.
oCreatorposition: position of the case creator.
oCreatorloginname: user name of the case creator.
oUserfullname: full name of the current logged user (CurrentUser).
oUserposition: position of the currently logged user (CurrentUser).
oUserloginname: username of the current logged user (CurrentUser)
oidWfClass: Allows filtering according to the Process id (wfclass).
oidApplication: Allows filtering according to the application's id.
oidCategory: Allows filtering according to the category's id.
oidTask: Allows filtering according to the current Task.
oguidApplication: Allows you to specify the guidContext of the Entity where the query is being executed. If this parameter is not included, a message will be shown with the possible GUIDs for the entity.
To get this value, refer to How to obtain the guidApplication.
This element uses additional attributes such as:
o"Include": Can be set to true in order to include the results for the attribute.
o"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.
o"Approx": Can be set to true to perform an approximate search on string-type attributes.
•XPaths: Contains one 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 must always start from the process entity where the query will be made. 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:
o"Include": Can be set to true in order to include the results for the attribute.
o"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.
o"Approx": Can be set to true to perform an approximate search on string-type attributes.
•Parameters: Contains one 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.
Possible "Name" options and their values are:
o"idEnt": Indicates the id of the process Entity. This parameter is mandatory if the entity belongs to multiple Applications. However, if the XPaths tag is not being used, this parameter is optional and may not be included in the input.
o"nameEnt": indicates the process entity's name and can be used instead of the idEnt. This parameter can be retreived from Bizagi Studio, in the entity properties. If both idEnt and nameEnt parameters are used, the nameEnt is ignored. This parameter is case sensitive.
|
If the XPath tag is used in the XML and the process entity that you want to query belongs to multiple applications, it is mandatory to define at least one of the following parameters: IdEnt or NameEnt. |
o"PageSize": defines a number for the size of the cases in each page
o"page": defines a number for the page number from which the results cases will be read
o"Culture": defines a global culture for multi-language supported results (i.e "en-us", "en-gb").
o"searchAllUsers" (for .NET): Optional though recommended to use. It allows a true or false value, in order to override the Search all users definition of a query form (searches for cases of the current user, or all users). When this value is not specified (nor the query looked up by its id), then cases corresponding to the current user in the XML are fetched.
How to obtain the guidApplication Parameter
The guidApplication allows you to specify the guid context of the Entity where the query is being executed. The way to obtain the guidApplication is using the Processes method of the OData Layer.
You can find all the documentation related to the Processes method in this link.
This method returns a JSON file with the ID of all your processes. That id is the guidApplication that can be used in the Query Cases method.
Input Example
With the following example, we will obtain cases by invoking a Query form whose cases:
•Are in pending status (Running).
•Have a Date in the OpeningDate attribute corresponding to November 1st of 2011 or higher.
•Have an Entity id of 10.
Output
Output Schema
The following shows a sample XML structure of information returned by Bizagi:
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.
•CaseTable: Contains one "Columns" node and undefined occurrences of "Rows" (one for each case from the result).
•The following are the included nodes and their definition:
oRADNUMBER: Radication number.
oBAWORKFLOWPATH: Process path.
oWFCLSDISPLAYNAME: Process display name (from wfclass).
oCASCREATIONDATE: Creation date of the case.
oCASSOLUCIONDATE: Solution date of the case.
oIDWFCLASS: Process id.
oIDCASE: Case number.
oIDCASESTATE: Case status. The following case status are valid: Initiated (1), Running (2), Suspended (3), Aborted (4), Completed (5), NotInitiated (6), CancelledByCompensation (7), CancelledByException (8).
•TaskTable: Contains one "Columns" node and undefined occurrences of "Rows" (one for each Task).
The following are the included nodes and their definition: TaskState: Current Task state. CurrentTask: Display name of the current Task. wiEstimatedSolutionDate: Estimated solution date for the Task. idTaskType: Task type. idTask: Task's id. idWorkItem: Workitem's id. idCase: Case number for that Task instance.
•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.
|
Some columns in the response may display an E_ prefix in their name, this prefix is always displayed when the column represents a multiple relation with another Entity. If you need to remove this prefix, refer to this article in our Knowledge base. |
Related Web methods
If you do not need to obtain business information from the queried cases, you may use the getCasesAsString or getCases Web method available in the WorkflowEngineSOA Web service.
For further information refer to the WorkflowEngineSOA Web methods article.
If you want to retrieve further information about one specific case, use the getCaseDataUsingSchemaAsString or getCaseDataUsingXPathsAsString Web methods available in the EntityManagerSOA Web service.
For further information refer to the EntityManagerSOA Web methods article.
Last Updated 5/19/2023 9:08:48 AM