Project administration using IBM Rational RequisitePro

Learn how you can use the included APIs to extend the capabilities of Rational RequisitePro

Learn how to use the project administration features of the IBM® Rational RequisitePro® APIs. Most of these APIs have been included in the product since the versions indicated in this article.

Share:

Sharoon Kuriyala (sharoonsk@in.ibm.com), Development Manager, IBM Japan

Sharoon S. Kuriyala is a development manager with IBM Software Group, Rational, in the India Software Labs. She has more than eight years of application development experience, and she is part of the team that designs and develops requirement management tools.



25 December 2007

Also available in Chinese

IBM Rational RequisitePro helps you administer your projects where you store them. You can use either the user interface provided in the native client or the Web client, and you can perform these tasks programmatically by using the Rational RequisitePro APIs that are provided.

Exclusive access to a project

Project administrators must gain exclusive access to a project to perform some modifications to project structure. Project administrators must gain exclusive access to a project to perform these actions:

  • Change requirement type tag prefixes
  • Change requirement type color and style
  • Delete a requirement type
  • Delete an attribute from a requirement type
  • Delete a document type

Exclusive access is a security condition by which change permissions for a project and its documents are only available to the user who opens the project. You can open a project and its documents in exclusive mode only if the project and documents are not already open by another user.

Listing 1. Create a project
Dim a_sName As String
Dim a_sPath As String
Dim a_sDescription As String
Dim a_sTemplateName As String
Dim a_oProject As ReqPro40.Project
Dim a_oRPX As ReqPro40.Application

' Get an instance of the RPX object
Set a_oRPX = New ReqPro40.Application
' Name of the project
a_sName = "Project1"
' Path of the project
a_sPath = "C:\program files\rational\requisitepro\projects\" 
& a_sName
' Description of the project
a_sDescription = "This is a new project. "
' Use the blank template
a_sTemplateName = vbNullString

' Create a new Project
a_oRPX.CreateProject _
      a_sPath, _ 		' Project Path
      a_sName, _		' Project name
      a_sDescription, _	' Project Description
      a_sTemplateName, _	' Project Template
      eDBType_Access, _	' Database Type
      , _			' User ID for Database
      , _			' Password for Database
      , _			' Database schema
      , _			' DSN for Oracle/SQL servers only
	, _			' For DB2 servers only                
' above five parameters are used for enterprise database
	, True		' flag to create directory if it 
' doesn't exist
    
' Open the newly created Project
Set a_oProject = a_oRPX.OpenProject(a_sPath & "\" & a_sName & 
".rqs", eOpenProjOpt_RQSFile, "admin", "")

Open a project with exclusive access

The project can be opened by using the following access modes:

ModeCode
Open project with exclusive accesseProjFlag_Exclusive
Open project with normal access [R/W]eProjFlag_Normal
Open project with read only accesseProjFlag_ReadOnly

These flags are used as parameters with the ReqPro40.Application.OpenProject API. If no option is provided, the default option is normal access.

Listing 2 shows how to switch the type of access when the project is already open.

Listing 2. Switching an open project to exclusive or normal access
Set a_oProject = a_oRPX.OpenProject(a_sPath & "\" & a_sName & 
".rqs", eOpenProjOpt_RQSFile, "admin", "", 
eProjFlag_Exclusive)

The administrator will get exclusive access, as long as there are no other users who have opened the same project with exclusive or normal mode of access.

Project structure

Project administrators have the project structure administration capabilities that the following subsections describe.

Project properties

Project administrators can view project properties and modify the name, prefix, and description for the project. The prefix is used as an identifier for requirements and requirement types in this project when it is referenced as an external project for cross-project traceability (see Listing 3).

Listing 3. Sample code listing at maximum width
Dim a_oProject As ReqPro40.Project
Dim a_sPath As String
Dim a_oApp As ReqPro40.Application

a_sPath = 
"C:\Program Files\Rational\RequisitePro\samples\Learning_Project-Use_Cases\LEARNING - 
USE CASES.RQS"

Set a_oApp = New ReqPro40.Application
If Not a_oApp Is Nothing Then
Set a_oProject = a_oApp.OpenProject _
                    (a_sPath, eOpenProjOpt_RQSFile, "admin", "")
If Not a_oProject Is Nothing Then

View project properties

