Level: Introductory Robert Pierce, Advisory Information Developer, IBM
15 Nov 2006 from The Rational Edge: The first in a two-part series, this article presents the example of how the IBM Rational ClearCase development team uses the ClearCase product and related integrations, and best practices to efficiently and effectively serve ClearQuest customers, developers, and all other product stakeholders. Part 2 discusses potential enhancements to the system.
If you're a parent, you may be all too familiar with the saying, "Do what I say, not what I do." But our kids quickly see right through that weak logic. It's up to us to model the good behavior, or we will lose their respect.
So, too, in software development. Our customers want to see us modeling best practices, not just talking about them. In particular, customers want to see us using the tools we are promoting. When those tools happen to be the very products we're creating and selling, that's termed "eating your own dog food" or (more palatably) "eating the same food you sell." Why not use the same tools we sell to others, if they work so well?
To elaborate further on the parenting analogy, parents need to model behavior for children in a manner that is successful, realistic, logical, and attainable -- something they can reasonably hope to emulate. Likewise, we need to provide use cases and examples of how to use the product if our software's customers are to see and believe in the value and necessity of using it. And, again, what better way to "teach by example" than to use the tools and best practices ourselves?
If we truly deserve the credibility and the respect of our customers and other stakeholders, then our own modeling of how the tools and process are applied within our organization should provide an exemplary demonstration of the solution we're offering. To make our example even more concrete, we can define roles and use cases that relate to actual customer requirements.
In this two-part article, I'll illustrate in-depth how the IBM Rational Software Group "eats what it sells" by using IBM Rational ClearQuest as its change management (CM) solution, while at the same time managing change to the product in the form of ongoing enhancements to its user interfaces and user assistance materials.
Here in Part 1, I'll describe in detail the ClearQuest schema that we use in our own CM development process. I'll also present the concept of a role-based user experience, which applies both to change management in the context of IBM Rational product development and to ClearQuest customer usage scenarios. In Part 2, I'll go a step further to elaborate on enhancements to our current change management practices that would benefit not only IBM Rational, but also any development organization that wants to better align change management with stakeholder requirements across the product development lifecycle.
By illustrating how the IBM Rational software development organization uses ClearQuest as their change management solution in its own development efforts, I hope to model some best practices that you can apply towards designing and implementing a CM workflow for your own organization.
Change management and IBM Rational ClearQuest
In the area of change management, using a software tool and defining an automated process around that tool can provide great benefits by helping to link and coordinate different groups or teams within the development organization, regardless of whether they are all in one building, or geographically distributed all over the world.
For example, if a customer speaks with a support representative and raises an issue that requires a change request, then the change management solution should not only allow the support representative to submit a change request, but also enable appropriate stakeholders in the development organization to receive automatic notification of the submission, so that they can prioritize and respond to it as efficiently as possible to bring about an appropriate resolution.
IBM Rational's change management needs
Like many other development groups in global enterprises, the IBM Rational development organization requires a CM system that can work in a distributed environment. The system must serve not just developers, but also quality engineers, managers, customer support staff, information developers, and any other stakeholders for change requests (CRs) that pertain to defects or requests for enhancements (RFEs).
IBM Rational uses ClearQuest to manage its own change requests relating to the ClearQuest product itself. Our CM system, which was developed by the IBM Rational Internal Deployment team, is known as RATLC, after the name of the master schema on which the user databases are based.
Within this system, CRs can come from a variety of stakeholders. For example:
- In response to a customer who calls Support with an issue or RFE, a Support representative can submit a new change request in the ClearQuest RATLC system.
- A quality engineer, in the course of testing an IBM Rational product, can submit a change request for an issue discovered in testing.
- An IBM Rational developer who has added new functionality can submit a change request for documentation to be updated or added for the new feature.
- A development manager can submit a change request based on features that customers are asking for.
These are just some of the many ways that team members across the IBM Rational development organization use ClearQuest to create change requests. Each CR is subsequently assessed, assigned, worked on, and then resolved, verified, and closed.
The RATLC mission
The IBM Rational development organization's CM requirements can be summed up in terms of the RATLC Mission, which is based on two organizational perspectives:
- From the corporate perspective, the RATLC mission is (1) to establish an integrated common workflow for all of IBM Rational development; (2) to design a schema that most appropriately uses ClearQuest technology; and (3) to provide real world usage of products prior to release.
- From an operational perspective, the RATLC mission is (1) to provide all of IBM Rational with a 24 x 7 CM (or production change request tracking) system; (2) to find problems in our software before our customers do; and (3) to provide the ClearQuest development organization with the immediate experience of using what they develop.
The RATLC schema embodies both these perspectives. It is deployed as a number of database replicas around the world, in order to support a distributed environment of development teams and other stakeholders. This deployment provides a dependable working example of how IBM Rational's ClearQuest development organization has been more successful by using ClearQuest to manage change.
Integrating with customer support -- the RETAIN RATLC Bridge
As would be the case in most large, distributed software development organizations, it is necessary for us at IBM Rational to integrate our ClearQuest change management system with other applications in order to not duplicate data stored in isolated repositories that should be logically connected to the change management system.
In particular, the IBM Rational Support organization uses a Call Center application, called RETAIN (remote technical assistance information network), for logging and tracking customer issues. Both Support and IBM customers use this system to view and track product problems. In this system, each specific problem report references a particular product and release, and has a unique Problem Management Record (PMR) and associated Authorized Program Analysis Report (APAR) number/ID.
The repository in which PMRs and APARs are logged was, at one time, disconnected from the ClearQuest change management system. Therefore, there was no direct way to ensure that these customer requests or issues were logged as change requests in the development team's ClearQuest system. The net result was a disconnect between the Support and Development organizations.
Both the Development and Support organizations needed an integrated system whereby data entered in RETAIN would populate the equivalent fields in ClearQuest and vice versa. For example, if a customer request is created in the Call Center application, a ClearQuest change request with the same data ought to be submitted automatically at the request of the Call Center user. Furthermore, when the ClearQuest change request is resolved, the relevant Call Center information should be automatically updated.
These requirements were met with an integration known as the RETAIN RATLC Bridge. The Bridge enables Development to communicate with Support and customers, using the existing change request tracking system. With this integration, the flow of information between Support and Development is automated and bi-directional. Support can log a customer request in the Call Center application that triggers a new RATLC change request to be submitted. Similarly, Development can resolve a RATLC change request with an associated APAR that updates the Call Center information directly from the ClearQuest record.
As part of this integration, a change request includes a tab for customer information and a tab for APAR information in the RATLC schema. Some of the information entered in fields on the APAR tab in ClearQuest will be seen by customers through the Call Center application.
Figure 1 illustrates some of the roles that ensure the resolution of an issue, as well as showing the processes the RETAIN RATLC Bridge automates.
Figure 1: Workflow to automate customer change request tracking
As Figure 1 illustrates:
- A developer works on a customer-related CR, delivers the changes for testing, and resolves the CR. (The developer must enter the required resolution fields in the RATLC CR.)
- The Bridge populates the associated RETAIN Call Center record with the resolution information from ClearQuest.
- QA testers validate the fix and then close the ClearQuest (RATLC) change request.
- A reviewer reviews and approves the APAR tab information.
- The Bridge closes the RETAIN Call Center record (RETAIN CR) if the approved CR has an available fix.
Once the Call Center record is resolved, a trigger can be used to notify the customer when the solution to their problem is available. With this integration, IBM Rational is able to provide faster, more efficient resolutions to customer issues or requests. The RETAIN RATLC Bridge also improves the organization's goal of streamlining the customer resolution process and enabling closer communication between customers, Support, and Development.
Resolving a customer change request
The scenario I'm about to describe illustrates how the ClearQuest development organization uses its own product to resolve customer change requests.
Developers and other stakeholders are listed as members of groups that are specified as default development (DEV), testing (QE), and documentation (Doc) owners for change requests, based on a specific product or component. With ClearQuest email notification, stakeholders can receive emails about change requests that may be of relevance to them and therefore need to assess.
With the RETAIN RATLC Bridge, a new customer change request submitted in the RETAIN Call Center application that includes an APAR number triggers a new ClearQuest change request, so that stakeholders receive automatic email notification for customer requests. This automation reduces the separation among customers, Support, Development, and Management and improves the timeliness of communication.
Here, then, is the scenario:
- A customer calls Support, notes an issue, and requests a change in the product.
- If the issue is a defect, Support creates an APAR in the Call Center application, which triggers the submission of a RATLC change request.
- Based on the information provided in the RETAIN Call Center application, the appropriate default owners in the RATLC change request are automatically filled in, and they receive email notification for the newly submitted change request.
- The change request is assessed, prioritized, and assigned to an appropriate developer who will work on and then resolve the change request.
Once the change request is resolved, the RETAIN RATLC Bridge ensures that the information in the Call Center application is updated, so that both Support and customers can see the status of the change request. Note that the Bridge integration also enables the opposite workflow, where a Support representative can submit a RATLC CR that then automatically generates the RETAIN Call Center record (or APAR).
It is important to remember that a change request can be submitted from an internal or external customer; that is, from consumers of a product within the organization that creates it or from a customer who purchased the product. Further, a change request can be a defect or a request for enhancement (RFE), but could be handled the same way in either case from a workflow process perspective.
It is also useful to recognize that customers and other stakeholders may be located all around the world and thus potentially benefit from an IBM Rational ClearQuest MultiSite solution, which I'll talk more about below.
Supporting a distributed environment with ClearQuest MultiSite
The need to support a distributed environment for change management is commonplace among the IBM Rational development teams, as it is with many IBM Rational customers. IBM Rational ClearQuest MultiSite provides the solution. We use it for RATLC, in which we've defined database replicas and mastership policies to support distributed development, support, and testing teams around the world.
Figure 2 illustrates the IBM Rational internal deployment of RATLC database replicas with ClearQuest MultiSite. (The actual names of the replicas have been been changed for this figure.)
Figure 2: A sample ClearQuest MultiSite deployment
While this article is not intended to fully elaborate the details of how to set up and support a distributed ClearQuest MultiSite environment, I'll cover some basic ideas on how to handle the issues of mastership and optimistic locking.
ClearQuest MultiSite mastership
ClearQuest MultiSite mastership functionality ensures that a ClearQuest record can be updated at only one database replica site at a time. A user who logs in to a site that does not have mastership of a record can view record information, but not modify it. The user must log in to the site that has mastership in order to do record updates.
Consider a scenario where the customer is in London, the Support representative is in Bangalore, the developer in Raleigh, and the Tester is in Beijing. If the change request validation occurs in Beijing, where one of several database replicas resides, the mastership of the record may change from one site to another, such as when the state of the record changes from Active to Resolve and the fix needs to be validated. (Note: Users can log in to any replica to read information, but must log in to the replica that has the mastership to make changes to a record.)
Optimistic locking
ClearQuest uses optimistic locking to handle cases where two people want to update the same record. The first person to save their changes -- not the first person to open the record for updating -- will be successful. Other sets of changes are not preserved. Therefore, the second person to attempt the record update will need to retrieve the record again and then restart his or her update.
One technique to reduce this inconvenience, which I can recommend because IBM Rational uses it in-house, is to create a record using a ClearQuest scripted Action type called a Record_Script_Alias. The Action is executed on a record that may be remote or is being updated at the same time. It creates a new record and updates a field on the new record with the ID of the Action record. ClearQuest then creates a back-reference (in the Action record) from the new record ID to the Action record, regardless of the mastership setting. Both records are then relational extensions of each other -- immediately at the current site and following replication at other sites. The back-reference ensures that the linked record is updated appropriately. That is, when you update a reference field when creating a record, the back-reference will update the related record regardless of mastership or optimistic locking contention.
And here's a further tip: when creating child records as a by-product of creating a parent record, use the Commit Event of the parent record you are creating to create the children records.
The role of Ownership
Because of the limitations of replication, it is not possible for ClearQuest to ascertain in real-time whether records are created or changed at more than one site. Therefore, if records are being created and back-referenced at multiple sites, there is no way to for a user to know that before the fact. You can limit this by assigning Ownership and making the Owner the person most likely (or the only person) to perform an Action. This reduces the likelihood of redundant processing of records by, in effect, creating a virtual threading mechanism.
This approach also helps to simplify the resolution of ClearQuest MultiSite mastership and optimistic locking contention issues. That is, you can either create a record and then link records using a back-reference as described above or construct records with implied update by Owner assigned. You need not use the two approaches together.
A role-based user experience
The ClearQuest product supports a role-based model for designing, implementing, and administering the change management system.
For our own purposes internally, as well as for explanatory purposes in the ClearQuest documentation, IBM Rational has identified three common (essentially universal) roles. Most other roles you might identify are specific instances of one of these three: User, Administrator, and Schema Developer.
The User role covers any common task available from a ClearQuest client that applies to retrieving, creating, or modifying data in a user database. Common user tasks include getting information from a user database and working with records, submitting a change request, working on a change request, modifying information in the record, and running queries. A User may be a Support representative who is submitting a customer request or a Developer, Quality Engineer, Information Developer, or Manager who is submitting, assigning, working on, resolving, or validating a change request for a given release of the product.
The Administrator role applies to database, user, and group management, as well as security policy administration. Common tasks for an Administrator include configuring and maintaining databases, managing user accounts, and setting up lightweight directory access protocol (LDAP) authentication.
The Schema Developer role includes most of the functions in ClearQuest Designer used for setting up the schemas that will define the databases that users will work with from one of the ClearQuest client user interfaces. Common tasks that a Schema Developer performs encompass all schema design and development, including developing the state transition model, record, field and action types, and the behavior for each record type, field, and action, including hooks and scripts, as well as developing the forms for users of a ClearQuest client.
In many change management implementations, there is likely to be a small number of Schema Developers and Administrators, whereas the number of users of a client application may be quite large -- possibly several thousands of users. This is true within IBM Rational's internal development group, where a small team of Schema Developers and Administrators supports the RATLC schema and makes ongoing enhancements to it. And it is true for many of our customers' development teams as well.
The lines between the roles can be blurred, however. For instance, the same people will often take on aspects of both the Administrator and Schema Developer roles at times. Similarly, it is not uncommon for the writer of a hook or the designer of a form to also be the designer of the security policy or the administrator for managing groups and permissions (also known as user privileges). And as is true at IBM Rational, there might be Users with Administrator privileges who may create queries and save them to public folders, and who may manage some databases, or replicas, or users and groups.
Internal and external audiences
In many CM implementations, a given role might apply to internal and/or external audiences. Roles like these are also very likely to benefit from supplementary use-case documentation for these varying audiences.
An internal audience within IBM Rational, within the IBM Software Group, or within IBM at large might refer to anyone who is doing work in product development, creating new user interfaces, working on integrations with the ClearQuest product or components of it, or working on applications relying on ClearQuest core functionality or services. The developers who maintain the RATLC schema for IBM Rational are themselves an internal audience for the ClearQuest Schema Developer and Administrator roles documentation, as are the developers in other geographic locations using RATLC database replicas who are developing new or enhanced user interfaces to the ClearQuest functionality or testing the product. The same is true for an IBM Rational field representative who is supporting a customer change management solution and requires information on schema development, or a customer support representative who may be trying to answer a customer question or issue on user administration. A new employee who needs to learn how to use ClearQuest would be a good internal audience for the User role documentation.
External audiences include customers who have their own Schema Developers, Administrators, and Users, or partners or independent software vendors (ISVs) who are creating solutions for customers. The documentation for the Schema Developer role is intended to support those service providers or technical specialists who develop the schemas for their customers, which in some cases apply to an internal team such as an in-house corporate IT group that will roll out the change management system for their organization. In some instances, for larger and highly customized deployments, customers create an additional layer of user documentation for their client application that provides details on how to use not just ClearQuest in general, but also their specific implementation of it. For example, the product itself provides information on creating and running queries, but a customer might create more detailed documentation for working with specific queries that apply to the unique record types, fields, states, or actions defined in their specific schema.
Making roles more specific
Beginning in version 7.0.0 of IBM Rational ClearQuest, the documentation is role-based in order to enhance the user experience for each of these roles. The User, Administrator, and Schema Developer roles defined in the documentation are useful for CM systems across most -- if not all -- industries.
But while these universal roles in a CM system are industry-neutral, the record types defined in a schema, as well as the states and actions (or the state transition model) and defined level of security, are highly customizable and subject to much variety across industries and organizations -- as are the roles themselves. While the User role may be generically descriptive, it does not fully elaborate actual jobs such as data entry clerk, bank teller, loan officer, or customer support representative.
For example, within the IBM Rational software development organization, a User role is defined that includes all users of the RATLC database replicas around the world. The User population includes developers, testers, technical writers (also known in IBM as Information Developers), product and project managers, field representatives who work with customer solutions, customer support representatives who review ongoing changes and also submit change requests based on customer requests, and sometimes even partners or customers who may have limited access to the information available in the change management system.
Some CM systems might benefit not only from "personalized" use cases for their varying roles, but also from more specialized roles within their ClearQuest schemas as well.
Next month
In next month's installment, Part 2, I'll explore possibilities devised by IBM Rational's Internal Deployment team for further enhancing our best practices change management process and how other development organizations that use ClearQuest can make use of these suggestions as well.
Acknowledgments
Special thanks to Robert W. Myers and the Rational Internal Deployment team (Shirley Dango, Chibuzo Obi, Barb Purchia, and Kathy Ludlow) for developing much of the technical information in this article. Robert helps lead IBM Rational Internal Deployment initiatives for the IBM Rational development organization's CM system.
About the author  | | | Rob Pierce is an Advisory Information Developer for the Rational User Assistance group. He is currently documenting IBM Rational ClearQuest API Reference and Schema Developer role-based Help, as well as the Rational Team API. He is also a member of IBM and IBM Software Group Councils for Information Development (ID) focused on design and development of ID processes including working with support toward improvements in collaboration and consistency of information. |
Rate this page
| 
