How to establish traceability by using IBM Rational RequisitePro and IBM Rational Systems Developer

This article demonstrates how to use traceability queries by using IBM® Rational® RequisitePro and IBM® Rational® Systems Developer, and explores an address book project as an example.

Scott Cowan (scowan@ca.ibm.com), Advisory Software Developer, IBM Canada

Scott joined IBM in 2002 with 5 years experience in the telecommunications industry developing network management systems. His work with the Rational Modeling Tools team has contributed to UML and EMF Compare Support, Java Code Review, Architectural Discovery for Java, Traceability, UML Model Analysis, BIRT Reporting and Web Publish.



29 April 2008

Also available in Chinese

About this article

Traceability is the ability to trace artifacts through all levels of abstraction, from specification to implementation and vice versa. Impact analysis is the ability to analyze the potential impact of a change to a system through all levels of abstraction, as well as within each level of abstraction.

Given a context element, traceability offers these types of queries:

  • Specifications
  • Implementations

Given a context element, these types of queries affect analysis:

  • Suppliers
  • Clients

This article demonstrates how to use each of these queries by using an address book project as an example.

Prerequisites

You need the following software installed before beginning this article:

  • Microsoft® Windows®
  • IBM® Rational® RequisitePro®, Version 6.0.1.1
  • Microsoft® Access®
  • IBM® Rational® Systems Developer, Version 7.0.5, or IBM Rational Software Modeler, Version 7.0.5

Address book example

The example used here to demonstrate traceability and impact analysis is a system of requirements, models, and Java™ code that implement an address book.

  • In Lesson 1, you build a RequisitePro project of requirements.
  • For Lesson 2, you create a UML project and an analysis model of use cases from those requirements and establish traceability back to the requirements. You also create a design model further refining the use cases with collaborations and UML classes and establish traceability back to the use cases.
  • In Lesson 3, you create a Java project, transforms the UML classes to Java classes, and establish traceability from the Java classes back to the UML classes. In each of these three lessons, there are two sections: The first section explains how to unzip and open or import the project. and the second section describes how to create the project.
  • Lessons 4 and 5 demonstrate what the traceability and impact analysis queries are for, what is expected from each query and example results using the Address Book system. To quickly get through lessons 1, 2, and 3 follow the first section of each.

Address book requirements

The user needs to be able to store contact information in an address book. Each contact needs to be able to maintain a contact's name and phone number. The user should be able to change a contact's information and also add and remove contacts to and from the address book.

Lesson 1. Create the RequisitePro Address Book project

This lesson demonstrates how to unzip or create a Rational RequisitePro Address Book project and the requirements for the address book.

Unzip and open the Address Book RequisitePro Project file

  1. Unzip the Address Book RequisitePro Project.zip file (from Downloads) to C:\RequisitePro Projects\.
  2. Follow the Steps 11 through 17 in the next subsection to open the project.

Create the Address Book project

  1. Start Rational RequisitePro (see Figure 1).
Figure 1. Rational RequisitePro screen
Screen capture of opening screen
  1. Click File > New > Project (Figure 2).
Figure 2. Create a new project
Path to select New and then Project from menus
  1. When the Create Project dialog opens (Figure 3), select Composite Template.
Figure 3. Create Project dialog in RequisitePro
Composite Template icon highlighted (selected)
  1. Click OK.
  2. When the Rational RequisitePro Project Properties dialog opens (Figure 4), in the Name field, enter Address Book, and in the Directory field, use the Browse button to select C:\RequisitePro Projects\Address Book.
  3. From the Database drop-down menu, select MS Access, and then click OK.
Figure 4. Project Properties dialog
Screen capture showing selections
  1. When a dialog opens and asks if you want to create the directory, click Yes, and wait for the project creation to finish.
Figure 5. Dialog to create the project directory
Dialog asks: Do you want to create it?
  1. Click Close.
Figure 6. Confirmation notice that the project has been created

  1. When the Project Logon dialog opens, click Cancel.
Figure 7. Project Logon screen
Project Logon screen capture
  1. Exit Rational RequisitePro.
  2. Start Rational Systems Developer.
  3. When the Workspace Launcher dialog opens, enter C:\workspace in the Workspace field, and then click OK.
Figure 8. Workspace Launcher dialog
Shows typing the location in the Workspace field
  1. Click Window > Open Perspective > Requirement to open the Requirement perspective.