General properties:

  • Name: a_oProject.Name
  • Prefix: a_oProject.Prefix
  • Creator: a_oProject.AuthorID (The creator name can be searched from the user's object by using AuthorID as the key.)
  • Directory: a_oProject.RQSFilepath
  • Description: a_oProject.Description

Modify the name, prefix, and description of the project

Listing 4 shows sample code for this purpose.

Listing 4. Modifying the name, prefix, and description of the project
a_oProject.Name = "NewProjectName"
a_oProject.Prefix = "newProj"
a_oProject.Description = "Project containing agile requirements"

Project revision history

The revision history is created by actions such as enabling or disabling project security, changing the project structure, and so forth.

View or modify project revision history

You can view these details in any revision history update:

  • VersionNumber: The revision number
  • VersionLabel: The label for this revision update
  • VersionUser: The user who caused this revision update
  • VersionUserKey: The unique key for the user who caused the revision update
  • VersionDateTime: The time stamp of the revision update
  • VersionReason: The description of the revision update

As the sample code in Listing 5 shows, you can retrieve the revision history of any requirement from the Requirement object or the history of changes made to the project, such as security modifications, from the Project object, and so on.

Listing 5. Retrieving the revision history
' Gets the Project VersionDateTime of last modification.
a_oProject.VersionDateTime

' Gets the Project VersionLabel
a_oProject.VersionLabel

' The Project VersionLabel can also be set programmatically
a_oProject.VersionLabel = "Label 1"

' Gets the Project VersionNumber
a_oProject.VersionNumber

' Modify the Project VersionNumber 
' The new revision number is validated to make sure it is in a 
' correct form, i.e. higher or equal to the current revision 
' number.

a_oProject.VersionNumber = "1.1"

' Gets the description of the revision entry
a_oProject.VersionReason

' Give the description of the revision entry when 
' programmatically adding an revision history
a_oProject.VersionReason = "Security is disabled for the project"

' Gets the name or key of the last user to perform a
' Project modification.
a_oProject.VersionUser
a_oProject.VersionUserKey

Requirement types

A requirement type serves as a template for your requirements. Project administrators can create, view, and modify requirement types. For example (also see Listing 6):

Dim a_sPath As String
Dim a_oProject As ReqPro40.Project
Dim a_oReqType As ReqPro40.ReqType
Dim a_oReqTypes As ReqPro40.ReqTypes
Listing 6. Modifying a requirement type
Dim a_oReqType = a_oProject.ReqTypes.Add
("Test", _
"TEST", _
eReqStyles_Normal, _ eReqColors_Magenta, _2)

Tip:
You can pass optional parameters to the ReqPro40.ReqTypes API to provide the following properties:

  • Description of the ReqType
  • String that a requirement of that ReqType must contain
  • Whether requirements of that ReqType can have external references or not
Listing 7. Modify requirement type properties
Set a_oReqType = a_oProject.ReqType("TEST", eReqTypesLookups_Prefix)

' Reqtype's name is a textual value that uniquely identifies the 
' reqtype
	a_oReqType.Name = "Feature"
' Set the number that was associated with the first requirement 
' that is created of this reqtype.
      a_oReqType.InitReqNumber = 4
' Requirement type's ReqPrefix value
	a_oReqType.ReqPrefix = "FEAT"
' Requirement type's ReqColor value.
' Document based requirements of this reqtype will
' be shown in this color in their document.
' ReqPro40.enumReqColors would provide all the supported colors
a_oReqType.ReqColor = eReqColors_White
' Requirement type's ReqStyle value.
' Document based requirements of this reqtype will
' be shown in this style in their document.
' ReqPro40.enumReqStyles would provide all the supported colors
a_oReqType.ReqStyle = eReqStyles_SmallCapitals

a_oProject.Save

Note:
The following capabilities are included with Rational RequisitePro Version 7.0.1 and later.

Listing 8. Change requirement type
Dim a_sNewReqType As String
Dim a_sOldReqType As String
Dim a_sName As String

a_sOldReqType = "FEAT"
a_sNewReqType = "TERM"
a_sName = "NewReqType"

' Create a requirement
Set a_oReq = a_oProject.CreateRequirement( _
         a_sName, a_sName, a_sOldReqType, eReqTypesLookups_Prefix)

a_oReq.Save

Set a_oReq = a_oProject.GetRequirement(a_sName, eReqLookup_Name)
' Change the requirement type
a_oReq.ChangeReqType a_sNewReqType, eReqTypesLookups_Prefix

a_oReq.Save

View requirement type properties

The requirement type properties, such as Name, InitReqNumber, ReqPrefix, ReqColor, and ReqStyle can be queried from the ReqType object.

Requirement attributes
Project administrators can add, modify, and delete requirement attributes. This can include predefined attribute values for list-type attributes. See the examples in Listings 9, 10, and 11.

Listing 9. Add custom attributes
Dim a_sReqTypeKey As String
Dim a_sLabel As String
Dim a_sDefText As String
Dim a_sDataType As String
Dim a_bAutoSuspect As Boolean
Dim a_iRank As Integer
Dim a_iDataTypeKey As Integer
Dim a_oReqAttr As ReqPro40.Attr

a_sReqTypeKey = 1
a_sLabel = "New"
a_sDefText = "Default"
a_sDataType = "RqCustomType.URLLink"
a_bAutoSuspect = False
a_iRank = 0
a_iDataTypeKey = enumAttrDataTypes.eAttrDataTypes_Text

' Project needs to be opened with exclusive access
Set a_oReqAttr = a_oProject.ReqType(a_sReqTypeKey, _
enumReqTypesLookups.eReqTypesLookups_Key).Attrs().Add( _
a_sLabel, _
a_iRank, _
a_bAutoSuspect, _ 
a_iDataTypeKey, _                                                     
a_sDefText, _
False)
a_oProject.Save
a_oReqAttr.SetCustomType a_sDataType, _
		enumCustomTypeLookups.eCustomTypeLookup_ProgID
            
a_oProject.Save
Listing 10. Modify requirement attributes
' Modify attribute list type
' Project needs to be opened with exclusive access
a_sReqTypePrefix = "FEAT"
a_sLabel = "Type"
    
Set a_oReqAttr = a_oProject.ReqType(a_ sReqTypePrefix, _
enumReqTypesLookups.eReqTypesLookups_ Prefix).Attrs().Item(
a_sLabel,_
enumAttrLookups.eAttrLookups_Label)
a_iDataTypeKey = a_oReqAttr.DataType()

' Change a single-select list to a multi-select and vice versa  
' Project needs to be opened with exclusive access
a_oReqAttr.ChangeAttrListType
a_oProject.Save
Listing 11. Delete requirement attributes
' Project needs to be opened with exclusive access
a_oProject.ReqType(a_sReqTypeKey, _ 
enumReqTypesLookups.eReqTypesLookups_Key).Attrs().Delete _
a_sLabel, _
enumAttrLookups.eAttrLookups_Label
a_oProject.Save

Document types

Rational RequisitePro allows documents to be organized by type. A document type serves as a template for the requirement documents. Project administrators can create and modify document types. This includes assigning a file extension, a default requirement type, and an outline for the document type. Listings 12 and 13 show examples of the code to use.

Listing 12. Create a new document type
Dim a_oDocType As ReqPro40.DocType
Set a_oDocType = a_oProject.DocTypes.Add("Test", _ 	    
' Name
"New Document Type", _' Desc
2) ' Default Reqtype
Listing 13. Modify document types
a_oDocType.Name = "Modified Test"
a_oDocType.DefReqTypeKey = 1 ' 1 corresponds to a 
     ' Reqtype key
a_oDocType.Description = "Documents of this type have modified 
					test reqs"
' When a new document of this doctype is created, its file
' extension will be set to this value.  If documents of this
' doctype exist, then the extension cannot be changed.
a_oDocType.Extension = "ModReq"

All of the properties previously shown here can be viewed and modified. Additionally, you can view or modify these properties:

  • File name of the document template:a_oDocType.TemplateFileName
  • Description for the document template:a_oDocType.TemplateDesc
  • Name of the template:a_oDocType.TemplateName

Document templates are useful for maintaining consistency across all documents of the same type. Rational RequisitePro includes several useful templates.

Document format and extended editing

Project administrators can control the format for saving documents and enable the extended editing function for the project.

Control document format, which can be viewed or modified:

a_oProject. DocSaveFormat

The Boolean value, if set, ensures that Microsoft Word documents can be opened successfully with Word outside of Rational RequisitePro.

Enable extended editing function, which can be viewed or modified:

a_oProject.DocTextEditEnabled

The Boolean value enables you to change requirement text outside of a document in any of these ways:

  • From a view
  • From Rational RequisiteWeb
  • From the RequisitePro Extensibility Interface
  • From integrated tool

Note:
This feature is provided with Rational RequisitePro Version 7.0.1 and later.

Project security

Project administrators can modify project security and user account information in these ways for all users:

  • Enabling security for user authentication and group permissions for access to requirements and documents
  • Creating and modifying user profiles and user groups

Enable or disable security for a project

Project administrators can enable or disable security for a project. By default, security is disabled, allowing unlimited user access to the project. Use the SecurityEnabled property of project object to enable or disable security of a project:

a_oProject.SecurityEnabled = True 
  a_oProject.Save

Manage groups

Project administrators can create and delete user groups. Administrators also control access to project documents and requirements by assigning document type and requirement type permissions to user groups.

Listing 14. Managing group permissions
Dim a_oProject As ReqPro40.Project
Dim a_sPath As String
Dim a_oApp As ReqPro40.Application
Dim a_oGroup As ReqPro40.Group
Dim a_sGrpName As String

a_sPath = "C:\Program"_
Files\Rational\RequisitePro\samples\Learning_Project-
Use_Cases\LEARNING - USE CASES.RQS"
a_sGrpName = "NewGroup"

Set a_oApp = New ReqPro40.Application
Listing 15. Adding a new group
If Not a_oApp Is Nothing Then
    Set a_oProject = a_oApp.OpenProject _
                    (a_sPath, eOpenProjOpt_RQSFile, "admin", "")
    If Not a_oProject Is Nothing Then
        ' Create new group with Read access
        Set a_oGroup = a_oProject.Groups.Add(a_sGrpName, _
ePermission_Read, "New Group ", ePerm_All, ePerm_All, 
ePerm_Read, ePerm_All, ePerm_All)
                
        If Not a_oGroup Is Nothing Then
            a_oProject.Save
	  End If
    End If
End If

Modify an existing group

Project administrators can change the following properties of a group (see Listing 16 for examples):

  • Name of the group
  • Description of the group
  • Permissions to manage project structure
  • Permissions to manage project security
  • Permissions of document types (edit)
  • Permissions of requirement types (edit)
Listing 16. Sample code listing at maximum width
If Not a_oApp Is Nothing Then
    Set a_oProject = a_oApp.OpenProject _
                    (a_sPath, eOpenProjOpt_RQSFile, "admin", "")
    If Not a_oProject Is Nothing Then
        Set a_oGroup = a_oProject.Groups.Item(a_sGrpName, 
eGroupLookups_Name)
                
            If Not a_oGroup Is Nothing Then
                ' Change the name of the group
                a_oGroup.Name = "ModifiedGroup1"
                ' Change the description of the group
                a_oGroup.Description = "Modify an existing Group"
    
                ' Can manage Project structure and Project 
    ' security                
    a_oGroup.ProjPermissions = ePerm_ModStructure Or 
 ePerm_ModSecurity
    ' Set default doctype permissions for the group

a_oGroup.DefDocTypePermissions = ePerm_All
    ' Set default reqtype permissions for the group
                a_oGroup.DefReqTypePermissions = ePerm_Delete
    ' Set default attribute permissions for a reqtype
                a_oGroup.DefAttrPermissions = ePerm_Update
                
                a_oProject.Save
            End If
    End If
End If

See Listings 17 and 18 for how to delete a group or transfer a user to a group.

Note:
Neither the predefined <Deleted Users> group nor the group to which the logged user belongs can be deleted.

Listing 17. Delete group
a_oProject.Groups.Delete a_sGrpName, eGroupLookups_Name
a_oProject.Save
Listing 18. Move a user to a group
Dim a_oGroup1 As ReqPro40.Group
                    
Set a_oGroup1 = a_oProject.Groups.Item("Administrators", 
eGroupLookups_Name)
a_oUser.GroupKey = a_oGroup1.Key
a_oProject.Save

Manage user profiles

Project administrators can modify user names, passwords, and e-mail addresses, as well as assign users to user groups (see Listings 19, 20, and 21). Users who do not have administrator permissions can change their own user names, passwords, and e-mail addresses.

Listing 19. Add a new user to a group
a_sUserName = "NewUser"
Set a_oUser = a_oProject.Users.Add(a_sUserName, a_oGroup.Key, "",
 "New User", "")
a_oProject.Save
Listing 20. Modify user properties
a_oUser.Name = "newuser2"
a_oUser.EMailAddress = "newuser2@example.com"
a_oUser.FullName = "New User 2"
a_oUser.ChangePassword "", "a", "a"
a_oProject.Save

Note:
The deleted user is moved to the <Deleted Users> group.

Listing 21. Delete a user from a group
a_oProject.Users.Delete a_sUserName, eUserLookups_Name
a_oProject.Save

External project connections

Project administrators can create and modify connections to external projects. These connections are required for users to create traceability between requirements in the current project and requirements in the external projects. The external projects can be configured to open automatically when the current project opens, and you can dynamically connect and disconnect the external projects while the project is open. See Listings 22, 23, and 24 for examples.

Note:
These capabilities are included with Rational RequisitePro Version 7.0.1 and later.

Listing 22. Needs a caption
Dim a_sExtProjRQS As String
Dim a_oCurProject As ReqPro40.Project
Dim a_oRelProjContexts As ReqPro40.RelatedProjectContexts
Dim a_oRelProjContext As ReqPro40.RelatedProjectContext

' Create a project
Set a_oCurProject = newProject()
Listing 23. Add external project
If Not a_oCurProject Is Nothing Then
    ' External Project
    a_sExtProjRQS = "C:\Program 
Files\Rational\RequisitePro\samples\Learning_Project-
Use_Cases\LEARNING - USE CASES.RQS"

    ' Get the related contexts object for the current Project
    Set a_oRelProjContexts = a_oCurProject.RelatedProjectContexts
        
    If Not a_oRelProjContexts Is Nothing Then
          ' Add a_sExtProjRQS as External Project
      	    Set a_oRelProjContext = 
a_oRelProjContexts.Add(a_sExtProjRQS, False)
    End If
End If

The public function Add in RelatedContexts object takes the second parameter as a flag to indicate whether the external connection is set for autoconnect or not.

Note:
These capabilities are included with Rational RequisitePro Version 7.0.1, iFix04.

Listing 24. Add external project with autoconnect
If Not a_oCurProject Is Nothing Then
    ' External Project
    a_sExtProjRQS = "C:\Program 
Files\Rational\RequisitePro\samples\Learning_Project-
Use_Cases\LEARNING - USE CASES.RQS"
        
    ' Get the related contexts object for the current Project
    Set a_oRelProjContexts = a_oCurProject.RelatedProjectContexts
        
    If Not a_oRelProjContexts Is Nothing Then
        ' Add a_sExtProjRQS as External Project
        Set a_oRelProjContext = 
a_oRelProjContexts.Add(a_sExtProjRQS, True)
    End If
End If

Note:
The code sample in Listing 24 assumes the use of admin"/" as the use ID and password to connect to the external project. If the external project has a different user ID and password, use the polymorphic function Add, which takes additional parameters for the user ID and password (see Figure 25).

Listing 25. Needs a caption
Dim a_sExtProjectName As String
Dim a_sExtProjectName As String
Dim a_sRelatedProjectContext As ReqPro40.RelatedProjectContext

a_sExtProjectName = "C:\Program 
	Files\Rational\RequisitePro\samples\Learning_Project-
	Use_Cases\LEARNING - USE CASES.RQS"

'Add external Project
Set a_sRelatedProjectContext = 
	a_oProject.RelatedProjectContexts.AddExternalProject(
			a_sExtProjectName, True, "admin", "")

Resources

Learn

  • Several useful RequisitePro Extensibility (RPX) scripts that add capabilities to Rational RequisitePro are available from IBM® developerWorks® in the RequisitePro extensibility script index. These programs are offered merely as useful examples of how to do RPX scripting, and they are not supported by IBM Rational software group. products.
  • Visit the Rational RequisitePro area on developerWorks area on developerWorks for requirements management content and resources.
  • Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  • Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
  • Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  • Browse the technology bookstore for books on these and other technical topics.

Get products and technologies

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=278580
ArticleTitle=Project administration using IBM Rational RequisitePro
publish-date=12252007