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:
|Open project with exclusive access||eProjFlag_Exclusive|
|Open project with normal access [R/W]||eProjFlag_Normal|
|Open project with read only access||eProjFlag_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 administrators have the project structure administration capabilities that the following subsections describe.
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
- 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
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)
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
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
ReqStyle can be queried from the
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
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:
- Description for the document template:
- Name of the template:
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:
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:
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
This feature is provided with Rational RequisitePro Version 7.0.1 and later.
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
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.
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 = "email@example.com" a_oUser.FullName = "New User 2" a_oUser.ChangePassword "", "a", "a" a_oProject.Save
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.
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.
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
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", "")
- 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
- Get a trial version of IBM Rational RequisitePro.
- Download trial versions of other IBM Rational software.
- Join 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.
- Check out developerWorks blogs and get involved in the developerWorks community.