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.
- Changing Types and Attributes
- Changing Enumerations (Custom Types)
- Changing Workflows
- Changing Editor Presentations
- Changing Operations Behavior
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
|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.|
|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. |
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.|
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.|
Work Item Attributes
|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. |
|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.|
|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.|
|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.|
|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.|
|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.
|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.|
|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. |
|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.|
|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.|
|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.|
|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. |
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.|
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.
|Motivation||You might need a new or duplicated workflow to bind to a work item type.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
|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.|
Workflow State Groups
|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.|
|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.|
|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.|
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.
|Motivation||New editor presentations allow you to provide custom layouts that can be later bound to the desired work item types.|
|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.|
|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 |
|Motivation||This action will create a new content-independent Tab/Section as discussed in the preceding point.|
|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.|
|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.|
|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).|
|Motivation||Existing and new work items will adopt the new attribute presentation.|
|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.
|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.|
- 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.
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