An introduction to Rational RequisitePro extensibility

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.

Mark Goossen, Software Engineer, IBM

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.



November 2007 (First published 25 November 2003)

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.

Extensibility Architecture
Figure 1: Extensibility Architecture

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.

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:

Using the RPX to open a project
'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:

Accessing requirements in the 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

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.

Using Packages
'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

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.

Accessing 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

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

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:

Getting Started
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.

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.

Working with Projects
' 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

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.

Working with 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

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

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



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.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=445
ArticleTitle=An introduction to Rational RequisitePro extensibility
publish-date=11252007