Returns information about a specified set of workflow instances.

Required Input Parameters

None

Optional Input Parameters

subjectId

Repository ID of the workflow subject whose instances should be returned. If omitted, instances for all workflow subjects are returned.

processName

Name of the workflow process whose instances should be returned. If omitted, instances for all workflow processes are returned.

segmentName

Name of the workflow process segment whose instances should be returned. This parameter takes effect only if the processName parameter is set. If omitted, instances for all segments of the specified workflow process are returned.

taskElementId

Process element ID of the workflow task where the returned instances must be waiting—that is, in order for the query to return an instance, the specified task must be active for that instance. This parameter takes effect only if both the processName and segmentName parameters are set. If omitted and taskElementIds, taskName, and taskNames are also omitted, all instances for the specified workflow segment are returned.

taskElementIds

Process element IDs of the workflow tasks where the returned instances must be waiting—that is, in order for the query to return an instance, at least one of the specified tasks must be active for that instance. This parameter takes effect only if both the processName and segmentName parameters are set, and if taskElementId is not set. If omitted and taskName and taskNames are also omitted, all instances for the specified workflow segment are returned.

taskName

Name of the workflow task where the returned instances must be waiting—that is, in order for the query to return an instance, the specified task must be active for that instance. This parameter takes effect only if both the processName and segmentName parameters are set, and if taskElementId and taskElementIds are not set. If omitted and taskNames is also omitted, all instances for the specified workflow segment are returned.

taskNames

Names of the workflow tasks where the returned instances must be waiting—that is, in order for the query to return an instance, at least one of the specified tasks must be active for that instance. This parameter takes effect only if both the processName and segmentName parameters are set, and if taskElementId, taskElementIds, and taskName are not set. If omitted, all instances for the specified workflow segment are returned.

Output Parameters

instances

Set to the results of the instance query, a Collection of ProcessInstanceInfo objects.

errorMessage

Set to the error message if an error occurs in the course of executing the query.

Open Parameters

output

Rendered after the instance query is complete and the results are placed into the instances parameter.

empty

Rendered if no instances are returned from the query.

error

Rendered if an error occurs while executing the query. The errorMessage parameter is set to the corresponding error message.

Usage Notes

WorkflowInstanceQueryDroplet performs a workflow instance query and returns the resulting Collection of atg.process.ProcessInstanceInfo objects. WorkflowInstanceQueryDroplet is typically used in conjunction with another servlet bean, such as ForEach or Range, which can iterate through the Collection to display the ProcessInstanceInfo objects. In addition, the information contained in each ProcessInstanceInfo (that is, the subjectId, processName, and segmentName properties) can be passed as input parameters to a WorkflowTaskQueryDroplet, in order to obtain the tasks (active or otherwise) corresponding to the workflow instance.

For some types of workflows, the number of returned workflow instances can be very large. It is a good idea to constrain the query as much as possible—for example, to a particular task element.

The Scenarios module does not include a Nucleus component of this class, because each component is typically configured to work with a specific type of workflow. When you create a workflow type, you can create a WorkflowInstanceQueryDroplet component and configure it by setting the following properties in the component’s properties file:

Example

The following example shows how to use a WorkflowInstanceQueryDroplet component to display all outstanding workflow instances:

<dsp:droplet name="WorkflowInstanceQuery">
  <dsp:oparam name="empty">
    No outstanding workflow instances.
  </dsp:oparam>
  <dsp:oparam name="output">
    <dsp:droplet name="/atg/dynamo/droplet/ForEach">
      <dsp:param name="array" param="instances"/>
      <dsp:oparam name="output">
        Workflow subject <dsp:valueof param="element.subjectId"/><br/>
      </dsp:oparam>
    </dsp:droplet>
  </dsp:oparam>
</dsp:droplet>