This tutorial introduces IBM® Rational® DOORS® Next Generation and describes how to use it to collaborate with a team as you capture, elaborate, and trace requirements across the development lifecycle. Rational DOORS Next Generation supports teams to realize the fundamental principle of requirements management across the lifecycle of a project. These areas of the product are explained:
collaboration, organization, granularity of information, attributes, reporting, tracking, and security.
This tutorial includes detailed instruction and step-by-step exercises. Following along with the exercises requires installation and setup of the exercise environment. You can run this exercise environment in these ways:
- Set up your environment for use with the tutorial.
- Enter the preconfigured environment provided by CloudOne, an IBM Business Partner (visit www.doorsng.com Note: This link takes you off the IBM developerWorks site.).
This document is written for Requirements Engineers, Requirements Analysts, Business Analysts.
Get started with Rational DOORS Next Generation
Requirements management (RM) consists of documenting requirements and their supporting information in an organized manner. In this way, requirements can be analyzed, interpreted, and referenced in context.
IBM® Rational® DOORS® Next Generation is a web-based RM tool for defining, managing, and tracing requirements across development projects.
1. Overview of the example in this tutorial
The example in this tutorial is of a fictional company, JK-Meters Corp, which wants to build an automated meter reader (AMR). The company develops a solution to read water meters and provide service in an electronically automated and cost-effective manner. The AMR is intended to help water providers lower the cost of operations by more accurately measuring water usage and quickly gathering data. The solution uses the existing infrastructure of meters, but might require enhancements to support a more flexible means of determining water consumption, including handheld devices, mobile/car mounted readers, or grid readers.
Figure 1. The company has several proposed ideas for improving the reader meter service.
To start developing requirements for this example, make a list of the information that is needed from the meter. The list can include these requirements:
- The AMR should meet various performance objectives in areas of reliability, data analysis, conservation, and accuracy of data.
- The AMR should be able to operate in the chosen market environments
- The AMR should comply with any necessary standards and regulations, specific to each country.
- The AMR should enable data to be collected by using various mechanisms, including wireless transfer to the central office and data collection through the use of hand-held devices.
The information for the AMR project might be stored in the following requirements documents, which are illustrated in Figure 2:
- Vision: This document describes the user or customer's view of the product to be developed. The vision is specified at the level of key stakeholder needs and features of the system.
- System: This detailed document definitively describes a system, for the purpose of developing or validating the system. This document supports the vision, and is an agreement between the stakeholders and the engineers of what to build.
- Software: This detailed document describes the software of the system under development, for the purpose of developing or validating the software.
- Hardware: This detailed document describes the hardware of the system under development, for the purpose of developing or validating the hardware.
- Hazards and Risks: This document describes the items that must be mitigated during project development.
Note: In Rational DOORS Next Generation, requirements documents are commonly referred to as modules, indicating the format of the artifact. Modules are explained in more detail later.
The requirements data might be related through these relationships (Figure 2):
- Satisfaction (Satisfied by/Satisfies): This relationship captures how the different levels of requirements are elaborated. For example: You expect every approved vision statement in the vision document to be satisfied by one or more stakeholder requirements. Consequently, every stakeholder requirement should show that it satisfies one or more vision statement. If this is not the case, you might end up with a solution that does not satisfy all of the user requirements or a solution where resources were spent for something the customer did not want and is not willing to pay for.
- Mitigation (Mitigated by/Mitigates): This relationship shows how requirements and risks are related. A requirement may exist because it mitigates a risk.
- Track (Tracked by/Tracks): This relationship shows how change requests and requirements are related.
- Validation (Validated by/Validates): This relationship shows how requirements were tested.
- Derivation (Derived from/ Derives): This relationship shows how requirements were delivered in the design.
Figure 2. Requirements documents can be related to each other and to other information in several ways.
Important: Keep such information in the project, and ensure that the team is aware of the information. Understanding why information is collected and how it is stored and analyzed is crucial to the project's success.
With this knowledge, you can find the information that you need, capture new requirements and their relationships, and answer key questions about the project.
2. Access Rational DOORS Next Generation
With Rational DOORS Next Generation, teams can concurrently access the Requirements Management (RM) application on a web browser. Team members need the URL to the application, and to access the relevant projects and team areas, they must log in.
Figure 3. In a browser, log in to the RM application on Jazz Team Server.
When you first log in, the All Projects page (Figure 4) lists the requirements management projects that you are a member of.
Figure 4. The All Projects page lists the projects that you belong to.
From the All Projects page, you can access dashboards, project properties, and the content of the project.
Note: At any point, you can expand the menu on the Home button to quickly return to the All Projects page for the RM application (Figure 5).
Figure 5. The Home button offers a convenient way to navigate among the different applications, dashboards, and projects.
3. Explore the requirements project
If you click Show Artifacts, the Artifacts page opens, which lists all of the artifacts in the project (Figure 6).
The projects are organized in folders in the left sidebar. Folders and other filters can restrict which artifacts are shown.
Figure 6. JTSAdmin is logged into the Automated Meter Reader (Water) requirements management project. You are looking at the Artifacts page.
Requirements and specifications
A good requirements management practice is for requirements to be clear, technically accurate, complete, and verifiable. Use atomic requirements to accurately control dependencies and acceptance. For example, instead of writing this requirement:
- The handheld device shall be capable of displaying diagnostic information, including suspected water leaks and shall record leakage data on the central office data store.
Consider writing these requirements:
- The handheld device shall be capable of displaying diagnostic information, including suspected water leaks.
- The handheld device shall record leakage data on the central office data store.
When requirements are atomic, the displaying of information and the recording of information are accepted and tested on their own.
Requirements must have supporting information, such as its status; has the requirement been approved? Writing atomic requirements also helps to keep the supporting information concise and clear.
Figure 7. Atomic requirements support good requirements management practices and make information easier to understand and analyze.
Basic concepts and terminology
In Rational DOORS Next Generation, a requirements project consists of requirement artifacts, which are often referred to as simply artifacts. An artifact is a general term for something that is part of the project. An artifact can be a specific requirement, or it can be supplemental information, such as a heading, a picture, a use-case diagram, or even something that you uploaded.
Artifacts have attributes that record and track data about an artifact, such as its acceptance status or verification method. You can modify some artifacts; others are controlled by the system. For example, attributes that are managed by the system include ID, Created By, and Modified On.
An artifact can have different attributes depending on its artifact type. For example, if an artifact is of the Information type, it might not make sense for that artifact to have a "Release date" attribute. However, an artifact of the Stakeholder Requirement type might need to store such information in an attribute.
Another best practice for requirements management states that requirements must be consistent and complete as a group in order to avoid ambiguities between requirements and ensure that no requirements are overlooked.
To analyze requirement artifacts as a group, you can organize them in many ways. Folders, collections, modules, tags, and attribute values are often used to organize artifacts.
Specification documents are typically captured in an artifact that is of the Module format. The artifacts in a module are individually managed, which means that you can individually edit them, link to them, track their history, and more.
A module is a special type of artifact format that contains other artifacts in a logical and hierarchical structure. A module looks like a rich-text document. In a module, artifact attributes can be displayed in columns; as a result, the module also looks like a spreadsheet.
Figure 8. A module contains other artifacts that are organized in a logical and hierarchical structure.
Module content can be organized in sections and hierarchically, and can be searched, filtered, and sorted. Figure 8 shows a module displaying only the contents attribute column of each attribute. Figure 9 shows a different set of columns including: ID, Contents, Accepted, Artifact Type, Priority 2, Requirement Type.
Figure 9. The artifacts inside a module can be organized hierarchically, edited, sorted, and filtered. Artifact attributes can be displayed in columns. Although not shown in the figure, views can be saved for the module and later used, allowing the perspective of the data to quickly change as needed. Multiple users can simultaneously edit a module.
Rational DOORS Next Generation supports a number of artifact types, which capture requirements in various formats:
- Text: Individual textual requirements, headings, information, embedded images, PDF files, or complete rich-text requirements specifications.
- Module: A hierarchically organized requirement specification that looks like a rich text document and acts like a spreadsheet. The contents of a module are individually managed within the module.
- Business process diagram: A diagram that describes business objectives, activities, and processes.
- Use-case diagram: A diagram that describes user interactions with the system.
- User interface sketch: A mock-up of a graphical user interface that supports the design of an application.
- Screen flow: A sequence of user-driven software processes that is shown in a series of graphical user interfaces.
- User interface part: A reusable set of user interface elements that you can use to populate sketches and storyboards.
- Storyboard: A frame-by-frame depiction of a user scenario that consists of sequentially numbered frames on a timeline.
- Collection: Multiple artifacts that are grouped for a specific purpose.
While you are creating an artifact, the format of the artifact is specified.
Figure 10. Rational DOORS Next Generation supports several editors.
Exercise 1. Optional: Review the basics
This exercise is optional because the same information is covered in this tutorial. Review two videos:
- Video: Rational DOORS Next Generation v4.0.x Terminology and Basic Concepts. This introductory presentation focuses on basic concepts and terminology that are helpful to know before you start using Rational DOORS Next Generation.
- Video: Navigating IBM Rational DOORS Next Generation. The video gives an overview of the product's user interface. It shows how to access a requirements project, find artifacts, explore artifact details, create views, and make basic edits to artifacts.
Exercise 2. Log in to the RM project
In this exercise, you access the Artifacts page of the Automated Meter Reader (Water) project in the RM application (Figure 11).
- To access the Requirements Management (RM) application, you use a URL that is specific to your installation, for example https://localhost:9443/rm/web, or https://jazz.net/sandbox02/setup/web. This step varies depending on how your environment is setup, but the goal is to log in to the RM application with the credentials that were assigned during the setup of the environment, and navigate to the All Projects page of the RM application.
- The All Project page lists all of the RM projects that you are a member of. In this exercise, you will use the Automated Meter Reader (Water) project. From the Automated Meter Reader (Water) project section, click Show Artifact. The Artifacts page of the project opens.
Figure 11. Log in and access the Artifacts page of the Automated Meter Reader (Water) project in the RM application.
Exercise 3. Locate an artifact by using the folder structure
Information about requirement artifacts is organized in folders. A folder is a type of filter for the information that is stored in an RM project.
- Go to the Artifacts page of the Automated Meter Reader (Water) project.
- In the left sidebar, in the Filter by folder section, click Automated Meter Reader (Water) > 01 Requirements.
- Determine how many artifacts are in the folder. Hint:
Look in the content section of the Artifacts page.
(Answer: The folder contains 4 artifacts.)
As you can see, the 01 Requirements folder contains subfolders that are not shown in the content section of the Artifacts page. Folders organize requirements information, but folders are not considered to be artifacts.
Exercise 4. Explore the properties of an artifact by a viewing a rich hover
Hover over the AMR Stakeholder Requirements Specification artifact (Figure 12).
- Question: What Artifact type is the specification?
(Answer: Stakeholder specification)
- Question: What is the artifact's format?
- Question: What is the description of the artifact?
(Answer: The artifact does not have a description)
- Question: When was this artifact last modified?
(Answer: That information is not shown in the rich hover, but you can access it, as you will see, from the properties of the artifact after it is open)
Figure 12. The rich hover reveals information about the artifact.
Exercise 5. Display artifact attributes in columns
The Artifacts page is customizable; you can change which information about the artifacts is shown in columns. In this exercise, you modify the Artifacts page to show only the ID, Name, and Description attributes (Figure 13).
Figure 13. The content section of the Artifacts page shows the ID, Name, and Description attributes of the artifacts in the "01 Requirements" folder.
- From the menu of the Configure page settings icon
(Figure 9) select Configure Columns
to Display. The Change Column Display Settings window opens (Figure 14).
Figure 14. You can determine which columns to show in the Change Column Display Settings window.
- In the Columns to show list, select Artifact Type and click Remove.
- Select and remove the Modified By and Modified On columns so that only ID and Name are in the Columns to show list.
- In the Select attributes or link types list, select Description. Click Add. Description is added to the Columns to show list.
- Click OK. On the Artifacts page, the artifact information is shown as you specified so that you can focus on the information that is relevant to you (Figure 13).
Concurrent and inline editing
With Rational DOORS Next Generation, you and your team members can concurrently access requirements data and review or modify it as needed.
You can edit requirements information in many ways. When you are viewing artifacts in a module or on the Artifacts, Collections, or Modules pages, you can directly edit the artifacts in their rows. While you edit, the artifact is locked. When you save, the artifact is unlocked (Figure 15). If you need to prevent other people from editing one or more artifacts, you can also manually lock them.
Figure 15. Artifacts are automatically locked while they are being edited.
Exercise 6. Directly edit requirements information
If attributes are editable and are shown in columns, you can directly edit them in a module or on the Artifacts, Collections, or Modules pages.
- On the Artifacts page, locate the AMR Stakeholder Requirements Specification, and double-click its description. The artifact is locked and is placed in edit mode.
- Type a description for the artifact; for example,
This module specifies the requirements the user expects.
- Click outside of the artifact to save the changes. Notice how the lock is released when it is no longer needed.
Change the perspective of your data by using views
Different people need to see different information. Consider these examples:
- Managers are interested in scheduling and cost information.
- Engineers are interested in technical design information.
You can create different views at the project level and inside your modules. The views satisfy the needs of the different stakeholders by providing a succinct and consistent view of the needed information.
Figure 16. Use views to quickly switch the perspective of your data.
Exercise 7. Change the perspective of the data by using views
You can create a personal or shared view, which you can use to quickly change perspectives of the data.
Changing the perspective of the data in one click is an important capability. Views provide a consistent perspective of the data and improve efficiency and communication.
Earlier in this tutorial, you changed the perspective of your data at the project level by filtering to show only the artifacts that were in a specific folder and then modifying which attributes were shown on the Artifacts page. If that is a perspective of the data that you want to repeatedly use, you can save it as a personal or shared view.
7.1) Create a view
- Make sure that you are on the Artifacts page. In the left sidebar,
expand the Views section and click the Save
view icon (Figure 17).
Figure 17. Click the Save View icon to save or update a view.
- In the New View window, provide information about the view (Figure 18):
- Type a name for the view; for example,
01 Req. modules and descriptions.
- Specify that the view is personal, and provide a description
for the view; for example,
A list of the modules in the "01 Requirements" folder and their description.
- This view is a personal view, created for your own purpose and will not be shared by other members of your team. Click OK to save the view.
Figure 18. The New View window contains information about a new personal view.
- Type a name for the view; for example,
After you save the view, it is listed in the left sidebar, in the Views section. Its color indicates that it is a personal view, but you can also see this information by hovering over the view. The background highlight indicates that the view is applied (Figure 19).
7.2) Clear an applied view
In the Views section, the available views are listed. Clear a view by clicking the eraser icon (Figure 19).
Figure 19. The available views are listed. To clear a view, click the eraser icon.
As you can see, the columns displayed and the artifacts listed in the content section of the artifacts page also changed. This is because you are no longer viewing only the artifacts from the 01 Requirements folder and you are displaying the default set of attributes in the columns instead of the ones you picked earlier
7.3) Apply a view
Reapply the view by clicking its name. The modules from the 01 Requirements folder and the columns that you specified as part of the view are once again shown on the Artifacts page.
4. Create a specification document as a module
In Rational DOORS Next Generation, a specification document is often created as an artifact of the Module format. When it comes to specification documents, a module provides many benefits over other formats:
- Granularity of information: You can review, annotate, accept, and relate each requirement artifact on its own. Because information is granular, multiple users can edit a specification document simultaneously. Also, you can analyze each requirement artifact on its own or as part of a group to answer questions such as: “Has this requirement been accepted?”, “Was this requirement tested?”, "What is the impact to my project if I change this requirement?”.
- Hierarchical organization of related information:
Modules make it easier to collect and organize requirements
- Each module organizes the contained data in sections (Figure 9), so information is grouped logically and easy to find. To hide all of the artifacts in a section, collapse the section. You can reorganize a module by dragging the heading to another location. All of its hierarchical children will also move. If a template is used, then you know you are collecting the needed information, and organizing it consistently.
- By using multiple modules, you can organize data for a particular purpose; for example, stakeholder requirements or system requirements. Relationships can be captured across modules.
- Focus on needed data:
- Collapse sections of your document that are of no immediate interest
- Display the artifact attributes that you want to see in columns
- Filter data by tags, attributes, and links
- Quickly switch perspectives of data: Create personal or shared views to use in your day to day work, or during meetings. With views you can consistently satisfy the needs of the audience by providing them the needed perspective of the requirements data (Figure 16).
As shown in Figure 20, the layout of a module looks like the Artifacts page. Directly below the project banner are breadcrumb links, which you can use to return to the page that you opened the artifact from. Notice an artifact title bar, which displays the artifact's ID and Name attributes and a few artifact-specific icons.
The right sidebar contains artifact-specific information. As you likely remember, on the Artifacts page, the right sidebar contained project-specific information.
Within the module, the right sidebar has two tabs. The Module tab contains information about the module artifact. The Selected Artifact tab, contains information about the artifact selected from the content section of the module.
The module content is shown in the center of the page. In the module, artifacts are hierarchically organized in sections that are indicated by headings. Notice the headings, such as "1 Introduction," and the subheadings, such as "1.1 Purpose of the document." Sections 1.1 and 1.2 are hierarchical children of section 1; therefore, section 1 is a hierarchical parent of section 1.1. Sections 1.1 and 1.2 are at the same level.
Figure 20. In this figure, a module artifact was opened. The module layout is like the layout of the Artifact page.
Exercise 8. Explore the contents of a module
8.1) Open a module
Locate the AMR Stakeholder Requirements Specification artifact and open it by clicking its ID or name. This artifact is of the Module format.
8.2) Browse the module contents
- Scroll through the module and notice that it looks like a document, with headings and subheadings, rich text, images, and even use-case diagrams.
- Hover over the ID of a heading and the ID of a requirement and notice the difference between them. Modules organize artifacts of different types. As you hover over the heading and requirement IDs, you can see that these are different types of artifacts. Each type collects its own set of attributes as needed for the project.
- Collapse the 1 Introduction section by clicking its heading number. Notice that all of the information that is hierarchically below section 1 is now hidden. Also notice the arrow next to section 1, which indicates that the section is collapsed (Figure 21).
Figure 21. Sections within a module can be collapsed or expanded.
8.3) Search for information in the module
In the upper-right corner of the module's content section, click the Find/Goto icon , and search the module for this phrase: meter reader.
8.4) Look up a glossary term
Consistent terminology is key to creating and maintaining a clear requirements document. In this example, the term meter reader is overloaded, used as Meter Reader which is a role, Automated Meter Reader which is the complete system, and can be confused for the meter display widow. Identifying which term is implied by linking the glossary term can help alleviate confusion and ambiguity.
- Look up the term meter reader.
- Double-click an artifact that contains the term meter reader so that it opens in edit mode. Notice the editing options that are shown.
- In the artifact, highlight the term meter reader.
- In the editing options, click the Insert tab.
- Click the Lookup Term icon . In the window that opens, you can see that a meter reader is "An employee who uses the handheld device or some other means to read usage data."
Figure 22. You can associate a glossary term with the text in an artifact.
- Associate the meter reader text in the artifact with the glossary term by clicking the Meter Reader link in the window.
- Save the artifact by clicking somewhere in the module besides the artifact.
- Hover over the Meter Reader link in the artifact. Now
that the term is associated with the glossary term, its details are
shown (Figure 23).
Figure 23. A rich hover reveals the glossary details.
Module editing involves several activities:
- Editing the module attributes
- Editing the artifact contained in the module
- Modifying the module structure.
Changing a module's structure can include these activities:
- Reorganizing the artifacts that are in the module
- Removing an artifact from the module, and if needed, deleting the artifact from the project
- Insert a new artifact to the module. (This action will create a new artifact and include it in the module).
- Insert an existing artifact to the module.
Note: An artifact in Rational DOORS Next Generation can be a base artifact, which is an artifact that you can access from the Artifacts page. It can also be used and reused in one or more modules.
Note: When you insert a new or existing artifact into a module, be mindful of the hierarchy.
- When you insert an artifact before or after the selected artifact, the new artifact is placed on the same hierarchy level as the currently selected artifact. The artifacts will be considered hierarchical siblings because they are at the same hierarchical level in the module.
- To place a new artifact in a hierarchy level below the selected artifact, insert the artifact below (as a child). The new artifact will be a hierarchical child of the selected artifact.
While you edit a module, an audit trail of the changes is saved for future reference.
Earlier in this tutorial, you modified the contents of a module by editing one of the artifacts contained in the module. Even earlier still, from the Artifacts page, you edited a module's attributes. Figure 20 shows how you can edit the module attributes from within a module.
Exercise 9. Edit the attributes of a module
- In the right sidebar, on the Module tab, notice the Description attribute value that you added to the specification document. You can see that a few attribute values were updated automatically, including Modified On and Modified By.
- In the upper-right corner, click Edit to enter edit mode and modify the attributes of the module. Notice that a few attributes, such as ID, are not editable.
- Change the name of the artifact from
AMR Stakeholder Requirements Specificationto
AMR Stakeholder Requirements Specification (option 1).
- Click Done to save your changes and exit edit mode.
Exercise 10. Review the artifact’s history
Changes to the artifact are tracked in the artifact's history. You can view the history at any time.
- To view the history of the module, click the Open History icon .
- Click the Audit History tab. On that tab, notice the
changes that you made today.
Figure 24. You can view the changes that were made to an artifact on its Audit History tab.
- Return to AMR Stakeholder Requirements Specification (option 1) by clicking the Open Current Version icon.
Exercise 11. Increase the content area of the module
When you are working in a module, it is often a good idea to increase your working area (figure 25).
- Minimize the banner by clicking on the minimize banner icon on the upper-right corner of the banner.
- Collapse both of the sidebars.
- Expand the left sidebar
- Resize the left sidebar to make it smaller or larger.
Figure 25. When you are working in a module, there are several ways to increase your working area.
Exercise 12. Display, in columns, the attributes of artifacts that are in a module
In the content section of the module, display artifact attributes i columns, just as you did earlier on the Artifacts page.
- From the menu of the Configure page section icon , select Configure Columns to Display . The Change Column Display Settings window opens. Change the settings so that these additional columns are displayed: Status, Used in Modules, and Comments.
- In the Status column, notice that some artifacts are approved, some
are rejected, others are obsolete, and so forth.
Note: Click a column heading to sort the artifacts by the value contained in the column. Click once for ascending, descending or remove the sort.
- In the Used in Modules column, look for artifact rows that contain this symbol. The symbol indicates that the artifact is used in multiple modules. If you edit an artifact in one module, the changes are reflected in the other instances of that artifact. However, the comments, links, and tags for that artifact are specific to the artifact in that particular module.
- Look at the Comments column. If the team made any comments about any artifact, they are shown here. Currently there are no comments on any of the artifacts in the module, but if you select an artifact, this column will provide a convenient way to create or respond to comments (Figure 26).
Figure 26. The artifacts’ attributes are displayed in columns. The attributes displayed are: ID, Contents, Status, Used in Modules, and Comments attributes.
Exercise 13. Create a shared view that is used in all modules of the project
For consistent collaboration across modules, you can save a view that is used in all modules. This view can be private or shared with the team. In this exercise, you save the current perspective of the data and share it with the team and across modules. By sharing a view across all modules, you make the view available in all modules. When you switch to the view, you and other team members get a consistent view of the data.
- In the left sidebar, in the Views section, click Save.
- In the New View window (Figure 27),
provide the following information:
- For the name, type
- For the view type, click Shared.
- Select Use in all modules.
Figure 27. The New View window shows the settings to create a shared view that is used in all modules.
- For the name, type
- Click OK to create the view.
Exercise 14. Filter the module content based on attributes
Filter the module to show only artifacts that are rejected.
- In the left sidebar, click Filter by Attribute. Some attributes are displayed here but click More attributes to see a complete list of attributes.
- From the list, select Status and then select Rejected (Figure 28).
- Click Apply. As you can see, the requirement artifacts were rejected because they are ambiguous (Figure 29).
- Clear the filter.
Figure 28. You can filter to display the requirement artifacts that are rejected.
Figure 29. The module is shown with the filter applied. Only the artifacts that meet the filter criteria are shown. Of the 92 artifacts in the module, 3 meet the filter criteria.
Note: To clear the filter you just applied, click the Remove filter icon next to the filter expression.
Exercise 15. Simultaneously edit the attributes of multiple artifacts
Often, artifacts' attributes have the same values. You can simultaneously edit attribute values for multiple artifacts.
In this exercise, the last five requirements of section 3.2 do not have a value for the Status attribute. To simultaneously set the value for those 5 attributes, complete these steps:
- Select the check boxes for all five of the artifacts (Figure 30).
- From the row edit menu of one of the artifacts, click Edit the attributes for 5 Artifacts (Figure 30).
- In the Edit Attributes window, select Status and set the value to In Process. Click OK.
Figure 30. You can simultaneously edit the attributes of multiple artifacts.
Exercise 16. Add a comment about an artifact
Online discussions can record communication between people, whether the discussions are directly with your customers or internal among different stakeholders and domain experts in your organization. Teams can use comments to collaborate, centrally capturing feedback in a format that is visible to all rather than lost in emails or chat windows.
- Within the content of the module, find this requirement:
Any portable equipment shall be yellow.This requirement is in the process of being reviewed.
- In the Comments column (Figure 26), create a comment for the artifact by hovering your cursor in the column and clicking Create Comment.
- In the "Create comment for Artifact" window, provide the following
- For the subject, type
- For the comment, type
Why are we not using our company color?
- In the Directed to field, direct the comment to another member of the project. If you are using the sandbox, no other members are in your project.
- For the priority, select Medium.
- For the subject, type
- Hover over the comment indicator in the comment column to review the comment.
- Comments are specific to the artifact, in the context of a module. This means that this comment will not appear in other modules where the artifact is used, or if the artifact is accessed from the Artifact page.
- An artifact accessed from the artifact page, and not from within a module, is also known as a base artifact.
- Comments on a base artifact can be toggled off and on from within the module.
Exercise 17. Create a requirement artifact
In this module, Section 2.5 seems to be missing a requirement. Insert a new artifact to that section of the module.
- Navigate to section 2.5 Operational Environments, which is a heading.
- Create a stakeholder requirement:
- Click 2.5 Operational Environments, and from its menu, click Insert New Artifact > Below (as a child). The newly inserted artifact will be a hierarchical child of 2.5 Operational Environments. Because the selected artifact is of type Heading, the new artifact will also be of type Heading (Figure 31).
- Change the new artifact's type to be Stakeholder Requirement.
- For the content of the requirement, type
The human reader shall be able to locate the handheld unit.
- Save the requirement artifact.
Figure 31. You can create an artifact that is of a specific type.
Exercise 18. Create a section in the module
A new stakeholder is identified: Marketing and Research. In section 2, Stakeholder Requirements, add a section:
- Click 2. General Description, and from its menu,
click Insert New Artifact > Below (as a child).
The new artifact will be of the same type as the one that you
selected, which in this case is a Heading. The new artifact is a
hierarchical child of Section 2. For the content of the artifact, type
Marketing and Research.
- Look at the numbering. The subsequent sections are renumbered as needed.
Figure 32. When you create a section, subsequent sections are renumbered.
Exercise 19. Rearrange the artifacts in the module
If you select a hierarchical parent from within the module and move it to a new location, all of its children are also moved.
Click section 2.7 Regulatory and move it to be after section 2.3 Product Perspective (Figure 33). The artifact that you moved becomes the new section 2.4, and all subsequent numbering is updated.
Figure 33. When you move an artifact in a module, the hierarchical structure changes.
While you reorganize the structure of the module, the module is automatically locked. The content is still editable, but not the structure. When you are finished editing, the structure is unlocked.
If you plan to extensively restructure a module, consider manually locking it. When you are finished, be sure to unlock the module.
Note: Keyboard shortcuts while working in a module:
- Shift+Alt+Right Arrow - Moves an artifact to a higher level in the hierarchy.
- Shift+Alt+Left Arrow - Moves an artifact to a lower level in the hierarchy.
- Ctrl+K, Ctrl+Alt+K, or Ctrl+Shift+K - Creates an artifact and adds it after, below, or before the current row.
- Ctrl+E, Ctrl+Alt+E, or Ctrl+Shift+E - Adds an existing artifact after, below, or before the current row.
- Ctrl+Enter, Ctrl+Alt+Enter, or Ctrl+Shift+Enter - Creates a similar artifact after, below, or before the current row.
- Ctrl+H - Changes the current row to or from a heading.
For more information refer to the information center: Keyboard shortcuts for Rational DOORS Next Generation
5. Trace artifact activity by using link relationships
To demonstrate conformance and compliance, it is essential to be able to capture and analyze traceability relationships across the lifecycle. Traceability is also helpful when you need to analyze the impact of requirements changes (Figure 2).
In Rational DOORS Next Generation, you can link related information within the product and across the lifecycle. If you installed the product as part of the Rational solution for CLM, you can link from requirement artifacts to test cases and work items in other CLM applications. In addition, you can link to any other application that supports OSLC-based linking. This linking ability is especially useful when you need to analyze information and make decisions.
Links provide traceability. You can verify that what you are building satisfies your user requirements. For example, you can link a user requirement to the design features that fulfill that requirement. You can also link the design features to the verification tests for the feature, such as a test case in IBM® Rational® Quality Manager.
You can follow links in both directions. For example, if a test fails, you can discover which requirements are affected by tracing the links from the test to the requirements or to the design features. You can also trace from the design features to the requirements.
Links are helpful for managing change. You can quickly trace how a change to one piece of data impacts the rest of your system.
Traceability can be seen in columns. Traceability can also be seen graphically.
When you view traceability, you can determine how information is related, and identify requirements that might have been dropped or requirements that have crept in during development with no links to higher level requirements (scope creep) . For example, one indication that a requirement is unsatisfied is that it does not have links.
You can find requirements that do not have links by using filters. In addition, you can configure views so that you can trace across multiple requirement documents as well as across use cases, models and designs, tests, and work items that are managed in other tools.
Exercise 20. View and analyze traceability
You are currently in the AMR Stakeholder Requirements Specification (option 1) module. In Figure 2, the link schema identified suggests that each Stakeholder requirement must satisfy one or more vision statements in a vision document. In addition, a stakeholder requirement must be satisfied by a system requirement.
In the next exercises, you view traceability in two ways: in columns and graphically.
20.1 View traceability in columns
- In the left sidebar of the module, in the View section, locate the Upstream and Downstream Traceability view. Hovering over this view, you see that it is a public view that is shared across all modules. If you click the view, the content of the module changes to include the Satisfies and Satisfied By columns, which contain traceability information.
- Scroll through the document and notice that no stakeholder
requirements are linked to vision statements (look in the Satisfies
column as per the link schema captured in Figure 2). Notice that many of the stakeholder requirements
are linked to systems requirements. Why do you suppose the links to
the vision document are missing?
(Answer: The Vision document does not exist in the project.)
- Locate this stakeholder requirement:
The meter interface unit shall be compatible with the existing meter models in use for the area covered by this project.
- Find the following information about the requirement:
- What is the status of the requirement?
(Answer: Rejected. Hint: Hover over the ID of the artifact)
- This stakeholder requirement is linked to a system
requirement. What does this link indicate?
(Answer: This requirement links to a system requirement. The link indicates that even though this requirement is rejected, some work has been done on it. That work might have been done before the requirement was rejected. You might need to determine whether the work should continue.)
- Is the linked system requirement linked to anything else? If
so, view the links to determine what they indicate. For
example, links might indicate work that is unnecessarily
continuing on a rejected requirement. Links might also
indicate that even though the requirement is rejected, work on
it must continue because it is required for a different part
of the program. Which case is it?
(Answer: When you hover over the linked system requirement, you can see that it has only one link: the link to the stakeholder requirement that you are viewing.)
- What is the status of the requirement?
20.2 View traceability in the links explorer
- Locate this requirement artifact:
"The meter interface shall detect water leaks and record leak status with the account data."
- Click the artifact, and from its menu, click Other Actions
> Open Links Explorer (Figure
Figure 34. You can open the links explorer from an artifact’s menu.
The links explorer shows how a stakeholder requirement traces to the system requirement.
- Expand the system requirement. You can see how the links to
lower-level requirements cascade in the hierarchy. You can also
graphically explore cross-lifecycle links, such as links to
enhancement requests, work items, test cases, and design.
Figure 35. The links explorer shows how requirements are linked to each other.
- Close the links explorer.
Exercise 21. Navigate traceability
You can navigate traceability in many ways: by using rich hovers, traceability columns, and the links explorer.
- The "Upstream and Downstream Traceability" view is applied. You are
looking at requirement artifact:
The meter interface shall detect water leaks and record leak status with the account data.The view Upstream and Downstream Traceability has been applied. In the Satisfied By column of the selected requirement, click the hyperlink to open the system requirements module and locate the linked requirement.
- Apply the Upstream and Downstream Traceability view. After you apply
that view, you might need to locate and click the artifact again. The
view should be familiar; you can complete a similar type of analysis
as you did before.
- Look for requirement artifacts that are not linked to stakeholder requirements. Such artifacts might indicate scope creep, where development efforts are being spent on functionality that was not agreed upon (Figure 36).
- Look for system requirements that are not linked downstream. Such artifacts might indicate dropped requirements (Figure 36).
Figure 36. Scope creep and dropped requirements can be identified in traceability views.
Exercise 22. Create traceability by dragging artifacts
The easiest way to create traceability is by dragging artifacts to create links.
In this exercise, the system requirement,
Meter usage data and leak diagnostic data shall be retrievable on demand from any meter interface via the network or a handheld,
is not linked to this stakeholder requirement:
The meter interface shall detect water leaks and record leak status with the account data.
You will fix that gap by creating a link to indicate that the system requirement satisfies the stakeholder requirement.
- Resize the system requirement window so that it fills the right half of the screen. Close all sidebars.
- Open the stakeholder requirements in a new window and resize it so
that it fills the left half of the screen (Figure 37). Close all sidebars.
Figure 37. Drag artifacts to create links. If you drag an artifact to a link column, a link of that type is created. If you drag the artifact to another artifact, you can choose the type of link to create.
- (Figure 37) Use the handle and drag the
system requirement named
Meter usage data and leak diagnostic data shall be retrievable on demand from any meter interface via the network or a handheldover the create link indicator of the stakeholder requirement named
"The meter interface shall detect water leaks and record leak status with the account data."
Figure 38. In the Create Link window, you can indicate the type of link to create.
- If the Satisfied By column is not displayed, you are prompted to
display it. Click Yes. Then, the link is created (Figure 39).
Figure 39. The link is created and is displayed in columns.
- Create another satisfaction link by using the display column as a
- Locate system requirement
The handheld device shall display the following data for leakage: timestamp, meter ID
- Locate stakeholder requirement:
The handheld device shall be capable of displaying diagnostic information, including suspected water leaks.
- The Satisfied by column is still in view from the last link.
- Drag the system requirement to the Satisfied By column on the stakeholder requirement. The appropriate relationship is created.
- Locate system requirement
6. Reach consensus and monitor project progress by using dashboards
Dashboards are a means of displaying various types of data from different sources on one page. They are useful for tracking status, progress, and activity at a glance. They can include information from all the CLM products. You can customize dashboards to track any data, and you can follow links on dashboards to access more details.
Figure 40. Dashboard with Requirements, Development, and Test information.
Several types of dashboards exist:
- Personal dashboards are useful for displaying information that is of interest to an individual team member.
- Project dashboards are useful for tracking the status or progress of an entire project at a high level.
- Team dashboards are useful for tracking information or status that is specific to a team's needs.
- Mini dashboards are small dashboards that show a limited number of high-priority widgets. You can view a mini dashboard in any context. For example, you can view the mini dashboard while you work on modules. The same mini dashboard is available from other areas of the project, even from other CLM capabilities in Jazz Team Server, such as work items.
Exercise 23. Customize your project dashboard
Depending on how you set up your exercise environment, the widgets that you add during this exercise might already be on your dashboard. The purpose of this exercise is to learn how to work with widgets and customize your dashboard.
23.1) Navigate to the project dashboard
In the upper-left corner, click Project Dashboard. The General tab already displays a few widgets.
23.2) Add a new tab to the dashboard
- Add a tab to the dashboard by clicking the Add New
Tab icon (Figure 41).
Figure 41. Add a tab to the dashboard by clicking the Add New Tab icon.
- By default, the new tab is named New Tab. Click the
name of the tab, and rename it to Tutorial (Figure 42).
Figure 42. Add new widgets on the Tutorial tab of the dashboard.
23.3) Add a widget to the dashboard
- To add widgets to your dashboard, click the Add
Widget icon (Figure 42). A
pane expands, showing several widgets, a list of categories, and other
options (Figure 43. Widgets are organized by
catalog and by category. The pane is organized by catalogs so
that you can add widgets from all of the applications that are
associated with this project and from Jazz Team Server.
Figure 43. Widgets are organized by catalog and by category.
- From the Select Catalog list, select Requirements Management.
- Click the Projects/Team category. Locate the Team Members widget and add it by clicking Add Widget. The Team Members widget shows a list of contributors that belong to a team or a project area, as well as their roles.
- Click the Requirements category and add these widgets:
- Comments: This widget lists the recent comments in all of the projects that you are a member of. It also shows the artifacts that the comments are related to. Click a link to access the corresponding artifact, or click someone's name to send them an email.
- Recent changes: This widget shows the recently modified artifacts in all of the projects that you belong to. Click a link to access the corresponding artifact.
- Close the pane.
23.4) Organize the dashboard
- Organize the dashboard according to your needs by collapsing widgets or moving them.
- Save the dashboard.
You modified a dashboard. If the project had reviews, you could display them on the dashboards. Plan to explore this functionality further after you complete this tutorial.
Figure 44. The project dashboard can be customized to fit the team’s needs.
Note: In the same way that you modified the Project dashboard, you can modify your personal dashboard and mini dashboard. Video: Using a URL to add an extension to the mini dashboard
Support for the development process across the lifecycle
Rational DOORS Next Generation is built on Jazz Team Server by using Jazz technology. The product is part of the Rational solution for Collaborative Lifecycle Management (CLM) [http://www.ibm.com/developerworks/downloads/r/clm/] and the Rational solution for systems and software engineering (SSE).
In addition to Rational DOORS Next Generation, the Rational solution for CLM includes Rational Team Concert and Rational Quality Manager. Because those products are built on the Jazz technology platform [https://jazz.net/story/about/about-jazz-platform.jsp], they share a common user interface, administration pages, and many services.
The Rational solution for SSE includes Rational Quality Manager, Rational Team Concert, Rational DOORS Next Generation, and Design Management, which teams use to enhance modeling and lifecycle traceability.
Related help topics
Traceability is used to trace a project element to related project elements, especially those related to requirements. Traceability helps determine that a requirement is satisfied from inception through implementation and testing. Suspect traceability indicates the potential impact of changes to linked artifacts.
Linking to development, design, test, and requirement
You can use the Rational solution for Collaborative Lifecycle Management (CLM) product integration and other OSLC lifecycle integrations to create traceability links to new and existing artifacts in other products
Creating artifacts to support requirements
In a requirements project, you can create module artifacts, rich-text artifacts and graphical artifacts such as use cases, storyboards, and business process diagrams.
Getting your requirements right from the very beginning can save you time and money. You can create a review of selected artifacts. You can designate other team members as participants in the review. Participants receive requests and, depending on their designated role in the review, they can approve, disapprove, review, or abstain from reviewing each artifact.
Creating requirements project templates
You can create a project template from an existing project and select the elements of the project to include in the template. You can include or exclude: artifacts, artifact templates, artifact types and attributes, links between artifacts, link types, folder structure, tags, and shared saved filters. You cannot modify templates for requirements projects after they are created.
Baselines for requirements projects
In a requirements project, a baseline captures the entire project at a specific moment in time. For example, you might create a project baseline after an artifact review. A baseline includes all artifacts, folder trees, and public tags.
Extending the Requirements Management (RM) application
You can enhance the Requirements Management (RM) application by authoring extensions for it. The extensions can enhance productivity and are useful for analysis.
Extending Rational DOORS Next Generation by using OSLC
Open Services for Lifecycle Collaboration (OSLC) is a community that is standardizing the way that lifecycle tools work together. IBM® Rational® DOORS® Next Generation supports the OSLC data sharing specification as a provider for the Requirements Management (RM) domain and as a consumer of other domains in the Rational solution for Collaborative Lifecycle Management (CLM). Data sharing is also supported by other RM tools that support OSLC integration, such as IBM Rational DOORS.
Reporting in the Requirements Management (RM) application
You can run and view reports that are based on a data warehouse and create document-style reports that are about requirement and other lifecycle data.