Work Item Configuration and Shared Process in Rational Team Concert
Daniel Pool, IBM and Chris Goldthorpe IBM,
Last updated: June 19, 2012
Build basis: Rational Team Concert 4.0
OverviewProcess Sharing allows many different project areas to share the same process and work item configurations. However if the project area which consumes process customizes the work item configuration this can cause updates in the shared process to not be reflected in the consumer. This article describes in more detail the effects of customization.
Introduction to Process Sharing
Process sharing is a mechanism which allows many project areas to share the same roles, permissions, operation behaviors, and process configuration data. In this document when we refer to shared process this will mean all of these aspects of process. Some aspects of process including members, timelines, and iteration types are not inherited. For more information on process sharing see the help system.
In process sharing one project area holds the shared process which can be used by any number of consuming projects. The shared process together with any process elements defined in the consuming project area together create an effective process which govern behavior in the consumer. The next section will describe in more detail the rules governing effective process.
What happens when a process consumer is customizedIf a project area which consumes shared process is not customized the shared aspects of process are inherited without modification. If the consumer has customized the process the following rules apply.
- If roles have been added in the consumer the effective process will include all roles from both provider and consumer. If two roles with the same id are defined in both provider and consumer the role from the provider will not be part of the effective process.
- Permissions are merged at the operation level using the following rules. If a permission is defined only in the provider or only in the consumer use the permission that is defined. If a permission is defined in both the provider and consumer use only the permissions from the provider if the final flag is set, otherwise use only the permissions from the consumer. Operation Behaviors work the same way as permissions.
- Configuration data is the other part of process that can be shared. Configuration data is used for various purposes, one of which is the definition of work item types.
Work Item Process Customization
In order to successfully customize work item behavior when using process sharing it is helpful to understand some of how process sharing works. Process configuration is managed as a group of process elements. For work items these process elements are: Types and Attributes, Enumerations, Attribute Customization, Workflows, Editor Presentations, Quick Information Presentations, Predefined Queries, Query Editor Presentations, Approval Trackings, Work Item Templates, Change Management Type Binding, and E-mail Templates.
You may customize the consumer’s process configuration for any process element. But when you customize the process configuration for a process element on the consumer then the consumer uses its own process configuration for that entire process element. This happens for each process element in an all or nothing manner. Once you have customized a process element on the consumer it no longer uses any settings for that process element from the provider. Note that if the configuration data of the provider project area is marked final then that element in the consumer’s configuration data is ignored.
Process Configuration Data
The settings for each process element are stored as configuration data. In Rational Team Concert you may customize the configuration of a process element using the Eclipse or Web client. When you do this Rational Team Concert copies the provider’s configuration data for the given process element into the consumer’s process configuration. After that the copied configuration data is used, so any further changes in the provider’s configuration data will be ignored.
Initializing Process Configuration Data
In order to correctly initialize a process element with data from the provider it is important you get a full copy of the provider’s configuration data for that process element. If you customize the configuration data through the Eclipse Client or the Web Client then Rational Team Concert will copy all of the configuration data of that process element for you. This is the recommended way to customize the configuration data for a process element in the consumer.
XML Representation of Process Configuration Data
The process configuration data can also be accessed as XML from the Eclipse client. You access the XML through the Process Configuration Source tab of the Project Area view. Viewing the XML can provide insight into how process elements work with configuration data.
Below is a list of the work item process elements as they appear in the Eclipse UI and in the XML. You can refer to this in order to understand what configuration data in the XML goes with what tab in the UI when you are reviewing or editing the Process Configuration Source.
- Types and Attributes – com.ibm.team.workitem.configuration.workItemTypes
- Enumerations – com.ibm.team.workitem.configuration.enumerations
- Attribute Customization – com.ibm.team.workitem.configuration.providers
- Workflows – com.ibm.team.workitem.configuration.workflow
- Workflow Binding – com.ibm.team.workitem.configuration.workflowBinding
- Editor Presentations – com.ibm.team.workitem.editor.configuration.presentations
- Editor Presentation Bindings – com.ibm.team.workitem.editor.configuration.workitemTypeEditorIdBinding
- Quick Information Presentations – com.ibm.team.workitem.editor.configuration.quickinformationconfiguration
- Predefined Queries – com.ibm.team.workitem.configuration.queries
- Query Editor Presentations – com.ibm.team.workitem.query.editor.configuration
- Approval Trackings – com.ibm.team.workitem.configuration.approvalTracking
- Work Item Templates – com.ibm.team.workitem.configuration.templates
- Change Management Type Binding – com.ibm.team.workitem.configuration
- E-mail Templates – com.ibm.team.workitem.configuration.emailTemplates
Note that the Web Client UI is similar to the Eclipse UI, but it only contains Types and Attributes, Enumerations, Editor Presentations, Workflows, and Change Management Bindings.
Interdependencies Between Process Configuration Data Elements
Understanding the interactions between different elements in the process configuration can help when customizing that process configuration. The major elements of process configuration for work items are shown below. The configuration data elements are shown in red text.
The primary challenge in customizing work item process configuration while using process sharing is the granularity at which the process configuration is defined in the consumer. Because each element of configuration data is customized in an all or nothing manner you need to define all the process information for a customized element in the consumer. Additionally data defined in one element of configuration data can refer to data defined in another element of configuration data. This can make it difficult to know which process is defined in the provider and which is defined in the consumer. Let’s examine the key configuration data elements in order to understand how all of this fits together.
Types and Attributes
When you customize the Types and Attributes tabs in the Eclipse Client, RTC copies the provider’s workItemType configuration data into the consumer’s process configuration. The workItemType configuration data defines three kinds of data: type, customAttributes, and attributeDefinitions. Additionally the identifier category is used in the workItemType configuration data. type simply defines a work item type. customAttributes are sets of custom attributes that are applied to work items based on work item type category. Each individual custom attribute is defined by an attributeDefinition. The attributeDefinitions are defined in the attributeDefinitions list. category refers to work item type categories. By default you have one work item type category for each work item type. However it is possible to have multiple work item types share a category. Using a work item type category allows multiple work item types to have a shared set of attribute types and workflow while having unique names, icons, and presentations.
The Types and Attributes tab is also used to define which workflow is used for a given work item type category. This is achieved through the workflowBinding which binds a workflow to a category. Customizing the workItemType configuration data through the Types and Attributes tab will copy the provider’s workflowBinding configuration data into the consumer’s process configuration.
Editor Presentation Bindings
The Types and Attributes tab is additionally used to define what editors are used for a given work item type. This is done through the workitemTypeEditorIdBinding which binds a type to a presentation. Customizing the workItemType configuration data through the Types and Attributes tab will also copy the provider’s workItemEditorIdBinding to the consumer’s process configuration.
When you customize the Enumerations tab in the Eclipse Client, RTC copies the configuration data from the provider’s enumeration node into the consumer’s process configuration. Enumerations are straightforward in that they do not contain references to other configuration data. However they are referred to by the configuration data of other process elements.
The Attribute Customization tab in the Eclipse Client allows customization of the provider section of the configuration data. Note that in this case provider is the name of this piece of the configuration data, this is not the same as the provider project area. providers are sources of input that is fed in to work item attributes. There are five main types of providers which appear in the Eclipse Client as: Calculated Values, Default Values, Value Sets, and Conditions, and Validators. In the XML these are valueProviders, defaultProviders, valueSetProviders, conditions, and validators. Note that providers are referenced from the attributeDefinitions in the workItemType configuration data.
The Workflow tab in the Eclipse Client allows customization of the workflow configuration data. The workflow configuration data contains two kinds of nodes stateGroupDefinitions and workflowDefinitions. Also note that even after customizing the consumer’s process definition in the Workflow tab the configuration data may not contain the stateGroupDefinition until you specifically modify the State Groups settings in the UI.
The Approval Tracking tab in the Eclipse Client allows customization of the approvalTracking configuration data. This is used to move work items from one state to another when they are approved. approvalTracking data references workflows and workflow actions configuration data.
The Editor Presentations tab in the Eclipse Client allows customization of presentation configuration data which is used to configure work item editors in the Eclipse and Web client. The presentation configuration data defines the section data type. The section data type references the attributeDefinition defined in the workItemType configuration data.
Other Work Item Process Elements
Predefined Queries, Query Editor Presentations, Work Item Templates, and Change Management Type Binding all have references that could be affected by changes in configuration data of other process elements. So it is possible that these could be negatively impacted by process configuration customization while using process sharing. These issues should be relatively straightforward to detect and fix in that it is unlikely to be a nested relationship that is affected. Nonetheless you should consider the impact configuration changes might have on these process elements.
Recommended practices when process sharing
The main reason for using process sharing is the ability use the same shared process in many project areas and have changes made to the shared process reflected in the consumer projects. The propagation of changes to consumers in shared process is what differentiates shared process from a process template. The recommended practice is to avoid situations where a customization in the consumer prevents the consumer from getting all of the changes made to shared process.
Adding roles to the consumer is safe in this regard as the roles from the shared process and the consumer are modifying permissions and operation behavior which are both included in the effective process. Modifying permissions is usually safe as the effective process is a merge of the permissions from the shared process and permissions in the consumer. Operation behaviors work the same way as permissions.
Modifying configuration data in the consumer is the case which can cause updates in the shared process to not get propagated. If the same configuration data section is modified first in the consumer and then later in shared process then the consuming project area will not get the updates made in the shared process. If consumer and shared process modify different configuration data sections there is no problem. If the configuration data in the consumer project area is never customized then updates to the shared process will always be reflected in the consumer, except for any permissions which have been overridden in the consumer. If configuration data has been customized in the consumer project area the situation is more complex.
Here are a few suggestions to consider:
- When using process sharing create the consumer project area using an Unconfigured Process template. Any other template will override the process from the shared producer project area.
- When using process sharing do not customize the configuration data in the consumer unless it is necessary to do so.
- Complete all process customization in the provider before performing any process customization in the consumer.
- Initially make any customizations of configuration data in the consumer through the UI and not the XML. This gives you the full set of data for the given process element.
- In order to minimize duplication, which breaks sharing, customize as few process elements as possible on the consumer.
- provider configuration data (which is accessed from the Attribute Customization UI) is referenced from other process elements. If possible perform any customization of provider configuration data in the shared process project area.
- enumeration configuration data (which is accessed from the Enumeration UI) is referenced from other process elements. If possible perform any customization of the enumeration configuration data in the shared process project area.
- workflow and approvalTracking can be modified on the consumer without impacting other process configuration data. This is done through the Workflow and Approval Tracking UI.
- presentations can be modified on the consumer without impacting other process configuration data. This is done through the Editor Presentations UI.
- Use the history feature to view changes in the XML source of the provider and consumer to ensure that they are in sync.
- When updating process configuration in the provider manually merge those changes into any customized process configuration XML source in the consumer.
- If you get into a state where the consumer’s process is not functional for some process element, you can remove the offending configuration-data node from the consumer’s XML configuration source. This is a last resort as you will have to rebuild your customizations for that process element.
How is the process configuration stored?Roles, permissions, behaviors and configuration data for a project area are all stored in a single XML object, the processconfiguration data. This data can be accessed in the Process Configuration Source tab of the Project Area editor in the Eclipse Client.
How do I see the history of changes to configuration data?From the Process Configuration Source tab of the Project Area editor right click and select “Show History” from the context menu.
Is the process configuration source available in the web UI?No. You can only access the process configuration source from the Eclipse client.
Where can I learn more about work item customization?You can get started learning about work item customization here. Many other articles are available on work item customization in RTC on the wiki and on the Jazz Community Site.
Copyright © 2012 IBM Corporation