The first time you sign into developerWorks, a profile is created for you. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.
All information submitted is secure.
The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.
Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.
Mark Goossen is a software engineer at IBM, based in Pennsylvania in the U.S. He works on the Rational Requirements Server team, focusing on process and configuration.
Summary: RequisitePro can easily be extended to help support your project's process. This article will demonstrate how to quickly get started with scripts that can be used to customize this requirements management tool.
Date: Nov 2007 (Published 25 Nov 2003)
Level: Introductory
Activity: 13548 views
Comments:
RequisitePro can easily be extended to help support your project's process. This article will demonstrate how to quickly get started with scripts that can be used to customize this requirements management tool. These scripts can be used to gather metrics, automate routine activities, or to exchange information with other applications, among other things.
There are two components that are used to extend RequisitePro. The first is the RequisitePro Extensibility server, or RPX. The RPX is used to access objects such as projects, packages, requirements and users.
The second is the RqGUIApp library. This is used to control the RequisitePro user interface, and it also provides some control over Microsoft Word documents.
The RPX is the RequisitePro Extensibility Interface. The core component is called ReqPro.dll, and this dll can be accessed through COM interfaces. The RPX contains classes used to read from or modify an existing RequisitePro project.
For an overview of the RPX's object model, including class diagrams, see the RequisitePro Extensibility Interface Help, which is installed with RequisitePro.
The following are examples of what may be accessed through the RPX:
Semantics of a requirements model, such as application, projects, packages, requirements, documents, relationships, discussions, attribute values
Administrative items, such as users and groups
Views
Meta-data, such as attribute types, requirement types, document types
These items are not accessible through the RPX:
Document contents (see the RqGUIApp section for how to deal with documents)
Once you have RequisitePro installed, you can begin writing code using the RPX. All of the examples provided below use Microsoft Visual Basic 6 syntax. If you are using Visual Basic, you will need to add the RPX (RequisitePro Extensibility Interface) to your project references.
You will also need a RequisitePro project to work with. A new project can be created to experiment with, or you can use one of the projects provided in the samples folder.
If you are making changes to objects through the RPX, make sure that you call that object's Save method before closing the project. Save will persist your changes to the database.
There are two steps in opening a project. The first is to create a new instance of the Application object. The second is to call Application.OpenProject. The OpenProject method can be used to open a project from its file path:
'open a project
Private Sub OpenProject()
Dim a_oReqPro As ReqPro40.Application
Dim a_oProject As ReqPro40.Project
Dim a_sProjectName As String
'start the server
Set a_oReqPro = New ReqPro40.Application
If Not a_oReqPro Is Nothing Then
'open a learning project by filename
a_sProjectName = a_oReqPro.ServerInformation.Path & _
"\..\samples\Learning_Project-Traditional\LEARNING - TRADITIONAL.rqs"
'a user id is required
Set a_oProject = a_oReqPro.OpenProject( _
a_sProjectName, _
eOpenProjOpt_RQSFile, _
"AnyUserID", _
"")
'close the project
a_oReqPro.CloseProject a_oProject, eProjLookup_Object
End If
Set a_oProject = Nothing
Set a_oReqPro = Nothing
End Sub
Listing 1: Opening a project by filename
Each user also has a catalog of recently opened projects. A project may be opened after it is retrieved from the catalog:
'open a project from the catalog
Private Sub OpenProjectFromCatalog()
Dim a_oReqPro As ReqPro40.Application
Dim a_oProject As ReqPro40.Project
Dim a_oCatalog As ReqPro40.Catalog
Dim a_oCatalogItem As ReqPro40.CatalogItem
Dim a_sProjectName As String
'start the server
Set a_oReqPro = New ReqPro40.Application
If Not a_oReqPro Is Nothing Then
Set a_oCatalog = a_oReqPro.PersonalCatalog
If Not a_oCatalog Is Nothing Then
'look up the first project in the catalog
Set a_oCatalogItem = a_oCatalog.Item(1, eCatLookup_Index)
'a user id is required
Set a_oProject = a_oReqPro.OpenProject( _
a_oCatalogItem, _
eOpenProjOpt_Object, _
"AnyUserID", _
"")
'close the project
a_oReqPro.CloseProject a_oProject, eProjLookup_Object
End If
End If
Set a_oCatalog = Nothing
Set a_oCatalogItem = Nothing
Set a_oReqPro = Nothing
End Sub
Listing 2: Opening a project in the catalog
Note: Once a project has been opened, it needs to remain open while its data is being accessed. When your script has completed, the project may be saved, then closed.
Once the project has been opened, the requirements may be retrieved. This can be very useful if you want to generate a report or export the information to another application. The following listings demonstrate how to retrieve requirements from an already opened project:
'print all requirements
Sub PrintAllRequirements(oProject As ReqPro40.Project)
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq As ReqPro40.Requirement
'retrieve all requirements
Set a_oReqs = oProject.GetRequirements("", eReqsLookup_All)
'iterate through requirements
While Not a_oReqs.IsEOF
Set a_oReq = a_oReqs.ItemCurrent
'print out tag and text to the debug window
Debug.Print a_oReq.Tag & " " & a_oReq.Text
a_oReqs.MoveNext
Wend
Set a_oReq = Nothing
Set a_oReqs = Nothing
End Sub
Listing 3: Printing requirements information
This example demonstrates one way to export information to another application.
'print requirements to Microsoft Excel
Sub PrintAllRequirementsToExcel(oProject As ReqPro40.Project)
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq As ReqPro40.Requirement
Dim a_oExcelApp As Object
Dim a_oWorkbook As Object ' Excel.Workbook
Dim a_oSheet As Object ' Excel.Worksheet
Dim a_lRow As Long
Set a_oExcelApp = CreateObject("Excel.Application")
Set a_oWorkbook = a_oExcelApp.Workbooks.Add
a_oExcelApp.Visible = True
Set a_oSheet = a_oWorkbook.ActiveSheet
a_oSheet.Name = "ReqPro"
a_oSheet.Cells(1, 1).Value = "Tag"
a_oSheet.Cells(1, 2).Value = "Requirement"
a_lRow = 2
'retrieve all requirements
Set a_oReqs = oProject.GetRequirements("", eReqsLookup_All)
'iterate through requirements
While Not a_oReqs.IsEOF
Set a_oReq = a_oReqs.ItemCurrent
a_oSheet.Cells(a_lRow, 1).Value = a_oReq.Tag
a_oSheet.Cells(a_lRow, 2).Value = a_oReq.Text
a_lRow = a_lRow + 1
a_oReqs.MoveNext
Wend
Set a_oReq = Nothing
Set a_oReqs = Nothing
End Sub
Listing 4: Exporting requirements to Microsoft Excel
Requirements may also be created through the RPX. This is an example of how to automate a routine activity. It could be useful in performing imports of requirements information from other sources.
The following example demonstrates how to create a new requirement. The requirement type must first be defined.
'create a requirement
Private Sub CreateRequirement(oProject As ReqPro40.Project)
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq As ReqPro40.Requirement
'get all requirements of type "PR"
Set a_oReqs = oProject.GetRequirements("PR", eReqsLookup_TagPrefix)
'add a requirement to the collection of PR requirements
Set a_oReq = a_oReqs.Add( _
"requirement_name", _
"This is a root PR requirement.", _
"PR", eReqTypesLookups_Prefix)
'commit this to the database by doing a save on the requirement
a_oReq.Save
Set a_oReq = Nothing
Set a_oReqs = Nothing
End Sub
Listing 5: Creating a new requirement through the RPX
The RPX can also be used to help maintain traceability between requirements. You are able to retrieve collections of relationships, as well as create new relationships. The next example demonstrates how to create a new trace relationship.
'create a trace-to relationship
Private Sub CreateTraceRelationship(oProject As ReqPro40.Project)
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq1 As ReqPro40.Requirement
Dim a_oReq2 As ReqPro40.Requirement
Dim a_oRel As ReqPro40.Relationship
'get all requirements
Set a_oReqs = oProject.GetRequirements("", eReqsLookup_All)
'lookup the requirements that you would like
'to be a part of the relationship
Set a_oReq1 = a_oReqs.Item("PR1", eReqLookup_Tag)
Set a_oReq2 = a_oReqs.Item("SR1.6", eReqLookup_Tag)
If Not a_oReq1 Is Nothing Then
Set a_oRel = a_oReq1.TracesTo.Add(a_oReq2, eReqLookup_Object)
End If
'commit this to the database by doing a save on the requirement
a_oReq1.Save
Set a_oReq1 = Nothing
Set a_oReq2 = Nothing
Set a_oRel = Nothing
Set a_oReqs = Nothing
End Sub
Listing 6: Create a trace relationship
RequisitePro can also be extended to access a requirement's attribute information. New attributes can be created and attribute values may be updated. An attribute's value could even be calculated from the values of other attributes.
'modify requirement attribute values
Private Sub ModifyAttributeValue(oProject As ReqPro40.Project)
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq As ReqPro40.Requirement
Dim a_oAttrValues As ReqPro40.AttrValues
Dim a_oAttrValue As ReqPro40.AttrValue
'get all requirements
Set a_oReqs = oProject.GetRequirements("", eReqsLookup_All)
Set a_oReq = a_oReqs.Item("PR1", eReqLookup_Tag)
If Not a_oReq Is Nothing Then
Set a_oAttrValues = a_oReq.AttrValues
If Not a_oAttrValues Is Nothing Then
'cycle through each AttrValue object and modify the value
'based on the attribute's specific data type.
For Each a_oAttrValue In a_oAttrValues
Select Case a_oAttrValue.DataType
Case ReqPro40.eAttrDataTypes_Text
a_oAttrValue.Text = "RequisitePro Example"
Case ReqPro40.eAttrDataTypes_List
'Rather than using the Value property of a List
'Attr, we need to use the ListItemValues
'property, which returns a collection of
'ListItemValue objects.
'Once we have a ListItemValue object reference,
'we can then query its Text property,
'and set its Selected property.
Dim a_oListItemValues As ListItemValues
Dim a_oListItem As ListItemValue
Set a_oListItemValues = a_oAttrValue.ListItemValues
For Each a_oListItem In a_oListItemValues
If a_oListItem.Text = "Low" Then
a_oListItem.Selected = True
End If
Next a_oListItem
End Select
Next a_oAttrValue
End If 'Not a_oAttrValues Is Nothing
End If 'Not a_oReq Is Nothing
' Commit this to the database by doing a save on the requirement
a_oReq.Save
Set a_oReq = Nothing
Set a_oAttrValues = Nothing
Set a_oAttrValue = Nothing
Set a_oListItemValues = Nothing
Set a_oListItem = Nothing
Set a_oReqs = Nothing
End Sub
The package structure of a project can help to keep requirements, documents and view organized. When creating new elements, it is usually necessary to move them from their default location, the root package, to another location. The next example demonstrates how to create a new package.
'create a package
Sub CreatePackage(oProject As ReqPro40.Project)
Dim a_oRootPackage As ReqPro40.RootPackage
Dim a_oPackage As ReqPro40.Package
'retrieve the root package
Set a_oRootPackage = oProject.GetRootPackage
'create a package at the root level (Don't need to call save.
CreatePackage will persist the package)
Set a_oPackage = a_oRootPackage.CreatePackage("Package Name1", _
"My Package")
Set a_oRootPackage = Nothing
Set a_oPackage = Nothing
End Sub
Listing 8: Creating a new package
The following code gives an example of creating a new requirement in a package other than the root package.
'move a requirement
Sub MoveRequirement(oProject As ReqPro40.Project)
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq As ReqPro40.Requirement
Dim a_oRootPackage As ReqPro40.RootPackage
Dim a_oPackage As ReqPro40.Package
'get all requirements of type "PR"
Set a_oReqs = oProject.GetRequirements("PR", _
eReqsLookup_TagPrefix)
'add a requirement to the collection of PR requirements
Set a_oReq = a_oReqs.Add( _
"requirement_name", _
"This is a root PR requirement.", _
"PR", eReqTypesLookups_Prefix)
'commit this to the database by doing a save on the requirement
a_oReq.Save
'retrieve the root package
Set a_oRootPackage = oProject.GetRootPackage
'create a package at the root level
'Don't need to call save, CreatePackage will persist the package
Set a_oPackage = a_oRootPackage.CreatePackage("Package Name1", _
"My Package")
a_oPackage.AddElement a_oReq, _
ePackageLookup_Object, _
eElemType_Requirement
Set a_oReqs = Nothing
Set a_oReq = Nothing
Set a_oRootPackage = Nothing
Set a_oPackage = Nothing
End Sub
Although a document's content may not be accessed through the RPX, there is still information that may be useful for reporting purposes. This example shows how to access documents in the RPX, and print the name and tag of the requirements contained within those documents.
'print all requirements in each document
Sub PrintAllDocBasedRequirements(oProject As ReqPro40.Project)
Dim a_oDocs As ReqPro40.Documents
Dim a_oDoc As ReqPro40.Document
Dim a_oReqs As ReqPro40.Requirements
Dim a_oReq As ReqPro40.Requirement
'retrieve all documents
Set a_oDocs = oProject.Documents
For Each a_oDoc In a_oDocs
'print out document path and name
Debug.Print a_oDoc.Name & ": " & a_oDoc.FullPath
'retrieve all requirements in this document
Set a_oReqs = a_oDoc.Requirements
'iterate through requirements
If Not a_oReqs Is Nothing Then
While Not a_oReqs.IsEOF
Set a_oReq = a_oReqs.ItemCurrent
'print out tag and text to the debug window
Debug.Print vbTab & a_oReq.Tag & " " & a_oReq.Text
a_oReqs.MoveNext
Wend
End If
Next a_oDoc
Set a_oDocs = Nothing
Set a_oDoc = Nothing
Set a_oReq = Nothing
Set a_oReqs = Nothing
End Sub
RqGuiApp is the RequisitePro GUI Application interface. The core component is called RqGuiApp.tlb. This library allows some control over the RequisitePro application, as well as RequisitePro documents opened in Microsoft Word.
These interfaces are also described in the RequisitePro Extensibility Interface Help, which is installed with RequisitePro.
The following are some of the actions available through RqGuiApp:
Opening and closing projects
Opening, closing, creating, saving, and positioning the selection within documents
Creating and updating document-based requirements
Opening views and finding the currently selected requirement.
In order to use RqGuiApp to interact with RequisitePro, it is necessary to have RequisitePro running. This example shows how the running instance of RequisitePro is retrieved:
Dim a_oRqGuiApp As Object
'get the current running instance of RequisitePro from Windows
On Error Resume Next
Set a_oRqGuiApp = GetObject(, "ReqPro40.GUIApp")
On Error GoTo 0
' if not open
If a_oRqGuiApp Is Nothing Then
MsgBox "Please open RequisitePro"
End If
Listing 11: Using RqGuiApp to work with RequisitePro
Alternatively, RqGuiApp may be used to open the RequisitePro application:
Dim a_oRqGuiApp As Object
'get the current running instance of RequisitePro from Windows
Set a_oRqGuiApp = CreateObject("ReqPro40.GUIApp")
Many of the methods provided in RqGuiApp require the use of a callback object. A callback object is an instance of a class that exposes certain pre-defined methods. These methods are defined in the RequisitePro Extensibility Interface help. It is necessary to compile a .dll that contains a class that defines these methods, then pass an instance of this class into the RqGuiApp methods. In RequisitePro 2003, a .dll that encapsulates this callback object is provided.
When the RqGuiApp operation is complete (I.e. the project is opened, the document has been created), the callback object is notified.
In order to open a project, a callback object must be used. It is possible to use this callback object to obtain an instance of the RPX Project object from the RqGuiApp library.
' If another project is open, RequisitePro closes the project
'(and the appropriate dialog boxes) and opens the specified project.
Function OpenProjectInGui(oRqGuiApp As Object, _
sPath As String, _
sUser As String, _
sPwd As String) As ReqPro40.Project
Dim a_bRet As Boolean
Dim a_oCallback As RqCallback.Callback
'need to instantiate callback object
Set a_oCallback = New Callback
'tell the RequisitePro application to open a project
a_bRet = oRqGuiApp.OpenProject(sPath, _
eOpenProjOpt_RQSFile, _
sUser, sPwd, _
eProjFlag_Normal, _
a_oCallback)
If a_bRet Then
'wait until the operation is complete
While Not a_oCallback.IsDone
DoEvents
Wend
'retrieve the project object
Set OpenProjectInGui = a_oCallback.GetObject
End If
Set a_oCallback = Nothing
End Function
RqGuiApp allows for additional control over RequisitePro documents. This control allows scripts to request that RequisitePro create, open and close documents. Additionally, requirements may be added to documents, and existing document-based requirements may be updated in documents.
' Creates a RequisitePro document in the current project.
' The new document is opened in Word, and becomes the active document.
Public Sub CreateDocument(oRqGuiApp As Object, _
sName As String, _
sPath As String, _
sDocTypeGUID As String, _
sDescription As String)
Dim a_bRet As Boolean
Dim a_oCallback As RqCallback.Callback
'need to instantiate callback object
Set a_oCallback = New Callback
'the path should be the project's path, including the
'filename with the proper document type extension
a_bRet = oRqGuiApp.CreateDocument(sName, _
sPath, _
sDocTypeGUID, _
sDescription, _
a_oCallback)
If a_bRet Then
'wait until the operation is complete
While Not a_oCallback.IsDone
DoEvents
Wend
End If
Set a_oCallback = Nothing
End Sub
Listing 14: Creating a new document
Here is an example of how to update an existing requirement in a document.
'Updates requirement text in a document.
'The document must be saved for the change to take effect.
Public Sub UpdateRequirementInDocument(oRqGuiApp As Object, _
oReq As ReqPro40.Requirement, _
sNewText As String)
Dim a_bRet As Boolean
Dim a_oCallback As RqCallback.Callback
'need to instantiate callback object
Set a_oCallback = New Callback
a_bRet = oRqGuiApp.UpdateRequirementInDocument(oReq, _
sNewText, _
a_oCallback)
If a_bRet Then
'wait until the operation is complete
While Not a_oCallback.IsDone
DoEvents
Wend
End If
Set a_oCallback = Nothing
End Sub
Listing 15: Creating a new document-based requirement
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
Visit the Requirements Management and RequisitePro forum on developerWorks to post your questions and comments and to share your thoughts, ideas, and solutions with others who use RequisitePro.
Mark Goossen is a software engineer at IBM, based in Pennsylvania in the U.S. He works on the Rational Requirements Server team, focusing on process and configuration.
The first time you sign into developerWorks, a profile is created for you. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.
The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.
Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.
This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.
And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.
Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.
Use the search field to find all types of content in My developerWorks with that tag.
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags
for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
