Building Web Services Queries

All queries consist of the following three optional parts that can be used to build Web Services queries:

• The predicate element which is used for filtering.
• The order element used to specify a custom order.
• The policy element used to specify policies e.g. a subsetPolicy to limit results to a subset.

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

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)

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:

• xsd:string (default)
• xsd:long
• xsd:double
• xsd:dateTime

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:

• xsd:string (default)
• xsd:long
• xsd:double
• xsd:dateTime

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
• ActivityInstanceQuery
• ProcessInstanceQuery
• UserQuery
• UserGroupQuery
• LogEntryQuery
• ProcessDefinitionQuery
• DocumentQuery
• DataQuery
• PreferencesQuery

WorklistQuery

For the worklist query primarily userContribution is used to configure private worklist and participantContributions to configure specific participant worklists inclusion.

ActivityInstanceQuery

ProcessInstanceQuery

ProcessDefinitionQuery

UserQuery

UserGroupQuery

LogEntryQuery

DocumentQuery

DataQuery

PreferencesQuery

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