In any software development scenario, we make a lot of changes, add new code, delete old data, and so on daily. For this purpose, we use Rational ClearCase to track the changes that we make to our data or code and track versions of our software. Also, in a development lifecycle, we test the software that we develop. When we test a piece of software, there are bound to be a lot of change requests to handle or enhancements that need to be made. These change requests are maintained in Rational Change. The purpose of integrating these two tools is to seamlessly join them so that we know the code change that is in place for a change request, and vice versa. The integration creates a link between the change request in Rational Change and the piece of code in Rational ClearCase.
Integrating change management in Rational Change and configuration management in Rational ClearCase results in better management of the software development lifecycle.
- IBM® Rational® Synergy
- A task-based configuration management solution that brings globally distributed
development teams together to work on a unified configuration and release
- IBM® Rational® Change
- A web-based change management solution that tracks the quality of software over
the software's development lifecycle and provides a powerful querying and
- IBM® Rational® ClearCase®
- A software configuration management tool that helps teams use version control
for their source code and other project artifacts and allows parallel
development and graphical merging capabilities, which accelerates the
- VOB (versioned object base)
- A ClearCase repository that stores files and directory
- CR (change request)
- A Rational Change defect or enhancement request
Setting up and configuring the integration
- Install Rational Synergy, Rational Change and server side components of the Rational Change for ClearCase Interface on UNIX or windows machine (as mentioned in the Rational Change for ClearCase Interface readme file).
- Install Rational ClearCase and the client-side component of the Rational Change for ClearCase Interface on the same machine where Rational Change is installed or on a different UNIX or windows machine (as mentioned in the Rational Change for ClearCase Interface readme file). This client-side installer installs the Rational Change for Rational ClearCase Interface - Configuration Tool, which is used to gather Rational Change server details and to configure ClearCase triggers to be used by the integration, as shown in Figure 1.
Figure 1. Rational Change for ClearCase Interface - Configuration Tool
As mentioned in the installation steps, Rational Change is considered the server and Rational ClearCase is considered the client for the integration.
Integrating Rational Change with the base ClearCase model
Setting up the integration
- Create a versioned object base (VOB) in Rational ClearCase, and open the configuration tool. The VOB will be listed under Rational ClearCase VOBs on the left side.
- Click the VOB, provide Rational Change server details, and choose the respective
trigger policy for check-in and checkout operations for the VOB, and save your
changes. The value for the query field can be taken from Rational Change
Queries. Example: (
- Choose the trigger policy. The commonly used policy is Prompt,
and it requires selections for check-in and checkout operations on the VOB.
- If the Do not prompt users policy is selected, the integration will not prompt users to select a Rational Change change request (CR) when there is a check-in/checkout operation on the VOB.
- If the Prompt, but do not require selection(s) policy is selected, the integration will prompt users to select a Rational Change CR when there is a check-in or checkout operation on the VOB. The selection of CR will not be mandatory.
- If the Prompt, and require selection(s) policy is selected, the integration will prompt users to select a Rational Change CR when there is a check-in/checkout operation on the VOB. The selection of CR will be mandatory. The operation will not proceed without selection of a CR.
Figure 2 shows configuring a VOB for Rational Change.
Figure 2. Configuring Rational Change on a VOB
Checking in and out from Rational ClearCase
Next, you'll create Rational Synergy tasks while working in Rational ClearCase and see how you can integrate ClearCase with Rational Change.
- Go to Rational ClearCase explorer and select the VOB that you created -- the one for which Rational Change server details have been stored by using the configuration tool.
- Create a directory or a file in this VOB. This will now be the object for our integration. From the context menu of that object, perform the action (check in or check out).
Because the Prompt, and require selection option is selected as the
trigger policy on the configuration (see Figure 2 above), it opens a CR selection
dialog with CRs coming from Rational Change. This is shown in Figure 3. The CRs that
are populated in the selection dialog are within the scope of the query specified
during the configuration. The query here is:
(cvtype=problem) and (crstatus=assigned)
So it populates CRs that are in the assigned state.
Figure 3. CR selection dialog during check-in or checkout of a Rational ClearCase object
Upon completion of the check-in/checkout operation, an integration task gets created in Rational Synergy and is associated with the CR selected in the previous step. See the integration task on the CR in the Associated Tasks field in Rational Change, which is shown in Figure 4. An integration task and a non-integration task can be easily differentiated through the synopsis. For example, the integration task synopsis is simply this: ClearCase Integration Task.
Figure 4. Integration task associated with the CR
If there is already an integration task associated with a CR, it will not associate another integration task on the same CR. Instead, it will add the object being checked in or checked out to the same integration task. But there is an exception to this case: a CR can have two integration tasks. This exception is when an integration task has already been completed. It does not re-open the completed integration task but creates a new integration task when a check-in or checkout happens on an object from Rational ClearCase. This can be seen in Figure 5.
Figure 5. Integration task states on the CR
- Under Associated Tasks on the CR, click the task ID link(the numbered link), to reveal the objects under the task.
This opens the task dialog, and the objects are shown under Associated Objects field on the task. The objects listed here are the objects that were checked in or checked out in Rational ClearCase for which this CR was selected. Each object listed under this field shows the object name that was checked in or checked out and the corresponding state, which can be either integrate or working. The objects associated with the task are as shown in Figure 6.
Figure 6. Associated objects on the task
The objects that are checked out are shown in a working state, and the ones that have been checked in are shown in integrate state. So in Figure 6, the user can see that the task has two objects associated with it:
- cc2.txt, which is in integrate state
- cc4.txt, which is in working state
So far, you've learned about the CR-task-object association. Now you'll see what happens when the task that was created from this integration needs to be completed. Remember these two points:
- A task can be completed only if all of the associated objects are in integrate state. If any of the associated objects are in working state, the task cannot be completed.
- After all of the integration tasks associated with a CR have objects in integrate state, and then the CR can be resolved directly from Rational Change. Resolving the CR automatically completes the integration tasks associated with the CR.
Undoing checkouts on base ClearCase
Consider an object that has been checked out and associated with an integration task on a CR on Rational Change.
When you perform Undo Checkout in Rational ClearCase, the object associated with the integration task will be deleted. If this was the only object associated with the integration task, the integration task will also be deleted.
Integrating Rational Change with the UCM ClearCase model
Setting up the integration
- Create a UCM project and a VOB in Rational ClearCase, and select that VOB in the configuration tool.
- Provide Rational Change server details and select the trigger policies.
- For the purposes of this tutorial, under "Activities - Create activity policy" in the configuration tool, select Prompt, and require selection(s) (see Figure 7).
Figure 7. Create activity policy
Working with activities and objects
- On the Rational ClearCase explorer, select the VOB created (the one for which Rational Change server details have been configured).
- Create an object (file or directory) in this, and add it to source control.
The integration will prompt you to create a new activity, as Figure 8 shows.
Figure 8. Creation of new activity
Because you have selected Prompt, and require selection(s) as the trigger policy for "create activity," creating a new activity will prompt to select a CR. When a CR has been selected, it associates an integration task with the CR. The task description shows the activity that this task was created for (see Figure 9).
Figure 9. Task description shows the activity that the task was created for
As in the case of object check-in or checkout, if an integration task is already associated with the CR for the selected activity, the integration does not create a new integration task again. However, in case the integration task is completed, it will create another integration task and associate it with the CR with details of the activity.
Now that an activity has been created in UCM ClearCase, you're ready to move to Rational ClearCase objects. Similar to base ClearCase, when you check in or check out objects, the integration will create objects in Rational Change and associate them with the task.
Undoing checkouts on UCM ClearCase
Consider an object that has been checked out and associated with an integration task that is associated with a CR in Rational Change.
When you perform an Undo Checkout operation on this object, the object that is associated with the task is deleted. However, the task itself is not deleted, and it is still associated with the CR. The activity used for checkout of the object is not deleted either. So, the CR-task and task-activity relationships remain intact even if there are no objects associated with the task.
You can remove an activity if it does not have any change set (ClearCase objects) associated with it. When you remove the activity, the Rational Synergy task associated with this activity is deleted, provided that there are no other placeholder objects associated with that task.
Delivering the finished work
When you are finished with your development and testing work in the development stream, you will need to deliver the work to the integration stream so that it can be tested along with the other components.
- From the project explorer, deliver the activity from the development stream to the integration stream.
After the activities have been merged into the target integration stream and you are satisfied with the testing results, you can finish the delivery process. Finishing the delivery process will also complete the Synergy tasks associated with the delivered activities. The integration will automatically transition all of the objects associated with the task to integrate state.
- If the deliver activity policy on the configuration tool is set to Do not make activity obsolete on deliver, as shown in Figure 10, then the activity remains in the unlocked state after delivery. This means that this activity can be used further and work can be done under this activity on Rational ClearCase.
Figure 10. Deliver activity policy - do not make activity obsolete
- If the deliver activity policy on the configuration tool is set to Automatically make activity obsolete on deliver, as shown in Figure 11, then the activity is made obsolete.
Figure 11. Deliver activity policy - make activity obsolete
- You can check the activity Properties dialog view to see whether an activity is locked or in an obsolete state.
When an activity is made obsolete on delivery, this activity cannot be further used for work. Trying to use this obsolete activity for check-ins or checkouts on any object will result in the error message shown in Figure 12.
Figure 12. Error upon using the obsolete activity for work
Rational Change integration reports
The Prerequisites section of this article mentions that Rational Change provides a powerful reporting mechanism. You can use this feature to view the integration reports.
- Log in to Rational Change as a user, and select Reports > System.
The screen lists the ClearCase CRs-Objects, ClearCase CRs-Tasks-Objects and ClearCase CRs-Tasks-Objects (Long) reports from this integration. This can be seen on the left side, as shown in Figure 13.
Figure 13. Integration reports menu
- Click the report link to view a specific report.
ClearCase CRs-Objects report
This report shows the relationship between a Rational Change CR and the Rational ClearCase objects associated with the integration tasks on this CR. This association is seen for all of the CRs that are within the scope of the query specified for the VOB.
Figure 14 shows one such association from the report.
Figure 14. ClearCase CRs-Objects report
ClearCase CRs-Tasks-Objects report
This report shows the relationship of Rational Change CRs and Rational Synergy tasks, as well as Rational Synergy tasks, to the ClearCase objects associated with the integration tasks. One such association from the report is as shown in Figure 15.
Figure 15. ClearCase CRs-Tasks-Objects report
ClearCase CRs-Tasks-Objects (Long) report
This report shows the relationship of Rational Change CRs and Rational Synergy tasks and also Rational Synergy tasks to the ClearCase objects associated with the integration tasks. One such association from the report is as shown in Figure 16. This is a more detailed report, so it lists more properties of the object.
Figure 16. ClearCase CRs-Tasks-Objects (Long) report
These reports can be further customized using Rational Change if you need additional information in the reports.
- Start at the respective developerWorks pages to find out more about Rational Change integrated Web-based, change control and change management and Rational ClearCase configuration management software.
- You might also find the Software Change and Confirmation Management offerings page helpful.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the “Getting Started” ones are free.
Get products and technologies
- Get the free Trial Download or check the Trials and Demos page for Rational software.
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Join the Enterprise Change Management with Rational Change forum to ask questions and participate in discussions.
- Join the Rational ClearCase forum, where you can ask questions and participate in discussions.
- Rate or review Rational software. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
- Get social about thought leadership. Join the Rational community to share your Rational software expertise and get connected with your peers.