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.