Figure 9. Requirement perspective
Drop-down menus with selections highlighted
  1. In the Requirement Explorer (Figure 10), click the Open a RequisitePro Project icon: Open a RequisitePro Project icon
Figure 10. Requirement Explorer view
Screen capture showing icon to click at the top
  1. When the Open a RequisitePro Project dialog appears (Figure 11), in the "File name" field, use the drop-down menu to select C:\RequisitePro Projects\Address Book\Address Book.rqs, and then click Open.
Figure 11. Open a RequisitePro Project dialog
Screen capture showing selection
  1. When the Project Logon dialog opens, click OK.
Figure 12. Project Logon screen
Project Logon screen capture
  1. Expand the Address Book project folder and then the Use Cases folder under that (Figure 13).
Figure 13. Requirement Explorer with both folders expanded
Use Cases folder expanded under the Address Book folder
  1. From the Use Cases drop-down menu (Figure 14), click Create Requirement by type > UC requirement, and then enter this requirement name: Change contact.
Figure 14. Use Cases drop-down menu
Screen capture showing choices described
  1. Create two more use case requirements with these names: Add contact and Remove contact (see Figure 13).
Figure 15. Create additional use cases
Shows added use cases, which makes a total of 3

Lesson 2. Create the UML Address Book project

This lesson demonstrates how to unzip or create an Address Book UML project, an Analysis and Design model, and sequence diagrams and classes, including traceability to the requirements.

Unzip and import the Address Book UML project

  1. Unzip the Address Book UML Project.zip (from Downloads) file to the workspace: C:\workspace\
  2. Click Window > Open Perspective > Modeling to open the Modeling perspective.
  3. Click File > Import.
  4. When the Import dialog opens, expand the General folder and select Existing Projects into Workspace.
  5. Click Next.
  6. In the "Select root directory" field, enter C:\workspace.
  7. Press Enter and then click Finish.
  8. In the Project Explorer, expand Address Book and then Models.
  9. From the Design model drop-down menu, click Open.

Create the Address Book UML project

  1. Click Window > Open Perspective > Modeling.
Figure 16. Path to open the Modeling perspective
Screen capture of drop-down menus
  1. After the modeling perspective opens, click File > New > Project.
Figure 17. Creating a new project in the Modeling perspective
Drop-down menus showing selections as described
  1. In the New Project wizard that opens, under Wizards, expand Modeling and select Model Project.
  2. Click Next.
Figure 18. Selecting a new model project
Model Project chosen under Modeling wizard option
  1. In the Project name field, enter Address Book.
  2. Click Next.
Figure 19. Name the model project
Address Book entered in Project name field
  1. Complete the required information:
    • Categories list: Select General
    • Templates list: Select Blank Model
    • File name field: Enter Analysis
  2. Click Finish.
Figure 20. Complete the model project specifications
Model Project view with information completed

A new Address Book project that contains and Analysis model will be created.

  1. In the Project Explorer, expand Address Book and Models.
  2. In the Main diagram of the Analysis model, expand the Use Case drawer in the Palette, and select Use Case.
  3. Control-click in the Main diagram 3 times to create 3 use cases. Name them:
    • Add contact
    • Remove contact
    • Change contact
Figure 21. Main diagram tab of the Analysis model
Screen capture showing all 3 use cases created
  1. Click Window > Show View > Requirement Explorer to open the Requirement Explorer.
Figure 22. Requirement Explorer view
2 drop-down menus showing options selected
  1. From the Project Explorer, drag and drop the Change Contact use case onto the Change Contact use case requirement.
  2. Drag the remaining two use cases onto the use case requirements with the same names. The use cases and the use case requirements icons are annotated with a small arrow to indicate they are linked.

Note:
These links trace the use cases to the use case requirements.

  1. Click File > Save to save the Analysis model.
  2. In the Project Explorer, select the Address Book project.
  3. Click File > New > Other.
Figure 23. Open the New wizard
Drop-down menus showing path as described
  1. After the New wizard opens, expand Modeling and select Model in the Wizards tree.
  2. Click Next.
Figure 24. Select the Model wizard under the Modeling folder

  1. Click Next again.
Figure 25. Create Model view
Standard template set as default, Next selected
  1. Complete the required information:
    • Categories list: Select General
    • Templates list: Select Blank Model
    • File name field: Enter Design
  2. Click Finish.
