Configuring an HTTP filtered value set provider

You can configure an HTTP filtered value set customization that fetches data sets from XML documents through HTTP.

About this task

The HTTP Filtered Value Set provider reads XML data and transforms the document into a table of strings that use XPath expressions for rows and columns. A value set entry is created from each row by using a format pattern that describes how to construct the label from the column entries. Data set entries can be sorted and filtered to match the filter string.

Important: The XML data source URL used in this procedure (http://example.com/makes) is fictitious and does not work.

Tip: You can find several samples online that include more instructions on how to configure an HTTP filtered value set provider. To help find the XML data source URL, you can use Apache Tomcat.

If a Jazz™ Team Server is installed by using the directory structure InstallDir/server/tomcat/webapps/ROOT/ and you have a file that you want to publish on your Tomcat server, you can copy the file into the root folder or subfolder structure: $CATALINA_HOME/webapps/ROOT/

For example, in a standard Jazz Team Server and Tomcat deployment, to publish a file that is named makes.xml as https://localhost:9443/example_data/makes.xml, complete the following steps:

Note: If you are importing large HTTP value sets from an external server, you may experience significant delay. This delay can reduce overall server performance. Caching these requests in an intermediate format allows the server to handle a large volume of requests rapidly. The default for this caching ability is set to Off.

You can set the caching ability to On in the advanced properties of the application settings. Available options are:

HTTP Filtered Value Set Cache Duration: currently defaults to 600 seconds
HTTP Filtered Value Set Cache Enabled: currently defaults to false. Changing HTTP Filtered Value Set Cache Enabled to true will enable the caching.
HTTP Filtered Value Sets max Entries: currently defaults to 150.

Create a folder named example_data in the following location: InstallDir/server/tomcat/webapps/ROOT/
Copy the file makes.xml into the folder you created.

The file is now accessible as https://localhost:9443/example_data/makes.xml. Remember to replace localhost with the fully qualified host name of your deployment. Also ensure that your folder name does not conflict with the context root of any web application that is deployed on Tomcat.

The example that is described in this procedure adds an HTTP filtered value set that retrieves car makes from an XML document. The XML document uses the following structure:

<xml>
  <node>
    <id>1</id>
    <make>Car_A</make>
    <regions>,1,2,</regions>
  </node>
  <node>
    <id>2</id>
    <make>Car_B</make>
    <regions>,2,</regions>
  </node>
...
</xml>

Procedure

Open the Attribute Customization page:
1. In the Work Items perspective, in the Team Artifacts view, right-click the project area and click Open.
2. Click the Process Configuration tab.
3. Expand Project Configuration > Configuration Data > Work Items, and then click Attribute Customization.
Select Value Sets and click Add. Enter a name that describes the customization. From the Provider list, select HTTP Filtered Value Set.

In the Configuration section, specify the following information.

XML data source URL: This resource is expected to return an XML document.
Row XPath expression: Selects a list of nodes from the XML document.
Column XPath expressions: Expressions are relative to each node found and are used to get the labels for each column.
Column identifiers: Specifies a name for each column.
Entry label format: String template that describes how to construct the label that is based on the number of the column.
Click Apply filter string to values received from the data source if the data source does not filter the results according to the filter string.
Click Sort values received from data source if the data source does not sort the results according to the label.
Authentication method:
- No Authentication Required
- Basic HTTP authentication: Provide a user ID and password. The user ID and password are stored as plain text in the process specification.
- Form based authentication: Provide form information and a user ID and password. The user ID and password are stored as plain text in the process specification.
- OAuth: The remote server must be a friend. The user is prompted for a password. See Configuring friends.

Example:

Configuration section for an HTTP Filtered Value Set.

To change the previous example to use more than one column expression, specify the following values:

XML data source URL: http://example.com/makes
Row XPath expression: //xml/node
Column XPath expressions: ./make|./id.
Column identifiers: Make|Id
Entry label format: ${0} (${1})

The XML data source URL and the row XPath expression can also support the following variables:

Table 1. Supported variables
Variable	Description
`${filter}`	The current filter
`${xy.value}`	The value of attribute `xy`. The value is the internal representation of an attribute value, for example, `severity.literal.l5`.
`${xy.label}`	The label of attribute `xy`. The label is the display name of the attribute value, for example, `Critical`.

Example:

XML data source URL: http://example.com/makes
Row XPath expression: //xml/node[starts-with(./make, '${filter}')]
Column XPath expressions: ./make.
Column identifiers: Make
Entry label format: ${0}

Click Attributes and Types and select the work item type, such as Defect or Task. Scroll to the Attributes section. Click Add and create a custom attribute that is named Car of type Medium String. In the Value Set field, select Cars provider, and click OK.
Tip: In addition to Medium String, Short String, and Long String, you can also use String List. With attributes of type String List, you can use the String List presentation.
Click Editor Presentations. Select the editor presentation to which to add a field for the new attribute. Select the tab and then the section to which to add the field. For example, select the Details section on the Overview tab. With the section selected, click Add Presentation to add the field for the new attribute. In the Add Presentation window, in the Kind field, select either Value Set Combo or Value Set Picker.
The Value Set Combo option displays all the values in a list. The Value Set Picker option displays a window in which you enter text in a Filter field to see matching values. For value set providers that return many values, consider selecting Value Set Picker. The Value Set Combo option does not filter values; therefore, you might notice slower performance with many values.
Tip: If you specify String List as the attribute type, the Kind field is available in the Add Presentation window. Then, for the Kind field value, if you select String List, the Allow any value check box is available.
- To allow adding any string values for the custom attribute, select the Allow any value check box.
  
  The String List presentation includes the New and Add buttons.
  
  The New button displays a text field where you enter a string; the Add button displays a window where you enter text in a Filter field to see matching values.
- To disallow adding string values for the custom attribute, clear the Allow any value check box.
  
  The String List presentation includes the Add button only.
To save your changes to the project area, click Save.

Results

If the http://example.com/makes URL was valid, when you create or open a work item, the editor would include the Car field where users can select a car from the set of values that are provided by the XML document.

video icon Watch videos

CLM playlist
Jazz.net channel
User Education channel

learn icon Learn more

CLM learning circle
Agile learning circle
Learning circles

ask icon Ask questions

Jazz.net forum
developerWorks forums

support icon Get support

Support Portal
Deployment wiki
Support blog