Building Web Services Queries

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.

Predicate

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 descriptions

Predicate Description
FilterAndTermBuilding complex filter terms.
FilterOrTermBuilding complex filter terms.
OperatorFilters (attribute)Applying filters to according attributes.
OperatorFilters (variable)Finding activity instances / process instances containing specific workflow data.
ProcessDefinitionFilterFinding instances belonging to specific process definitions.
ProcessInstanceFilterFinding instances belonging to specific process instance hierarchies.
ActivityFilterFinding instances of specific activities / finding instances related to instances of specific activities.
ActivityInstanceFilterFinding specific activity instances / finding log entries related to specific activity instances.
ActivityStateFilterFinding activity instances currently being in specific states.
PerformingUserFilterFinding activities currently being performed by a specific user.
PerformingParticipantFilterFinding activities currently being performed by a specific participant.
PerformedByUserFilterFinding activities that were performed and completed by a specific user.
ProcessStateFilterFinding process instances currently being in specific states.
StartingUserFilterFinding process instances being started by a specific user.
UserStateFilterLimiting 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.

Example

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

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)

Unary

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> 

Binary

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>

BinaryListValued

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>

Query Dependent Filters

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" />

Order

By setting an attributeOrder or dataOrder the query results can be ordered.

Example

<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

Policies allow setting special options for the query. One important policy that can be used to realize paging is the subsetPolicy.

Example

<quer:policy>
    <quer:subsetPolicy>
        <quer:evaluateTotalCount>true</quer:evaluateTotalCount>
        <quer:maxSize>5</quer:maxSize>
        <quer:skippedEntries>0</quer:skippedEntries>
    </quer:subsetPolicy>
</quer:policy>

Specific Queries

This section describes the following query classes with the specific predicates that can be used for filtering, available attributes and policies.

WorklistQuery

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:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
  • ProcessDefinitionFilter
  • ProcessInstanceFilter
  • ActivityFilter
  • DataFilter
  • SubProcessDataFilter
  • HierarchyDataFilter
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:
  • startTime
  • lastModificationTime
  • activityOid
  • activityInstanceOid
  • processOid
  • processPriority
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

ActivityInstanceQuery

ActivityInstanceQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
  • ProcessDefinitionFilter
  • ProcessInstanceFilter
  • ActivityFilter
  • ActivityInstanceFilter
  • ActivityStateFilter
  • PerformingUserFilter
  • PerformingParticipantFilter
  • PerformedByUserFilter
  • DataFilter
  • SubProcessDataFilter
  • HierarchyDataFilter
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:
  • startTime
  • lastModificationTime
  • activityOid
  • processOid
  • processPriority
  • oid
  • currentPerformerOid
  • currentUserPerformerOid
  • performedByOid
  • state
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

ProcessInstanceQuery

ProcessInstanceQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
  • ProcessDefinitionFilter
  • ProcessInstanceFilter
  • ProcessStateFilter
  • StartingUserFilter
  • DataFilter
  • SubProcessDataFilter
  • HierarchyDataFilter
  • ProcessInstanceHierarchyFilter
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:
  • oid
  • startTime
  • terminationTime
  • state
  • processDefinitionOid
  • rootProcessOid
  • startingUserOid
  • startingActivityInstanceOid
  • priority
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

ProcessDefinitionQuery

ProcessDefinitionQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
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:
  • triggerType
  • invocationType
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

UserQuery

UserQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • ParticipantAssociationFilter.FILTER_KIND_MODEL_PARTICIPANT
  • ParticipantAssociationFilter.FILTER_KIND_USER_GROUP
  • ParticipantAssociationFilter.FILTER_KIND_TEAM_LEADER
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
  • UserStateFilter
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:
  • oid
  • accountId
  • firstName
  • lastName
  • eMail
  • validFrom
  • validTo
  • description
  • failedLoginCount
  • lastLoginTime
  • realmId
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

UserGroupQuery

UserGroupQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • ParticipantAssociationFilter.FILTER_KIND_USER
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
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:
  • oid
  • id
  • name
  • validFrom
  • validTo
  • description
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

LogEntryQuery

LogEntryQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
  • ProcessDefinitionFilter
  • ProcessInstanceFilter
  • ActivityFilter
  • ActivityInstanceFilter
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:
  • oid
  • type
  • code
  • subject
  • timestamp
  • processOid
  • activityOid
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

DocumentQuery

DocumentQuery Mapped Structure Comments
Inherited from Query    
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> Refer to section Predicate

Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
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:
  • id
  • name
  • contentType
  • owner
  • dateCreated
  • dateLastModified
  • content
  • score
  • documentQuery:metaDataFilter:any
  • documentQuery:metaDataFilter:named:<name>
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies

DataQuery

DataQuery Mapped Structure Comments
getFilter()
where(FilterCriterion)
<element name="AndTerm" minOccurs="0" /> See section about PredicateTerm. Also, refer to section Predicate.
Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
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:
  • processId
  • dataTypeId
  • declaredTypeId
  • modelOid
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> Supported Policies:

PreferencesQuery

PreferencesQuery Mapped Structure Comments
getFilter() where(FilterCriterion) <element name="AndTerm" minOccurs="0" /> See section about PredicateTerm.
Supported:
  • FilterAndTerm
  • FilterOrTerm
  • UnaryOperatorFilter
  • BinaryOperatorFilter
  • TernaryOperatorFilter
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:
  • scope
  • moduleId
  • preferencesId
  • realmId
  • userId
getPolicy(Class)
setPolicy(EvaluationPolicy)
removePolicy(Class)
<element name="Policy" minOccurs="0" /> No policies are supported.

PredicateTerm Building

	<!-- 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>