Blogs about Jazz

Blogs > Jazz Team Blog >

Improve document generation experience with Configuration Layer in Publishing template

Before generating a document with IBM Engineering Lifecycle Optimization – Publishing (PUB), end-users must configure the data source and provide a number of inputs. Though this cannot be avoided, we can make the user experience better by enabling value selection instead of manually entering the values, thanks to the Configuration Layer in PUB.

Configuration layer in PUB template allows the end-user to select URLs from a drop-down instead of typing them. End-user will be shown a list of readable values (ID, title, etc.) as the labels for the URLs. The configuration layer also helps in setting values for template variables wherever applicable. ETM, EWM, RMM use configuration layer to support document generation from Web UI. In this blog, we will see how it can be done for document generation from Publishing Launcher.

Edit Configuration Metadata in Publishing Studio
To add or edit configuration metadata for a data source or variable, you need to edit the template in Publishing Studio. In Outline view, right-click on the data source that needs to be configured and select “Edit Configuration Metadata”. Usually, this data source is the parent data source that the end-user has to configure – one that is not dynamically configured and the name does not start with “_”.

There are 4 fields in the “Edit Configuration Metadata…” window.
Type – restricts the format of user input.
Identifier – XPath expression that selects the data PUB will use to configure the report. The values of this attribute must be Reportable REST URLs.
Display – XPath expression that selects the data PUB will show the user.
Request URL – the URL on which PUB will make data request. There are pre-defined variables that can be used in this field that point products will recognize. You cannot use these values if configuring the report from standalone Publishing.
$public: Public URL of the server
$projectAreaUUID: project area.

Note: You can drag and drop attributes from Data Source View into the identifier and display fields.

How PUB uses these values?
If the Request URL is not set, then user has to manually input the data source value when executing the report. If the Request URL is set, and the Identifier field is not set, the resolved value of the Request URL will be used for report generation.
If both Request URL and Identifier fields are set, a GET request to the resolved Request URL is made, then Identifier and Display XPath expressions are evaluated on the server response and a list is shown to user to choose from. The values matching Display expression are shown in the list and the corresponding value of Identifier is set as data source URI.

Note: The identifier XPath and display XPath must return collections of equal size and in the same order since PUB will match them 1:1 in the order they are received.

Example 1 (setting URI for data sources):
A template that reports on ETM test case details needs to be configured with an URL that looks likes this:
There are chances of human error while end-user enters this URL. In contrast, the configuration layer provides a drop-down so that end-user can select any test case. The URL for the selected test case will be used to configure test case data source and there is no room for error.

The dialog presents the user with the list of the test case titles from the JKE Banking project area in ETM. When the end-user selects an entry from the drop-down, PUB configures the data source to the Reportable REST URL of that test case.

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

What happens in the background?

1. PUB makes a GET request to the address specified in the Request URL. End-user is prompted to authenticate if needed.
2. PUB reads the XML returned and executes the identifier XPath on it. Assuming the XPath is valid this will return a list of strings.
3. Since the display XPath is set, PUB executes it on the same XML to build the string labels.
4. PUB shows the list returned by the display XPath to the end-user. Each label is associated with a corresponding identifier.
5. On selecting a particular test case title, its identifier is used as the data source URI.

Example 2 (providing values for template variables):
Suppose we have to list all the category values for EWM WorkItems, this is how the category variable has to be configured:
Type: string
Identifier: /workitem/category/name
Display: /workitem/category/name
Request URL: ${public}/rpt/repository/workitem?fields=workitem/category/name

List of category names is shown to user when he selects “Configure using Metadata”.

You may note the difference between fields=workitem/category and fields=workitem/workItem/category. The latter will return only those categories that have one or more WorkItems assigned to them.

You can consider using configuration layer to shift the complexity from the end-user to the template designer. The Template designer adds his knowledge in the template so that user can set the URI for data sources and provide values for template variables without any error. This makes document generation easy even for non-technical users.

Subramanya Prasad Pilar
IBM Engineering Lifecycle Optimization – Publishing