Introduction

Requirements management is a systematic approach to finding, documenting, and managing requirements. Requirements define the desired features and function of an application. More important, documenting requirements constitutes an agreement between the stakeholders and development team to ensure that the solution adequately meets the needs of the targeted users.

For more information on why requirements management is necessary, see the developerWorks article "Requirements management: Your insurance policy on large-scale projects."

Project requirements

To complete the steps in this article, you will need a copy of RequisitePro Version 2003. (Download a trial version of RequisitePro Version 2003.) You will also need Microsoft® Word® 2000, XP (Word 2002), or Word 2003 to get the most benefit from the system.

Learning to manage requirements

Managing requirements is about managing change. We live in a dynamic world where change is pervasive: customers change their minds, competitors come up with comparable solutions before we deliver ours, the business environment changes. Change itself isn't bad, but uncontrolled change -- where the impact is not measured before it happens -- can be detrimental to the success of a project. The ultimate goal is to deliver a timely solution that solves your customers' real problems. Without requirements management, more than two-thirds of projects lack requested user needs, are late, or are over budget. The key to a successful project is to manage change by clearly defining the requirements and to adapt them as needed over the solution development cycle.

For details on requirements management in an iterative team development environment, refer to the developerWorks article, "Supporting Iterative Development Through Requirements Management."

Managing use cases

Use cases are used to represent requirements. They are user friendly and represent a user's view of the system and its behaviors. Because a use-case model is defined from a business analyst's view, it provides a level of abstraction that's a useful communication tool for project stakeholders.

To better understand how use cases relate to requirements, read the developerWorks article, "Ending Requirements Chaos."

Back to top

Managing requirements with Rational RequisitePro

IBM Rational RequisitePro is a powerful, easy-to-use, integrated product for requirements and use-case management that promotes better communication, enhances teamwork, and reduces project risk. RequisitePro provides a database for storing and tracking requirements. You can add requirements to the database using either of the following methods:

• A dedicated project management-like interface
• A documented requirements specification within Microsoft Word

The latter method lets you continue using your familiar requirement-specification documents and templates -- and even generate the requirements from within Word -- while helping you to gain the benefits of a managed database of requirements. This article focuses on populating the database using traditional requirements and use-case documentation created with Microsoft Word.

Back to top

Creating a project

First, you must create a project. RequisitePro has four project templates: blank, traditional, use case, and composite. (You can also create a project template, which we do later in this article.) We'll use the use-case template for this scenario because we intend to represent our system requirements with a use-case approach.

Create the project as follows:

1. Start RequisitePro application Programs > Rational Software > Rational RequsitePro.
2. You are prompted to create a new project or open an existing one. To create a new project:
   a. Select the New tab.
   b. Choose the Use-Case Template project type and select OK, as shown in Figure 1.
   Figure 1. Create project
   
   c. Enter the project name External Claims Assessor, as shown in Figure 2, and select OK.
   Figure 2. New project properties
   
   d. When prompted to create the project directory, select Yes, as shown in Figure 3.
   Figure 3. Create new directory
   
   e. Select Close when the project is created successfully. If prompted for a user name, use the administrative user or enter analyst.

The project directory is created under the C:\Rational\RequisitePro\Projects directory by default. As shown in Figure 4, the use-case project template creates a requirements management plan document, as well as seven packages with additional documents and views. Each view is a specific representation of data in the requirements database.

Each project has associated document types, requirement types, and requirement attributes. You can view the defined project values by opening the project properties dialog using File > Project Administration > Properties, as shown in Figure 5.

We have a prepared Vision document (which replaces the blank template) generated with the project in the Features and Vision folder. (Click the code icon at the top to download the Vision document.)

1. First, delete the blank Vision document by selecting the document and Delete from the context menu, as shown in Figure 6.
   Figure 6. Delete document
   
   
2. Import the completed Vision document by selecting the File > Import menu option. As shown in Figure 7, specify the type of file as Microsoft Word Document, specify the document to import, then select Next.
   Figure 7. Import document
   
   
3. Specify the import content as Document only and select Next. As you become familiar with RequisitePro, you can learn more advanced tasks, such as how to parse and define requirements from within the document using a single import function.
   Figure 8. Document only import option
   
   
4. When prompted with the document properties dialog, provide the required values:

• Name: Vision
• Filename: Vision
• Document Type: Vision

The Filename attribute uses the My Documents directory by default and can locate documents with the Name value and the default Word extension of .doc.

Now you have a source document from which to harvest requirements to store in the project database. When the document opens in Word, a new RequisitePro toolbar and menu category displays, as shown in Figure 9.

