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).
The description provided in this article applies too for the queryCases web method available in Bizagi .NET edition.
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.
The following shows a sample XML structure of information to send to Bizagi:
•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.
•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 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"Approx": Can be set to true to perform an approximate search on string-type attributes.
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.
•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": A mandatory parameter. Indicates the id of the Entity.
o"PageSize": defines a number for the size of the cases in each page
o"pag": 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.
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.
The following shows a sample XML structure of information returned by Bizagi:
•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 1 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.
With the following sample returned XML-structured response from Bizagi SOA layer, we can see how is the information returned.
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.