Jazz Library Changing your Rational Team Concert Process Configuration – Best Practices
Author name

workflow-management,rational-team-concert

Tue, 24 Jul 2012
5 min read
0

Changing your Rational Team Concert Process Configuration – Best Practices

David Karam, Jan Wloka, IBM
Last updated: June 27, 2012
Build basis: Rational Team Concert 4.0

RTC offers a variety of possibilities to customize work items, their attributes, and editors. Some of these customizations should only be done with careful attention. In general, the potential for unanticipated effects varies from being safe and unobtrusive to harmful and unrecommended. Performing the latter type can cause disruption to the functionality of RTC, especially when performed on running project areas that have already been used under a previous configuration.

Removing elements like work item types and workflow states for example is harmful because there can be data in the repository referencing such elements. The UI will work with such non-existent data in most cases by just showing the ID of the element instead of its name. Also functionality will be broken; think of a deleted workflow state that provides no actions to transition back into an existing state.

The purpose of this document is to outline all possible changes that can be made to the work item process configuration and categorize them as safe, cautious, or harmful, along with a broader context and a possible workaround for potentially unsafe changes. As a rule of thumb, safe changes are customizations that either add new elements (e.g. work item types) or only change UI related features like display names or editor layouts. Unsafe changes are generally those that remove elements referenced by components of RTC. Removing those elements can invalidate existing references and also break the corresponding functionality.

Since this is a reference article on how to perform work item customizations, it can be read sequentially to get an overview on how to customize the work item component. However, it can also be used as a reference guide in cases where you are planning to customize the default behavior of RTC. Review the corresponding section in this article to understand what potential harm can be caused by your customization and to learn how to perform the change in a safe manner. In every section you can find an enumeration of possible customizations, along with a motivation and an explanation of potential problems.

Outline

All presented configuration changes are marked with a degree of severity that is intended to help the reader differentiate between the various possibilities for change:

Safe refers to very safe changes. The user can perform these changes without risking any disruption to the functionality of RTC.

Cautious refers to changes that the user should perform with caution. Some of the changes might cause only user confusion but others might break functionality. For all of those actions, we explain ways in which they can still be performed in a safe manner.

Harmful refers to changes that are unrecommended and can be dangerous as they most likely will break existing functionality.

Changing Types and Attributes

The changes in the category “Types and Attributes” modifying the model and presentation of work items in RTC. Most changes in the category can be applied in a safe manner without breaking any functionality in RTC. In general, you should never change the ID of any item, attribute or presentation element if there might be existing work items that use it.

Work Item Type

Summary Add (Safe)
Motivation You may want to add a certain work item type to reflect new process semantics. For example, you could add a new Todo type if the Task item is not concise enough to model small tasks.

Summary Remove (Cautious)
Motivation You may want to remove a certain work item type from your process due to deprecation or migration purposes. New items cannot be created with that type afterwards.
Problem While existing work items of the removed type will be displayed in the default editor, no workflow is assigned to them, and hence the Save operation will not succeed. In place of the type name and icon, there will be shown the old ID and an empty icon.
Mechanics You will have to delete all work items of that type before the type can be safely removed. Note that you will need to be a JazzAdmin and own extra permissions to be able to delete work items.
  1. Run a query in the Web UI to display all existing items of the type to be deleted.
  2. Check thoroughly if all shown items can be deleted.
  3. Click on Edit Multiple Work Items and select all shown items.
  4. Click on Delete Work Items.
  5. Rerun the query to double check that all items are deleted.
  6. Go to the Project Admin UI and remove the type.

Work Item Type – ID

Summary Change ID (Harmful)
Problem Changing the work item type ID will break the editor presentation and the workflow of existing work items with the previous ID. Work items with that ID will open with the default editor, but they won’t have any workflow assigned and hence cannot be saved.

Work Item Type – Name

Summary Change Name (Cautious)
Motivation You may want to rename the work item type to reflect changes in your process semantics. The name of the work item will change when creating, editing, or viewing it in editors.
Problem Other work items may refer to work items of this type, e.g., as Defect 123 in their Description or Discussion section. Link detectors have created links with that name to facilitate navigation. Once the name, e.g. Defect, is changed all such links will no longer appear.
Mechanics
  1. Change the type name to New Name.
  2. Add the Old Name to the list of aliases to preserve the referring links.

