This article provides guidance to enterprise teams that are adopting new IBM® Jazz™-based tools to improve their teams’ performance. Such teams are often expected to stay integrated with existing project or corporate change management workflows, and they require tool interoperability that integrates the new change management tool with the existing ones.
Deploying and integrating new Jazz-based tools with existing change management workflows can be generalized as two situations, each driving specific requirements for choosing the right interoperability strategy for the new deployed and integrated solution:
- In the first situation, teams adopting Jazz based tools such as IBM® Rational Team Concert™ and IBM® Rational® Quality Manager might be expected to fully participate in a formal change management practice implemented as a corporate-wide change management deployment on IBM® Rational® ClearQuest®. In such a situation, integration through synchronization is a recommended approach.
- In the other situation, teams that adopt a Collaborative Application Lifecycle Management (C/ALM) approach with a team change management practice might choose an integration strategy based on establishing traceability through linking to enterprise change management assets.
In both situations, implementing an interoperability solution also gives users of Rational ClearQuest tighter collaborative capabilities.
This article describes the adoption situations in more detail and explains how to choose and deploy an interoperability strategy for each integration scenario.
Approaches to change management
The sections that follow give you more information on each of the factors involved to help you decide which interoperability method would work best for you.
Traditional, formal change management approach
Formal change management is a well-established practice that is adopted by most software delivery organizations. Figure 1 illustrates this approach. It institutes an end-to-end workflow that ensures the control of change requests through the defined lifecycle. This lifecycle starts with the submission of a change request, flows through the implementation and validation of the resulting changes, and the final resolution of the request.
Figure 1. Formal change management workflow steps
Such a formal change management process often flows through multiple teams and roles. For example, a stakeholder submits the change request, a project lead triages the request, a developer implements the request, a tester validates the implementation, and a product owner might resolve the change request and approve its inclusion in a product or the delivery of an application.
A common implementation approach to a formal change management process is to use a ClearQuest record of a customized change request record type, which passes in sequence through the states of the request. Ownership of the record is passed from team member to team member to orchestrate the sequence of work. The ClearQuest record specifies the property values of the request and references other supporting records. Figure 2 shows a general state flow for a change request record.
Figure 2. Formal workflow implemented in ClearQuest
When providing an interoperability strategy for traditional change management approaches, it is important to support and integrate it with the controlling workflow implemented in Rational ClearQuest.
Over the lifecycle of a single ClearQuest request, team members will contribute to the resolution of a request by using Jazz-based tools.
For example, a developer that is assigned a defect will deliver the changes in Rational Team Concert, and a tester will validate the fix in Rational Quality Manager.
Configuring interoperability for a traditional change management approach requires the change request to be synchronized across the repositories, along with its key properties and request state. Interoperation might be optimized to synchronize only with records where ownership is transferred to team members on the Jazz technology-based tool.
Collaborative Application Lifecycle Management approach
Collaborative Application Lifecycle Management (C/ALM) introduces an alternative. In this approach, the workflow is no longer implemented as a single orchestrated workflow by a single record. Rather, a collection of artifacts are integrated to participate and orchestrate the workflow through collaboration. The states of the related artifacts and their dependencies shape the lifecycle.
As an example, in Figure 3., a single enhancement change request might be identified as two work items, each owned and tracked by a component team. The team plans the work related to developing and validating the request.
Figure 3. Collaborative Application Lifecycle Management workflow
It is also feasible that each team might have adopted a slightly different development process whereby one team, for example, requires a code review before delivering changes to the integration stream.
This approach to Collaborative Application Lifecycle Management is available in ClearQuest by using the ALM schema. It is also the foundation principle for Collaborative ALM integrations that use the Jazz Integration Architecture.
When using the ClearQuest ALM schema, it is good practice to divide the flow of work among multiple ClearQuest records (ALMRequests, ALMTasks, ALMActivities) to capture the complete lifecycle. Ownership of records is distributed by function or role.
When using the Collaborative Application Lifecycle Management with the Jazz tools, the flow of work is orchestrated by the linking and completion of related work items, for example tasks and defects in Rational Team Concert. Validation artifacts are managed by Rational Quality Manager as, for example, test cases and test execution records. Defects are submitted from Rational Quality Manager as defect records in ClearQuest or Rational Team Concert, depending on the tool used. Figure 4 shows a principal view of the Collaborative Application Lifecycle Management assets.
Figure 4. Linked C/ALM assets
Teams that adopt a Collaborative Application Lifecycle Management approach will benefit from choosing an interoperability solution that enables the linking of artifacts between ClearQuest and the Jazz tools.
Interoperability strategy choices
Rational ClearQuest provide two types of interoperability technologies with the Jazz tools:
- A linking solution that integrates ClearQuest Bridge with the Open Services Lifecycle Collaboration (OSLC) Change Management specification to link ClearQuest records and Rational Team Concert or Rational Quality Manager work items. This fits the Collaborative ALM approach.
- A synchronization solution that uses the ClearQuest Connector to transfer data between ClearQuest records and Rational Team Concert or Rational Quality Manager work items. This fits the traditional change management approach.
These methods give teams the flexibility to choose whether to transfer data between records and work items or to merely link records and work items, instead. A balance between the way that ClearQuest is used and how much data you need to transfer between ClearQuest and Rational Team Concert or Rational Quality Manager will help you determine which strategy will work best for your situation.
The ClearQuest Bridge enables a loose coupling and provides a link between ClearQuest records and Rational Team Concert work items. No record data is transferred between the records. The ClearQuest Bridge is provided as a service in the IBM® Rational® Jazz™ Team Server and configured by using the Administration (Admin) console. There is no additional installation required.
Also, the ClearQuest Bridge stores information only in the Jazz work items, and no changes are required to the ClearQuest schema configured for change management. This simplifies team adoption of the ClearQuest Bridge, because the record linking can be used without any changes to the ClearQuest schema deployed to production across the enterprise. You can also use the ClearQuest Bridge to link any record type or any number of record types, which gives you flexibility.
To configure the ClearQuest Bridge, follow these steps:
- Log in to the Admin Web UI and open the Advanced Server Settings in Rational Team Concert or Rational Quality Manager.
- In the ClearQuest Bridge section, enter the host name (recommended) or IP address to the ClearQuest Change Management Server.
- Optionally, enter the default ClearQuest schema connection to use.
- Optionally, select the setting to enable the ClearQuest Records tab in the Rational Team Concert Web client.
After configuring the Jazz server, you can link ClearQuest records and Rational Team Concert or Rational Quality Manager (Jazz) work items. When a ClearQuest record or a Jazz work item is updated, the linked work item or record is not updated, because no data is synchronized between the records. The link remains intact throughout the lifecycle of the request, but the user must follow the link to see state and value changes in the linked record.
You can find additional information in the Rational Team Concert Information Center section on Configuring and using the Rational ClearQuest Bridge.
OSLC for change management
ClearQuest and the ClearQuest Bridge can also be configured to become a change management service provider for integrations with Rational Team Concert, Rational Quality Manager, and other tools that use OSLC change management services. This integration will enable defects to be created in ClearQuest from Test Execution Results in Rational Quality Manager. The OSLC for change management is a standards approach, so the integration can also be configured for other change management service tools, such as Rational Team Concert or IBM® Rational® Change software.
To configure the change management service in Rational Quality Manager software, follow these steps:
- Establish a Cross-Server Communication relationship between the Rational Quality Manager server and the ClearQuest server in the Jazz Server Administration settings using a Root Services URI.
- Establish a link between the Rational ClearQuest repository and the Rational Quality Manager project area.
- When submitting a new defect from Rational Quality Manager, select Rational ClearQuest as your change management provider.
You can find additional information in the Rational Quality Manager Information Center section called Setting up integration using the Rational ClearQuest Bridge.
The ClearQuest Synchronizer enables a tight coupling and transfer of data between ClearQuest and Rational Team Concert or Rational Quality Manager. The ClearQuest Synchronizer is a separate installation component and requires additional configuration in both ClearQuest and Rational Team Concert or Rational Quality Manager. The ClearQuest Synchronizer gives you more control but requires more complex configuration when developed and more maintenance when taken into production.
Follow these steps to configure the ClearQuest Synchronizer:
- The ClearQuest schema that implements the formal change management workflow has to be adapted to the ClearQuest Synchronizer. This involves applying the JazzInterop package.
- A ClearQuest Connector server has to be deployed. This server will perform the synchronization between ClearQuest and Jazz tool records.
- Synchronization rules must be created with mappings of record types to work item types and record properties to work item properties. When a ClearQuest record or Jazz (Rational Team Concert or Rational Quality Manager) work item is created or updated, the corresponding work item or record is updated.
- The Change Request records in ClearQuest and Jazz tools might need to be refactored. Ensure that additional attributes required by the change management workflow are added to Rational Team Concert and Rational Quality Manager. Also ensure that consistent enumeration values are used across the tools. For example, update enumerations value inconsistencies such “High” as opposed to “high.”
- Deploy the ClearQuest Synchronizer to a sandbox for development and testing.
To get additional information about configuring the ClearQuest Synchronizer, check the Rational Team Concert Information Center section on Configuring and using the Rational ClearQuest Connector.
Additional configuration factors to consider
The following section covers information useful to help determine and balance the complexity with the capability of an interoperability strategy while taking into consideration the desired amount of data transfer.
Using ClearQuest Connector for traditional change management
The following should be considered:
- A mapping of the ClearQuest change request record type to Jazz work items must be modeled and implemented.
- The ClearQuest change request state model must be unified with the Jazz work item state model. Make sure that the ClearQuest record states used for transitioning a request to an owner on the Jazz tool is modeled. Also, make sure the state is transferred back to ClearQuest when exiting the ownership.
- Map the key attributes in the ClearQuest change request with the Jazz work item. Note that enumeration values can be translated in a sync rule between ClearQuest and Jazz enumeration values. Using enumerations reduces the risk of synchronization errors and lowers solution maintenance.
- Model and map additional ClearQuest record types referenced by the change request record type. Each record type will require its individual synchronization rules.
- Seek one-to-one mapping of a record to a work item and field and value mappings to ease configuration.
Figure 5. ClearQuest Connector transfers data
When modeling the workflow, take these factors into consideration:
- When the ClearQuest record is changed, the Rational Team Concert work item is automatically updated through the ClearQuest Connector.
- When the Rational Team Concert work item is changed, the ClearQuest record is automatically updated through the ClearQuest Connector.
- Creating a new record might create ripple effects. A tester might create a new ClearQuest defect record that causes a single Rational Team Concert work item for the development team to be created through the ClearQuest Connector.
When deploying the ClearQuest Connector, bear these things in mind:
- When using IBM® Rational® ClearQuest Multisite®, there is a restriction that records updated by the connector have to be mastered at the server that is running the ClearQuest Connector integration. This puts special considerations into schema design and limits multisite support. A centralized ClearQuest installation will resolve such limitations.
- Accept the need to modify the established formal change management workflow to limit synchronization errors. Make sure to refactor ClearQuest record text fields to enumeration values to limit synchronization errors.
- Apply change and configuration management practices to ClearQuest schema development to allow schema and synchronization rules to be co-developed and co-deployed.
- Develop the ClearQuest Connector solution in a sandbox. Always test changes to synchronization rules prior to deployment in production.
- Always perform root cause analysis on synchronization errors to improve synchronization rules and resolve data value inconsistency.
Using ClearQuest Bridge for traditional change management
Consider the following when using the ClearQuest Bridge to integrate traditional change management with Rational Team Concert and Rational Quality Manager:
- Testers can use the ClearQuest Bridge on Rational Quality Manager to create change requests, such as defects reports in ClearQuest.
- The ClearQuest record and Jazz work item links are available only in the Jazz Web UI (Work Items tab and ClearQuest Records tab) and in the Rational Team Concert Eclipse client. Links are not available in the ClearQuest Web or ClearQuest Eclipse clients.
- A link between a ClearQuest record and a Jazz work item is stored only in the work item.
- A ClearQuest request record can be mapped to many Jazz work items in many repositories.
- A Jazz work item can link to one or many ClearQuest records. This eliminates the need to design mappings between record types and work items types.
- A tester creates a single ClearQuest defect record.
- A developer creates a Rational Team Concert work item to track the work to be done to fix the defect that is reported in the ClearQuest record. The developer links the work item to the ClearQuest record through the ClearQuest Bridge.
- When the ClearQuest record is changed, the Rational Team Concert work item is not updated.
- When the Rational Team Concert work item is changed, the ClearQuest record is not updated.
- No mappings need to be created for record fields and values.
Figure 6. Traditional change management using ClearQuest Bridge
Using the ClearQuest ALM schema
The following should be considered when enabling projects by using the ClearQuest ALM schema to integrate with delivery teams that are using Rational Team Concert and Rational Quality Manager with the ClearQuest Connector:
- A synchronization rule has to be configured for each record type.
- Each record type has to be mapped to a unique work item type. Therefore, because the ALM schema specifies the Request, Tasks, and Activity records as types, there must be mappings to each of these types to unique work items types.
- Each field of each ClearQuest record type that will need to be updated through the ClearQuest Connector needs to be mapped to a field in Rational Team Concert or Rational Quality Manager.
- Each reference field used by one of the ClearQuest ALM record types has to be implemented as an individual synchronization rule that will be invoked by the parent sync rule. The ALM schema frequently uses reference types and then further increases the complexity of a mapping.
- Many fields in the ALM schema are mandatory when submitting a new record. This adds complexity to the creation of new ALM tasks and activities from work items not yet synchronized with a ClearQuest record.
- The planning capabilities in ClearQuest ALM and Rational Team Concert use different approaches to model the project, teams, phases, and iterations. Mapping two different models cannot effectively be implemented with the ClearQuest Connector that is designed to solve 1:1 field and value mappings. This results in the need to implement custom mapping logic in the ClearQuest schema.
These are examples of such cases:
- A ClearQuest ALMRequest record is created by a tester.
- One or more ALMTasks are created through ClearQuest ALM.
- One or more ALMActivities are created through ClearQuest ALM.
- Rational Team Concert work items are created for each of the ALMTasks and ALMActivities.
- When a ClearQuest record is changed, the corresponding work item is updated through the ClearQuest Connector.
- When a Rational Team Concert work item is changed, the corresponding ClearQuest record is updated through the ClearQuest Connector.
Using ClearQuest MultiSite and the ClearQuest Connector
Consider the following when using Rational ClearQuest MultiSite with the ClearQuest Connector:
- ClearQuest records updated by the ClearQuest Connector have to be mastered at the server that is running the ClearQuest Connector.
- Configure the ClearQuest Connector selection queries to validate multisite mastership to avoid synchronization errors.
- Attempt to automate mastership settings based on the record ownership and user mastership settings.
- Consider the benefits of a centralized ClearQuest installation for resolving ClearQuest mastership limitations for the ClearQuest Connector.
Figure 7. ClearQuest ALM connected with Rational Team Concert or Rational Quality Manager through ClearQuest Connector
Using the ClearQuest ALM schema and the ClearQuest Bridge
Consider the following when you are using the ClearQuest ALM schema with the ClearQuest Bridge:
- A Jazz work item can link to one or many ClearQuest records. This eliminates the need to design mappings between record types and work items types.
- Work items can be linked to ALM Requests, Tasks, or Activities as needed by the adopted change management workflow.
- Work items can be linked to other types of records, such as the BTBuild record type defined in the Build Tracking schema, to track build failures and build resolutions.
- Work items can be linked to records that are not change management-related and can be used to assign and track work. For example, link to Enhancements to assign and track work to elaborate requirements.
- When configuring the OSLC CM provider in Rational Quality Manager, note that the default record type in ClearQuest will be chosen as the default defect type. Update the default record type in ClearQuest to map to the record type used for defects in your specific schema configuration.
Figure 8. ClearQuest ALM connected with Rational Team Concert or Rational Quality Manager through ClearQuest Bridge
Which option to use when
The following suggestions are based on the method of interoperability for a deployment based upon the way that ClearQuest is implemented and the need for a transfer of data between products.
When to use the ClearQuest Bridge
- Start exploring interoperability by configuring the ClearQuest Bridge and OSLC Change Management in your Jazz tools. This approach provides quick results and ensures openness and flexibility across Rational products. It also lets you explore integrations with other change management vendors’ software that supports OSLC.
- Choose the ClearQuest Bridge if you want to implement Collaborative Application Lifecycle Management using links to a change management workflow in ClearQuest.
- Choose the ClearQuest Bridge of you want to integrate your Traditional change management workflow in ClearQuest with Rational Team Concert or Rational Quality Manager but have no need to synchronize state or transfer attribute data between the repositories.
When to use or not use the ClearQuest Connector
- Choose the ClearQuest Connector for a traditional change management workflow that uses a single change request record, where ClearQuest records and Jazz work items are synchronized and they share states and attributes. Also, choose the Connector when ownership of the change request record is passed among team members across multiple platforms.
- We suggest using the ClearQuest Connector only in situations where the need for data to be transferred between ClearQuest and Rational Team Concert or Rational Quality Manager is such that the work to implement and maintain the complex configuration is acceptable.
- We do not suggest using the ClearQuest Connector for ClearQuest Application Lifecycle Management because of the complexity of configuration and the maintenance that are necessary to map the fields and values of ALMRequests, ALMTasks, and ALMActivities with work items.
To learn more about implementing Jazz interoperability, check the citations in the Resources section below.
- Learn more in the IBM® C/ALM™ Information Center.
- Collaborative Application Lifecycle Management with IBM Rational Products, in IBM Redbooks.
- Browse the Rational ClearQuest page on IBM developerWorks and check the Rational ClearQuest Information Center.
- Explore the developerWorks page for Rational Team Concert, with links to many other resources, as well as the Rational Team Concert Information Center.
- Check the Rational Quality Manager page on developerWorks for links to product documentation, articles, tutorials, courses, downloads, and other useful areas. Also browse the Rational Quality Manager Information Center.
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Some of the "Getting Started" courses are available free of charge.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
Get products and technologies
- Download trial versions of other IBM Rational software.
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.