 | Mark Goossen (markgoossen@us.ibm.com), Staff Software Engineer, IBM
20 Nov 2007 IBM® Rational® RequisitePro® offers the capability to move or reposition requirements in the RequisitePro Explorer by renumbering the requirements. Renumbering replaces the tags of the affected requirements. To implement this functionality, a new API method is provided in the RequisitePro Extensibility Interface.
Purpose
This document describes the use of the renumbering requirements feature in IBM® Rational® RequisitePro®. This feature is available starting with version 2003.06.15. This feature is separate from the existing renumbering functionality, which allows for renumbering all requirements of a type to remove missing tags and to reorganize by document. This new feature provides the following capabilities:
- Renumbering individual requirements to change the order in which they appear in the RequisitePro Explorer
- The creation of a new requirement between existing requirements. This is accomplished by creating a requirement, then moving or renumbering it in a new position.
Introduction
RequisitePro offers the capability to move or reposition requirements in the RequisitePro Explorer by renumbering the requirements. Renumbering replaces the tags of the affected requirements. To implement this functionality, a new API method is provided in the RequisitePro Extensibility Interface. A ready-to-run example is included with the whitepaper and is described below.
Usage
This feature is intended for use with RequisitePro version 2003.06.15 or later.
Support for requirement renumbering has been added to the RequisitePro Extensibility Interface. Although renumbering may be done while a project is open in the RequisitePro client, the project explorer view will not be refreshed automatically. Views will need to refreshed manually, or in some cases, the project will need to be closed and reopened.
RequisitePro Extensibility Interface
You can renumber individual requirements using the Requirement object. The Renumber method is shown below in Table 1:
Syntax
Table 1. Named arguments in the renumber method
| Argument | Description |
|---|
| vReqPositionAfterLookupValue | A Variant that specifies the requirement that will precede the repositioned requirement. This value can represent a key, tag, etc. of the requirement as specified by the eReqLookupType argument. |
|---|
| vReqLookupType | An enumeration that specifies the type of value in vReqLookupValue. If this argument is not provided, a lookup type of key is assumed. |
|---|
Remarks
If no arguments are included, the requirement is renumbered to the beginning of all requirements of the same type.
Code examples
Listing 1 shows how to use the renumber method to position the FEAT4 requirement after the FEAT2 requirement. Note that FEAT4 will become FEAT3, and FEAT3 will become FEAT4.
Listing 1. Reordering requirements
Dim a_oApplication As ReqPro40.Application
Dim a_oProject As ReqPro40.Project
Dim a_oReqSource As ReqPro40.Requirement
'Instantiate the application object
Set a_oApplication = New ReqPro40.Application
'Open the project
Set a_oProject = a_oApplication.OpenProject
("C:\program files\rational\requisitepro\projects\test\test.rqs",
eOpenProjOpt_RQSFile, "admin", "")
'Obtain the source requirement
Set a_oReqSource = a_oProject.GetRequirement("FEAT4", eReqLookup_Tag)
'Move the source requirement after the "FEAT2" requirement
a_oReqSource.Renumber "FEAT2", eReqLookup_Tag
|
Listing 2 shows how to insert a new requirement between two existing requirements. The new requirement will be positioned after FEAT2. All subsequent requirements will be renumbered.
Listing 2. Inserting requirements
Dim a_oApplication As ReqPro40.Application
Dim a_oProject As ReqPro40.Project
Dim a_oReqSource As ReqPro40.Requirement
'Instantiate the application object
Set a_oApplication = New ReqPro40.Application
'Open the project
Set a_oProject = a_oApplication.OpenProject
("C:\program files\rational\requisitepro\projects\test\test.rqs",
eOpenProjOpt_RQSFile, "admin", "")
'Create the source requirement
Set a_oReqSource = a_oProject.CreateRequirement
("newName", "", "FEAT", eReqTypesLookups_Prefix)
a_oReqSource.Save
'Move the source requirement after the "FEAT2" requirement
a_oReqSource.Renumber "FEAT2", eReqLookup_Tag
|
Listing 3 shows how to move a requirement under a new parent and between two existing child requirements.
Listing 3. Movng a requirement under a new parent
Dim a_oApplication As ReqPro40.Application
Dim a_oProject As ReqPro40.Project
Dim a_oReqSource As ReqPro40.Requirement
'Instantiate the application object
Set a_oApplication = New ReqPro40.Application
'Open the project
Set a_oProject = a_oApplication.OpenProject
("C:\program files\rational\requisitepro\projects\test\test.rqs",
eOpenProjOpt_RQSFile, "admin", "")
'Obtain the source requirement
Set a_oReqSource = a_oProject.GetRequirement("FEAT4", eReqLookup_Tag)
'Reparent the source requirement under FEAT2
Set a_oReqSource = a_oReqSource.AssignParent("FEAT2", eReqLookup_Tag)
'Move the source requirement after the "FEAT2.1" requirement
a_oReqSource.Renumber "FEAT2.1", eReqLookup_Tag
|
Example
A ready-to-run example executable and accompanying source code are included with this article. The example includes the RenumberReq.exe file. This example contains a graphical component that shows a tree view of requirements of one type. To view this tree, browse to a RequisitePro project and select a requirement type from the drop-down list. Requirements should be displayed as in Figure 1.
Figure 1. The requirements tree
You can renumber requirements by dragging a node and dropping it on the requirement that will precede the repositioned requirement. Figure 2 shows FEAT4 moved after FEAT2.
Figure 2. Renumbering FEAT4 after FEAT2
To move a requirement to the beginning of the list, hold down the SHIFT key and drag the requirement to the top of the list. Figure 3 shows FEAT4 moved to the beginning.
Figure 3. Renumbering FEAT4 to the beginning
Revisions
Each requirement that is updated and saved as a part of a renumbering operation is given a new version number and reason. The version reason contains information about the old tag and new tag.
Supported use cases
The following use cases are supported by the renumbering functionality:
- Moving a requirement after another requirement
- Moving a requirement to the beginning of all requirements of the same type
- Moving a requirement with children
- Moving a child requirement within the hierarchy of its parent
Unsupported use cases
The following use cases are not supported, and an exception is reported:
- Moving a requirement when that requirement type cannot be locked
- Moving a requirement when the user does not have adequate permissions for that requirement type
- Moving a child requirement outside the hierarchy of its parent
- Moving a requirement under a new parent
- Moving a requirement after a requirement of a different requirement type
Download | Description | Name | Size | Download method |
|---|
| Sample scripts for this article | RenumberReq.zip | 19KB | HTTP |
|---|
Resources Learn
- A number of useful RequisitePro Extensibility (RPX) scripts that add additional capabilities to your use of RequisitePro are available from developerWorks in the RequisitePro extensibility script index.
- Download the trial version of IBM Rational RequisitePro V7.0 from the Downloads section on developerWorks.
-
Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- See also the Rational RequisitePro area on developerWorks for requirements management content and resources.
-
Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
Discuss
About the contributor | | | Mark Goossen is a software engineer with IBM Rational, with over ten years of application development experience. His focus is on the design and development of requirement definition and management tools. |
| | | |
