In Part 1, about navigation, we explored the various ways that an artifact can be located and opened in an editor. Now we turn your attention to what you can do with an artifact after it has been opened.
In Rational Requirements Composer, the features that you use to comment on artifacts or elements within them and to link to artifacts created by other members of your team are universal. The editor for every kind of artifact — even those artifacts not native to Rational Requirements Composer (images, Microsoft® Word® documents, and so forth) — include the same controls in the header and sidebar to view and manage the artifact's comments, links, and requirements. The sections that follow describe how to make the best use of these features.
Tips for adding comments
Comments sidebar view
The Comments sidebar view shows all of the comments for a particular artifact. Comments can be created from either of these areas:
- The editor area of an artifact, by using the Add Comment toolbar button (left control in Figure 1) or the drop-down menu for an element.
- The Comment menu (right button in Figure 1) in the Comments sidebar view. The Comment menu is context-sensitive, based on what is selected in the editor area of the artifact.
Figure 1. Creating a comment
Options for creating a new comment for the active element ("Mastercard" label in the previous screen capture) and for replying to the selected comment are in the Comment menu. You can display the Comment menu either by using the drop-down tool item on the sidebar toolbar or by using a right mouse click within the sidebar.
Before writing a comment that is specific to an element in the artifact (for example, a label in the user interface sketch or a paragraph in a document), click that element to select it. When your teammates click the comment later, that element will be selected for them.
The Comments sidebar also contains an option for creating a comment for the artifact (as opposed to commenting on an element within the artifact). Artifact-level comments are created by using the Create a New Comment for the Artifact action. To create comments for non-Rational Requirements Composer resources, use artifact-level comments.
Rich text comments
The Add Comment window (Figure 2) supports a spelling checker that is enabled by default, as well as rich text formatting and link creation.
Figure 2. The Add Comment window
Where appropriate, augment your comments with rich text and links to make navigation easier for people who read the comment. Take advantage of the spell-checking feature, too.
You can navigate to links within comments from the Comments sidebar. The comment shown in Figure 3 has two links.
Figure 3. A comment with links
As artifacts are defined, reviewed, and revised, the number of comments about the artifact will grow. You can use filtering to limit which comments are displayed in the sidebar. For example, you might be interested only in comments within a certain time period, or you could be interested only in comments directed to you. Use the Filter toolbar button in the Comments sidebar to filter comments.
The Comments sidebar sections will indicate when comments are filtered. In the screen capture in Figure 4, three comments meet the specified criteria and two comments are filtered out, as indicated by the "(3 of 5)" label.
Figure 4. Filtering indicated in the Comments sidebar section
Use the filtering controls in the Comments sidebar to view only those comments that are important to you, such as those addressed to you or created within the last week, and so forth.
When filtering comments, the comment and all replies will be considered, and the originating comment for the reply will always be displayed. In Figure 5, Comment 1 is shown because we were filtering by "Janet Thompson," and Janet replied to the original comment.
Figure 5. Replies to an unfiltered comment
The Highlight All action takes filtering into account. In Figure 6, only those elements that have comments that show in the Comments sidebar are highlighted. Elements with comments filtered out are not highlighted.
Figure 6. Highlighted commented elements
Sorting and grouping comments
Comments can be sorted and grouped within the Comments Sidebar. For example, you can use the Group by Artifact Element option to view comments as they relate to the particular elements in a diagram.
Figure 7. Comments grouped by element
You can also sort and group by Author and by Date.
- When sorting and grouping by Author, the author of the top-level comment will be used as the basis of the operation.
- When sorting and grouping by Date, the top-level comments and all of its replies will be considered; therefore, the date of the last activity for the comment (including its replies) will be reflected.
In the Figure 8, the comments are sorted by Date Last Modified (most recent first). "Last Modified" is the key point here. Comment 4 was made on December 9, 2008, so the comment itself is less recent than that of Comment 10, which was made on January 6, 2009. However, the comment made earlier (4) appears before the later one (10) because the earlier comment has the latest reply. Therefore, Comment 4 ends up before Comment 10 in the display.
Figure 8. Comments and replies sorted by date
Group or sort comments by Date Last Modified to call to attention to comment threads that are "active" (comments or replies that have been made recently).
Sending e-mail from a comment
Each comment includes the name of the user who wrote the comment and the name of the user that the comment is directed to (if specified). Left-click the user name to send e-mail to that particular user.
Figure 9. Clicking on User Name to send e-mail
Resolving multiple comments
The Comments sidebar supports multiple selections. To select multiple comments, use the Ctrl key while selecting a comment. The Resolve Comment action in the context menu is available when one or more comments are selected, so multiple comments can be resolved in one operation.
To resolve all comments for an element, select the element within the artifact editor area. This action will select the element's associated comments in the sidebar. In the screenshot below, three comments are associated to the Validate Credit Card task. These comments are selected in the sidebar when the element is selected. The Resolve Comment action can then be executed to resolve all of the element's comments.
Figure 10. Selecting multiple comments
Use Ctrl to select multiple comments and resolve them all at once. To resolve all comments for an element, select that element and resolve the comments that are highlighted as a result.
Tips for adding links
Links sidebar view
The Links sidebar view shows all the links to and from a particular artifact. Within the view, links are displayed in the following format:
Target Artifact (from Source Element)
where Target Artifact is the artifact that you are linking to (destination) and Source Element is the element that you are linking from (origin).
Links can be created from the editor area of an artifact by using the element's context menu or by using the Link to other artifacts toolbar button () for an element that is in a diagram-based artifact.
Links can also be created from the Links sidebar view (Figure 11). The Links menu on the Links sidebar is context-sensitive based on what is selected in the editor area of artifact.
Figure 11. Create a link for an element or the artifact
The Links sidebar also contains an option for creating a link for the artifact (a link where the artifact is the source of the link, not an element within the artifact). You can create artifact-level links by using the Create a New Link for the Artifact action. Artifact-level links are particularly useful for defining links from resources that are not native to Composer.
Within the Links sidebar view, you can filter links according to the type of the link's target artifact. Use the Filter toolbar button (the three right-pointing arrows shown in Figure 12) in the Links sidebar to filter links.
Figure 12. Filter the links that are displayed in the Links sidebar
Filter links in the Links sidebar to quickly find references to artifacts of a particular type (for example, a Microsoft Word document).
The Links sidebar sections will indicate when links are filtered. In Figure 13, four outgoing links are filtered out and 5 of 9 are showing.
Figure 13. Outgoing links displayed with some links filtered
The Highlight All action takes filtering into account. In Figure 14, only those elements with links that show in the Links sidebar are highlighted. Elements with filtered out links will not be highlighted.
Figure 14. Only elements with links that are not filtered out are highlighted
Within Rational Requirements Composer, each artifact is identified by a permalink string, which is a unique identifier that is not derived from the artifact name nor its location. Therefore, if an artifact is renamed or moved to a different folder, links that point to the artifact will be preserved.
Don't be concerned about links to an artifact when you rename that artifact or move it to another folder. Existing links to it will not be affected.
You can modify existing links by using the Edit option from the Links pop-up view (Figure 15). You can open that view by using the Link to other artifacts button on the element toolbar or in the element's drop-down menu.
Figure 15. Indication that an element has a link when it is selected
To edit an existing link, select the link in the view and use the view's drop-down menu. The Edit Link action will open the "Link to" dialog window, where the link description, the type of link, and the link target can all be modified.
Figure 16. Modifying an existing link
Artifact-level links can be modified from the Links sidebar. Use the Manage Artifact Links menu item (Figure 17) from the Links button on the sidebar toolbar. This will open a Links Popup view that lists all artifact-level links. Note that this popup view lists only artifact-level links, not all of the links for the artifact. Links that originate from elements within the artifact have their own links popup view that can be opened via the element's context menu or the Link to other artifacts button on the element's toolbar.
Figure 17. Modifying or deleting links for the top-level artifact
Drag items to create links
You can drag and drop resources onto the following artifacts to create links:
- Business Process Diagram
- Use Case
- Use Case Diagram
Use the Project Explorer or the Search view to drag artifacts to create links. In diagram-based editors, a light-gray background will indicate which element the link will be created for (see Figure 18).
Figure 18. Drag an artifact onto a diagram element to create a link
You can also create artifact-level links for a diagram by dropping the target artifact onto the empty space in the diagram.
When decorating an artifact with links to several different other artifacts, consider bringing up the other artifacts in either the Project Explorer or the Search view and adding the links by dragging. If you create links in the editor instead, you will need to navigate to each target artifact in the "Link to" dialog. Dragging artifacts will save time, because there is no need to perform this navigation for every link.
For document-based editors (actor, document, requirement, use case), a red vertical line will indicate where that the link will be created in the document. For document-based editors, artifacts can also be embedded in the document by holding down the Ctrl key when you drop the artifact on the target.
Figure 19. Embed an artifact by dragging it onto a document while holding the Ctrl key
Linking and requirements
Associating requirements with artifacts and the elements within an artifact is an operation that is separate and distinct from creating links. When creating links, the Choose Existing Artifact panel on the "Link to" dialog will filter out requirement artifacts, and the Create New Artifact panel will not include the requirement type. To associate a requirement with an element within an artifact, use the Mark as Requirement action (Figure 20). This action is on the context menu for artifact elements.
Figure 20. Extracting a requirement from a diagram element
You can also associate requirements with an element by using the Show Requirements icon on the element's toolbar (Figure 21).
Figure 21. Manage links for an element through the control on its toolbar
Requirements that are related to an artifact appear in a separate sidebar. The Requirements sidebar operates like the Links sidebar. You can choose from Highlight All, Filter, or Sort actions, and navigation to the source and target element is available. Notice that the Requirements sidebar (Figure 22) does not include Outgoing and Incoming sections like the Links sidebar does. When a requirement is associated with an artifact, the artifact will appear as an Incoming Link in the Links sidebar for the requirement.
Figure 22. The Requirements sidebar
To associate requirements with the artifact as a whole, use the Create a New Requirement for the Artifact action from the Requirements menu on the Requirements sidebar.
Figure 23. Extracting a requirement from an entire artifact
You can manage and edit artifact-level requirements by using the Manage Artifact Requirements action from the Requirements menu on the sidebar. This action opens a Requirements view that lists all artifact-level requirements.
Figure 24. Modify or delete requirements for the top-level artifact
Notice that this pop-up view lists only artifact-level requirements, not all of the requirements for the artifact. Requirements that are associated with elements within the artifact show in a separate Requirements pop-up view, which you can open by using either the element's context menu or the Show Requirements icon on the element's toolbar.
A placeholder link is a link with an initially undefined target. Suppose you are meeting with a user to discuss the requirements for a particular application. During the meeting, you start to discuss some of the user interface design, and you decide to create a User Interface Sketch to capture what is being discussed. As you are defining the elements of the sketch with the user, it becomes apparent that a Document artifact is necessary to define the validation rules for a particular field. Rather than having to explicitly create a new Document artifact for this additional information, you can create a placeholder link for the field and continue with the work at hand (designing the user interface). You can capture the validation rules later.
Use placeholder links to capture relationships to artifacts that do not yet exist as a way to rapidly prototype requirements.
To create a placeholder link, use the Links pop-up view and specify a link description, but do not specify a target for the link. In Figure 25, a link for shipping and handling rules is being created, but the artifact that defines those rules does not yet exist, so just a link description is specified.
Figure 25. Add a link without defining a target
In the Links sidebar, placeholder links are identified with a diamond-shaped icon . To specify the target for a placeholder link, you can click the link in the Links sidebar, or you can edit the link in the Links pop-up view. Both of these actions will open the "Link to" window, where you can specify the target for the link.
Figure 26. A placeholder link
You can also use placeholders when associating requirements with an artifact. In Figure 27, the Cardholder name field has a placeholder requirement for Cardholder Validation.
Figure 27. A placeholder requirement
Several operations create relationships between artifacts, and Rational Requirements Composer automatically captures those relationships by creating a link in the Links or the Requirements sidebars. The operations that create links are listed by artifact type:
- Business Process diagram
- Elaborating a task with a Use Case diagram or sketch
- Associating a System use case with a task
- Associating a process with a subprocess
- Use Case diagram
- Using a shared actor or shared use case
- Elaborating a use case with a storyboard
- Specifying a related or synonym term
- Managing a requirement in IBM® Rational® RequisitePro®
- User Interface sketch
- Reusing an image, part, or sketch
- User Interface part
- Reusing an image, part or sketch
- Associating a sketch with a frame
- Text-based artifacts (document, actor, use case, requirement)
- Inserting an image or artifact (if the inserted artifact is a requirement, this association will be added to the Requirements sidebar)
- Embedding a requirement by using Mark As Requirement (this association will be added to the Requirements sidebar)
- Linking to a term
Notice that these links cannot be directly edited or deleted. Instead, Rational Requirements Composer manages these links as information about the relationship changes, or the relationship is removed.
When reading or reviewing an artifact written by a peer, take a look at the outgoing and incoming links and requirements to see whether there are related artifacts that are of interest to you.
Summary of tips
Tip 1: Before writing a comment that is specific to an element in the artifact (for example, a label in the user interface sketch or a paragraph in a document), click that element to select it. When your teammates click the comment later, that element will be selected for them.
Tip 2: Where appropriate, augment your comments with rich text and links to make navigation easier for people who read the comment. Take advantage of the spell-checking feature, too.
Tip 3: Use the filtering controls in the Comments sidebar to view only those comments that are important to you, such as those addressed to you or created within the last week, and so forth.
Tip 4: Group or sort comments by Date Last Modified to call to attention to comment threads that are "active" (comments or replies that have been made recently).
Tip 5: Use Ctrl to select multiple comments and resolve them all at once. To resolve all comments for an element, select that element and resolve the comments that are highlighted as a result.
Tip 6: Filter links in the Links sidebar to quickly find references to artifacts of a particular type (for example, a Microsoft Word document).
Tip 7: Don't be concerned about links to an artifact when you rename that artifact or move it to another folder. Existing links to it will not be affected.
Tip 8: When decorating an artifact with links to several different other artifacts, consider bringing up the other artifacts in either the Project Explorer or the Search view and adding the links by dragging. If you create links in the editor instead, you will need to navigate to each target artifact in the “Link to” dialog. Dragging artifacts will save time, because there is no need to perform this navigation for every link.
Tip 9: Use placeholder links to capture relationships to artifacts that do not yet exist as a way to rapidly prototype requirements.
Tip 10: When reading or reviewing an artifact written by a peer, take a look at the outgoing and incoming links and requirements to see whether there are related artifacts that are of interest to you.
- Watch this 10-minute demo to learn about the full scope of IBM Rational Requirements Composer and its capabilities.
- Explore the Rational Requirements Composer Information Center.
- Join the discussion in the Rational Requirements Composer forum about all aspects of requirements definition, including both general, tool-independent concepts and tool-specific information.
- Try the free trial of IBM Rational Requirements Composer.
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
- Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Browse the technology bookstore for books on these and other technical topics.
- Visit Rational Requirements Composer on jazz.net to view iteration plans for the next release and view or submit feature requests and bug reports.
Get products and technologies
- Download trial versions of IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.