Extracting data by using native filters

You can use native filters with all of the supported data sources. Native filters, which are interpreted by the Reporting Data Services Adapters, allow you to enter filters in the data source format. The native filter is processed by the Reporting Data Services Adapters rather than by Rational® Publishing Engine, so the use of native filters improves Rational Publishing Engine performance.

Before you begin

If you are integrating Rational Publishing Engine with a product that does not support Reportable REST data sources, the entire data set is fetched and cannot be filtered. To verify that your product does support Reportable REST data sources, you can test the filter condition in the native data source before using it in Rational Publishing Engine.

Review the Reportable Rest v1 document for more information about defining Reportable REST v1 services requirements.

About this task

Native filters are supported by Reportable REST data sources, which enable the filtering, sorting, and selective support of properties. The native filter requests a set of data from the data source, and then filters and refines the data for output from a Rational Publishing Engine template. You are not required to create filters in the product the data came from unless you would like to test the filters for accuracy, but you can create filters exclusively for use in Rational Publishing Engine templates from within Rational Publishing Engine.

In previous releases of Rational Publishing Engine, you could only define filters that were static. You had to know what the filters were when you designed the template and they could not be changed at run time.

Procedure

  1. In Document Studio, select the template element that contains the query that is to be filtered.
  2. In the Properties view, select the Data tab.
  3. In the Filter field, click the ellipsis.
  4. In the Native Filter tab, expand Variables.
    Note: Variables used in filters can be modified before the first query on that data source is used.
  5. Select a variable to filter on.
  6. Enter the syntax ${} to define your query to be filtered. For example, you can filter by a product name. Multiple product teams can use this template and specify a product name in the document specification at run time.
    cq:Product{cq:Product"${productName}"
    Note:
    • Custom attributes cannot be used in native filters.
    • If you rename a variable, the name is not updated in a script expression or native filter and creates a reference error. When you rename a variable, ensure that you revise the name in the script expressions and native filters as well.
    • To extract Rational DOORS data, use the DXL script as native filter condition. To extract REST data, use the XPath filter condition.
  7. Click OK.

Data sources that support the Reportable Rest v1 syntax

In Reportable Rest v1 native filters, you are only required to enter the text between the brackets []. The rest of the filter is generated by Rational Publishing Engine.

Design Management

Design Management supports native filtering from Reportable Rest v1 data sources. For more information, see Reportable Rest v1.

IBM® Rational ClearCase

The Rational ClearCase adapter supports native filtering from Reportable Rest v1 data sources. See Reportable Rest v1 for more information.

IBM Rational ClearQuest

The Rational ClearQuest adapter supports native filtering from Reportable Rest v1 data sources. See Reportable Rest v1 for more information.

IBM Rational RequisitePro

The following Reportable Rest v1 native filter example extracts the Rational RequisitePro PRRequirements schema by using Stability='High'.

Example

Add a filter expression to the node under Appliances, so only the appliances manufactured by a specific manufacturer are selected.
fields=Project/Requirements/PRRequirement[Stability = 'High']/(Stability|FullTag|Priority|Status)

IBM Rational Rhapsody

Rational Rhapsody supports Reportable Rest v1 data sources for use in native filters. For more information, see Reportable Rest v1.

IBM Rational Team Concert

Rational Team Concert supports Reportable Rest v1 data sources for use in native filters. See the Reportable REST API on Jazz.net for more information.

Example

projectArea/name="Rational Publishing Engine"  and target/name="1.2.1"
Resolved request:
fields=workitem/workItem[projectArea/name="Rational Publishing Engine" and target.name="1.2.1"]/(@href|summary)

Data sources that support the Reportable Rest v2 syntax

About this task

Note:
  • Requests are made to a data source only when required. For example, you can use conditions to have an element display in the output only when it contains data. The condition on a container element might be variable == "true". If this condition is not met and no data meets the variable condition, no requests are made to the data source.
  • You can calculate native filters before making the request. The native filter is calculated at the point where the query is encountered and uses the variable values at that point. So you can perform calculations in the template, which impacts the native filters.

IBM Rational ClearQuest

Rational ClearQuest version 8 supports native filtering from Reportable Rest v2 data sources. For more information, see Rational ClearQuest OSLC CM REST API .

Example

Sample variable filter:
cq:Product{cq:Product="${productName}") 
Sample resolved filter where the productName is Rational Publishing Engine:
cq:Product{cq:Product="Rational Publishing Engine")

Data sources that support the proprietary API syntax

IBM Rational DOORS

Rational DOORS supports a proprietary API and the filter is expressed using the Rational DOORS View syntax.

Example

The following Rational DOORS native filter example filters objects that contain the word "Documentation" in the Object Text attribute.
Attribute 'Object Text' contains 'Documentation' (case sensitive)
To generate the native filter text for a Rational DOORS data source:
  1. Open a Rational DOORS Module, and then click Tools > Filter > Define menu entry.
  2. Create the filter syntax:
    1. Select the Attributes tab.
    2. For Attribute, select Object Text.
    3. For Condition, select Contains.
    4. For Value, enter a specific value to filter on. For example, to filter only those objects that contain the word Documentation in the Object Text attribute, enter: Documentation
    5. Click Add. In the Advanced options section, the rule syntax is created.
  3. Click Description and copy the full description. You now have the Rational DOORS filter, which is a DXL script.
To add the Rational DOORS filter to the Rational Publishing Engine template element:
  1. Select the template element that contains the query that is to be filtered.
  2. In the Properties tab, expand Data.
  3. In the Filter field, click the ellipsis. The Filter Editor window opens.
  4. In the Native Filter tab, paste the Rational DOORS filter (DXL script) and click OK.

IBM Rational Tau

Rational Tau supports a proprietary API and the filter is expressed as an OCL query.

Example

The following Rational Tau native filter example filters packages that contains predefined names:
  • model.predefinedPackage represents the current schema element.
  • GetEntities(“predefinedPackage”).select(IsKindOf(“Package”) represents the underlying Rational Tau query.
  • select(HasPropertyWithValue("Name", "Predefined")) represents the native filter condition.
The query executed by the Rational Tau query evaluator is:
GetEntities(“predefinedPackage”). select(IsKindOf(“Package”))
select(HasPropertyWithValue("Name", "Predefined"))

Feedback