Figure 26. Select General in Categories and Blank Model in Templates
Create Model view with selections as described

A new Design model is created in the Address Book project.

  1. In the Design model drop-down menu, click Add Diagram > Sequence Diagram to create a new collaboration that contains a new sequence diagram.
  2. In the Project Explorer, rename the Collaboration to Change contact.
  3. Create an Unspecified lifeline on the diagram and name it user.
  4. Create another lifeline, but for this one, click Create Class. Enter the class name, Contact and give the lifeline the name contact.
  5. Create an Option Combined Fragment over the user and contact lifelines, and name it set name.
  6. Within the set name option combined fragment, create a Synchronous Message from user to contact.
  7. When the "Enter operation name and owner" dialog opens:
    1. In the "Operation name" field, enter setName.
    2. From the Operation owner drop-down menu, select Contact
    3. Click OK.
  8. Create another Option Combined Fragment over the user and contact lifelines, and name it set phone number.
  9. Within the set phone number option combined fragment, create a Synchronous Message from user to contact and select Create New Operation.
  10. When the "Enter operation name and owner dialog" opens:
    1. In the "Operation name" field, enter setPhoneNumber.
    2. From the Operation Owner drop-down box, select Contact.
    3. Click OK.
Figure 27. SequenceDiagram1 view showing results
setName and setPhoneNumber show in the diagram
  1. In the Design model drop-down menu, click Add Diagram > Sequence Diagram.

A new collaboration is created that contains a new sequence diagram.

  1. In the Project Explorer, rename the Collaboration to Add contact.
  2. Create an Unspecified lifeline on the diagram and name it user.
  3. Create another lifeline, but, for this one, click Create Class. Enter the class name AddressBook and give the lifeline the name addressBook.
  4. Create a Synchronous Message from user to addressBook.
  5. When the "Enter operation name and owner" dialog opens:
    1. In the "Operation name" field, enter addContact.
    2. From the Operation owner drop-down box, select AddressBook.
    3. Click OK.
Figure 28. Results for Interaction1 input
addContact added, addressBook:AddressBook selected
  1. In the Design model drop-down menu, click Add Diagram > Sequence Diagram.

A new collaboration is created that contains a new sequence diagram.

  1. In the Project Explorer, rename the Collaboration to Remove contact.
  2. Create an Unspecified lifeline on the diagram and name it user.
  3. Create another lifeline, but, for this one, click Select Existing Element. Select AddressBook and give the lifeline the name addressBook.
  4. Create a Synchronous Message from user to addressBook and select Create New Operation.
  5. When the "Enter operation name and owner" dialog opens:
    1. In the "Operation name" field, enter removeContact.
    2. From the "Operation owner" drop-down menu, select AddressBook
    3. Click OK.
Figure 29. Results for Operation name and Operation owner
Screen capture of diagram showing results
  1. Close and save the sequence diagrams.
  2. On the Design model, open the Main diagram and complete these steps:
    1. Drag the three use cases from the Analysis model onto this diagram.
    2. Drag the three collaborations onto this diagram.
    3. In the drop-down menu of each collaboration view on the Main diagram, uncheck Filters > Show/Hide Compartment > Structure Compartment.
    4. Create a Realization relationship from each collaboration to each use case with the same name.

Note:
These realizations trace from the collaborations to the use cases.

Figure 30. Main diagram showing realization relationships
First Screen capture showing the 3 relationshipsSecond Screen capture showing the 3 relationships
  1. In the Design model drop-down menu, click Add UML > Package. Name it addressbook.
Figure 31. Design model Add UML and Package menus
Screen capture of 2 drop-down menus
  1. Move the new classes, AddressBook and Contact, into the addressbook package.

Note:
As types of lifelines on a sequence diagram in a collaboration, these UML classes trace from each UML class to each corresponding collaboration.

Figure 32. addressbook package with AddressBook and Contact classes added
Project Explorer, 2 classes added under package
  1. In the addressbook package, open the Main diagram.
  2. Drag AddressBook and Contact onto the diagram.
  3. Create a one-to-many Composition Association from AddressBook to Contact. This creates a dependency, with AddressBook dependent on Contact. This relationship is relevant for Impact Analysis, but is not relevant for traceability.
Figure 33. Main tab showing association
Arrow between AddressBook and Contact with 1 to *
  1. Click File > Save to save the model.

Lesson 3. Create the Java Address Book project

