This article explains how to customize IBM® Rational Team Concert™ for use beyond the traditional application lifecycle management. It starts with a sample scenario — to build an application to track web-based opportunities — to show Rational Team Concert administrators how to create a new work item type, customize the work item type (add custom attributes, update the editor presentation for those attributes, and configure required attributes) and test the work item type. It includes links to Resources that further describe how to create new work items, workflows, and editor presentations.
Before you start
To follow this article, you need to have access to a Rational Team Concert Version 4.x server with an appropriate project area created. If you have not already purchased and installed Rational Team Concert or are not currently using Rational Team Concert on the cloud, you can download an evaluation version from Jazz.net. Or, if you do not want to download and install Rational Team Concert on your local machine, you can try it online in a sandbox on Jazz.net. For more information on the evaluation version or sandbox options from Jazz.net, see the links provided in Resources.
Once you have access to a server, you will also need to have the Rational Team Concert client for the Eclipse IDE installed and a connection established to the appropriate repository for your server. Currently, certain customizations can only be performed using the Eclipse client and cannot be accomplished using the web client.
Sample use case: application to track opportunities
This article is based on the sample use case to create a web-based opportunity management tracking application. The end users of the application are primarily managers within a consulting services organization. An opportunity refers to potential consulting work for clients. The intent is for managers or consultants to create work items for new business opportunities as they arise. The ultimate goal is to provide visibility to the pipeline, track metrics around the demographics of the customer base, and understand what factors influence the outcome of winning or losing an opportunity. An added requirement is to foster an environment where employees at all levels of the organization can submit a business opportunity for consideration and be able to track the opportunity through the entire opportunity lifecycle.
The following sections explain how to:
- Create a new work item type.
- Customize the work item type:
- Add custom attributes.
- Update the editor presentation for those attributes.
- Configure required attributes.
- Test the work item type.
Create a new work item type
The first step to customize Rational Team Concert for your non-traditional needs is to create a new work item type. This can be accomplished using either the web client or the Eclipse client. For the opportunity management use case, name the new work item type
Opportunity with the ID
opportunity and category
opportunity – com.ibm.team.workitem.workItemType.opporunity, as shown in Figure 1.
Figure 1. Create the Opportunity work item type
If you do not intend to use any of the work item types provided by Rational Team Concert by default, you can delete them using the Remove option available in the Eclipse client, so that they will not appear in your work item menu selection.
It is necessary to set a workflow when defining your new work item type. If none of the existing workflows in Rational Team Concert fit, add a new workflow. Such is the case for opportunity management. Workflow states that are appropriate for an opportunity work item can be seen in Table 1. Actions and transitions between the states can be defined to suit your needs and can be as unconstrained or restrictive, according to your requirements.
Table 1. Opportunity management workflow
|Uninitialized||This is the initial state of a new opportunity in Rational Team Concert. A prospect was found that could be a potential lead.|
|Noticed||The lead has been received but customer interest has not been checked.|
|Identified||The team has confirmed that the offering or service is in our domain and an owner has been assigned.|
|Validated||The owner has validated that the opportunity is consistent with our business mission and is a valid opportunity. The owner has identified the skills required and the potential revenue amount.|
|Qualified||The prospect deems our consulting organization to be on the list of potential vendors. We determine the opportunity is worth pursuing and we have resources available.|
|Conditional Agreement||We provided all information for the customer to make a decision.|
|Won||A consulting agreement has been completed. (The contract has been signed and the project has been staffed).|
|No bid||We decide not to bid.|
|Customer did not pursue||The customer is no longer looking for service, due to a change in the budget, the focus areas, or executive roles.|
|Lost to competition||The customer has chosen a competitor to address a specific need.|
It is also necessary to set an editor presentation when defining your new work item type. A new editor presentation should be added for this purpose. For the opportunity management use case, a
com.ibm.team.workitem.editor.opportunity editor presentation is appropriate. If there is an existing editor presentation in Rational Team Concert that you would like to use as a model for your new editor presentation, you can use the Duplicate function available in the Eclipse client interface. See Resources for more information about duplicating the editor presentation.
Customize the new work item type
To customize your new work item, you need to add custom attributes. You can use the web or Eclipse client to add the new attributes. Some custom attributes that are appropriate for the opportunity management use case are shown in Table 2.
Table 2. Custom opportunity work item type attributes
|Identified By||Contributor||The person who identified the business opportunity|
|Opportunity Amount||Decimal||The estimated revenue associated with the opportunity|
|Skills Required||String list||The list of skills that are necessary to fulfill the staffing requirements|
|Client Name||Small String||The name of the customer|
|Client Email||Medium String||The email address for the primary client contact|
|Target||(Enumeration)||The quarter/year in which the project or opportunity is expected to begin|
|Probability||(Enumeration)||High/Medium/Low – The likelihood that the project will come to fruition|
|Next Action||Large String||What must be done next to progress the opportunity? Example: "setup meeting with client"|
|Action Owner||Contributor||The person responsible for carrying out Next Action|
|Action Target Date||Timestamp||The date by which Next Action is expected to be completed|
|Resources Assigned||Contributor list||The consultants assigned to work on the project or opportunity|
|Reason For Outcome||Medium String||A brief explanation to support the end result of the opportunity, for example, "won – our experience far exceeds that of our competitors" or "lost due to price"|
You will also likely want to repurpose several of the default attribute types for your new work item type. A few that can be repurposed for opportunity management are shown in Table 3.
Table 3.Default attributes used for opportunity work item type
|Summary||Medium HTML||Rename Summary in the editor presentation to be |
Note: In the query builder, this attribute will retain the name Summary.
|Owned By||Contributor||The person managing the opportunity|
|Description||Large HTML||The description of the work to be performed|
Once these attributes are created in your new work item type, you need to define presentations for them in your editor presentation.
These are the basic set of attributes necessary for opportunity management in Rational Team Concert. You can further customize your work item type with attributes that are appropriate for opportunity management within your organization, such as contract type, contract links, reviewers, reviewer notes, and so on. Guidance on creating additional attributes follows.
Select the attribute type
When determining the type for your new custom attributes, it may be easiest to think of how you would like these new attributes to appear in the user interface. For some attribute types, such as a String type attribute with a String or Text presentation, the appearance is easy to anticipate. For others, the tips in Figures 2 and 3 will be helpful.
Figure 2. Options for single selection
Figure 3. Options for multiple selections
Set the required attributes
Once the custom attributes are created, you may want to set particular attributes as required in certain workflow states. The validation for required attributes occurs at the time the work item is saved. If required attributes are not populated, Rational Team Concert prohibits the work item from being saved and will return an error to you. As of Version 18.104.22.168, this customization feature is available only in the Eclipse client.
Follow these steps to define the required attributes, as shown in Figure 4:
- Go to the Process Configuration tab
- Expand the Team Configuration section
- Select Operation Behavior
- Locate the Operations table and scroll down to the view the various operations
- Locate the Work Items operation
Figure 4. Required attributes: Steps 1-5
Steps 6-10 are illustrated in Figure 5.
- Select the icon in the Everyone column of the Save Work Item (server) row.
Note: When selected, the icon become highlighted in blue as shown in Figure 5.
- Scroll down to the Preconditions list and click the Add button. This generates an Add Preconditions popup window.
- Within the Add Preconditions popup, scroll down and locate the options for required fields: Required Attributes ForCondition, Required Attributes For Type and State, and so on.
- Select the precondition of your choice. In the opportunity management use case our required fields are based on the following precondition: Required Attributes for Type and State.
- Click OK.
Figure 5. Required attributes: Steps 6-10
Steps 11-13 are illustrated in Figure 6.
- Locate the Name field, which will populate with Required Attributes For Type and State. In this field enter a name for your precondition. In the screen shot the name highlighted is 02 Noticed which is the earliest stage in the Opportunity Management use case workflow.
- In our use case, the list of required attributes expands as the work item advances through the various stages of the work flow. Notice that the precondition names we used correspond to the stages of our work flow.
- Scroll down and locate the Category or Type / Attributes section and identify the work item for which you would like to define a required attribute. Click on the arrow to expand the contents of the work item type.
Note: In the opportunity management use case there were three types listed. You may find it necessary to hover over the choices to distinguish the types from one another. In this case we are working with the work item type for opportunity.
Figure 6. Required attributes: Steps 11-13
Steps 14-16 are illustrated in Figure 7.
- Scroll down to the appropriate type. Notice in the opportunity management use case the desired type is located as a subset called opportunity
- Highlight the type for which you would like to define required attributes. In the screen shot below we are working with the work flow stage 02 – Noticed.
- Click the Edit button to specify which fields will be required for this type.
Figure 7. Required attributes – steps 14-16
Steps 17-21 are illustrated in Figure 8.
- Select the required properties by placing a check mark next to the respective fields in the popup box.
- Click the OK button once all fields are specified.
- Click the Apply changes button.
- Click the Save button
This is critical. If you don't click Save you may lose your configuration changes. If you attempt to close the window without saving you will be prompted that your changes were not saved.
- Repeat steps 7-20 as needed until all required attributes are defined.
Note: When specifying required fields for stages in a workflow please keep in mind that required fields for each stage must be explicitly stated. Rational Team Concert does not assume that everything required in your first state is also required in your second state. You must specify the fields.
Figure 8. Required attributes - steps 17-20
Helpful hints for custom attributes
When creating and working with custom and required attributes, here are some helpful hints to consider.
- Delete and re-add a custom attribute type to change it: Once you have added a new custom attribute, you can choose to edit the attribute. However, you will not be able to change the attribute type when editing. If you need to change the type of the attribute, you will need to remove the attribute and then add a new custom attribute of the appropriate type.
- Use HTTP filtered value sets to define your values in XML: HTTP filtered value sets are useful when you are working with a large amount of data and you want to be able to update the values in the set outside of the Rational Team Concert environment. However, HTTP filtered value sets currently have a limit of 150 values. With XML that contains more than 150 values, the additional values for the attribute using the HTTP filtered value set will not be rendered by Rational Team Concert.
- Synchronize to reflect new fields: If new fields are added to your work item type, any existing work items of that type must be synchronized to reflect the new fields. Synchronization must be performed in the Eclipse client. As of Version 22.214.171.124, this feature is not available in the web client. For additional details on how to synchronize your work items, refer to the Rational Team Concert information centers in the Resources.
If your intention is to make the newly added field a required attribute, you must first synchronize all of the existing work items, as well as populate the attribute in each of the work items before making the field required. Otherwise, if you set the field to
required before synchronizing, Rational Team Concert will not add the new attribute to work items that are in states where the attribute is required.
Unassigned literalfor required attributes: When creating enumerations, one literal has to be declared as the default value. When working with required attributes, be sure to use the
Unassigned literalinstead of the
default literal. The unassigned literal makes it possible to configure the enumeration as a required attribute.
Test the new work item type
Test your new work item type by creating a new work item using both the Eclipse and web client interfaces to Rational Team Concert. If you removed all other work item types provided by default by Rational Team Concert as discussed in Create a new work item type, your new work item type will be the only type available for selection.
Verify that the work item is rendering as intended in both the Eclipse and web clients. Sections defined in the editor presentation will appear differently in the different clients, and so the presentation will look different in each of the clients. If the layout and attribute presentations are not as expected, you need to alter your editor presentation as needed, until the layout and all attributes are displayed as intended in both clients.
Once the presentation is correct, move your new work item through the workflow, and validate that attributes are required at the appropriate states in the workflow as configured in your required attributes settings.
Rational Team Concert provides features and capabilities out of the box to facilitate application lifecycle management. However, it is easy to customize Rational Team Concert for non-traditional uses as well, such as opportunity management. This article discussed how to create a new work item type, how to set the custom attributes, workflow, and editor presentation for this work item type, and how to define required attributes in the context of opportunity management. The information provided here can be used to customize Rational Team Concert for many other non-traditional uses.
After you have created and customized a new work item type, you can continue to customize Rational Team Concert for your non-traditional use by creating new queries and dashboards appropriate for your new work item type. For example, for opportunity management some appropriate queries include: opportunities that are currently being pursued, opportunities that are currently being pursued and require some specific skill, opportunities that were won, and opportunities that were lost. A custom dashboard with graphs showing comparisons of opportunities with specific required skills or graphs comparing the number of opportunities lost and won, for example, is also practical for this use case.
- Learn more about Customization of work items in Rational Team Concert (including information on value sets.)
- Explore this article series on advanced customization:
- Advanced customizations in Rational Team Concert project areas: Part 1. Create a custom work item in Rational Team Concert (developerWorks, August 2011)
- Advanced customizations in Rational Team Concert project areas: Part 2. Use role-based customizations for work items (includes duplicating an editor presentation) (developerWorks, September 2011)
- More about Rational Team Concert:
- Find Rational Team Concert articles and links to many other resources on IBM developerWorks, and check the product overview page, features and benefits, system requirements, and the user information center.
- Check the Rational Team Concert page on Jazz.net.
- Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
- Explore the Rational software area on developerWorks for technical resources, best practices, and information about Rational collaborative and integrated solutions for software and systems delivery.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
Get products and technologies
- Download Rational Team Concert from Jazz.net and try itfree on up to 10 developers for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, or use it in a cloud environment.
- Get connected with your peers and keep up on the latest information in the Rational community.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter(@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.