You must always use the RequisitePro toolbar and menu for typical file commands, such as Save and Close to synchronize your changes with the RequisitePro database. Do not use the standard Word menu options.

Back to top

Defining a requirement

As shown in Figure 10, there are six basic types of requirements associated with a use-case project:

• Stakeholder Request
• Feature
• Use Case
• Supplementary
• Glossary Item
• None (which is a placeholder for values that do not qualify as requirements as defined by the default types)

Typically, you first start with stakeholder requests, which are the general needs of those who have a stake in the finished product. Next, product features are defined based upon these requests. Finally, the product features are broken down into system use cases and supplementary requirements that can be further analyzed and detailed as low-level requirements for the system components. Since development is an iterative process, requirements definition does not end in the initial project-definition phase. Requirements are defined and refined throughout the process as supporting documentation for the system and component-level architectures evolve. This evolutionary process occurs in parallel with change-induced refinement discussed earlier.

To define a documented requirement in RequisitePro:

1. As shown in Figure 11, select the requirement text in the Vision document (we chose the text for the first feature outlined in the Product Features section). Choose the New Requirement toolbar icon () on the RequisitePro > Requirements > New menu option.
   Figure 11. Creating a requirement
   
   
2. As seen in Figure 12, at the Requirement Properties dialog specify the following values:

• Type: Feature
• Name: Claims Process Monitoring and Management

The requirement shows as pending until you save the document. Remember to use the RequisitePro > Document > Save menu option or the Save Requirements Document RequisitePro toolbar icon (). Now your requirement no longer appears as pending in the Vision document. It should also be visible in the project database. In the project management client, you can now see the new feature listed in the Features and Vision folder. If you open the All Features view, as shown in Figure 13, you'll also see the requirement associated with its attributes.

As shown in Figure 14, the default attributes include Priority, Type, Status, Difficulty, Stability, Risk, Planned Iteration, Actual Iteration, Origin, Contact Name, Enhancement Request, Defect, and Obsolete. These attributes are defined using the Attributes tab of the project properties editor (File > Project Administration > Properties).

Requirement attributes can be added, modified, deleted, or reordered using this editor. If you add a new attribute or edit an existing one, an attribute editor appears, as shown in Figure 15.

To customize the attributes that are displayed for a particular view, open the view, right-click on any attribute column, and select the option in the context menu, as shown in Figure 16.

You can also sort, remove, or query by attribute using this menu. To summarize, RequisitePro can be customized at the project, requirement, and requirement attribute levels, allowing it to serve any organizational process and its artifacts.

Back to top

Defining a use case

A use case is a well-known Unified Modeling Language (UML) modeling artifact that represents a sequence of actions a system performs in response to a user or other system interaction to yield an observable and valued result. In other words, a use case is a representation of a system requirement, and RequisitePro treats use cases as a special type of requirement. The use-case project supports a use-case document type that can be used to define the details for each use case.

To define a use case:

1. Open the Use Cases folder and create a use-case document by selecting New > Document from the context menu, as shown in Figure 17.
   Figure 17. New use-case document
   
   
2. Specify the document name Retrieve Claim Status, and select the document type Use Case Specification.
   Figure 18. Use-case document properties
   
   
3. The document is created using the use-case template and is launched inside Microsoft Word. Edit the file by adding the project name, use-case name, use-case details, and so on. The file template has valuable comments on what needs to be defined, but we have also provided the sample file Retrieve Claim Status.doc. This sample document can be imported similarly to the Vision document as shown in the project definition section. (Click the code icon at the top to download the sample Retrieve Claim Status document.)
4. Once the use-case document is defined, you can populate the requirements database with the use-case details by selecting the use-case text and creating a requirement of type case.

   a. Select the use-case name and create a use-case requirement. Enter the name Retrieve Claim Status on the General tab, as shown in Figure 19.

   
   Figure 19. Use-case requirement properties - general
   
   

   b. As shown in Figure 20, select Attributes and the Name property. Select OK to save the requirement.

   
   Figure 20. Use-case requirement properties - attributes
   
   

   c. Repeat for the other use-case details as needed. You can create Brief Description, Basic Flow, and Alternate Flow use-case attributes provided in the sample document. Additional attribute types include Special Requirement, Pre-Condition, Post Condition, and Extension Point. Advanced users can extend by defining custom attributes (as shown in Figures 14 and 15).

5. Once the use-case requirements are created, they are visible in the Use Cases database view. Select the Use Case Traced to Features database and open it, as shown in Figure 21.
   Figure 21. Use Case Traced to Features database view
   
   
