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.
Overview of Extensibility Architecture
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.
|
|
Figure 1: Extensibility Architecture
|
Back to top
RPX
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)
- Project creation
Getting Started
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.
Using the RPX to open a project
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.
Accessing requirements in the project
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 |
|
|
Listing 7: Update an attribute's value
|
Using Packages
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 |
|
|
Listing 9: Move a requirement between packages
|
Accessing Documents
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 |
|
|
Listing 10: Print requirements by document
|
Back to top
RqGuiApp
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.
- Refreshing the project explorer
Getting Started
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") |
|
|
Listing 12: Opening RequisitePro with RqGuiApp
|
Callback Objects
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.
Working with Projects
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 |
|
|
Listing 13: Opening a project with RqGuiApp
|
Working with Documents
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
|
Back to top
Related Reading
- For additional information and examples, please see the RequisitePro Extensibility
Interface Help provided with RequisitePro.
Resources
Learn
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 author
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.
Comments (Undergoing maintenance)
Back to top
Trademarks | My developerWorks terms and conditions
Help: Update or add to My dW interests
What's this?
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.
View your My developerWorks profile
Return from help