Work Item Type – Icon

Summary Change Icon (Safe)
Motivation You may want to replace the work item type icon to reflect changes in naming schemes or for better visibility. The new icon will be shown when opening the work item in editors.

Work Item Type – Alias

Summary Change Alias (Cautious)
Motivation You may want to rename the work item type alias to reflect changes in your process semantics. For example, in you process you want to rename the Defect’s alias bug instead of defect without affecting previous functionality.
Problem Other work items may refer to work items of this type as defect x. Link detectors have created links with that alias to facilitate navigation. Once the alias, e.g. defect, is changed all such links will no longer appear.
Mechanics
  1. Don’t remove the Old Alias.
  2. Add the New Alias to the list of comma-separated aliases and all referring links will be preserved.

Work Item Attributes

Summary Add (Cautious)
Motivation You may want to add a certain attribute to reflect a new property of work items of a certain type.
Problem Once its presentation is bound an editor section, the new attribute will be shown only in newly created work items. Already existing work items will not contain the new attribute. An uninitialized presentation will be shown without the ability to modify its value.
Mechanics You can add the new attribute to all existing work items of that type.
  1. In Project Configuration > Configuration Data > Work Item > Types and Attributes go to the Attributes section.
  2. Add a new attribute using the Add… button.
  3. Save the process specification.
  4. Click on the link “Check attributes usages in repository” and to find existing work items without the new attribute.
  5. If you want to add the new attribute click on Synchronize Attributes in the shown dialog. In case you are unsure, you can click on Shown Items to inspect the work items to be updated.

Summary Edit (Safe)
Motivation You may want to edit a certain attribute to modify its properties. All permissible edits in the UI are safe. Unsafe edits, like editing its ID, are made read-only to circumvent broken functionality.

Summary Remove (Cautious)
Motivation You may want to remove a certain (custom) attribute from your work item due to deprecation or migration purposes. New items cannot be created with that attribute afterwards.
Problem Removed attributes are not deleted from the database, thus all work item types that reference the attribute will still be able to use it. Also presentations for the work item type that reference this attribute will still show it. This can be confusing to the user who removed the attribute, but still sees it in the editor.
Mechanics
  1. In the Attributes section of Project Configuration > Configuration Data > Work Items > Types and Attributes select the custom attribute to be removed.
  2. Click on the link “Check attributes usages in repository” and if work items are shown review them thoroughly.
  3. Remove the attribute, will remove it from the Attributes table and from presentations shown editors.
  4. Go to Project Configuration > Configuration Data > Work Items > Editor Presentations select the editor the work item type with the removed attribute.
  5. Find the attribute presentation in the layout and remove it from the editor. Repeat these two steps for other editor presentations showing this attribute.
  6. Go to Team Configuration > Operation Behavior and find in the Operations table the Save Work Item (server) operation.
  7. Select the precondition icon in the table for every assigned process role and inspect the Preconditions section.
  8. Make sure that the removed attribute is not required by any precondition here.

Editor Bindings

Summary Change (Cautious)
Motivation You may want to change the editor binding to reflect a new presentation layout for the work item. Existing and newly created work items will be displayed accordingly to the new editor. If the new binding contains attributes not in previously created work items, an uninitialized presentation without the ability to modify the attribute value will be shown.
Problem Some attributes of this work item type may be declared required as part of a precondition to the work item save operation. If the new editor binding does not show a presentation for all of these attributes users cannot assign values to them and thus not save the work item.
Mechanics
  1. Go to Team Configuration > Operation Behavior and find in the Operations table the Save Work Item (server) operation.
  2. Select the precondition icon in the table for every assigned process role and inspect the Preconditions section.
  3. Check any precondition here for required attributes.
  4. In case you found any required attributes, go to Project Configuration > Configuration Data > Work Items > Editor Presentations select the editor presentation for the new editor binding.
  5. Check if the editor presentation shows all required attributes.

Workflow Binding

