What is new in RPE 1.1.2 – Variables in native filters


UPDATE: the example template is available here.

One of the most exciting features of RPE 1.1.2 is the ability to use variables in native filters. Prior to 1.1.2 native filters were hardcoded in the template limiting the applicability of this extremely useful feature.

Best practice: native filters should be used over scripted filters is to be preferred whenever available as it results in the minimum amount of data returned by the provider, reducing the data RPE has to process ( and discard).

Being able to use variables in native filters means that you can now adapt the native filters to the run-time conditions and create simpler and more efficient templates.

Syntax

The editor in RPE Document Studio allows you to insert variables in your native filters by drag&drop. If you want to type it then you need to surround the variable name in ${}. This is needed for RPE to be able to identify the variables in the native filter and replace them with the concrete values.

Limitations

For data sources that are configured through the docspec the value of the variable used in the native filter is the value at the start of the execution ( the value specified in the docspec or the default value for internal variables). Attempting to modify the variable’s value before the queries  on the data source will have no effect on the filter since the filter is computed when the doc gen starts.

If you need to use calculated variables than you have to configure your data sources through “Dynamic Data Source” elements.

Filter DOORS requirements based on an attribute value provided by the user

In the following I will use the “User Requirements” DOORS module that ships with DOORS 9.3 examples database. The challenge is to create a template that will display only the requirements with a given Criticality. The Criticality is a custom attribute of the User Requirements module and the desired value will be provided by the user through a template variable.

NOTE: I have modified some of the values to make the point.

Designing the template

The steps to design a template to achieve what you need are:

  • add the data source – use the Schema Discovery to pull the schema from the module you want
  • add a container to iterate over the objects
  • select what attributes you want to display and how you want them displayed
  • define a DOORS native to get only the “High” criticality requirements

After the first 3 steps the template looks like this:

The hardcoded native filter set on query $1 on the container looks like this:

If you generate the document now you will get the following output:

This fine but if you want to report on medium/low requirements you have to change the template or use scripted filter, neither of them being ideal. The “variables in native filter” is what will allow to get the best of both worlds: the performance of the native filter and the flexibility of scripted filters.

What needs to be changed is:

  • add a new external variable named “selectedCriticality”. This variable will be used in the native filter and its value will be read from the user
  • change the native filter to use the variable instead of the hardcoded “High” value

The filter now looks like this:

Running the report and providing the value “Medium” to the variable will result in the following output:


Best practice: assign a default value for all variables used in filters if the filter becomes invalid if an empty value is provided. This will avoid the report crashing if the end-user fails to provide a value for the variable. See bellow, I use the “High” as default for the selectedCriticality variable

Advertisements

Author: Dragos Cojocari

Architect for Rational Publishing Engine

2 thoughts on “What is new in RPE 1.1.2 – Variables in native filters”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s