Contents


Use Rational Team Concert to create calculated fields within a work item

Comments

In IBM® Rational Team Concert ™ work items require a new attribute that automatically calculates and holds a value based on one or more values from custom or built-in attributes in the same type of work item. This article is based on the example of adding a custom attribute of type Decimal, which automatically holds the result of multiplying two other custom Decimal attributes from that work item. The following topics are covered.

Understanding the basics of custom attributes in Rational Team Concert

  • Writing JavaScript that performs calculations on one or more custom or built-in attributes
  • Creating a custom attribute that references the JavaScript to automatically perform the calculations in a work item when at least one of the dependent attributes have changed
  • Handling different types of attributes in the script

Prerequisites

This article assumes basic familiarity with customization of work items in Rational Team Concert, including how to create a custom attribute and add it to a built-in or custom work item type.

Creating a custom attribute

The first step is to create a custom attribute to hold the value of the calculation. In this example, you create the Decimal attribute Cost To Date (id: costToDate) as shown in Figure 1.

Figure 1. Creating the new decimal attribute
Custom attribute of type Decimal
Custom attribute of type Decimal

Writing JavaScript to hold the calculation

The next step is to create some JavaScript to hold the desired calculation. Store the result of multiplying two existing custom attributes of Decimal type: Rate (id: task.rate) and Hours To Date (id: task.hoursToDate), as shown in Listing 1. You can create the JavaScript in any basic text editor.

Listing 1. JavaScript containing attribute calculation
dojo.provide("com.example.costToDate");
dojo.require("com.ibm.team.workitem.api.common.WorkItemAttributes");

 (function() {
    dojo.declare("com.example.costToDate", null, {

    getValue: function(attribute, workItem, configuration) {

        try {
            var rate = parseFloat(workItem.getValue("task.rate"));
            var hours = parseFloat(workItem.getValue("task.hoursToDate"));

            var cost; 
            cost = rate * hours

            return cost.toString();
        }
        catch(err) {
            var txt; 
            txt="There was an error on this page.\n\n";
            txt+="Error description: " + err.message + "\n\n";
            txt+="Click OK to continue.\n\n";
            alert(txt); 
        }

    }

    });
})();

Figure 2 and Listing 2 show the various parts of the code.

Only the highlighted code in Figure 2 (only the code in bold in Listing 2) requires modification. Use this code as a template for other calculated fields.

Figure 2. Explanation of the JavaScript file
Code with items highlighted
Code with items highlighted
Listing 2. Explanation of JavaScript file
// script name must be the same in line 1 and 5
dojo.provide("com.example.costToDate");
dojo.require("com.ibm.team.workitem.api.common.WorkItemAttributes");

 (function() {
    dojo.declare("com.example.costToDate", null, {

    getValue: function(attribute, workItem, configuration) {

        try {
            // - sets the value that is stored in the custom attributes to the rate and 
            //   hours attributes
            // - task.rate and task.hoursToDate are the attribute ids assigned when the
            //   attribute was created
            // - the parseFloat Javascript function is used as the workitem.getValue
            //   function returns a string
            var rate = parseFloat(workItem.getValue("task.rate"));
            var hours = parseFloat(workItem.getValue("task.hoursToDate"));

            var cost; 
            cost = rate * hours  // actual calculation

            // always use the toSring() Javascript function when returning a value
            // (exceptions when returning a date field)
            return cost.toString();
        }
        catch(err) {
            var txt; 
            txt="There was an error on this page.\n\n";
            txt+="Error description: " + err.message + "\n\n";
            txt+="Click OK to continue.\n\n";
            alert(txt); 
        }

    }

    });
})();

Adding the script to the Project Area configuration

The third step is to add the JavaScript to the Project Area configuration.

  1. Open the Project Area configuration in the Rational Team Concert client.
  2. In the Process Configuration tab, expand Project Configuration, as shown in Figure 3 .
  3. Expand Configuration Data.
  4. Expand Work Items.
  5. Click Attribute Customization.
  6. On the right panel, right-click Calculated Values > Add...
Figure 3. Adding the script to the project configuration
Calculated values within project area
Calculated values within project area

As shown in Figure 5, add a Name to identify the script. In this example the name is costToDate. Type is Calculated Values. Provider is Script Based Calculated Value.

Figure 4. Selecting a name for the script
Adding script name
Adding script name