Summary Change (Cautious)
Motivation You may want to change the workflow of a work item type to conform to a new state change policy. For example, you could update the workflow of the work item type Task to make it more compliant to the Defect workflow.
Problem All existing work items lose their workflow state when a work item type is bound to a new workflow. The workflow state of these items will have to be saved again before they use the newly assigned workflow. Also, all entries in the work item history related to the old workflow will be lost.
Mechanics
  1. In the Workflow section of Project Configuration > Work Items > Types and Attributes select the work item type to be changed.
  2. In the Workflow section select the new workflow and save the project area.
  3. Use the “Check workflow usages in repository” to see all work items that are using the old workflow.
  4. Go manually through the work items, edit Status and Resolution if needed, and save them again so that their state enters into the new workflow.

Summary Remove (Harmful)
Problem Removing the bound workflow (selecting None from the drop-down menu) will cause both existing and new work items to be opened without a state. Since no workflow is bound, it will not be possible to save any of these work items.

Changing Enumerations (Custom Types)

An enumeration is a fixed or extensible list of defined literals that constitute the possible values the attribute. The configuration UI in RTC allows for adding new or duplicating existing enumerations. It also allows for defining their literals and for archiving or removing a literal in cases where attribute values became deprecated.

Changes in this category affect attributes and their values of work items in RTC. Special caution is required when removing enumerations or their literals because existing work items may refer these values in their attributes. Following the mechanics in this section can however prevent any broken functionality.

Enumerations

Summary Add/Duplicate (Safe)
Motivation You may want to add a new or duplicate an existing enumeration when creating a custom attribute type. A new attribute type can be handy when the value set of existing types don not meet your requirements.

Summary Remove (Cautious)
Problem Removing an enumeration essentially removes an attribute type from RTC. Values for attributes of this type in existing work items can no longer be displayed correctly. It’s not recommended to delete enumerations for built-in attributes.
  1. In Project Configuration > Configuration Data > Work Items > Enumerations select the enumeration to be deleted.
  2. Select the button Remove… and click on “Just Show Affected Items” to review the work items that are affected when removing the selected enumeration.
  3. If some work items are shown, you should go the type of these items and change of remove the attribute using that enumeration type.
  4. Once you made sure you can remove the enumeration safely, select the Remove… again and click on Yes to remove the selected enumeration.

Enumeration Literals

Summary Add (Safe)
Motivation You may want to add a new enumeration literal to give further options in your enumeration’s value set. New work items will have the new literal available for assignment.

Summary Change (Cautious)
Motivation You may want to change the name, icon, or external value of an enumeration literal.
Problem Changing the name or icon of a literal is side-effect free. Changing the external value however may breaks RESTful clients to RTC which use that external value to reference the enumeration literal.
Mechanics
  1. Check which RESTful clients rely on this external value to reference the literal.
  2. Change the value in those clients to reflect the new external value.

Summary Archive (Safe)
Motivation You may want to deprecate an enumeration literal. An archived literal does not appear in new work items but is still shown in existing work items where it was selected before. It also cannot be selected as new value in existing work items. This is a safe and preferred alternative to Remove.

Summary Remove (Cautious)
Problem Similar to Archive, remove prevents that the literal can be selected in work item attributes. Unlike Archive it deletes the literal from RTC entirely. In work items where this literal was assigned to an attribute, only the literal ID will be shown along with a message that the enumeration is broken and the value is not applicable. It’s is generally recommended to use Archive instead of Remove.
  1. In Project Configuration > Configuration Data > Work Items > Enumerations select the enumeration to be changed.
  2. In Enumeration Literals select literal to be removed and click the Remove… button.
  3. Choose on “Just Show Affected Items” in the displayed dialog to review the work items that are affected when removing the selected enumeration.
  4. If some items are shown, you choose a different attribute value before removing the literal.
  5. Once you made sure the literal can be removed, select the Remove… again. Click on Yes to remove the selected literal.

Default/Unassigned Enumeration Literals

Summary Change Default (Safe)
Motivation You may want the enumeration to be initialized with a different default value.

