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:
- 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
- Identifier – the XPath used to select the values. You can use full XPath syntax and functions here.
- Display – (optional) the XPath used to select the labels for the values. You can use full XPath syntax and functions here.
- 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:
- RPE sends a GET request to the address specified in the Request URL
- the user is prompted to authenticate if needed
- RPE reads the XML returned and executes the identifier XPAth on it. Assuming the XPath is valid this will return a list of strings.
- If the display XPath is set, RPE executes it on the same XML to build the label list of strings.
- 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.