All queries consist of the following three optional parts that can be used to build Web Services queries:
Some available query filters are query dependent. For working with specific queries please refer to the section Specific Queries, which describes the specific predicates, available attributes and supported policies accordingly.
The predicate element in queries is of type AndTerm
and can contain a list of various PredicateBase elements which
are evaluated via and conjunction. By using nested and
and or elements more complex filter statements can be realized.
Note that not every query type supports every predicate element.
| Predicate | Description |
|---|---|
| FilterAndTerm | Building complex filter terms. |
| FilterOrTerm | Building complex filter terms. |
| OperatorFilters (attribute) | Applying filters to according attributes. |
| OperatorFilters (variable) | Finding activity instances / process instances containing specific workflow data. |
| ProcessDefinitionFilter | Finding instances belonging to specific process definitions. |
| ProcessInstanceFilter | Finding instances belonging to specific process instance hierarchies. |
| ActivityFilter | Finding instances of specific activities / finding instances related to instances of specific activities. |
| ActivityInstanceFilter | Finding specific activity instances / finding log entries related to specific activity instances. |
| ActivityStateFilter | Finding activity instances currently being in specific states. |
| PerformingUserFilter | Finding activities currently being performed by a specific user. |
| PerformingParticipantFilter | Finding activities currently being performed by a specific participant. |
| PerformedByUserFilter | Finding activities that were performed and completed by a specific user. |
| ProcessStateFilter | Finding process instances currently being in specific states. |
| StartingUserFilter | Finding process instances being started by a specific user. |
| UserStateFilter | Limiting to only logged in users. |
| ParticipantAssociationFilter (for ModelParticipant, UserGroup, TeamLeader, Department) | Restricting to users having granted specific roles/organizations or being members of specific user groups. |
| ParticipantAssociationFilter (for User) | Restricting to UserGroups having specific users associated. |
The following example shows a SOAP Request for a query retrieving only ActivityInstances which
have an oid of less than 10 and are in state Completed.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://http://eclipse.org/stardust/ws/v2012a/api" xmlns:quer="http://eclipse.org/stardust/ws/v2012a/api/query">
<soapenv:Header/>
<soapenv:Body>
<api:findActivities>
<api:query>
<quer:predicate>
<quer:lessThan>
<quer:lhsAttribute>oid</quer:lhsAttribute>
<quer:rhsValue>10</quer:rhsValue>
</quer:lessThan>
<quer:activitiesInState>
<quer:states inclusive="true">
<quer:state>Completed</quer:state>
</quer:states>
</quer:activitiesInState>
</quer:predicate>
</api:query>
</api:findActivities>
</soapenv:Body>
</soapenv:Envelope>
Operator Filters are used to filter results by either by query type predefined attributes or by variables using dynamic data defined in the model. There are Unary, Binary and BinaryListValued Predicates.
The XSD Elements look like the following:
<!--Unary--> <element name="isNull" type="tns:IsNullPredicate" /> <element name="notNull" type="tns:NotNullPredicate" /> <!--Binary--> <element name="isEqual" type="tns:IsEqualPredicate" /> <element name="notEqual" type="tns:NotEqualPredicate" /> <element name="lessThan" type="tns:LessThanPredicate" /> <element name="lessOrEqual" type="tns:LessOrEqualPredicate" /> <element name="greaterOrEqual" type="tns:GreaterOrEqualPredicate" /> <element name="greaterThan" type="tns:GreaterThanPredicate" /> <element name="isLike" type="tns:IsLikePredicate" /> <!--BinaryListValued--> <element name="between" type="tns:BetweenPredicate" /> (exactly two values) <element name="inList" type="tns:InListPredicate" /> (only for variables) <element name="notInList" type="tns:NotInListPredicate" /> (only for variables) <element name="notAnyOf" type="tns:NotAnyOfPredicate" /> (only for variables)
UnaryPredicates can either be used with variables or attributes.
The variable element is used to pass a dataId, while the attribute
element can hold a predefined attribute.
For example:
<quer:notNull>
<quer:variable>someDataId</quer:variable>
</quer:notNull>
<quer:notNull>
<quer:attribute>oid</quer:attribute>
</quer:notNull>
BinaryPredicates additionally use a single rhsValue
element to specify a value to compare with. Similar to UnaryPredicates
the lhsVariable or lhsAttribute element can be used.
When using lhsAttribute the type
attribute of element rhsValue is restricted to the following types:
lhsAttribute Example:
<quer:isEqual>
<quer:lhsAttribute>oid</quer:lhsAttribute>
<quer:rhsValue xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:long">100</quer:rhsValue>
</quer:isEqual>
For most attributes the default string type is sufficient, e.g.:
<quer:isEqual>
<quer:lhsAttribute>oid</quer:lhsAttribute>
<quer:rhsValue>100</quer:rhsValue>
</quer:isEqual>
The lhsVariable element allows the use of rhsValue
for all supported types. Please refer to the table in the section
Supported Data Types
of the chapter Stardust Web Services.
The values in the table are also supported for filtering workflow data
and can thus be used as rhsValue for the lhsVariable element.
Structured data can be dereferenced using . or /
delimiter, as illustrated in the following examples:
<quer:isEqual>
<quer:lhsVariable>primitive_string_data1</quer:lhsVariable>
<quer:rhsValue>text</quer:rhsValue>
</quer:isEqual>
<quer:isEqual>
<quer:lhsVariable>primitive_long_data1</quer:lhsVariable>
<quer:rhsValue xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:long">100</quer:rhsValue>
</quer:isEqual>
<quer:isEqual>
<quer:lhsVariable>SupportCaseData.Name</quer:lhsVariable>
<quer:rhsValue>Smith</quer:rhsValue>
</quer:isEqual>
BinaryListValuedPredicates are used for OperationFilters which
require more than one value. The between element requires
exactly two values.
Data type restriction is the same as for BinaryPredicates.
When using lhsAttribute the type
attribute of element rhsValues is restricted to the following
types:
The following example illustrates how the between element
can be used:
<quer:between>
<quer:lhsAttribute>lastModificationTime</quer:lhsAttribute>
<quer:rhsValues xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:dateTime">
<quer:value>2011-05-28T12:12:38.323+02:00</quer:value>
<quer:value>2011-06-28T12:12:38.323+02:00</quer:value>
</quer:rhsValues>
</quer:between>
The rest of the available filters are not available for every query. For more information please refer to the section Specific Queries.
The XSD Elements look like the following:
<element name="forProcessDefinition" type="tns:ProcessDefinitionFilter" /> <element name="forProcess" type="tns:ProcessInstanceFilter" /> <element name="processesInState" type="tns:ProcessStateFilter" /> <element name="forActivityDefinition" type="tns:ActivityDefinitionFilter" /> <element name="forActivity" type="tns:ActivityInstanceFilter" /> <element name="activitiesInState" type="tns:ActivityStateFilter" /> <element name="performingUser" type="tns:PerformingUserFilter" /> <element name="performedByUser" type="tns:PerformedByUserFilter" /> <element name="performingParticipant" type="tns:PerformingParticipantFilter" /> <element name="startingUser" type="tns:StartingUserFilter" /> <element name="userState" type="tns:UserStateFilter" /> <element name="participantAssociation" type="tns:ParticipantAssociationFilter" />
By setting an attributeOrder or dataOrder the
query results can be ordered.
<quer:order>
<quer:attributeOrder>
<quer:attribute>startTime</quer:attribute>
<quer:ascending>true</quer:ascending>
</quer:attributeOrder>
</quer:order>
<quer:order>
<quer:dataOrder>
<quer:dataId>primitive_descriptor1</quer:dataId>
<quer:ascending>true</quer:ascending>
</quer:dataOrder>
</quer:order>
Policies allow setting special options for the query. One
important policy that can be used to realize paging is the subsetPolicy.
<quer:policy>
<quer:subsetPolicy>
<quer:evaluateTotalCount>true</quer:evaluateTotalCount>
<quer:maxSize>5</quer:maxSize>
<quer:skippedEntries>0</quer:skippedEntries>
</quer:subsetPolicy>
</quer:policy>
This section describes the following query classes with the specific predicates that can be used for filtering, available attributes and policies.
For the worklist query primarily userContribution is
used to configure private worklist and participantContributions
to configure specific participant worklists inclusion.
| WorklistQuery | Mapped Structure | Comments |
|---|---|---|
| setUserContribution(boolean) setUserContribution(SubsetPolicy) |
<element name="UserContribution" minOccurs="0" /> | Enables or disables the retrieval of the UserWorklist and optionally a SubsetPolicy can be set. |
| setParticipantContribution(PerformingParticipantFilter) setParticipantContribution(PerformingParticipantFilter, SubsetPolicy) |
<element name="ParticipantContributions" minOccurs="0" /> | Supports setting PerformingParticipantFilter and optionally a SubsetPolicy |
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies
|
| ActivityInstanceQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies
|
| ProcessInstanceQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies
|
| ProcessDefinitionQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies |
| UserQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies |
| UserGroupQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies |
| LogEntryQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies |
| DocumentQuery | Mapped Structure | Comments |
|---|---|---|
| Inherited from Query | ||
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | Refer to section Predicate Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of
AttributeOrder or DataOrder elements Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies |
| DataQuery | Mapped Structure | Comments |
|---|---|---|
| getFilter() where(FilterCriterion) |
<element name="AndTerm" minOccurs="0" /> | See section about PredicateTerm. Also, refer to
section Predicate. Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of AttributeOrder or DataOrder elements. Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | Supported Policies: |
| PreferencesQuery | Mapped Structure | Comments |
|---|---|---|
| getFilter() where(FilterCriterion) | <element name="AndTerm" minOccurs="0" /> | See section about PredicateTerm. Supported:
|
| getOrderCriteria() orderBy(OrderCriterion) orderBy(FilterableAttribute) orderBy(FilterableAttribute, boolean) |
<element name="OrderCriteria" minOccurs="0" /> | Works as a list of OrderCriteria which consists of AttributeOrder or DataOrder elements.
Supported Attributes are:
|
| getPolicy(Class) setPolicy(EvaluationPolicy) removePolicy(Class) |
<element name="Policy" minOccurs="0" /> | No policies are supported. |
<!-- filter terms -->
<complexType name="PredicateTerm" abstract="true">
<complexContent>
<extension base="tns:PredicateBase">
<sequence>
<choice minOccurs="0" maxOccurs="unbounded">
<element name="and" type="tns:AndTerm" />
<element name="or" type="tns:OrTerm" />
<element name="isNull" type="tns:IsNullPredicate" />
<element name="notNull" type="tns:NotNullPredicate" />
<element name="isEqual" type="tns:IsEqualPredicate" />
<element name="notEqual" type="tns:NotEqualPredicate" />
<element name="lessThan" type="tns:LessThanPredicate" />
<element name="lessOrEqual" type="tns:LessOrEqualPredicate" />
<element name="greaterOrEqual" type="tns:GreaterOrEqualPredicate" />
<element name="greaterThan" type="tns:GreaterThanPredicate" />
<element name="isLike" type="tns:IsLikePredicate" />
<element name="inList" type="tns:InListPredicate" />
<element name="notInList" type="tns:NotInListPredicate" />
<element name="notAnyOf" type="tns:NotAnyOfPredicate" />
<element name="between" type="tns:BetweenPredicate" />
<element name="forProcessDefinition" type="tns:ProcessDefinitionFilter" />
<element name="forProcess" type="tns:ProcessInstanceFilter" />
<element name="processesInState" type="tns:ProcessStateFilter" />
<element name="forActivityDefinition" type="tns:ActivityDefinitionFilter" />
<element name="forActivity" type="tns:ActivityInstanceFilter" />
<element name="activitiesInState" type="tns:ActivityStateFilter" />
<element name="performingUser" type="tns:PerformingUserFilter" />
<element name="performedByUser" type="tns:PerformedByUserFilter" />
<element name="performingParticipant" type="tns:PerformingParticipantFilter" />
<element name="startingUser" type="tns:StartingUserFilter" />
<element name="userState" type="tns:UserStateFilter" />
<element name="participantAssociation" type="tns:ParticipantAssociationFilter" />
</choice>
</sequence>
</extension>
</complexContent>
</complexType>