Summary Change Unassigned (Cautious)
Motivation You may want another literal in the value set to symbolize the Unassigned state. This state is used for example by required conditions to figure out whether an enumeration has been set. Also queries using this value to find work items with no value assigned for that attribute.
Problem Existing work items with required conditions on that attribute can become inconsistent under the new value of the Unassigned literal.
Mechanics
  1. Create a query to find all work items that have an attribute of this enumeration set to the new Unassigned literal.
  2. Review the shown work items manually. In case a work item is subject to a required condition that is invalidated by the new Unassigned literal, modify the attribute value so that the required condition is met.

Changing Workflows

Every work item in RTC can reach different states (open, in progress, complete) while the described task is performed. This life cycle of a work item is called a workflow. Work item types use workflows as state transition policies consisting of states that a work item can be in and actions (state transitions) that users can take to move the work item from one state to another.

Changes in this category manipulate how RTC is representing progress on work items. While most of the changes are considered to be safe, removing workflows or any part of a workflow can break state transition policies and might prevent users from saving work items. Following the mechanics in this cases can help to clean up your process specification and remove unused parts of a workflow. We do not recommend to remove an entire workflow from the system in general.

Workflow

Summary Add/Duplicate (Safe)
Motivation You might need a new or duplicated workflow to bind to a work item type.

Summary Remove (Harmful)
Problem Both new and existing work items of the types bound to this workflow cannot be saved anymore. Once a workflow is removed, an alternative workflow has to be bound to the affected work item types. Disrupting work item type bindings always causes functionality to break.

Summary Change Name (Safe)
Motivation You might need to change the name of a workflow to reflect modified state policy semantics. The name will change in existing and future bindings.

Summary Change Description (Safe)
Motivation You might need to change the description of a workflow for better clarity. The description will change in existing and future bindings.

Workflow Transitions

