An Introduction to Rational RequisitePro Extensibility

Transcription

1 Copyright Rational Software An Introduction to Rational RequisitePro Extensibility by Mark Goossen Editor's Note: Each month, we will feature one or two articles from the Rational Developer Network, just to give you a sense of the content you can find there. If you have a current Rational Support contract, you should join the Rational Developer Network now! 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.

2 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

3 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 Set a_oproject = Nothing Set a_oreqpro = Nothing 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:

4 '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 Set a_ocatalog = Nothing Set a_ocatalogitem = Nothing Set a_oreqpro = Nothing 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:

5 '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 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 (5 of 14) [6/13/2003 1:14:37 PM]

6 a_lrow = a_lrow + 1 a_oreqs.movenext Wend Set a_oreq = Nothing Set a_oreqs = Nothing 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 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.

7 '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) '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 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

8 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 Next a_olistitem End Select Next a_oattrvalue 'Not a_oattrvalues Is Nothing '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 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.

9 '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 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

10 Set a_oreq = Nothing Set a_orootpackage = Nothing Set a_opackage = Nothing 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 Next a_odoc Set a_odocs = Nothing Set a_odoc = Nothing Set a_oreq = Nothing Set a_oreqs = Nothing Listing 10: Print requirements by document RqGuiApp

11 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" 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 (11 of 14) [6/13/2003 1:14:37 PM]

12 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 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 documentbased requirements may be updated in documents.

13 ' 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 Set a_ocallback = Nothing 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 (13 of 14) [6/13/2003 1:14:37 PM]

14 Set a_ocallback = Nothing Listing 15: Creating a new document-based requirement What's Next? As you become more comfortable working with the RPX and RqGuiApp to extend your requirements management solution, take time to look over some of the custom scripts that have been posted on RDN. Related Reading For additional information and examples, please see the RequisitePro Extensibility Interface Help provided with RequisitePro. Demystifying the Rational TestManager API About the Author Mark Goossen has been in the software industry since Before joining Rational Software/IBM, he worked with Rational products in both the machine vision and broadcasting software industries. For more information on the products or services discussed in this article, please click here and follow the instructions provided. Thank you! Copyright Rational Software 2003 Privacy/Legal Information