queryProcessInstances
This request returns the instances for the specified process templates.
Syntax
com.tibco.wcc.base.Requests.queryProcessInstances(requestId,
arrProcessTemplates,
txtFilter,
txtSort,
numPageSize,
arrAttributes,
arrAttributeTypes);
Parameters
- requestId - (String) Uniquely identifies the request. For more information, see Submitting Server Requests.
- arrayProcessTemplates - (Array[Object]) The process templates whose instances are to be returned.
[ { moduleName: moduleName, processName: processName, processVersion : processVersion } ]where:
- moduleName - (String) The path to the XPDL file that defines the “process package”.
- processName - (String) The name of the process template whose instances are to be returned.
- processVersion - (String) The version of the process template.
Note that if you specify any of the next three parameters — txtFilter, txtSort, numPageSize — you must include attributes (arrAttributes) in the method call. If you do not specify any of the next three parameters, including attributes is optional. If you do not specify attributes, they are all returned.
- txtFilter - (String) A filter expression to limit the number of process instances. Only the process instances that satisfy the expression are returned. (Also see note above.) For information about filter syntax, see the "Sorting and Filtering Process Lists" topic in the developer's guide for your BPM runtime environment.
For a list of the attributes that can be used in the filter expression, use the listProcessInstanceAttributes request.
- txtSort - (String) The sort order to apply to the process instances returned. Specify the sort attribute, following by either ASC or DESC, for ascending or descending, respectively. Separate multiple sort attributes with commas. (Also see note above.) For example:
INSTANCE.PRIORITY ASC, INSTANCE.NAME DESC
For a list of the attributes that can be used in the sort order, use the listProcessInstanceAttributes request.
- numPageSize - (Number) The number of process instances per page to return. Specify 0 (zero) to return all process instances on a single page. (Also see note above.)
- arrAttributes - (Array[String]) The attributes to return with the process instances. Also see the note above — if you do not specify attributes, they are all returned.
Note that the attributes you specify must exist in all of the specified process templates. There are a number of “system attributes” (for example, INSTANCE.START_DATE, INSTANCE.PRIORITY, etc.) that exist for all templates, but you must be careful that attributes associated with the process instance data are only requested if attributes of the same name are in all of the specified templates. If a requested attribute is not valid for a process template, instances of that template are not returned in the response.
Also note that if you include any attributes in this parameter, at least one of them must be INSTANCE.VERSION, INSTANCE.NAME, or MODULE.NAME.
- arrAttributeTypes - (String) An array of attribute names and data types. For each attribute that is referenced in a sort or filter expression, you must include that attribute in this array.
Returns
Returns an <ap:QueryProcessInstances> element, which contains the following elements:
- <ap:QueryId> - If 0 (zero) was specified in the numPageSize parameter, the value in this element is 0 (zero). If you specified a page size other than 0, this element contains an ID that can be used as the input to the queryProcessInstancesNextPage, queryProcessInstancesPreviousPage, and queryDone requests.
- <ap:ProcessInstanceCount> - The number of process instances returned. If you have requested paging (the arrPageSize parameter contained a value other than 0), this is the number returned on the current page.
- <ap:ProcessInstances> - Contains an <ap:ProcessInstance> element for each process instance that is returned. The <ap:ProcessInstance> element contains the following elements:
- <ap:INSTANCE.VERSION> - The version of the process instance.
- <ap:INSTANCE.NAME> - The name of the process instance.
- <ap:INSTANCE.ID> - An identifier for the process instance.
- <ap:MODULE.NAME> - The path to the XPDL file that defines the “process package”.
- <ap:INSTANCE.STATUS> - The status of the instance: Active, Canceling, Completing, Failing, Halted, Halting, Not started, Restarting, Resuming, Starting, Suspended, or Suspending. For descriptions of all of these statuses, see the TIBCO Workspace User’s Guide.
- <ap:INSTANCE.WAITING_WORK_COUNT> - The number of outstanding work items in the process instance.
- <ap:INSTANCE.PRIORITY> - The priority value of the process instance.
- <ap:INSTANCE.PARENT_PROCESS_ID> - The instance ID of the parent process instance — only applicable for re-usable sub-processes.
- <ap:INSTANCE.START_DATE> - The date and time the process instance was started.
Each of these elements represents a “system attribute”. Note that all system attributes are returned in the response, however, only those that you requested in the queryProcessInstances request are populated with values.
If you have specified attributes that contain instance-specific data (for example <ap:ContactPhone>, <ap:IssueDescription>, etc.) in the request, those are also returned under the <ap:ProcessInstance> element.
For example:
<ap:Requests> <ap:QueryProcessInstances Id="ApiSample.queryProcessInstances"> <ap:QueryId>-1909332857</ap:QueryId> <ap:ProcessInstanceCount>3</ap:ProcessInstanceCount> <ap:ProcessInstance> <ap:INSTANCE.VERSION>1.0.0.201101101507</ap:INSTANCE.VERSION> <ap:INSTANCE.NAME/> <ap:INSTANCE.ID>pvm:0a122</ap:INSTANCE.ID> <ap:MODULE.NAME/> <ap:INSTANCE.STATUS/> <ap:INSTANCE.WAITING_WORK_COUNT>0</ap:INSTANCE.WAITING_WORK_COUNT> <ap:INSTANCE.PRIORITY>0</ap:INSTANCE.PRIORITY> <ap:INSTANCE.START_DATE>2011-02-23T17:07:00.767-08:00</ap:INSTANCE.START_DATE> <ap:ContactPhone>509-555-1212</ap:ContactPhone> <ap:IssueDescription>He wants more information.</ap:IssueDescription> </ap:ProcessInstance> . . . </ap:ProcessInstances> </ap:QueryProcessInstances> </ap:Requests>