This lesson demonstrates how to unzip or create an Address Book Java project the Java classes for the address book and traceability to the UML classes.

Unzip and Import the Address Book Java project

  1. Unzip Address Book Java Project.zip file (from Downloads) to: C:\workspace\
  2. Click File > Import.
  3. When the Import dialog opens, expand the General folder and select Existing Projects into Workspace.
  4. Click Next.
  5. In the "Select root directory" field, type C:\workspace and then press Enter.
  6. Click Finish.

Create the Address Book Java Project

  1. Click File > New > Project to open the New Project wizard (Figure 34).
Figure 34. Open the New Project wizard
Path to open wizard, as described
  1. Under Wizards (Figure 35), select Java Project and then click Next.
Figure 35. Select Java Project in the New Project wizard
New Project wizard view with Java Project selected
  1. In the Project Name field, type addressbook (see Figure 36) and then click Finish.
  2. When the "Open Associated Perspective?" dialog opens, click No.
Figure 36. Enter "addressbook" as the project name
New Java Project view showing Project name field
  1. In the Project Explorer, select addressbook and then click File > New > Other (Figure 37).
Figure 37. Project Explorer view
File menu plus 2 drop-down menus show selections
  1. Under Wizards, expand Transformations and select Transformation Configuration (Figure 38).
  2. Click Next.
Figure 38. Select the Transformation Configuration wizard

  1. When the New Transformation Configuration wizard opens, type addressbook in the Name field.
  2. Under Forward transformations, select UML to Java (Figure 39).
  3. Click Next.
Figure 39. Name and transformation view
Shows UML to Java selected
  1. Under Selected source, expand Address Book and Models, and then select Design.
  2. Under Selected target, select addressbook.
  3. Click Next on this screen and the three screens that follow (thus, click Next four times).
Figure 40. Source and Target view
Design selected as source, addressbook as target
  1. Under Transformation options (Figure 41), select Create trace relationships, and click Finish.

Note:
This transformation option traces from each created Java class to each corresponding UML class, thereby completing the traceability from RequisitePro requirement specifications down to Java class implementations.

Figure 41. Common screen in New Transformation Configuration wizard

  1. In the Project Explorer, expand addressbook.
  2. In the addressbook.tc drop-down menu (Figure 42), select Transform > UML to Java. The addressbook package is created in the source folder of the Address Book project, and both AddressBook.java and Contact.java files are created in that package.
Figure 42. Project Explorer selections leading to addressbook.tc menu drop-down menus
Transform selected on 1st menu, UML to Java on 2nd
  1. Open the AddressBook.java and Contact.java files (Figure 43).
Figure 43. Project Explorer with classes under addressbook package
AddressBook and Contact Java classes selected

Notice this Java™doc tool annotation: @uml.annotations derived_abstraction= (Figure 44). The value of this annotation is the URI that refers back to the UML class, AddressBook. This is what the transformation created to persist the trace relationship from the Java AddressBook class to the UML AddressBook class. The same is true for Contact.java.

Figure 44. AddressBook.java screen output of code
Code for package, import, public class

Lesson 4. Traceability queries

Traceability queries, instructions,and examples follow.

Query: Specifications of AddressBook

This query starts at a context element and follows immediate trace relationships in the forward direction to discover elements that are one level of abstraction higher. Another way to phrase this query is: "From which specifications is this element immediately derived?"

  1. In the "AddressBook UML class" drop-down menu, select Query > Traceability > Specifications. The Save As dialog will open (see Figure 45).
Figure 45. AddressBook specifications query path
Shows path of drop-down menus and selections
  1. Click OK.
Figure 46. Save as Address Book
Save As screen showing Address Book selected

A new diagram is created and the query results are added (Figure 47).

Figure 47. AddressBook.dnx specifications with query results added
Diagram shows AddressBook added

Query: All Specifications of AddressBook

This query starts at a context element and follows all trace relationships in the forward direction to discover all elements in higher levels of abstraction. Another way to phrase this query is: "From which specifications is this element derived?"

  1. In the "AddressBook UML class" drop-down menu, select Query > Traceability > All Specifications.
  2. Wen the the Save As dialog is open, click OK.
Figure 48. All Specifications of AddressBook.dnx tab
AddressBook added to display

Query: Implementations of Contact

