Get started with Rational Requirements Composer: Guidance for Rational RequisitePro users
Rational RequisitePro users take note: the future is here. Rational Requirements Composer (RRC) is the next-generation platform for defining, managing, and tracing requirements across your development projects. If you have been thinking about transitioning from Rational RequisitePro to Rational Requirements Composer, now might be the time to do it. RRC v4.0 includes many powerful new capabilities and supports RequisitePro project migration. Read on to learn more about:
- The next-generation requirements definition and management capabilities of Rational Requirements Composer
- How these capabilities can affect how you perform some common requirements related tasks
- How to successfully migrate RequisitePro projects to RRC
Requirements management for the development lifecycle
Requirements definition and management
Rational Requirements Composer combines requirements definition and management capabilities in a single Web-based application. Its versatile upload and import capabilities allow you to gather initial requirements information from informal sources such as meeting notes, or automatically import structured requirements from external documents. You can explicate and refine imported requirements or create new ones in rich-text documents. Graphical editors enable you to visually elaborate requirements in business process diagrams, use case diagrams, user sketches, or storyboards. Customized suspicion profiles allow you to track changes to specific sets of link types, artifact types, and attributes so that you can manage change in a targeted way.
Transparency and in-context collaboration
Rational Requirements Composer is powered by the Jazz technology platform. The Jazz platform provides a foundation of capabilities that make it easy for distributed teams to have visibility into project assets and activities and to openly collaborate among themselves and with stakeholders. Customizable project and personal dashboards provide real-time information on individual tasks as well as insight into overall project status, coverage, risks, and more. Personal and shared tags allow you to capture specific views of requirements information and share those views with team members. Using commenting, team members and stakeholders can collaborate in-context to define and refine requirements. And, a robust reviewing capability allows you to manage and retain a record of requirements reviews.
Part of the Rational solution for Collaborative Lifecycle Management
Rational Requirements Composer is part of the Rational solution for Collaborative Lifecycle Management (CLM), an integrated set of software lifecycle delivery tools. The applications that comprise the CLM solution share a common underlying technology that enables seamless integrations. And, they share a common look and feel from a user perspective, which makes it easy to work across the applications.
Working within the CLM context, you can extend traceability to project assets across the software delivery lifecycle, such as to implementation plans in Rational Team Concert and to validation plans in Rational Quality Manager. The traceability relationships are based on OSLC linking, which means that you always get the latest information about a linked resource. Rich hover windows enable you to view information about linked artifacts in context. And, the new Links Explorer makes it easy to visualize and manage traceability relationships.
As part of CLM, your requirements teams can take advantage of other common CLM capabilities. Requirements projects can track to common delivery plans. You can manage requirements project tasks and log defects and enhancement requests using the work item management capability. And, common reporting makes it possible to generate document or dashboard-based graphical reports based on data from across the project lifecycle.
Working in Rational Requirements Composer
While Rational RequisitePro and Rational Requirements Composer have common requirements management functionality, the way that you approach and complete some requirements definition and management tasks differs between the two tools. This section discusses how you might approach common tasks in RRC as compared to in RequisitePro.
Click the links below each sub-section to watch a video demonstration of the described tasks performed in RRC.
For a detailed mapping of application functionality, see the help topic Capability comparison: Rational RequisitePro and Rational Requirements Composer.
Capture and edit requirements
In RequisitePro, you can create and edit requirements directly in the application database or import requirements from CSV files, but a common usage model is to create and edit requirements in Microsoft Word documents.
By contrast, in RRC, you do not create or manage requirements in Microsoft Word documents. In RRC, requirements and requirements-related information is stored in the form of individual artifacts that can be grouped and categorized in different ways. An artifact can be an individual requirement, such as a particular Product Feature requirement. Or, an artifact can be a requirements-related object, such as a business process diagram, an image, storyboard, or a document.
Figure 1: Use graphical artifacts to support requirements elaboration.
To capture requirements information in RRC, you can do any of the following:
- Upload external files (image, video, pdf, text files, and more) as wrapped resources that can be used to support requirements work.
- Import a document (Word, Open Office, Open Document, rich text) to create a rich-text artifact.
- Import and extract individual requirements from a CSV file or from a document file (Word, Open Office, Open Document, rich text).
- Create new requirements artifacts directly in the application using rich-text or graphical editors; the rich-text editor provides an experience that is similar to working in Word.
Demo: Representing requirements in IBM Rational Requirments Composer
Demo: Creating and editing requirements in IBM Rational Requirements Composer
Organize requirements
RRC includes a number of capabilities that offer a great deal of flexibility in how you organize requirements. As in RequisitePro, the project is the top level organizing structure in RRC. Each project contains a number of folders. Like packages in RequisitePro, folders provide a visual way to organize artifacts. Folders also provide a mechanism for controlling write access to certain artifacts within a project. Folder structure can be part of a project template and created automatically when a project is created. And, folders can be added or deleted as needed.
Figure 2: Organize requirements in folders
Two other great organizing features in RRC are tags and collections. Tags are a flexible mechanism you can use to categorize artifacts in different ways. For example, you can use tags to group all the requirements that are part of a particular sprint, or associated with a specific release, or that support a particular component. Shared tags are available to all users in the project. Personal tags are only available to the user who creates them. You can apply tag filters to create queries that display all artifacts that have the same tag.
A collection is a set artifacts that you assemble for a specific purpose. You can use collections to group and organize artifacts in different ways: to group related artifacts to work with, to group artifacts ready for review, to capture an approved version of artifacts, to identify artifacts related to a common goal, or to export artifacts to a CSV file. A single artifact can be included in a number of different collections.
Demo: Organizing requirements in IBM Rational Requirements Composer
Analyze requirements
In RRC, you can use views to analyze requirements. You can create specific views of requirements information by applying filters and by modifying the artifact list on the Artifacts page. Filters are like query criteria in RequisitePro. You can filter requirements by folder, artifact type, attributes, links, tags, or any combination thereof. The artifact list can be modified by adding or removing columns, or by grouping artifacts to display by category. The resulting views are similar to what you would see in a RequisitePro Matrix view. A view can be saved and stored as a shared view within the project or saved for personal use. Views do not live within folders or packages as they do in RequisitePro. They are accessed from the project Views section of the left sidebar on the Artifacts page.
Figure 3: Create views to analyze requirements
Demo: Analyzing requirements in IBM Rational Requirements Composer
Collaborate on requirements
In RequisitePro, the two main vehicles for collaboration are email notifications and discussion groups. RRC opens new avenues for collaboration by providing access to real-time information about project assets and activities, and by facilitating in-context communication.
In RRC, team members can get real-time information about requirements artifacts through dashboard widgets. A project dashboard provides the latest information on recent changes, pending reviews, comments, and implementation plans. Project dashboards can be customized by the project administrator. Individual team members can use private dashboards to create personalized views of project and cross-project data.
Commenting enables team members and stakeholders to communicate and collaborate on requirements in-context. Comments can be made on the entire artifact or on specific elements within the artifact. They can be directed to the whole team or to specific individuals. Team members can reply to comments directly and resolve them with the issues are addressed. Comments are highly visible within a project via the Comments widget of the Project dashboard, or in the sidebar of the artifact.
RRC also includes capabilities that allow you to create and manage requirements reviews. You can create and request reviews of a selection of artifacts or of a collection. Informal reviews can be used at any time during the requirements definition process: they contain live versions of the artifacts. Formal reviews contain a specific version of the artifact captured when the review was created: they can can be used to capture stakeholder approvals at key project checkpoints.
Figure 4: Engage team members and stakeholders in requirements reviews
Demo: Collaborating on requirements in IBM Rational Requirements Composer
Manage change
Establishing traceability relationships between requirements makes it easier to manage change during the course of a project. In RequisitePro, you can create trace links between individual requirements. Suspect links alert you when a requirement change may have an impact on other requirements.
RRC provides a more flexible, customizable, and extensible traceability capability than RequisitePro. In RRC, each project contains a set of predefined link types that indicate specific 2-way relationships between the linked requirements, such as satisfies/satisfied by, illustrates/illustrated by, extracted/extracted from, and more. RRC links are based on OSLC data sharing, which means that the information about a linked resource is always the latest. And, OSLC data sharing between CLM applications means that traceability can extend across the project lifecycle, enabling you to manage requirements from inception, through design, implementation, and validation. You can view existing links in rich hover, in the sidebar of the Artifact Editor, by adding link type columns to the artifacts list on the Artifacts page, or by opening the Links Explorer. The Links Explorer displays linked artifacts in a graphical diagram.
Figure 5: The Links Explorer displays a graphical view of all links, including lifecycle traceability links.
RRC v4.0 features a flexible suspicion capability based on suspicion profiles. A suspicion profile identifies a set of link types, artifact types, and attributes to watch for changes. When artifacts that match the profile criteria are changed, the linked artifacts are marked with a suspicion indicator to alert team members of possible impact of the change. Project administrors can create multiple suspicion profiles based on role or areas of interest. Each team member selects a suspicion profile and receives targeted suspicion information based on that profile.
Figure 6: Suspicion notifications based on suspicion profiles help to manage change
Demo: Traceability relationships in IBM Rational Requirements Composer
Report on requirements
In RequisitePro, you may have produced reports using a tool such as SoDA. RRC has built-in report capabilties that make it easy to generate high quality document-based reports. Rational Reporting for Document Generation, the CLM document-based reporting capability, uses a runtime version of Rational Publishing Engine to produce reports based on a set of pre-defined templates, which include:
- User Interface Specification (by sketches, screenflow diagrams, or storyboards)
- Traceability Report
- Use Case Specification
- Audit History
- Requirements Specification
Requirements Composer also includes Rational Reporting for Development Intellgience (RDDi), which allows you to create dashboard-based graphical reports,. RDDi reports can communicate status, monitor progress, diagnose problems, identify corrective actions. RDDi is an optional install with CLM, and comes with a set of predefined reports that can be customized using RRDi authoring tool.
Figure 7: Examples of RDDi reports
Demo: Reporting on requirements in IBM Rational Requirements Composer
Migrating RequisitePro projects to Rational Requirements Composer
Overview
Rational Requirements Composer includes a capability that migrates RequisitePro projects to Rational Requirements Composer (versions 3.0.1.1 and later). The migration uses a RequisitePro project baseline as its input, and creates a new project in RRC. Because the migration uses the baseline file, the migration process is entirely offline from the RequisitePro application: there is no project downtime or repository contention on the RequisitePro side.
The process produces a migration summary that allows you to verfiy that items migrated successfully: it notes the number of requirements, documents, trace relationships, views, discussions, and more. A log file is produced that provides information about unexpected errors in the process. Detailed listings of migrated items are also produced and can be used to verify the migration at a finer level of detail. These files serve as a history of the migration that you can use to troubleshoot any issues that might surface later on.
Constraints
Project migration is considered a one-time event. There is no support for re-running the migration to update an existing project with new data later on. There is also no support for importing the same project multiple times on the same server, even if you use different baselines. The migration always creates a new RRC project. Updating an existing project or merging two projects into one project are not supported. Consequently, the migration should be for a full RequisitePro project baseline even though RequisitePro supports partial baselines.
The migration tool does not migrate data for RequisitePro integrations other than for Rational Quality Manager. If an integration uses attributes to store integration data, the attribute data is migrated, but the integration will not be active from RRC or from the integrated application.
Some RequisitePro items are not migrated, including:
- Trace Matrix views: RRC does not have an equivalent way to display traceability information.
- Package permissions: RRC uses a different mechanism to enable folder permissions.
- Project templates: They can be migrated by creating a project from the template in RequisitePro, migrating a baseline of that project into RRC, and then creating a project template from the migrated RRC project.
- Document templates: They can be migrated outside of the project migration process by importing the Word template into RRC and then creating an artifact template from the imported artifact.
- RPX scripts: RRC does not have an equivalent scripting capability.
- Suspect state of a trace relationship: Suspect state is not a permanent state of any requirements artifact. Clear suspect state before the migration.
- Display settings for RequisitePro views, for example: column/row size, page size, retain hierarchy.
- Denial of read access to documents: RRC does not support read-access denial.
More detailed information can be found in the help topic Support for data types in migrated projects.
In a few cases, the data is migrated, but the paradigm or terminology in RRC is slightly different:
- Traces in RequisitePro migrate to links in RRC.
- Views in RRC are not stored in folders as they are in RequistePro packages. They are shown together, sorted alphabetically, in the Views section of the left sidebar.
- Discussions in RequisitePro migrate to comments in RRC.
- Document and requirement types in RequisitePro migrate to artifact types in RRC.
- Documents in RequisitePro migrate to artifacts in RRC, not to Word documents. They are assigned the artifact type corresponding to their document type in RequistePro.
- Packages in RequistePro migrate to folders in RRC.
- Attributes in RRC can be shared across artifact types. If multiple RequisitePro attributes are identical, a single attribute is created and shared across multiple artifact types.
- User groups in RequisitePro migrate to roles in RRC. Group permissions are then associated with the role. This includes document and requirement type permissions associated with the group. Other details of user group and role assignment can be found in the help topic Support for user groups in migrated projects.
Migration preparation
Be sure to complete these tasks in your RequisitePro project before you create the baseline to use for the project migration.
Data integrity
Make sure that the data in your RequisitePro project is up-to-date and that there are no outstanding edits in process. Also, be aware of the migration constraints cited and take action to reduce or eliminate any impact.
- Bring all offline documents back online to preserve any changes. The baseline picks up the state of the document when it was taken offline.
- Resolve and clear suspect links. The suspect state of trace relationships is not be preserved in the migration.
- Remove the Retain Hierarchy setting from views to determine its impact on the query results: this setting is not migrated to RRC.
- Additional preparation activities are described in the help topic Migrating a Rational RequisitePro project.
Project clean up
Use this opportunity clean up the project to avoid migrating unessential data.
- Remove any obsolete requirements and documents from the project.
- Remove any obsolete packages from the project. Make sure that all items within the package and sub-packages are moved or deleted first.
- Remove any obsolete requirement and document types. Make sure that all requirements and documents of these types are deleted first.
- Remove any obsolete attributes from each requirement type definition.
- Remove any obsolete views.
- Review document and requirement type names. Since RRC migrates these both to artifact types, determine if there is any duplication or similarities in the RequisitePro naming that will cause confusion in RRC. If so, adjust the naming to eliminate confusion. One approach is to prefix the name with Document – or Requirement – .
- Other clean up suggestions are described in the help topic Migrating a Rational RequisitePro project.
Leverage new capabilities in RRC
In some cases, RRC has more flexibility than RequisitePro, which can be beneficial. You may want to make some minor adjustments to the RequisitePro project prior to migration to leverage these capabilities.
- Ensure naming consistency for attributes and attribute values across requirement types where you want to reuse a single attribute definition in RRC. Consitency will make artifact list display and filtering easier in RRC. In RRC the artifact list displays artifacts of different types, unlike the Attribute Matrix view in RequisitePro, which only displays requirements of a single type. If attributes are shared across types, the RRC artifact list will display them in a single column rather than showing separate columns for each type.
- In RRC, the shared views are displayed outside of the context of folders. To reduce or eliminate confusion, review the view names in RequisitePro and make sure that the names make it easy to find the migrated views in RRC. One approach is to prefix the view name with the folder name so that the view name sorting in RRC displays all views for a folder together.
Prepare for validation
Collect metrics on the RequisitePro project so that you can compare them to the migration summary information.
- Run queries (views) to get counts of:
- Requirements by type
- Documents by type
- Get manual counts of:
- Requirement types
- Document types
- Packages
- Users
- User groups
Migration process
Follow the instructions in the help topic, Migrating a Rational RequisitePro project and the migration wiki page on Jazz.net.
Try out the migration in a test environment before migrating within the production environment. This system verification test report provides a good explanation of the migration process using the Learning Project as an example.
Back up the RRC repository. This precaution mitigates any data corruption that might occur during the upgrade process. In the unlikely event that data is corrupted, you can restore the from the the backup file. For more information on backing up and restoring, refer to help topic Backing up and restoring the Jazz Team Server.
The migration process can consume considerable system resources on the target RRC server, so choose a migration time that will minimize the impact to end users.
- On the RequisitePro server, use the RequisitePro Baseline Manager to create a new baseline archive of the project you want to migrate.
- Copy the resulting baseline.zip archive file to a share directory.
- In a browser, navigate to your RRC server @ https://<server>:9443/rm/web
- Using the RRC Import RequisitePro project wizard, select the .zip file from the file share and import it into RRC. Select a user mapping option that matches with what was used in RequisitePro
Post-migration tasks
Verify that the migration was successful. Some of the verification will be directly from the migration summary, but some will come from inspection of the migrated project.
On the migrated RRC project, run queries (filters) to get counts of artifacts by artifact type.
Perform the following verifications:
- Verify that the counts in the migration summary match the query counts that you pulled from the RequisitePro project prior to migration.
- Verify that the manual counts from RequisitePro match the corresponding counts from RRC.
- Inspect the migrated folder structure and compare it to the package structure in RequistePro.
- Inspect the migrated type system and compare it to the requirement types, document types, and attributes in RequisitePro.
- Verify that the RequisitePro history is stored in the RRC artifact’s first revision in artifact history.
- Verify that the RequisitePro project history is stored in a special artifact in the root level folder in RRC.
- Verify that users and their roles migrated properly.
Assign licenses to the migrated users.
Save the migration files to facilitate troubleshooting of any future problems.
Troubleshooting tips
- If your migration fails, or you want to re-run it, you can do so by “archiving” the project on the jts/admin > Projects page. Click the archive icon to the far right of the project name. Re-run the import and provide a new name for the project when prompted in the wizard. Note: This should not be a standard practice, but should be used only in the case of failure. The migration described in this report should also not be tested on a production server.
- If after migration you are missing content in a document, make sure that all offline documents were brought online before the baseline for the migration was taken. The migration cannot detect offline changes otherwise.
- If after migration you are missing artifacts, make sure that the RequisitePro project baseline was created properly and that the artifacts in question are present in the baseline.
For more information
- Rational Requirements Composer on Jazz.net
- CLM v4.0 Information Center
- IBM Rational Education Channel on YouTube
- Rational RequisitePro to RRC Migration SVT Report
- Rational RequisitePro to RRC migration wiki page on Jazz.net
- Migrating RequisitePro projects to Rational Requirements Composer Help topics
About the authors
Brenda Myers is an instructional designer and content developer currently acting as the lead Curriculum Architect for Rational Requirement Composer and CLM. She can be reached at myersb@us.ibm.com
Bill Betz works for IBM Rational as a System Test Architect. He has worked in the requirements space for over 14 years, and is currently working on test architecture for the Rational Requirements Composer product and the Collaborative Lifecycle Management solution. For questions or comments he can be reached at: wdbetzr@us.ibm.com
Bala Kolla is an advisory software engineer at IBM, in Research Triangle Park, North Carolina, in the U.S. He works on the Rational Requirements Composer Server team. He can be contacted at brkolla@us.ibm.com
Mario Maldari works for IBM Rational as a System Test Engineer. He has worked in the requirements space for over 10 years, and is currently working on testing of the Rational Requirements Composer product. For questions or comments he can be reached at Email: mamaldar@us.ibm.com Phone: 303-924-7490
Devang Parikh is a senior architect at IBM. He provides technical direction to requirements server team . He can be contacted at dparikh@us.ibm.com
Yan (Tina) Zhuo is the Rational Requirements Management Project Managment Council Lead. She can be contacted at Tina.Y.Zhuo@us.ibm.com
Copyright © 2012 IBM Corporation
Yes