Read-only control for Work Item attributes in Rational Team Concert 4.0
This article walks you through the different ways of defining read-only attributes in work items, with special consideration for the new features introduced in version 4.0. This article assumes that you are already familiar with customizing work items.
Overview
Work items help you to manage different type of tasks in your development effort. You can define the attributes to be used in your work items either by creating new ones, or by adding existing attributes to the work item. This allows you to customize the information to be managed in your team, and to gather the relevant information needed for the work. This information customization includes scenarios where some information has to be presented to the users in a read-only state.
Rational Team Concert 4.0 allows a more fine-grained definition of conditions under which an attribute can be made read-only. These new features, in combination with those already available in previous versions, can be categorized as one of two types of “read-onliness”:
- Static read-onliness: the attribute remains read-only regardless of the state of the work item and the value of the rest of the attributes.
- Read-only attribute definition
- Read-only attribute presentation specification in work item presentation
- Dynamic read-onliness (new in 4.0): the attribute’s read-onliness behavior can change dynamically under defined conditions:
The rest of this article will review each of these options with special emphasis on the new features introduced for Rational Team Concert 4.0
Static read-onliness options
This topic reviews the available options for defining work item attributes as read-only in a static manner. Static means that the configured behavior for the work item will not vary as a result of changes in the information of the work item where the attribute is used. There are two types for this static definition:
Defining read-only attributes
The value of an attribute defined as read-only cannot be changed in the work item once it has been created. This behavior is configured at the attribute definition level in the Types and Attributes section of the Work Items Process Configuration (you have to navigate in your Eclipse Client to Project Configuration > Configuration Data > Work Items > Types and Attributes within the Process Configuration tab). There you can create a new attribute (or open an existing one), and tick the “read-only” checkbox. Let’s review the process with an example:
- In the Eclipse Client, navigate to Types and Attributes in the Process Configuration section of your Project Area editor.
- Click Add in the attributes section of the wizard and add a simple attribute called myReadOnlyAttribute of type Small String. Don’t forget to check the Read-only option.
An attribute presentation for this attribute can now be added to a work item editor and check that you won’t be able to change its content.
Customizing the content for static read-only attributes: typically when you define an attribute as read-only, you will end up attaching a default value or a calculated value to it, defined in the Attribute Customization section. This will give you the ability to customize the content of the attribute while keeping its read-only behavior for user modification (see References for further details).
Defining read-only attribute presentations
To be able to modify an attribute using one of the Rational Team Concert clients you need to add a presentation of the attribute to a work item editor presentation. This presentation can be defined itself as read-only, preventing the modification of the attribute in any work item type that makes use of that editor presentation.
Continuing with the previous example, you would perform the following steps:
- Create a new attribute for the work item called myAttribute of Type Small String
- In Eclipse Client, navigate to Project Configuration > Configuration Data > Work Items > Editor Presentations within the Process Configuration tab
- Choose the Editor Presentation you want to add the attribute to
- Click Add Presentation, select the attribute and a kind for it; and configure the read-onliness behavior:
This configuration will make the work item editor show a non-editable presentation for the attribute.
Note about combining static read-onliness features: you may wonder what would happen if using a read-only attribute with a writable attribute presentation in a work item editor. In that case, the work item will let you add content, but the entered information won’t be saved. (No error will be flagged).
Dynamic read-onliness options
The new features available in Rational Team Concert version 4.0 allow you to dynamically determine the read-onliness behavior of an attribute. These features are based on new out-of-the-box preconditions called Read-Only Attributes For Type And State and Read-Only Attributes For Condition.
Note about Dynamic Requiredness: Rational Team Concert 4.0 offers the same kind of behavior for dynamic requiredness for work item attributes. In that case the preconditions you may use are the ones called Required Attributes For Type and State and Required Attributes For Condition. The way you would have to configure that preconditions for requiredness is the same you will see in this topic of the article for specifying read-onliness
To enable these features you have to configure the Precondition Operation:
- Open your Project Area in the Eclipse Client and navigate to: Project Configuration > Team Configuration > Operation Behavior
- Select the Work Items > Save Work Item (server)for the role you want the operation to be activated
- Check Preconditions and follow-up actions are configured for this operation
- Click Add in the Preconditions. The wizard that opens will allow you to activate and configure these new features:
The following topics in this section will walk you through the use of these preconditions.
Dynamic behavior (requiredness and read-onliness) in Web UI: in Rational Team Concert 4.0 the attribute presentation is not automatically updated based on the preconditions’ computation. The Web client, unlike the Eclipse client, requires a save before the UI reflects the change. The behavior on the server however remains consistent; neither a read-only attribute which has been modified nor a required attribute which is unassigned will be saved. On such attempts, an error message like the following will be shown:
Read-only attributes in your workflow: Read-only attribute depending on work item type and state
The first precondition we are going to introduce it is the one called Read-Only Attributes For Type and State, which allows you to define read-only behavior of attributes for the different workflow states of a Work Item Type (or Type Category). The precondition configuration provides a presentation where to specify the state of the work item type and the attribute.
To show how this actually works, the next example defines a custom attribute called myAttribute as read-only in the In-Progress state for a Task work item:
After that simple configuration the attribute behavior will change restricting its modification for the defined states. In the Eclipse Client, the behavior change will look like the following:
Dynamic read-only attributes with conditions
What if defining an attribute as read-only is not that simple as identifying “forbidden” states? Then you can use the new precondition called Read-Only Attributes For Condition that allows you to write a small script with the condition checking that will make the behavior of your attribute change. The condition has to be defined in the Attribute Customization section for Work Items customization
Note for using scripts: Server-side execution of scripts is disabled by default. To enable it, you must go to the admin console of the application (https://{applicationURL}:9443/ccm/admin) and under Advanced Properties search for the Enable Process Attachment Scripts property and make sure it is set to true.
Continuing with the previous example, if you would like the custom attribute to be write enabled only if the estimated effort is less than 3 days; you would have to perform the following steps:
- Create a new condition and a script implementing it:
- Activate the Precondition and configure the attribute and condition that will handle it:
An easy sample script code implementing a condition could be as follows:
dojo.provide("net.jazz.example.readonly.Condition"); (function() { var EstimateDurationAttId = "duration"; var EstimateThreshold = 86400000; //ms for 3 days of work dojo.declare("net.jazz.example.readonly.Condition", null, { matches: function(workItem, configuration) { if(workItem.getValue(EstimateDurationAttId) > EstimateThreshold) return true; } }); })(); Please note that the mentioned script applies code to RTC’s built-in Estimate attribute with a Time Estimate presentation. Using this script on other estimate attributes with a different presentation may require modifications to the code.
Once you have performed the previous steps, the behavior will be the same as using the Read-Only Attributes For Type and State precondition. It is worth to highlight that in case of using conditions, they will be evaluated for every work item that has the attribute defined, there’s no way of restricting it to a certain Work Item Type (you could of course restrict the evaluation in your condition script code).
References
- Work Item Customization in Rational Team Concert 3.x
- Work Items attribute customization
- Dynamically changing an attribute to ReadOnly in Rational Team Concert
About the author
Jorge A. Diaz is a member of the Jazz Jumpstart Team. The Jazz Jumpstart Team is a worldwide group of development specialists who bring new and advanced Jazz-based technologies to customers. For additional information about the topic presented in the article add your comments or questions directly in the discussion part, or visit our Jazz.net Forum.
© Copyright 2012 IBM Corporation
Yes