Summary Add/Change (Safe)
Motivation You may want to modify state change policy by guiding workflow via different transitions. Adding (selecting New Action… or changing (using an existing Action) will cause existing and new work items to use the new action to make the transition to the target state.

Summary Remove (Cautious)
Motivation You may want to remove a transition (select None from the drop-down menu) to block the workflow from going from a particular source state to a destination state.
Problem Existing work items in that source state will not be able to transition to the indicated target state anymore. This might cause a problem if this transition was the only way a work item could get out of that state. For example, it might not be possible to move a Closed work item back into the Reopened state; this would result in the work item being permanently Closed.
Mechanics
  1. Remove the desired transition by selecting None from the drop-down menu.
  2. Make sure there are other possible transitions of the workflow state back into other target states.
In many cases, it might be important to keep workflows as flexible as possible. Therefore, care should be taken to retain the possibility to reach, within the space of a few transitions, any target state from any source state.

Workflow Actions

Summary Add (Safe)
Motivation You might need to add an action to create a new kind of transition between states in your workflow. New and existing work items will have the possibility of using that action to transition between states. Adding a new action without using it in a transition however has no effect on the existing workflow.

Summary Change (Safe)
Motivation You might need to edit the name, icon, or description of an existing action to reflect new workflow semantics. New and existing work items will have the possibility of using that action to transition between the same states as before. This change will just replace that icon and name in work items using that workflow action. Changing the Workflow Start, Resolve, or Reopen actions is also considered to be safe. Newly created work items will execute the new Start action upon creation, and existing work items will move into the Closed or the Open state group upon executing the latter two actions.

Summary Remove (Cautious)
Motivation You may want to remove an action from a certain workflow to reflect the changed process semantics.
Problem Removing a workflow action causes all transitions in which that action is used to be removed. As detailed in the preceding section, this might cause a problem if this transition was the only way a work item could get out of that state. It might not be possible, for example, to move a Closed work item back into the Reopened state if the Reopen action is removed; this would result in the work item being permanently Closed.
Mechanics
  1. Remove the desired action from the Actions menu.
  2. Check the Transitions menu to make sure there are other possible transitions of the workflow state back into other target states.
In many cases, it might be important to keep workflows as flexible as possible. Therefore, care should be taken to retain the possibility to reach, within the space of a few transitions, any target state from any source state.

Summary Add Resolution (Safe)
Motivation You may want to add a resolution to a particular action so that the resolution is available for the action’s target state. New work items will have access to that new resolution. Existing work items in that target state will need to change state back and forth once before viewing the newly added resolution.

Summary Remove Resolution (Cautious)
Motivation You may want to remove a certain resolution which is deprecated in the context of that workflow action. After removal, new work items executing that workflow action will not have access to the new resolution anymore.
Problem Existing work items which have been assigned this resolution will still show it leading to an inconsistent resolution state.
Mechanics
  1. Create a query to find all work items that have their resolution set to the to be removed one.
  2. Go over them manually and change the resolution to something that is consistent with your post-remove context.

Workflow States

Summary Add (Safe)
Motivation You might need to add a state to model new behavior in your workflow. New and existing work items will have the possibility of transitioning to that state. Adding a new state without identifying transitions makes no difference in the existing workflow.

Summary Change (Safe)
Motivation You might need to edit the name or icon of an existing state to reflect new workflow semantics. New and existing work items will still have the possibility of transitioning to that state. This will just replace that icon and name in existing and new work items accessing that state.

Summary Remove (Cautious)
Motivation You may want to remove a state from a certain workflow to reflect the changed process semantics.
Problem Existing work items which have been assigned this state will show the state ID instead of the state name and icon.
Mechanics
  1. Create a query to find all work items that have their state set to the one intended to be removed.
  2. Go over them manually and change the state to something that is consistent with your post-remove context.

Workflow Resolutions

Summary Add (Safe)
Motivation You may want to refine the meaning of a state to reflect more specific semantics. After adding a resolution, it needs to be bound to a workflow action and will then be available for state transitions executing that workflow action.

Summary Change (Safe)
Motivation Editing the icon, name, or state group will just replace that icon, name, and state group in existing and new work items accessing that resolution. Refer to notes in State Groups for information for the effect of modifying state groups on existing queries.

Summary Remove (Cautious)
Motivation You may want to remove a certain resolution so that it cannot be used in any workflow action anymore. After removal, new work items executing any action will not have access to the new resolution anymore. Note that this is different from removing a resolution from a workflow action. The latter removes that resolution from the action’s target state. This one removes it from all actions’ target states.
Problem Existing work items which have been assigned this resolution will show the resolution ID instead of the resolution name and icon.
Mechanics
  1. Create a query to find all work items that have their resolution set to the one intended to be removed.
  2. Go over them manually and change the resolution to something that is consistent with your post-remove context.

Workflow State Groups

Summary Add (Safe)
Motivation You might have several states that are similar but do not want to make them part of the existing state groups. Adding a group is not sufficient however; states and resolutions need to be bound to that group before the addition has any effect.

Summary Change (Cautious)
Problem Editing OSLC groups might affect existing clients, e.g., in queries, that rely on that configuration. Editing that group will not break the query but it might have it return different results. All changes to other properties of a state group are considered to be safe.

Summary Remove (Cautious)
Motivation You may want to remove a state group from the system because it is no longer used, and put its states into another group.
Problem Removing groups might affect queries from both normal and RESTful clients based on that state group. For example, querying for Resolved work items is in effect a query for work items in the Closed state group. Removing that group will not break the query but it will have it return different results.
Mechanics
  1. Check your queries manually whether they rely on this state group.
  2. Change the reference in those queries to something that conforms with your post-remove logic.

Changing Editor Presentations

Editor presentations defined how work items are shown in both the Eclipse and the Web UI. An editor presentation consists of tabs, sections, and attribute presentations. A tab contains (depending on its layout) several sections which show attribute presentations in a specified order.

Changes in this category are in general considered to be safe, as they affect the presentation of work items only. However, removing a editor presentation that is used by existing work item types will break functionality. Also, attribute presentations can be shared across different sections and tabs. Modifying a shared presentation can cause unexpected effects on other editor parts of RTC.

Editor Presentations

Summary Add/Duplicate (Safe)
Motivation New editor presentations allow you to provide custom layouts that can be later bound to the desired work item types.

Summary Remove (Harmful)
Problem Existing and new work items of the types bound to this editor will cause an error on opening and will not show anymore. As with workflows, disrupting editor bindings causes functionality to break.

Presentation Sections/Tabs

Summary Add (Cautious)
Motivation You may want to add a new presentation layout to a particular work item type. After this change, existing and new work items with types bound to this presentation will incorporate the new section/tab.
Problem On Add, you are given the option to either create a new section/tab or reuse an existing one. If you choose to reuse one which already exists in the same presentation, then content will be shared across those two sections. Changes you make in one will be conveyed in the other.
Mechanics To create a content-independent copy of a section or tab
  1. Right click on the source section/tab and press on “Duplicate…”. The result will be an identical and content-independent section/tab.

Summary Duplicate (Safe)
Motivation This action will create a new content-independent Tab/Section as discussed in the preceding point.

Summary Change (Safe)
Motivation Existing and new work items will adopt the new section presentation’s name, layout, and properties. The ID is made read-only to circumvent any breakage in functionality.

Summary Remove (Safe)
Motivation New and existing work items will not show the presentation for this section/tab in their editors anymore. This might be problematic in case the removed section/tab contains a presentation of a required attribute. Such a scenario however reflects bad application logic and cannot be considered an unsafe customization.

Attribute Presentations

Summary Add (Safe)
Motivation Existing and new work items will adopt the new presentation. If it is a presentation of a new type that did not exist in the existing work item, the presentation is shown in its uninitialized form (e.g. a deactivated combo box).

Summary Edit (Safe)
Motivation Existing and new work items will adopt the new attribute presentation.

Summary Remove (Safe)
Motivation New and existing work items will not show the presentation for this attribute in their editors anymore. This might be problematic in case you remove the presentation of a required attribute. Such a scenario however reflects bad application logic and cannot be considered an unsafe customization.

Changing Operations Behavior

In RTC, users can specify preconditions that have to be met before a work item can be saved successfully. These preconditions can be enabled for users with a certain role in the project or just for everyone. For example, the required precondition can prevent the saving of a work item if some its attributes have not a value (other than the Unassigned value) assigned.

Required Attributes

Summary Change (Cautious)
Motivation A required attribute needs to have a value assigned (other than the Unassigned value) before the work item can be saved to the repository successfully. There are two possibilities to enforce “requiredness” on work item attributes. Either a precondition can be configured based on the state for a certain work item type, or based on a certain value of any attribute of the work item.
Problem Declaring an attribute as required prevents users from saving a work item, even if the editor does not show any for that attribute. Be aware of required attributes when changing editor presentations.
Mechanics
  1. Go to Team Configuration > Operation Behavior and find in the Operations table the Save Work Item (server) operation.
  2. Select the precondition icon in the table for the process role you want to define a required precondition for.
  3. Enable the Preconditions and follow-up check box if not already enabled.
  4. In the Preconditions section Add… one of the preconditions for required attributes.
  5. Select the condition and Edit… the attributes.
  6. Go to Project Configuration > Configuration Data > Work Items > Editor Presentations and choose the editor for work item type to which you added the precondition.
  7. Make sure that you can find an attribute presentation for every required attribute.

Related Articles

  • Customization of Work Items in Rational Team Concert – This article describes give a complete overview of possible customizations in RTC. It describes in detail how work items can be customized, illustrates each customization with an example and presents a guideline for choosing the right customization.
  • Work Item Editor Presentations – This article describes the concept and configuration to customize work item editors for new and existing work item types in both the Web UI and Eclipse client.
  • Read-only control for Work Item attributes in Rational Team Concert – This article presents the different ways of defining read-only attributes in work items, which are very similar to the precondition for required attributes discussed here.

Conclusion

This document presented a catalogue of changes that can be used to customize the work item component in RTC. All presented are categorized as safe, cautious, or harmful and explanations are given with motivation, problem description and safe steps to avoid broken functionality. As a general rule of thumb when changing the process specification: safe changes are customizations that either add new elements or only change UI related presentations. Unsafe changes are generally those which remove elements the can potentially be referenced by other parts of RTC. Removing those elements can break these references and corresponding functionality. For details on these possible changes, the reader can always come back and consult this catalogue of entries for advice and guidelines on how to safely modify work item’s process configuration.

About The Authors

The authors are developers in the Tracking and Planning team working on the Work Item component of Rational Team Concert with main contributions to the query engine, work item templates, and the server backend. 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

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Tue, 24 Jul 2012