Customizing attributes in Rational Team Concert 3.0

Patrick Streule, Dimitar Asenov, IBM Rational
Last updated: May 25, 2011
Build basis: Rational Team Concert 3.0, 3.0.1

This article describes the possibilities of customizing attributes with default values, dependent value sets, validation rules and dynamic required attributes. You should be familiar with work item customization already. If not, please read Work Item Customization and Work Item Editor Presentations first. The functionality shown here applies to both the Web UI and the Eclipse UI.

Overview

An early preview of attribute customization was made available in RTC 2.0.0.2. In 3.0 the functionality has been extended and is now configurable in the Process Configuration UI of the Eclipse client. Default values, value sets and validation rules are managed in the Attribute Customization section of the Project Area Editor. Once you have defined them there, you have the option to associate e.g. a value set with custom or built-in attributes. Required attributes can be configured in the Operation Behavior section of Team Configuration and, since 3.0.1, computed dynamically for values of other attributes using a Condition.

Default values

A simple case of customization is to define the default value of an attribute. When a work item is created, the attribute will have that value pre-filled. As an example, we want to populate the description field with some guidelines on how to file a defect.

1. In the Attribute Customization section, add a new Default value definition for Multi-Line HTML. The selected type has to match the type of the attribute:

   

2. Add the text that should be pre-filled on creation into the configuration area. You can use the same formatting capabilities as in the work item description field, e.g. Bold (Ctrl+B) and Italic (Ctrl+I). You can also copy and paste links to artifacts:

   

3. In the Types and Attributes section of the Process Configuration Editor, edit the Description attribute and select the default value that we have just created:

   

4. When you now create a new Defect, the description will be pre-filled with the guidelines:

   

Simple default values can be defined for any attribute type, not just for text attributes. For enumerations, we also support a special default value definition called Role Based Enumeration Default that allows to define the attribute’s default value by user role. As an example, we look at an enumeration How Found that describes the activity during which a defect was found:

• Testing
• Self-Hosting
• Customer

The default should be chosen according to the role of the user that files the defect (assuming that the roles correspond to the mostly likely activity).

Dependent enumerations

A very frequent use case is to have the value set of an attribute depend on the current value of another attribute. In the following example, we look at two enumerations, Operating System and Browser. The possible values for Browser depend on the Operating System selected.

1. Create two enumerations. The enumeration literals for Operating System are defined as:
   • Windows XP
   • Windows 7
   • OS X 10.6
   • Ubuntu 10.04
   The enumeration literals for Browser are defined as:
   • IE 7
   • IE 8
   • IE 9
   • Firefox 3.6
   • Chrome
   • Safari 5

2. In order to define the dependent value set, create a new Dependent Enumerations value set definition, and select the two enumerations. For each selection on the left side (the source enumeration), you can check the values that should appear in the value set of the target enumeration if that value is selected:

   

3. Create two custom attributes for Operating System and Browser. For the Browser attribute, select the value set that was defined above, and define a dependency on the Operating System attribute:

   

4. Add the two attributes to the editor presentation, and you are done:

   

Role-based user lists

For custom attributes of type Contributor, a special value set definition allows to show all users in a project or team area that have a specific role. The following example explains how to set up a custom attribute Stakeholder that offers to select all users that have the Stakeholder role in the project.

1. Create a new value set definition of type Role Based User List:

   

2. Choose the appropriate role in the configuration section:

   

3. Create a new custom attribute of type Contributor, associate it with the value set definition and add it to the editor presentation. The drop-down will contain the users that have the Stakeholder role:

   

As you can see from the above screen shot, the drop-down contains an entry More… to select other users. This may not be desirable in this case where the role of the user is important. Since RTC 3.0 there is a special presentation Generic Combo that shows only the values from the value set, without any additional logic:

With this presentation, only the users from the value set will be shown:

Validation

Sometimes there are constraints on the allowed values of an attribute. For instance a specific format for a text attribute, or a permitted range for a number attribute. Since RTC 3.0, there are two out-of-the-box validation rules that can be configured for this kind of constraint checking: A regular expression based one and a number range one.

In the following example, we look at an attribute Product Number whose values need to conform to: 4 characters, dash, 5 digits, dash, followed by P, Y or Z.

1. Create a new validator of type Regular Expression. For each validation rule, you can choose whether the result is informational, a warning or an error. And you can specify the message that will be shown in the tooltip when the validation fails:

   

2. Create a new custom attribute of type String and associate the validator with it:

   

3. The field will now validate the input on typing and show the configured error message in a tooltip if the value is invalid:

   

When you try to save the work item with an invalid value, you will notice that the work item can be saved anyway. In order to prevent saving in this case, you can configure the precondition Attribute Validation:

With the precondition enabled, saving a work item that has failing validation results will be prevented. Note that only validation rules that are configured as Error are enforced.

Hint: The Regular Expression validation rule can also be used to enforce a maximum number of characters in a text field:

Dynamic required attributes

In RTC it is possible to dynamically determine which attributes of an item are required based on other attributes. Two options are available:

• Required attributes can be determined based on item type and state. An example here is requiring that the Estimate attribute is set whenever an item’s state is Resolved. This is configured entirely using the Eclipse UI.
• Since 3.0.1 it is also possible to determine required attributes based on the value of any other attribute of the item. For instance Due Date might be required whenever the Severity of an item is Critical. This is based on a user provided script.

Here is how to configure a required attribute based on state. A typical case is to check this when saving an item:

1. In the Operation Behavior section of the project configuration choose the Save Work Item (server) operation and the Everyone user:

   

   
   
   
2. Add a new Required Attributes precondition:

   

   
   
   
3. Select the item and state for which you want to require that an attribute is set and click Edit:

   

   
   
   
4. Select the attribute which must be provided by the user whenever the item is in the specified state:

   

To configure a required attribute based on the value of other attributes follow these steps:

1. Create a new condition in the Attribute Customization section of the project configuration. Currently only Script Based conditions are supported. For more information about creating the necessary script please refer to Work Items attribute customization Wiki:

   

2. In the Operation Behavior section of the project configuration choose the Save Work Item (server) operation and the Everyone user like in the previous example.
3. Add a new Dynamic Required Attributes precondition:

   

   
   
   
4. Click the Add button on the right to create a new entry. Specify the Rule that is defined by the script you created and choose which attributes will be required. The script implementing the rule can make a decision based on the value of any attribute of the work item:

   

   
   
   

Script based customization

This functionality is still experimental in RTC 3.0.1. For more details, please refer to the Work Items attribute customization Wiki.

---

About the authors

Patrick Streule is a developer and component lead for the RTC Work Item team and has mainly worked in the area of queries, work item backend, OSLC-CM and CLM.

Dimitar Asenov is a developer for the Work Item team during a summer internship focusing on attribute customization.

---

© Copyright 2010, 2012 IBM Corporation