RPE Configuration Layer or docgen configuration made simple

One of RPE’s weakest points is its usability which comes as the price for RPE being a highly flexible, generic document generation tool. The user that wants to generate a document with RPE needs to know about XML schemas, REST APIs, data URLs and how they are connected.  This is not an easy feat even for the technical users of RPE and not all RPE users are necessarily technical.

The RRDG implementation in various tools hides very well this complexity but there are scenarios where the standalone RPE is still needed.  To address those scenarios RPE 1.2.1 has introduced the Configuration Layer.

The configuration layer allows template authors to embed knowledge in the templates , knowledge that is used by RPE to allow for the end user to select URLs from lists instead of typing URLs. Furthermore the end user can be shown a list of human readable properties ( like the title of the entity) as the labels for the URLs.  In the same way the configuration layer allows providing values for template variables where that makes sense.

What the configuration layer is essentially doing is moving the complexity from the end user to the template author. From RPE’s perspective this keeps RPE a generic tool while enhancing the templates with scenario specific information.

RQM and RTC also use the configuration layer to support for their docgen Web UI. See Customize RPE report to be executable from Quality Manager and Configuring metadata in Rational Publishing Engine for document-style reports

Using the Configuration Layer in RPE

A template tat prints information on an RQM test plan needs to be configured with an URL that looks likes this:


This URL is not easy to build manually and the process has a lot of room for human error. In contrast the configuration layer replaces the manual process with a selector dialog that leaves no room for error and is much more usable:


The dialog presents the user with the list of the the test plan names from the JKE Banking Project sample in RQM. When the end user selects an entry from the list RPE configures the data source to the Reportable REST URL of that testplan.

This feature is accessed from the context menu  of the data source in RPE Launcher and is visible only if the data source has configuration metadata associated with it in the template.


Editing the Configuration Layer Information

To add/edit the configuration metadata for a data source you need to edit the template in RPE Document Studio and select the “Edit configuration metadata” menu.


The metadata consists of:

  1. Type – the type of the data being selected. This field is not used by RPE directly so any value can be defined but you should use something that matches the selection type. RRDG integrations can use this for validating user input
  2. Identifier – the XPath used to select the values. You can use full XPath syntax and functions here.
  3. Display – (optional) the XPath used to select the labels for the values. You can use full XPath syntax and functions here.
  4. Request URL – the URL of the XML that contains the identifier and display value lists

Alternatively you can select a Value Set if the RPE Central Library is installed and configured. This will be covered in a future article.

How it works

The flow of data when a data source is configured using metadata information is described below:

  1. RPE sends a GET request to the address specified in the Request URL
    • the user is prompted to authenticate if needed
  2. RPE reads the XML returned and executes the identifier XPAth on it. Assuming the XPath is valid this will return a list of strings.
  3. If the display XPath is set, RPE executes it on the same XML to build the label list of strings.
  4. RPE shows the list returned by the display XPath to the end user. Each label is associated with the matching entry (by position) from the identifier list.
    • if the display XPath is not set, RPE will show the identifier values
    • the identifier XPath and display XPath must return collections of equal size and in the same order as RPE will match them 1:1 in the order they are received

TIP: when learning to use this feature I recommend using only the identifier XPath and put various XPaths queries in it to easily visualize what they return.

The example explained

In this example RPE is configured to use the TestPlan feed to build a list of title-URL pairs for the testplans.

Request URL: the URL of the JKE Banking Example test plan feed


Identifier XPath: the XPath of the “id” element in the feed xml. The id elements stores the URL for each entry in the feed.


Display XPath: the XPath of the “title” element in the feed xml. The id elements stores the human readable title for each entry in the feed.



Author: Dragos Cojocari

Architect for Rational Publishing Engine

13 thoughts on “RPE Configuration Layer or docgen configuration made simple”

  1. Hi Dragos,

    Thanks for this post, using the configuration layer looks set to simplify document generation for anyone using my templates! I no longer have to make a .dsx file for every module in our project!

    That said I’ve run into difficulties. When I configure a data source or variable to be set using the configuration layer and provide it with a request URL to our DNG project, it seems to timeout during the request and returns no information. The request URL is certainly correct, and returns the correct XML when I address it in my web browser. RPE prompts with the User Authentication tab, it then tells me it is processing the request, but then the progress dialogue closes without any further information returned. I have tried this with ‘Auto’ and ‘OAuth’ selected as the authentication method.

    Have you found this feature to work with DNG? Does this behaviour indicate that the request URL returned no xml, or that the identifier query returned no info, or either?


    1. My apologies. I have just realised that my problem was the query. I was querying ‘data/artifact/title/_value’ when it seems to work fine if I use ‘data/artifact/title’
      The template progresses!

      I’m now trying to use an Xpath function (replace) but I’m struggling to find the right namespace for it. It doesn’t recognise it as is and prefixing with fn: doesn’t seem to work.

      1. Hey Sam,

        RPE uses the JRE’s XPath processor which only supports XPath 1.0 functions ( see links below). To the best of my knowledge XPath 1.0 has no replace function and there is no way to “inject” that function in the context in which RPE evaluates the Configuration’s Layer xpaths.

        You can use other functions like contains and you need no namespace for that. This is an example of a valid expression supported by XPath 1.0 and usable in RPE: /Project/Requirements/PRRequirement[contains(FullTag, ‘PR1’)]/Text


  2. Is there a limit on the number of entries that a feed can return. I’m getting a list of test plans in a project area but not all of them.

    1. Hey Ben,

      I believe the configuration layer only lists the first page of results returned by the data provider and the default page is of 50. Can you use an XPath query that returns a smaller subset of the test plans?

      Alternatively you could check if you can increase the page size of the data returned by QM.

      We also need to look what we could do in RPE to support more than the first page of results.


      1. I found how to fix the problem (it’s a setting in the QM application, default is to limit feed results to 50)

  3. Ben,

    it is great if this works for you with the new limit you set to for the feed limit.

    Please note though that RQM has a hard limit to its feed limit. If you set it to 100.000 it will lower it automatically to 500 or something similar as larger values would impact the server’s performance. Well, at least this is how this worked a few years ago.


  4. When I do this and upload report resource to RQM, when i run report I get a browse… button, which, when clicked then provides a list of Test Plans. Is this correct? As I have seen OOTB reports that have the list of Test Plans in the dialog box without having to select browse. Also, the other datasources are dynamically configured, but are appearing on the screen to the user as if to have values provided when the report is run…how can I remove this?
    Using this as the Request URL for a list of test plans: ${public}/service/com.ibm.rqm.integration.service.IIntegrationService/resources/${projectAreaUUID}/testplan

      1. Hi Michele. Rename the DSC in the .dta file that you do not want to appear when publishing with an underscore preceding the name. For example _IDontWantThisToShowUp. With the “_” it will be hidden by RRDG.

        Did you ever get a response on how to to get a list of test plans without having to use the browse button?

  5. Can anyone provide me with an example of how to the user the Configuration Layer to present a list of documents from a named RRC project area? And to generate a data source for the selected module?

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s