6. The use-case details can be further organized into parent-child relationships:

   a. Select the Brief Description use-case requirement and select Change Parent, as shown in Figure 22.

   
   Figure 22. Creating use-case parent-child relationships
   
   

   b. Select <Choose Parent> from the drop-down list in the Select New Parent dialog. Select UC1 Retrieve Claim Status requirement as the parent, and OK to close the Parent Requirement Browser dialog.

   c. Select OK to close the Select New Parent dialog.

   d. The relationship change is pending and isn't visible in the database view until the requirements document is saved. Save the requirements document by selecting the Save Requirements Document icon () on the RequisitePro toolbar in Word. The new relationship displays as shown in Figure 23.

   
   Figure 23. Database view of use-case parent-child relationships
   
   
7. Repeat these steps for the remaining use-case details as needed. Again, how you populate the database and assign attributes and relationships is flexible and can be customized to suit the needs of any project.

The use-case parent-child relationships display in a Word document as shown in Figure 25.

Back to top

Tracing requirements

Once the project requirements are created, relationships can be defined between different requirement types, providing a means to trace requirements through the project life cycle. Because change is inevitable, these traceability relationships serve as reminders to verify that all changes are disseminated through all the relevant artifacts.

To create a requirements trace relationship:

1. Open the relevant database view. To create a trace between features and use cases, open the Use Cases Traced to Features view in the Use Cases folder.
2. As shown in Figure 26, right-click in the box that maps to the use case and related feature details. Select Trace To in the context menu to establish the trace from the use case to the feature.
   Figure 26. Create trace relationship
   
   
3. The trace is represented as a blue arrow, as shown in Figure 27.
   Figure 27. The trace relationship of use case to feature
   
   
4. Additional trace relationships can be set up between other levels, such as features to stakeholder requests, supplementary requirements traced to features, and requirements to XDE model artifacts. When an element of the requirements chain changes, all the trace relationships are marked as suspect, as shown in Figure 28.
   Figure 28. Suspect trace relationship
   
   
5. After you verify the changes are complete, you can remove the suspect flag by selecting Clear Suspect in the context menu, as shown in Figure 29.

Back to top

Customizing a project template

RequisitePro comes with several project templates, but you may want to customize one for your team. You can add custom requirement types, requirement attributes, custom folders, and database views. You can also delete or add document types included with RequisitePro in one of the project templates.

To create a custom project template:

1. Open the RequisitePro application, but do not open any projects. Open the Create Project window (File > New > Project, or select the New tab when prompted to open an existing project), and select the Make New Template icon.
   Figure 30. Create new project template
   
   
2. Select Next, as shown in Figure 31, and follow the wizard instructions.
   Figure 31. Create new project template wizard
   
   
3. Enter the template name Extended Use Case, and choose a RequisitePro project on which to base the template (External Claims Assessor.rqs). If you select Include Project Data, you need to copy the specified project data structure as part of the new template. Otherwise, the template is empty and you can add elements to it from scratch. Leave it unselected for this exercise. You can optionally provide a documentation file (in .rtf format) with a text description for the new project template type.
   Figure 32. New project template information
   
   
4. A summary screen appears with the template characteristics. Select Next and Finish to create the template.
5. Select Close when the template is completed. A dialog appears stating that the template was successfully created. The template now appears in the template list, as shown in Figure 33.
   Figure 33. Create new project
   
   
6. Create a new project called Test Project using the new template named Extended Use Case. The project is empty (with no default elements).
   Figure 34. Create new package
   
   
7. Add a package named Use Cases by selecting the project root Test Project and choosing New > Package from the context menu.
   Figure 35. New package properties
   
   
