RegisterLog In to Jazz.net dW

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":

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:

  1. In the Eclipse Client, navigate to Types and Attributes in the Process Configuration section of your Project Area editor.
  2. 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.
  3. Read-only attribute definition
    How to define an attribute which content is read-only


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:

  1. Create a new attribute for the work item called myAttribute of Type Small String
  2. In Eclipse Client, navigate to Project Configuration > Configuration Data > Work Items > Editor Presentations within the Process Configuration tab
  3. Choose the Editor Presentation you want to add the attribute to
  4. Click Add Presentation, select the attribute and a kind for it; and configure the read-onliness behavior:
  5. Read-only attribute presentation
    Set the Read Only attribute to True to make the presentation read-only


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:

  1. Open your Project Area in the Eclipse Client and navigate to: Project Configuration > Team Configuration > Operation Behavior
  2. Select the Work Items > Save Work Item (server)for the role you want the operation to be activated
  3. Check Preconditions and follow-up actions are configured for this operation
  4. Click Add in the Preconditions. The wizard that opens will allow you to activate and configure these new features:

  5. Preconditions configuration
    The new features are avaiable as Preconditions to the Save Work Item operation


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:

Error message

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:

Read-only enabling
Configure the read-only conditions choosing Work Item Type, State and affected attributes


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:


Read-only testing
See how the attribute presentation changes to read-only when the work item state changes


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:

  1. Create a new condition and a script implementing it:

  2. Defining the condition
    Create a new Condition within Attribute Customization and upload a script implementing 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.


  3. Activate the Precondition and configure the attribute and condition that will handle it:
  4. Activating the preconditon with condition
    You have to link the condition with the attribute that will affect in the Precondition configuration


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


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.

Feedback
Was this information helpful? Yes No 5 people rated this as helpful.