You then see the Name and Provider populated in the new section that opens at the right of the window. As shown in Figure 5, click Load... to select the JavaScript file from your local drive that you created in the previous step.

Figure 5. Loading the script
Load the script
Load the script

Updating the attribute to use the calculation

Next, update the custom attribute created in the first step to use the newly created script.

In the Project Area Configuration, edit the attribute. Select the new calculated value and any dependencies (attributes used in the script). As shown in Figure 6, in this example Hours to Date and Rate are selected. Both of these are used in the script.

Figure 6. Selecting the script for the attribute
Add script to the attribute
Add script to the attribute

Adding the new field to the editor presentation

The last step is to add the new attribute to the Editor Presentation. As shown in Figure 7, make this new calculated field non-editable by selecting True for the Read Only property.

Figure 7. Adding attribute to the editor presentation
Add attribute to editor presentation
Add attribute to editor presentation

After you have saved your Project Area Configuration, all new records created (of that work item type) will contain the new attribute. As shown in Figure 8, when one of the dependencies ( Rate or Hours to Date ) is changed, the Cost To Date is recalculated.

Figure 8. Cost to Date changes when Rate and Hours To Date change
Rate is 86, Hours to Date is 8, so Cost To Date is 688

Using different attribute types in the script

Learn how to handle some of the different types of attributes that you might need to reference in your calculations.

Enumeration values

To obtain the actual value stored in an Enumeration (instead of the literal value ...literal.l4... ), use the getLabel function (instead of getValue) when obtaining the value from the attribute, as shown in Listing 3.

Listing 3. Using getlabel instead of getValue
var project = workItem.getLabel("task.projectList");

Timestamp values

To use the value of a Timestamp attribute in your script, add a few lines to your script as highlighted in bold, as shown in Listing 4.

Listing 4. Using the Timestamp attribute
...
dojo.require("com.ibm.team.workitem.api.common.WorkItemAttributes");
dojo.require("dojo.date");
dojo.require("dojo.date.stamp");
…
    var fromISOString = dojo.date.stamp.fromISOString; 
…

To access the value of the Timestamp attribute, add the declaration (using the correct attribute id) shown in Listing 5.

Listing 5. Accessing the value of the Timestamp attribute
 var approved = fromISOString(workItem.getValue("task.approvedDate"));

Using built-in fields in the calculation

At times you want to include a built-in field as part of your calculation. Add the line of code shown in Listing 6 above your variable declarations.

Listing 6. Including a built-in field with your calculation
 var WorkItemAttributes = com.ibm.team.workitem.api.common.WorkItemAttributes;

Next, as shown in Listing 7, declare a separate variable for each built-in attribute that you require.

Listing 7. Declaring a variable for each attribute
 var status = workItem.getLabel(WorkItemAttributes.STATE);

Listing 8 shows a list of the most common built-in attributes.

Listing 8. Commong built-in attributes
 WorkItemAttributes.SEVERITY 
 WorkItemAttributes.PRIORITY 
 WorkItemAttributes.FOUND_IN 
 WorkItemAttributes.ID 
 WorkItemAttributes.TYPE 
 WorkItemAttributes.PROJECT_AREA 
 WorkItemAttributes.SUMMARY 
 WorkItemAttributes.STATE 
 WorkItemAttributes.CREATOR 
 WorkItemAttributes.OWNER 
 WorkItemAttributes.DESCRIPTION 
 WorkItemAttributes.CREATION_DATE 
 WorkItemAttributes.RESOLUTION 
 WorkItemAttributes.DUE_DATE 
 WorkItemAttributes.ESTIMATE 
 WorkItemAttributes.CORRECTED_ESTIMATE 
 WorkItemAttributes.TIME_SPENT 
 WorkItemAttributes.FILED_AGAINST 
 WorkItemAttributes.PLANNED_FOR 
 WorkItemAttributes.RESOLVER 
 WorkItemAttributes.RESOLUTION_DATE 
 WorkItemAttributes.TAGS 
 WorkItemAttributes.MODIFIED 
 WorkItemAttributes.MODIFIED_BY

Summary

The article explained how to create a custom attribute that automatically performs a calculation for display on a work item.

Acknowledgements

The author would like to thank his teammates Amin Eskooch and Karen Steele for their support and guidance. The author also thanks the numerous Rational Jazz community members who offer advice and support.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=981574
ArticleTitle=Use Rational Team Concert to create calculated fields within a work item
publish-date=08272014