8. If you want to add your own document type, you must create the relevant Microsoft Word document template (.dot file) and a definition file before adding a new document type. The definition file contains the outline (or document type) name, the outline description, and the corresponding .dot file.
9. To create a new document outline type, create a new Microsoft Word template (.dot file).

   Note: Open Word outside of RequisitePro! Create a blank document or open an existing document that will serve as your template. Save it as a document template type (File > Save As, and select the document type Document Template (.dot) in Word.

10. Create a text file containing three lines: outline name, outline description, and outline document template file (.dot). Save the file with the same name as the template with a .def extension (use_case_model.def).
11. Copy the new .def file to the RequisitePro outlines directory.
12. A sample document template (use_case_model.dot and corresponding definition file, use_case_model.def) is provided. (Click the code icon at the top to download the sample document template.) Copy them to the RequisitePro outlines directory, C:\Program Files\Rational\RequisitePro\outlines.
13. By default, all the existing document types are available for each project, as shown in Figure 36. However, you may also want to add a new document type to the system so it can be associated with your project template. To do this, open the project properties window (File > Properties, or right-click project and select Properties from the context menu).
    Figure 36. Document type project properties
    
    
14. Select Document Types tab and Add.
15. Enter the document type name Use Case Model, the extension UCM, and the outline name, as shown in Figure 37. The document type and extension are user-defined values, and they should recommend the new document type. The outline name is a list of available document templates that come with RequisitePro.
    Figure 37. Create new document type
    
    
16. The new document type now appears in the list, as shown in Figure 38. Select OK to confirm.
    Figure 38. New document type
    
    
17. Now create a new document under the Use Cases package of the Use Case Model type. Select the Use Cases package and New > Document from the context menu, as shown in Figure 39.
    Figure 39. Create new Use Case Model document
    
    
18. Enter the new document name Use Case Model, filename Use Case Model, document type Use Case Model, and select OK, as in Figure 40.
    Figure 40. Create new Use Case Model document
    
    
19. The new document displays in the project, as shown in Figure 41.

RequisitePro supports customization at the project, document, requirement, and requirement attribute levels. You can also add custom database views and document templates. RequisitePro is a powerful and flexible tool for managing project requirements and their traceability throughout the project life cycle.

For more details on using RequisitePro to manage requirements, refer to the developerWorks tutorial "Manage your requirements and more with RequisitePro."

Back to top

Summary

This series about model-driven development focuses on taking an end-to-end development perspective for the business scenario involving a merger of two insurance companies to create an external claims assessor system. Throughout this series, you'll find out about integration issues, the exchanges between roles, and the flow of development artifacts between tools. You'll also learn about end-to-end traceability and its current level of support in our proposed tools story.

In this article, you learned how IBM Rational RequisitePro can help you manage requirements and that managing change is the key issue faced by development projects. If valid requirements are defined and the appropriate traceability relationships are created, any size project is more likely to succeed in satisfying the customer's expectations. RequisitePro is an easy-to-use and highly customizable tool for managing project requirements.

Upcoming articles focus on:

• Rational XDE as a central tool for modeling the business and design assets and for possible asset code generation (You will see how each of the analyst, architect, and developer roles use the Rational XDE tool. You will also find out how to link RequisitePro requirements to the XDE model artifacts.)
• WebSphere Business Integration Modeler and business process modeling for Business Process Execution Language (BPEL) generation and its support by WebSphere Process Choreographer
• WebSphere Studio Application Developer Integrated Edition to add the implementation detail into the business process and editor support for the application-code assets (Development and deployment are the focal points in this discussion.)
• Bowstreet Portlet Factory, a plug-in to WebSphere Studio Application Developer, as an example of adding a portlet face to the business process

Back to top

Download

Information about download methods

Resources

• Tune into IBM Distinguished Engineer Alan Brown's blog that explores model-driven development.
  
  
• "Requirements management: Your insurance policy on large-scale projects" (developerWorks, June 2003) explains that starting requirements management early, especially when dealing with large-scale, long-term projects, is a critical factor to project success.
  
  
• "Supporting Iterative Development Through Requirements Management" (developerWorks, June 2004) explains how requirements management can help team members work more effectively together to support iterative development.
  
  
• "Ending Requirements Chaos" (developerWorks, February 2004) elaborates on the cost and other consequences of requirements chaos and how this problem might be avoided.
  
  
• "Manage your requirements and more with RequisitePro" (developerWorks, June 2004) explains how to turn the requirements you receive into a project within RequisitePro, which enables you to track the requirements information and use information to produce project plans and requirements documents.
  
  
• "Writing good requirements is a lot like writing good code" (developerWorks, June 2004) proves that developers can effectively serve as requirements engineers.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Lori Small is a member of the IBM SMB Emerging Technologies group, where she is focusing on development and operational tools used in the midmarket of SMB. She worked for IBM Software Group On Demand Solution Center for two and a half years as a solution architect of reference implementations showcasing IBM and its partner products within realistic industry scenarios. She worked in event management (IBM and Tivoli) for more than four years. Prior to joining IBM, Lori worked in the telecom industry. You can reach Lori at lsmall@us.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Managing requirements with Rational RequisitePro
• Creating a project
• Defining a requirement
• Defining a use case
• Tracing requirements
• Customizing a project template
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational RequisitePro
• Demo: Creating requirements with Rational RequisitePro
• Webcast: Modernization approaches to reduce the total cost for multi-platform enterprise applications
• Briefing: Jazz and Rational Team Concert
• Buy: Rational RequisitePro

My developerWorks community