This query starts at a context element and follows immediate trace relationships in the reverse direction to discover elements one level of abstraction lower. Another way to phrase this query is, "Which implementations are immediately derived from this element?"

  1. In the "Contact UML class" drop-down menu, select Query > Traceability > Implementations.
  2. When the Save As dialog is open, click OK. (See Figure 49.)
Figure 49. Implementations of Contact.dns tab

Query: All Implementations of Change contact

This query starts at a context element and follows all trace relationships in the reverse direction to discover all elements in lower levels of abstraction. Another way to phrase this query is: "Which implementations are derived from this element?"

  1. In the "Change contact UML use case" drop-down menu, select Query > Traceability > All Implementations.(Figure 50).
  2. When the Save As dialog is open, click OK.
Figure 50. All Implementations of Change contact.dns tab

Lesson 5. Impact analysis queries

Impact analysis queries, instructions,and examples follow.

Query: Suppliers of AddressBook

This query starts at a context element and follows immediate dependencies in the forward direction to discover elements that are immediate suppliers of this element. Another way to phrase this query is:"On which elements is this element immediately dependent?" or "Which elements, if changed or removed, could immediately impact this element?"

  1. In the "AddressBook UML class" drop-down menu, select Query > Impact Analysis > Suppliers (Figure 51).
  2. When the Save As dialog opens, click OK.
Figure 51. Suppliers of AddressBook.dnx tab

Query: All Suppliers of AddressBook

This query starts at a context element and follows all dependencies in the forward direction to discover all elements that are suppliers of this element. Another way to phrase this query is: "On which elements is this element dependent?" or "Which elements, if changed or removed, could impact this element?"

  1. In the "AddressBook UML class" drop-down menu, select Query > Impact Analysis > All Suppliers.(Figure 52).
  2. When the Save As dialog opens, click OK.
Figure 52. All Suppliers of AddressBook.dnx tab
AddressBook added

Note:
The results of the All Specifications Traceability query are a subset of the results of the All Suppliers Impact Analysis query. This is because all trace relationships are dependencies. On the other hand, the results of the All Suppliers Impact Analysis query are a superset of the results of the All Specifications Traceability query, because not all dependencies are trace relationships.

Query: Clients of Contact

This query starts at a context element and follows immediate dependencies in the reverse direction to discover all elements that are immediate clients of this element. Another way to phrase this query is: "Which elements immediately depend on this element?" or "If this element is changed or removed, which elements could be immediately impacted?"

  1. In the "Contact UML class" drop-down menu, select Query > Impact Analysis > Clients (Figure 53).
  2. When the Save As dialog is open, click OK.
Figure 53. Clients of Contact.dns tab
Shows

Query: All Clients of Change contact

This query starts at a context element and follows all dependencies in the reverse direction to discover all elements that are clients of this element. Another way to phrase this query is: "Which elements depend on this element?" or "If this element is changed or removed, which elements could be impacted?"

  1. In the "Change contact UML use case" drop-down menu, select Query > Impact Analysis > All Clients (Figure 54).
  2. When the Save As dialog is open, click OK.
Figure 54. All Clients of Change contact.dnx tab
Shows ChangeContact selected

Note:
The results of the All Implementations Traceability query are a subset of the results of the All Clients Impact Analysis query. This is because all trace relationships are dependencies. On the other hand, the results of the All Clients Impact Analysis query are a superset of the results of the All Implementations Traceability query, because not all dependencies are trace relationships.

Summary of lessons and benefits

In Lessons 1 through 3, you learned how to create requirements in Rational RequisitePro, elaborate on the requirements in analysis and design UML models, and transform the design model into a Java project while maintaining traceability between artifacts and through the different levels of abstraction.

In Lesson 4, you learned about the different specification and implementation traceability queries, and Lesson 5 demonstrated and explained the different supplier and client impact analysis queries, comparing and contrasting them to the traceability queries.

With a traceable system of requirements, models, and a Java implementation, you can use the traceability queries to find out what requirements a context UML element exist to satisfy or what Java elements exist to implement a context UML element. You can also use the impact analysis queries to find out what elements require a context UML element or what elements are required by a context UML element.


Downloads

DescriptionNameSize
Sample projectAddressBookRequisiteProProject.zip164KB
Sample projectAddressBookUMLProject.zip10KB
Sample projectAddressBookJavaProject.zip3KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=302461
ArticleTitle=How to establish traceability by using IBM Rational RequisitePro and IBM Rational Systems Developer
publish-date=04292008