Filter conditions supported by REST native filters

The Reportable REST service implementer optimizes the information that is returned by the native filter. The filter is specified as an XPath filter on the fields argument.

Extracting information using multi-level filtering

Use the filter to limit the XML elements that are included by the child elements that are filtered. All the fields in the filter are values of the XML elements that are directly contained by the parent element. However, you can use XPath syntax to retrieve elements deeper in the hierarchy. You can extract specific information by using the following methods:
  • Multi-level filter conditions
  • Multi-level path conditions
  • XML attributes
Filters can be specified at multiple levels. The following example shows the PRRequirement that is returned with the fields argument.
fields=Project/Requirements/PRRequirement[Stability = 'High']/(FullTag|Priority|Status|TracesTo/Relationship[Suspect='true']/*).

This filter condition extracts the appliances manufactured by a specific manufacturer, along with additional information selecting all TracesTo relationships that are suspect. The following example shows the results of the filter:

<PRRequirement>
<FullTag>PR1</FullTag>
<Priority>Medium</Priority>
<Status>Incorporated</Status>
<TracesTo>
<Relationship>
<Suspect>true</Suspect>
<RelationshipType>Traceability</RelationshipType>
<Direction>TracesTo</Direction>
<RelationshipID>{10C4D0CE-24CF-4C80-8167-E5A849FC821B}16{10C2D0CE-84CF-4C80-9166-E5A849FC821B}1RelationshipID>{10C2D0CE-84CE-4C80-9166-E5A849FC821B}16{10C2D0CE-84CF-4C80-9166-E5A849FC821B}1</RelationshipID>
<RelatedRequirement/>
</Relationship>
[… More matching relationships]
</TracesTo>
</PRRequirement>

Extracting information using a multi-path setting

You can use XPath syntax to retrieve values that are deeper in the hierarchy. However, you can supply only one value for the filter to evaluate. If you supply multiple values, the expression is considered undefined. For example, the PRRequirement has a related document. This expression is defined in the schema as:

xs:element maxOccurs="1" name="Document" type="ReqDocument" minOccurs="0".

Because there can never be more than one related document, the expression can be evaluated. If there is no related document, there is no match. The fields expression for the multi-path setting is:

fields=Project/Requirements/PRRequirement[Document/Extension=prd]/(*|Document/*.

Using XML attributes in a filter

You can extract information using the XML attribute values in a filter condition. The following example shows how the attributes are used:
fields=Project/Requirements/PRRequirement[attribute::Stability = 'High']/(FullTag|Priority|Status).
fields=Project/Requirements/PRRequirement[@Stability = 'High']/(FullTag|Priority|Status).
Both forms of the attribute axis attribute:: and @ are supported. The XML results are identical, because Stability is not included in the results.