CaliberRM 2008 SP1 · 2010. 12. 22. · provides an overview of working with requirement trees, ... Imports Starbase.CaliberRM.Interop ' The Initializer object is responsible for

CaliberRM™

2008 SP1

SDK Programmer’s Guide

Borland Software Corporation may have patents and/or pending patent applications covering subjectmatter in this document. The furnishing of this document does not give you any license to thesepatents.

Copyright © 1997–2009 Borland Software Corporation and/or its subsidiaries. All Borland brand andproduct names are trademarks or registered trademarks of Borland Software Corporation in theUnited States and other countries. All other marks are the property of their respective owners.

CRM06-SDKPG

March 2009

i

Table of Contents

Chapter 1Introduction 1

Chapter 2Using Visual Basic to Write SDK Applications 3

Introduction . . . . . . . . . . . . . . . . . . . . . . 3Setting up Your IDE . . . . . . . . . . . . . . . . . . 3Initializing the CaliberRM Library . . . . . . . . . . . 4Connecting To a CaliberRM Server . . . . . . . . . . 5Using Sessions . . . . . . . . . . . . . . . . . . . . 6Creating CaliberRM Objects . . . . . . . . . . . . . 6Modifying CaliberRM Objects . . . . . . . . . . . . . 7Deleting CaliberRM Objects . . . . . . . . . . . . . 8Requirements . . . . . . . . . . . . . . . . . . . . . 8

Creating Requirements . . . . . . . . . . . . . . 8Attributes and Attribute Values. . . . . . . . . . . 9List Attributes Values . . . . . . . . . . . . . . . 11Setting Attribute Values . . . . . . . . . . . . . . 13Requirement Descriptions . . . . . . . . . . . . . 14Document References . . . . . . . . . . . . . . . 15Responsibilities . . . . . . . . . . . . . . . . . . 16History . . . . . . . . . . . . . . . . . . . . . . . 17Discussions . . . . . . . . . . . . . . . . . . . . 19Requirement Trees. . . . . . . . . . . . . . . . . 20

Traceability . . . . . . . . . . . . . . . . . . . . . . 23Obtaining Traces . . . . . . . . . . . . . . . . . . 24Creating Traces Between Requirements . . . . . 24Creating Traces to Non-Requirements Software

Artifacts . . . . . . . . . . . . . . . . . . . . . 25Deleting Traces . . . . . . . . . . . . . . . . . . 26

Chapter 3Using Java to Write SDK Applications 27Introduction . . . . . . . . . . . . . . . . . . . . . . 27Creating a CaliberServer . . . . . . . . . . . . . . . 27Using Sessions . . . . . . . . . . . . . . . . . . . . 29CaliberRM Java SDK Conventions . . . . . . . . . . 29Creating CaliberRM Objects . . . . . . . . . . . . . 30Modifying CaliberRM Objects . . . . . . . . . . . . . 30Deleting CaliberRM Objects . . . . . . . . . . . . . 31Requirements . . . . . . . . . . . . . . . . . . . . . 31

Requirement Trees. . . . . . . . . . . . . . . . . 31Creating Requirements . . . . . . . . . . . . . . 35Requirement Attributes . . . . . . . . . . . . . . 36Requirement History . . . . . . . . . . . . . . . . 37

Traceability . . . . . . . . . . . . . . . . . . . . . . 38Obtaining Traces . . . . . . . . . . . . . . . . . . 39Creating Traces Between Requirements . . . . . 39Creating Traces to Non-Requirements Software

Artifacts . . . . . . . . . . . . . . . . . . . . . 40

Chapter 4Creating a Traceability Add-in for CaliberRM 41

Introduction . . . . . . . . . . . . . . . . . . . . . 41Using the Visual Basic.NET Sample. . . . . . . . . 41Traceability Add-in Interface . . . . . . . . . . . . . 42

VendorSession . . . . . . . . . . . . . . . . . . 42VendorView . . . . . . . . . . . . . . . . . . . . 43VendorObject . . . . . . . . . . . . . . . . . . . 44

Registering and Enabling Your Traceability Add-In . 45

Appendix ACaliberRM Object Model 47

ii

Chapter 1: Introduct ion 1

C h a p t e r

Chapter 1IntroductionCaliberRM promotes extensibility through the CaliberRM Software Development Kit (SDK) and a traceability add-in API.

CaliberRM SDKUsing the CaliberRM SDK, you can create, modify and delete CaliberRM information, such as projects, baselines, requirements, users, and groups. The CaliberRM SDK gives you access to all requirements data in CaliberRM through programs written in Java and any other programming language that supports .NET or COM.

This document provides the necessary information for Visual Basic and Java programmers to get started with the CaliberRM APIs.

Note: Detailed programmer’s documentation in Javadoc format is available at Program Files\Borland\CaliberRM SDK <version>\api\index.html or contact Borland support for additional information.

Important: If your existing SDK application must connect to a server not yet upgraded to this release, do not recompile your application with the SDK included in this release. In general when writing SDK applications, use the same version of the SDK as the version of the oldest server you need the application to connect to. You must recompile your .NET/COM SDK applications to make use of the new SDK functionality (create and assign security profiles, get/set user LDAP DN) provided in this release, and the recompiled application will be compatible with this release of the server.

For more information about creating SDK applications, refer to Using Visual Basic to Write SDK Applications and Using Java to Write SDK Applications sections in this guide.

Traceability Add-In TechnologyCaliberRM provides a unique way to extend your traceability information with any third party tools using its traceability add-in technology. You can create a traceability add-in to provide traceability to an external application. For example, creating a traceability add-in for Microsoft Project, allows you to easily define and manage real-time traces from requirements in CaliberRM to Tasks in Project. Once the trace has been created,

2 Cal iberRM SDK Programmer’s Guide

you can view it in the Traceability Matrix, Traceability Diagram, and report on it with Document Factory.

For more information about creating a traceability add-in refer to the Creating a Traceability Add-in for CaliberRM section in this guide.

More InformationIf you require assistance with the CaliberRM SDK, please post your request in the CaliberRM SDK Newsgroup at news://newsgroups.borland.com/borland.public.caliber-rm.sdk.

If you need to report a problem with the CaliberRM SDK, please contact support at http://support.borland.com/.

Chapter 2: Using Visual Basic to Wri te SDK Appl icat ions 3

C h a p t e r

Chapter2Using Visual Basic to Write SDKApplications

IntroductionThis chapter introduces the CaliberRM Software Development Kit (SDK) for Visual Basic programmers. This chapter:

■ describes the steps needed to set up your IDE to use the CaliberRM SDK,

■ explains the way programmers can use the SDK to connect to a CaliberRM server,

■ describes how CaliberRM information can be created, modified and deleted,

■ provides an overview of working with requirement trees, attributes and history,

■ presents an introduction to working with CaliberRM discussions,

■ explains how programmers can utilize the SDK to view, create and delete trace relationships.

Setting up Your IDETo use the CaliberRM SDK in your project, you need to set a reference to the SDK’s object library in your IDE.

Visual Studio 6.01 Click Project > Reference... on the main menu.

If you have successfully installed the CaliberRM SDK, you should see a reference named CaliberRM library in the list of available references.

2 Select CaliberRM library and click OK to save the changes.

3 If you cannot see a reference named CaliberRM library in the list of references, click Browse and locate the CaliberRMSDK DLL file on your hard disk. (Typically, the library is located in Program Files\Borland\CaliberRM SDK <version>\api\lib folder and the name of the library file is CaliberRMSDK<version>.dll.)

4 Click OK in the References dialog box.


Visual Studio .NET 20031 Click Project > Add Reference... on the main menu.

2 Click the Browse button in the Add Reference dialog box.

3 Locate CaliberRM SDK library on your hard disk and click Open. (Typically, the library is located at Program Files\Borland\CaliberRM SDK <version>\api\lib folder and the name of the library file is CaliberRMSDK<version>.NET.dll.)

4 Click OK in the Add Reference dialog box.

Visual Studio 20051 Click Project > Add Reference... on the main menu.

2 Click the Browse tab in the Add Reference dialog box.

3 Locate CaliberRM SDK library on your hard disk and click OK. (Typically, the library is located at Program Files\Borland\CaliberRM SDK <version>\api\lib folder and the name of the library file is CaliberRMSDK<version>.NET.dll.)

4 Click OK in the Add Reference dialog box.

To check if the reference to CaliberRM SDK is correctly set, perform the following:

1 Click Project > Test VBNET Properties on the main menu.

2 Click the References tab. You should see CaliberRMSDK<version>.NET in the References pane.

Now you can use CaliberRMSDK library in your code. Make sure you import CaliberRM SDK classes in your code as follows:

Initializing the CaliberRM LibraryWhenever the COM SDK is launched, the SDK launches a Java Virtual Machine (VM). The code in this section must be called prior to any other SDK calls because once the VM is loaded these options cannot be set.

COM applications can utilize the SDK’s Initilizer and IStJavaVMInfo objects, for example:

Imports Starbase.CaliberRM.Interop

' The Initializer object is responsible for loading the Java VM. Dim objInitializer As New Initializer 'IStJavaVMInfo describes a Java VM. Dim objStJavaVMInfo As IStJavaVMInfo ' Get the current VM from the initializer... Set objStJavaVMInfo = objInitializer.JavaConfiguration.CurrentJavaVM ' Set the max memory flag to 1000 MB...

objStJavaVMInfo.Options = "-Xmx1000M"


Note: By default, most VMs can only consume a maximum of 64 MB of memory. This limit can be overridden by setting the VM’s maximum memory flag (Xmx).

Specify the maximum size, in bytes, of the memory allocation pool. This value must be a multiple of 1024 greater than 2MB. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes. The default value is 64MB. For example:

■ -Xmx83886080

■ -Xmx81920k

■ -Xmx80m

If the application is not able to start Java VM and you get a Not enough space for object heap error, decrease the JVM heap size. Generally, you must specify the memory size for Java VM according to the available memory on you computer.

Connecting To a CaliberRM ServerThe first step to using the CaliberRM SDK is creating a connection to a CaliberRM server. To establish a connection, you need to create a reference to a CaliberServer object. Simply put, a CaliberServer object is used to establish and maintain a connection with a CaliberRM server on behalf of a CaliberRM user.

In the following code, a simple Visual Basic application is created that connects to a CaliberRM server:

Notice in the above example that creating a CaliberRM server reference is a two-step process. First, you must create a CaliberRM server factory:

' Declare object variables for Caliber ' server factory, server and session objects. Dim objServerFact As CaliberServerFactory Dim objServer As CaliberServer Dim objSession As Session ' Assign object references to the server and ' server factory variables. Set objServerFact = New CaliberServerFactory Set objServer = objServerFact.Create(“localhost”)

' Assign an object reference to the session ' variable by logging in to the Caliber server. Set objSession = objServer.login(“admin”, “admin”)

Set objSrvrFctry = New CaliberServerFactory


Second, you should use the server factory to produce a new server reference:

Using SessionsA Session object represents a user’s view of the CaliberRM and, as such, provides an entry point into the CaliberRM object model. In the previous example, we created a Session by logging in to a CaliberServer object. In the following code, we will use this Session to display the names of all projects available to the user.

Creating CaliberRM ObjectsThe CaliberRM SDK allows you to create, modify and delete the following objects:

■ Projects

■ Baselines

■ Users

■ Groups

■ Departments

■ Requirements

■ Requirement Types

■ Security Profiles

■ Glossaries

■ Glossary Terms

■ Integrations

To create most CaliberRM information, complete the following steps:

1 Create a factory that will produce the new object.

2 Call the factory’s Create method.

3 Call the new object’s Save method.

Set objServer = objSrvrFctry.Create(“localhost”)

' Declare object variable for a Caliber Project. Dim objProject As Project

'Iterate through each Project in the session. For Each objProject In objSession.Projects Debug.Print objProject.Name Next objProject


The following sample follows these steps to create a new User object.

Modifying CaliberRM ObjectsTo modify a CaliberRM object, complete the following steps:

1 Obtain an instance of a CaliberRM object.

2 Call the object’s Lock method.

3 Set one or more of the object’s properties.

4 Call the object’s Save method.

See the example on the following page.

' Create a factory that will be used to produce new User objects. Set objUserFactory = New UserFactory

' Create a new User object. Set objNewUser = objUserFactory.Create(“jdoe”, objSession)

' Set the properties of the new User object. objNewUser.FirstName = “John” objNewUser.LastName = “Doe” ' Save the new User object. objNewUser.save

' Get a Group object. Set objGroup = objSession.Groups.Item(2) ' Lock the Group. objGroup.lock ' Modify the Group's properties. objGroup.Name = “New Name” objGroup.EmailAddress = “New Email Address” objGroup.Description = “New Description” ' Save the modified Group. objGroup.save


Deleting CaliberRM ObjectsYou can delete a CaliberObject from CaliberRM by calling its Remove method. For example:

Note that the Remove method only deletes a requirement from the current baseline. The requirement is not removed from any previous baselines.

RequirementsThis section details creating, modifying and deleting requirements.

Creating Requirements

SDK provides two methods for creating new requirements. The first method allows you to create requirements at the top level of a project’s requirement tree hierarchy. The second is used to create children of an existing requirement.

In the following example, the first create method (Create1) is used to create a new requirement.

In the previous example, notice that a zero is passed as the 4th parameter to Create1. This indicates the index in the project’s requirement tree where this new requirement is inserted.

Dim objRequirement As RequirementSet objRequirement = objSession.getRequirement(1)objRequirement.remove

' Get the first Project in the session's collection Set objProject = objSession.Projects.Item(0) ' Get the first Requirement Type in the project. Set objType = objProject.CurrentBaseline.RequirementTypes.Item(0) ' Create a factory for new Requirement objects. Set reqFactory = New RequirementFactory ' Create a new Requirement. Set newRequirement = reqFactory.Create1( _

“New Requirement”, _ objProject, _ objType, _ 0, _ objSession) newRequirement.save ““


The following example illustrates how the second create method (Create2) is used to create a requirement that is a child of an existing requirement.

Attributes and Attribute Values

CaliberRM allows you to define requirements with any number of user-defined attributes (UDAs.) Additionally, all requirements contain a Status and Priority system attribute. Likewise, in the CaliberRM SDK, a Requirement object provides Status, Priority, and AttributeValues properties that return its Status, Priority and UDAs values respectively.

In the CaliberRM SDK, Attribute objects represent a type of CaliberRM attribute while AttributeValue objects represent an instance of a type.

The following table describes the relationship between CaliberRM Attributes and the SDK’s Attribute and AttributeValue objects.

CaliberRM Attributes SDK Attribute SDK AttributeValue

Single Text Line

Multiple Line Text Field

UDAText UDATextValue

Long Integer UDAInteger UDAIntegerValue

Duration UDADuration UDADurationValue

Float UDAFloat UDAFloatValue

Date UDADate UDADateValue

Boolean UDABoolean UDABooleanValue

Multiple Selection List

Single Selection List

Multiple Selection Group List Single Selection Group List Multiple Selection User List Single Selection User List

UDAList UDAListValue

' Create a factory for new Requirement objects. Set reqFactory = New RequirementFactory

' Get a Requirement that will be a parent of the new Requirement. Set parentReq = objSession.getRequirement(1) ' Create a new Requirement that will be a child of parentReq Set newChildRequirement = reqFactory.Create2( _

“New Child Requirement”, _ parentReq, _ 4, _ objSession)


The following code shows how Attribute objects are obtained from a requirement type:

Likewise, you can obtain AttributeValue objects from a requirement. The following example displays the same list as the previous example but also adds the value:

Notice in this example the AttributeValue’s attribute property to obtain the name is used:

' Get the first Requirement Type in the session.Set objRequirementType = objSession.RequirementTypes.Item(0)

' Get the first Custom Tab in the Requirement TypeSet objCustomTab = objRequirementType.CustomTabs.Item(0)

' Print the name of the Attributes assigned to the Custom TabDim objAttribute As CaliberRM.AttributeFor Each objAttribute In objCustomTab.attributes Debug.Print vbTab & vbTab & objAttribute.NameNext objAttribute

Dim objAttribValue As AttributeValue

' Loop through all attribute values For Each objAttribValue In objRequirement.AttributeValues ' Print the name of the attribute and it's value Debug.Print _

objAttribValue.Attribute.Name _ & “ = “ _ & objAttribValue.Value

Next objAttribValue

objAttribValue.Attribute.Name


You can use this property any time you need to obtain an AttributeValue’s type. The example below illustrates dealing with a certain type of Attribute and AttributeValue.

List Attributes Values

As previously mentioned, a UDAListValue object embodies all list attribute values that are assignable to a requirement. This section contains practical examples that show how a UDAListValue object can be used to display single and multiple selection lists.

' Loop through all attribute values. For Each objAttribValue In objRequirement.AttributeValues

' Look for a UDATextValue. If TypeOf objAttribValue Is UDATextValue Then

' Cast the AttributeValue to a UDATextValue. Dim textValue As UDATextValue Set textValue = objAttribValue

' Cast the Attribute to a UDAText. Dim textAttribute As UDAText Set textAttribute = objAttribValue.Attribute

' Print information specific to the value. Debug.Print _ “The value of the UDATextValue is: “ _ & textValue.Value

' Print information specific to the value's type. Debug.Print _ “The maximum length this value can be: “_ & textAttribute.MaximumLength

Debug.Print _ “The minimum length this value can be: “_ & textAttribute.MinimumLength End If

Next objAttribValue


The example below displays the list entries and selected value of a requirement’s status list.

This code can be modified to display a Single Selection User List:

Notice in the above example a Single Selection User List is singled out from a collection of attributes by comparing the UITypeName property of its attribute against the UI_NAME_SSL constant:

Private Sub Form_Load() ... Dim objRequirement As Requirement Set objRequirement = objSession.getRequirement(1) PrintList objRequirement.StatusEnd Sub

Private Sub PrintList(objListValue As UDAListValue) ' Print the list entries Debug.Print “List Entries(s):” Dim listEntry As UDAListEntry For Each listEntry In objListValue.ListEntries Debug.Print listEntry.Object Next listEntry ' Print the selected value Debug.Print “Selected Value = “& objListValue.selectedValueEnd Sub

Private Sub PrintSSUserList(objReq As Requirement) Dim objAttribValue As CaliberRM.AttributeValue ' Iterate through all attributes associated with the ' supplied Requirement For Each objAttribValue In objReq.AttributeValues ' Only print “Single Selection User List” attributes. Set objAttribute = objAttribValue.Attribute If objAttribute.UITypeName = objAttribute.UI_NAME_SSUL Then ' Print the user list entries Debug.Print “User List Entries(s):”

Dim listEntry As UDAListEntry For Each listEntry In objAttribValue.ListEntries Debug.Print listEntry.Object.Name Next listEntry Debug.Print “Selected Value: “ & _ objAttribValue.SelectedValue.Name End If Next objAttribValue End Sub

If objAttribute.UITypeName = objAttribute.UI_NAME_SSUL Then


However, you could select an attribute from the collection by name. For example:

The UDAListValue object can also represent Multiple Selection List values. For example, the following code prints out the Name and Selected property of each element in a Multiple Selection Group List value:

Setting Attribute Values

To modify a requirement’s attribute values, complete the following steps:

1 Obtain a requirement.

2 Call the requirement’s Lock method.

3 Determine the types of Attribute Values (i.e. UDATextValue, UDAListValue) the requirement contains.

4 Modify the requirement’s AttributeValue objects based on their type.

5 Update the requirement by setting its AttributeValue property to the new value.

6 Call the requirement’s Save method.

See the example on the following page.

If objAttribute.Name = "My SSUL Attribute" Then

Dim listEntry As UDAListEntry For Each listEntry In objAttribValue.ListEntries ' Use the 'Selected' property of the list entry to ' to determine if the group is selected If listEntry.Selected Then Debug.Print listEntry.Object.Name & “ *** Selected ***"“ Else Debug.Print listEntry.Object.Name End If Next listEntry


Requirement Descriptions

In CaliberRM, a requirement description can be either a text string or a participant in a mapped/shared description relationship. A requirement’s description is shared when it is used by other requirements. Conversely, a requirement’s description is mapped when the requirement uses another requirement description as its own.

The CaliberRM SDK provides three classes that represent the possible states for a requirement’s description: RequirementDescription, RequirementDescriptionMapped and RequirementDescriptionShared. All of these

Set objRequirement = objSession.getRequirement(1) objRequirement.lock ' Loop through all attribute values in the Requirement.Dim objAttribValue As AttributeValueFor Each objAttribValue In objRequirement.AttributeValues

If TypeOf objAttribValue Is UDABooleanValue Then' If value is a Boolean UDA Value then set the new' value to the opposite of the current value.objAttribValue.Value = Not objAttribValue.Value

ElseIf TypeOf objAttribValue Is UDATextValue Then

' If the value is a Text UDA Value then set the' new value equal to the current time.objAttribValue.Value = Time

ElseIf TypeOf objAttribValue Is UDAIntegerValue Then' If the value is a Integer UDA Value then increment' the value by one.objAttribValue.Value = objAttribValue.Value + 1

ElseIf TypeOf objAttribValue Is UDAListValue ThenIf objAttribValue.MaximumSelections = 1 Then' If the value is a Single Selection List Value then' increment the selected index by 1.objAttribValue.SelectedIndex = _

objAttribValue.SelectedIndex + 1End If

End If' Update the Requirement object with the new valueobjRequirement.AttributeValue = objAttribValue

Next objAttribValue ' Save the modified RequirementobjRequirement.save “Modifying UDA Values”


description objects contain a Text property that allows you to obtain the text of a description. Therefore, the following code snippet works for all requirements:

To modify a requirement’s description you simply set the requirement’s Description property to a new RequirementDescription or RequirementDescriptionMapped object. For example, the following code creates a simple text description (Lock and Save method calls have been omitted for clarity):

The following example creates a simple HTML description for the requirement.

In the next example, the description of Requirement #1 to Requirement #2 is mapped.

Document References

The CaliberRM SDK provides three types of Document Reference objects: FileReference, TextReference and WebReference. You can create each of these reference objects and add them to a requirement’s DocumentReferences property. The example on the following page creates an instance of each of these objects and uses these objects to modify a requirement.

Debug.Print req.Description.Text

' Create a factory that will produce descriptions. Dim descriptionFactory As New RequirementDescriptionFactory ' Create a new description object and use it to set the Requirement's' Description property.req.Description = descriptionFactory.Create(“A new description.”)

' Create a factory that will produce descriptions.Dim descriptionFactory As New RequirementDescriptionFactory ' Create a new description object and use it to set the Requirement's ' Description property.req.Description = descriptionFactory.Create(“<html><body>A new <i><b>formatted description.</b></i></body></html>”)

Set req1 = objSession.getRequirement(1)Set req2 = objSession.getRequirement(2)' Create a factory that will produce mapped descriptions. Dim mapDescriptionFactory As New RequirementDescriptionMappedFactory' Create a new mapped description and use it to set Requirement 1's' Description property. req1.Description = mapDescriptionFactory.Create(req2, objSession)


In the above example, notice that the first thing that was done was the creation of a new collection using CollectionFactory’s CreateByIStCollection method. This is necessary because a requirement’s DocumentReferences property is a read-only collection and cannot be modified.

Responsibilities

Typically, several individuals are assigned as responsible users for each requirement in CaliberRM. You can obtain these users, and their corresponding groups, through a requirement’s Responsibilities property which is a collection of GroupMemberAssignment objects.

' First, we must copy the Requirement's existing collection of' references into a collection that can be modified.Dim colFactory As New CollectionFactorySet docRefs = colFactory.CreateByIStCollection(req.DocumentReferences) ' Create and add a text reference to the docRefs collection.Dim textRefFactory As New TextReferenceFactorydocRefs.Add textRefFactory.Create("Text Reference") ' Create and add a web reference to the docRefs collection.Dim webRefFactory As New WebReferenceFactorydocRefs.Add webRefFactory.Create(“www.microsoft.com”) ' Create and add a file reference to the docRefs collection.Dim fileRefFactory As New FileReferenceFactorydocRefs.Add fileRefFactory.Create(“C:\foo.txt”) ' Set the references and save.req.lockreq.DocumentReferences = docRefsreq.save ““


The following code unassigns all users who are responsible for a requirement.

History

The CaliberRM SDK allows for complete access to requirement history records. To obtain a requirement’s history, you can use the History property of any Requirement object. The following code demonstrates how to use these objects to display history revisions:

Now we can expand this example to include information about the individual changes that comprise these revisions. The code on the following page iterates through all HistoryChange objects for a HistoryRevision, prints the name of the requirement field that changed, the type of change that occurred and the field’s old and new values.

' Get the collection of GroupMemberAssignment objects ' that comprise the Requirement's responsibilities. Dim gmaCollection As CaliberRM.Collection Set gmaCollection = req.responsibilities ' Iterate through all GroupMemberAssignment objects ' in the collection. Dim gma As GroupMemberAssignment For Each gma In gmaCollection 'Iterate through all assigned members... Dim assignedMember As User For Each assignedMember In gma.AssignedMembers ' ... and unassign each. gma.removeAssignedMember assignedMember Next assignedMember Next gma ' Lock the Requirement, set its responsibilities and save. req.lock req.responsibilities = gmaCollection req.save ““

Dim revision As HistoryRevision For Each revision In objReq.History.Revisions Debug.Print “Major Ver: “ & revision.Version.MajorVersion Debug.Print “Minor Ver: “ & revision.Version.MinorVersion Debug.Print “Date: “ & Format(revision.OLEDate, “d-mmm”) Debug.Print “User Name: “ & revision.UserName Debug.Print “Comment: “ & revision.Comment Next revision


The OldValue and NewValue properties of a Change object represent the value of a requirement field before and after a change occurs. To work with these objects, you need to separate them by type. As a rule, a change value object is one of the following three types:

■ String: represents changes to non-UDA text fields such as a requirement’s name or description.

■ Attribute: represents changes to all user-defined and system attributes.

■ User: represents changes to a requirement’s owner field.

The following subroutine (called twice in the previous example) separates these OldValue and NewValue objects by String, Attribute and User.

Dim objChange As HistoryChange For Each objChange In revision.Changes Debug.Print “Field Name: “ & objChange.FieldName Debug.Print “Type: “ & ChangeTypeToString(objChange.changeType) Debug.Print “Old Value: “ & VariantToString(objChange.OldValue) Debug.Print “New Value: “ & VariantToString(objChange.NewValue) Next objChange

' Converts the specified variant to a string.Private Function VariantToString(ByVal vntValue As Object) As String

' Filter out any null changes. If IsNull(vntValue) Then VariantToString = “[NULL]”

' If its a string already then just return it. ElseIf VarType(vntValue) = vbString Then VariantToString = vntValue

Else ' “Narrow” the variant down to an object. Dim objValue As Object objValue = vntValue

' If the object is a CaliberObject then return it ' name attribute... If TypeOf objValue Is CaliberObject Then VariantToString = objValue.Name

' Print User Defined and System attribute changes. ElseIf TypeOf objValue Is AttributeValue Then VariantToString = UDAValueToString(objValue)

Else VariantToString = ““ End If

End IfEnd Function


Note that the first thing this code does is ensure the Variant passed into this subroutine is not null. Typically, a null change object emerges when a UDA has been added or removed from a requirement’s type.

Also note that the handler for AttributeValue objects calls the UDAValueToString function:

This conversion function (listed below) illustrates how different types of AttributeValue objects can be handled in a generic manner.

Discussions

CaliberRM allows project teams to provide feedback on requirements and projects through its Group Discussion feature. Likewise, the CaliberRM SDK allows programmers to view discussions about requirements and projects.

The following subroutine takes a CaliberObject and displays information about each of its discussion messages. This is accomplished by using the Discussion property for the specified CaliberObject. Note that this subroutine exits if this CaliberObject is not a

ElseIf TypeOf objValue Is AttributeValue Then VariantToString = UDAValueToString(objValue)

' Converts an AttributeValue (also know as UDA Value) to a String.Function UDAValueToString(ByVal objValue As AttributeValue) As String

' First, handle all AttributeValue objects whose ' “Value” attribute converts easily to a string... If TypeOf objValue Is UDABooleanValue _ Or TypeOf objValue Is UDAFloatValue _ Or TypeOf objValue Is UDAIntegerValue _ Or TypeOf objValue Is UDATextValue Then UDAValueToString = objValue.Value

ElseIf TypeOf objValue Is UDADateValue Then UDAValueToString = Format(objValue.OLEDate, “d-mmm”)

ElseIf TypeOf objValue Is UDADurationValue Then UDAValueToString = objValue.Value _ & objValue.Attribute.GranularityTextElseIf TypeOf objValue Is UDAListValue Then UDAValueToString = “Selected List Entries: “ For Each objListEntry In objValue.ListEntries If objListEntry.Selected = True Then UDAValueToString = UDAValueToString & _ VariantToString(objListEntry.Object) & _ “,” End If Next objListEntry End If

End Function


Requirement or Project object since only requirements and projects can have discussions.

The CaliberRM SDK also allows you to post discussion messages through the Discussion object’s postMessage method. Likewise, you can reply to discussion messages by using DiscussionMessage’s postReply method. The following example illustrates the use of these two methods.

Requirement Trees

Typically, hierarchical relationships exist between sets of requirements in a CaliberRM baseline. Taken together, these requirements comprise a Requirement Tree. The RequirementTree and RequirementTreeNode objects provide valuable options for working with these trees.

You can traverse the nodes of a Requirement Tree by:

1 Obtaining a RequirementTree object from a baseline.

2 Accessing the RequirementTree’s Root property to obtain the root RequirementTreeNode.

3 Recursively calling the RequirementTreeNode’s Children property.

Private Sub PrintDiscussion(objCaliberObj As CaliberObject) ' Only Projects and Requirements can have discussions. If Not TypeOf objCaliberObj Is Project _ And Not TypeOf objCaliberObj Is Requirement Then Exit Sub End If Dim objDiscussion As Discussion Set objDiscussion = objCaliberObj.Discussion Dim objMessage As DiscussionMessage For Each objMessage In objDiscussion.Messages intTab = objMessage.Depth * 5 Debug.Print Tab(intTab); “Subject: “ & objMessage.Subject Debug.Print Tab(intTab); “Have read: “ & objMessage.Read Debug.Print Tab(intTabDepth); “Date: “ & _ Format(objMessage.OLEDate, “d-mmm”) Next objMessage End Sub

' Get a Requirement's discussion. Set objDiscussion = req.Discussion ' Post a message to the discussion. Set objMessage = objDiscussion.postMessage(“My Subject”, “My Message”) ' Post a reply to the new message. objMessage.postReply “Re: My Subject”, “My Reply”


The following code follows these steps to print out information about each and every node in a Requirement Tree.

A RequirementTreeNode can represent either a project, requirement type or requirement node in a Requirement Tree. A RequirementTreeNode object contains the minimum data necessary to represent the CaliberRM object that it is associated with. For example, if a node is associated with a Project object then you can obtain the project’s name and ID number through RequirementTreeNode; however, you cannot directly obtain the project’s description and baselines.

... ' Get baseline's requirement tree... Dim objRequirementTree As RequirementTree Set objRequirementTree = objBaseline.RequirementTree

' Traverse the tree starting at the root node... TraverseTree objRequirementTree.Root End Sub

' Traverses the subtree rooted at the specified node depth-first ' and prints information about each node. Private Sub TraverseTree(ByVal parent As RequirementTreeNode)

' Print information about the parent node... Debug.Print _ String(parent.Level, vbTab) _ & parent.HierarchyNumber _ & “ “ _ & parent.Name _ & “ “ _ & parent.SerialNumberTag

' Recursively call this function for ' each of the parent's children... Dim child As RequirementTreeNode For Each child In parent.Children TraverseTree(child) Next child

End Sub


To obtain the full object that is associate with a RequirementTreeNode, you should use RequirementTreeNode’s AssociatedObjectID property. For example:

You can modify a requirement tree using RequirementTreeNode’s addChild and insertChild methods. The following example uses the addChild method to add the second requirement node in a requirement tree to the first requirement node.

You can also traverse requirement trees using a baseline’s Requirements collection in conjunction with the requirement’s ChildRequirements collection. It should be noted, however, that this method of tree traversal is significantly more resource intensive than using RequirementTree and RequirementTreeNode because you are requesting the entire Requirement objects from the remote CaliberRM server.

The example on the following page uses these collections to display the first two levels of a requirement tree.

' Get the ID of the CaliberObject that the node represents Dim id As CaliberObjectID Set id = objRequirementTreeNode.AssociatedObjectID

' Get the CaliberObject that the node represents Dim co As CaliberObject Set co = objSession.get(id) ' Print an attribute specific to the CaliberObject subtype... If TypeOf co Is Project Then ' Print the Project's Description Debug.Print co.Description

ElseIf TypeOf co Is RequirementType Then ' Print the Type's Tag Debug.Print co.Tag

ElseIf TypeOf co Is Requirement Then ' Print the Requirement's Description Debug.Print co.Description.Text End If

... ' Get the project node. This will always be the root node. Set objProjectNode = objRequirementTree.Root

' Get the first Requirement Type node under the project node. Set objTypeNode = objProjectNode.Children.Item(0) ' Get the first and second Requirements under the Requirement Type. Set firstRequirementNode = objTypeNode.Children.Item(0) Set secondRequirementNode = objTypeNode.Children.Item(1)

' Add the second Requirement to the first. firstRequirementNode.addChild secondRequirementNode

' Save the changes to the tree. objRequirementTree.save


You can also traverse from child to parent by using a requirement object’s ParentRequirement property. For example, the following procedure prints the path from a given requirement to the root requirement in its tree.

Traditionally, CaliberRM applications have displayed all top-level tree requirements as grouped and sorted by requirement type; therefore, the Requirements property of a Baseline object always returns requirements sorted and grouped this way.

Note: You can determine a requirement’s project, baseline and type by accessing its Project, Baseline and Requirement Type properties respectively.

TraceabilityIn CaliberRM, a trace relationship can exist between two requirements and between a requirement and an object external to CaliberRM. Similarly, the CaliberRM SDK supports the creation, deletion and modification of traces between both CaliberRM requirements and non-requirements software artifacts.

' Declare variables for Project and Baseline objects. Dim firstProject As Project Dim curBaseline As Baseline ' Set the Project variable to reference the first ' Project in the Session's collection of Projects. Set firstProject = objSession.Projects.Item(0) ' Set the Baseline variable to reference the ' "Current" Baseline in the first Project. Set curBaseline = firstProject.CurrentBaseline

' Declare a variable that will temporarily hold ' the first level of Requirements in the tree Dim parentReq As Requirement' Iterate through the first level of Requirements For Each parentReq In curBaseline.Requirements Debug.Print parentReq.Name Dim childReq As Requirement ' Iterate through all children of ' the current parent Requiremennt For Each childReq In parentReq.ChildRequirements log vbTab & childReq.Name Next childReq

Next parentReq

Private Sub PrintPathToRoot(ByVal objRequirement As Requirement) Do While Not objRequirement Is Nothing Debug.Print objRequirement.Name Set objRequirement = objRequirement.ParentRequirement Loop End Sub


Some of the more important trace-related objects are:

■ Trace: represents a trace relationship between two CaliberRM objects. These CaliberRM objects can be requirements or objects that reside outside CaliberRM.

■ TraceManager: provides the functionality for creating, modifying and deleting traces.

■ XGenericObjectManager: provides the functionality for creating traces between requirements and non-requirements software artifacts.

■ VendorAddIn: represents a reference to an object that resides within the realm of another application. Software vendors whose applications implement CaliberRM’s Traceability add-in module supply these objects.

Obtaining Traces

The CaliberRM SDK allows you to retrieve traces at many levels of the CaliberRM object model. For instance, the Session object provides a Traces property that returns all traces between all CaliberRM objects available to you. Furthermore, the Traces property of a Project object returns all traces that trace to or from the requirements that it contains. Finally, the Requirement object provides two properties for getting traces: TracesFrom and TracesTo.

The following example uses these TracesTo and TracesFrom properties to print out the names of objects tracing to or from a requirement.

Creating Traces Between Requirements

The TraceManager object allows for the creation and modification of trace relationships. The first step in creating a trace is to obtain a reference to this object:

Private Sub PrintTraces(objRequirement As Requirement) Dim objTrace As CaliberRM.Trace Debug.Print “Objects tracing from “ & objRequirement.Name For Each objTrace In objRequirement.TracesFrom ' The following Trace is to our Requirement ' FROM some other object. Debug.Print objTrace.FromObject.Name _ & vbTab _ & objTrace.Suspect Next objTrace Debug.Print “Objects tracing to “ & objRequirement.Name For Each objTrace In objRequirement.TracesTo ' The following Trace is from our Requirement ' TO some other object. Debug.Print objTrace.ToObject.Name _ & vbTab _ & objTrace.Suspect Next objTrace End Sub

Dim objTraceManager As TraceManager Set objTraceManager = objSession.TraceManager


Once you have obtained a TraceManager, you can use it to create traces. The following example creates a trace relationship between two requirements.

Creating Traces to Non-Requirements Software Artifacts

The previous example showed how a trace relationship could be created between two objects (both requirements) that reside within CaliberRM. The following example uses the XGenericObjectManager object to create a trace between a requirement and an object that resides outside of CaliberRM.

The XGenericObjectManager also provides a function for creating traces between two external VendorAddIn objects.

Dim req1 As Requirement Set req1 = objSession.getRequirement(1) Dim req2 As Requirement Set req2 = objSession.getRequirement(2)

objTraceManager.createTrace3 req1, req2, False

... Dim req1 As Requirement Set req1 = objSession.getRequirement(1) Dim objIntegrationMgr As IntegrationManager Set objIntegrationMgr = objSession.IntegrationManager ' Create a trace from req1 to the ABCObject provided ' by the ABCCorp objIntegrationMgr. createTrace2 _ req1, _ True, _ "ABCCorp", _ “ABCObjectID” ...

objIntegrationMgr. createTrace1 _ “ABCCorp”, _ “ABCObjectID”, _ “XYZCorp”, _ “XYZObjectID”


Deleting Traces

To delete a trace, use the TraceManager object’s deleteTrace method. For example, the following subroutine deletes all traces from a given requirement:

See “Appendix A: CaliberRM Object Models” for diagrams that can be used to locate the object you want to work with, and to understand how that object fits into the overall CaliberRM object model.

Private Sub DeleteTraces(objRequirement As Requirement) Dim objTraceManager As TraceManager Set objTraceManager = objSession.TraceManager Dim objTrace As Trace For Each objTrace In objRequirement.TracesFrom objTraceManager.deleteTrace objTrace Next objTrace End Sub

Chapter 3: Using Java to Wri te SDK Appl icat ions 27

C h a p t e r

Chapter 3Using Java to Write SDKApplications

IntroductionThis chapter provides an introduction to the CaliberRM SDK for Java programmers. This chapter:

■ explains the way programmers can use the SDK to connect to a CaliberRM server,

■ describes the conventions used by the SDK,

■ provides an overview of working with requirement trees, attributes and history,

■ explains how the SDK can be used to view and create trace relationships.

Creating a CaliberServerAll applications that use the CaliberRM SDK must first create a connection to a CaliberRM server. To establish a connection, you need to create a new instance of the CaliberServer class. A CaliberServer class is used to establish and maintain a connection with a CaliberRM server on behalf of a CaliberRM user.


In the following code, a simple Java application is created that connects to a CaliberRM server:

This code demonstrates the basic steps that every CaliberRM application must take:

■ import the pertinent CaliberRM packages,

■ create a CaliberRM server,

■ login to the CaliberRM server.

The first line imports the main CaliberRM package:

This package contains the Session class. For more information on the Session class, see “Using Sessions” on page 29.

The second line imports the CaliberRM server package:

This package contains all classes relating to server connections, transactions and exceptions. The CaliberServer class is contained in this package.

The following code creates an instance of CaliberServer, which is used to communicate with the CaliberRM server that resides on host “foo:”

import com.starbase.caliber.*; import com.starbase.caliber.server.*;

public class ConnectionCreator { public static void main(String[] args) { CaliberServer server = new CaliberServer(“foo”);try { Session session = server.login(“admin”, “admin”);

} catch(RemoteServerException rse) { rse.printStackTrace();

} } }

import com.starbase.caliber.*;

import com.starbase.caliber.server.*;

CaliberServer server = new CaliberServer(“foo”);


Finally, logging in to the CaliberServer creates a new Session object:

In the above example, the login method throws a RemoteServerException if a client is unable to login to a remote CaliberRM server. Typically, a login fails if an incorrect user ID or password is supplied to the login method. For more information on RemoteServerException, see “CaliberRM Java SDK Conventions”, below.

Note: Whenever the Java SDK is launched, the SDK launches a Java Virtual Machine (VM). By default, most VMs can only consume a maximum of 64 MB of memory. This limit can be overridden by setting the VM’s maximum memory flag (Xmx).

For Java SDK applications, this flag can be set on the command line, for example:

This code must be called prior to any other SDK calls because once the VM is loaded these options cannot be set.

Using SessionsA Session represents a user’s view of a CaliberRM server and, as such, provides an entry point into the CaliberRM object model. In the following code, we use the Session created in the previous example to display the names of all CaliberRM projects available to the user.

CaliberRM Java SDK ConventionsThe two previous examples illustrate various CaliberRM SDK conventions. First, whenever an SDK method depends on a CaliberRM server to perform an operation, that method is declared as throwing RemoteServerException. Typically, a RemoteServerException “wraps” an exception that is thrown by the remote server. You can get a detailed message describing this wrapped exception by calling the exception’s getMessage method.

Second, all methods that return multiple objects return those objects in arrays.

try { Session session = server.login("jdoe", "1234ABC");

} catch(RemoteServerException rse) { rse.printStackTrace();}

java -Xmx1000M com.company.SDKApp

try{ Project[] arrayOfProjects = session.getProjects();

for(int i = 0; i < arrayOfProjects.length; i++) { System.out.println(arrayOfProjects[i].getName());

}} catch(RemoteServerException) {

rse.printStackTrace();}


Finally, the CaliberRM SDK adheres to the naming standards established by the core Java APIs. The following table illustrates these rules.

Creating CaliberRM ObjectsThe CaliberRM SDK allows you to create, modify and delete the following objects:

■ Projects

■ Baselines

■ Users

■ Groups

■ Departments

■ Requirements

■ Requirement Types

■ Security Profiles

■ Glossaries

■ Glossary Terms

■ Integrations

The following sample code shows the typical pattern for creating CaliberRM objects:

Modifying CaliberRM ObjectsTo modify a CaliberRM object, complete the following steps:

1 Obtain an instance of a CaliberRM object.

2 Call the object’s Lock method.

3 Set one or more of the object’s properties.

4 Call the object’s Save method.

Group Rules Examples

Getter/Setter Methods getXxxxsetXxxx getName() setName()

Boolean Methods isXxxx isEstablished()

isKeyReference()

Event Listener Interfaces XxxxListener ServerConnectionListener

ServerTransactionListener

Event Listener Registration

addXxxxListener addServerConnectionListener

addServerTransactionListener

Event Handler Methods onXxxx onConnectionEstablished

onServerTransaction

Event Classes XxxxEvent ServerTransactionEvent

ServerConnectionEvent

User newUser = new User(“A New User”, session);newUser.save();


The following example follows these steps to modify a Group object:

Deleting CaliberRM ObjectsYou can delete a CaliberObject from CaliberRM by calling its Remove method. For example:

Note that the remove method only deletes a requirement from the current baseline. The requirement is not removed from any previous baselines.

RequirementsThis section of the document describes the basics for working with Requirement objects.

Requirement Trees

Typically, hierarchical relationships exist between sets of requirements in a CaliberRM baseline. Taken together, these requirements comprise a requirement tree. The RequirementTree and RequirementTreeNode classes provide valuable options for working with these trees.

You can traverse the nodes of a requirement tree by:

■ obtaining a RequirementTree object from a Baseline.

■ calling the RequirementTree's getRoot method to obtain the root RequirementTreeNode.

■ recursively calling the RequirementTreeNode’s getChildren method.

Group group = session.getGroups()[2];group.lock();group.setDescription("A New Description");group.setEmailAddress("[email protected]");group.save();

Requirement requirement = session.getRequirement(77);requirement.remove();


The following code follows these steps to print out information about each and every node in a requirement tree.

This code produces output similar to the following:

You can also traverse a requirement tree by utilizing RequirementTreeNode’s getDepthFirstEnumeration and getBreadthFirstEnumeration methods. To illustrate

... // Get current baseline's tree. RequirementTree tree = currentBaseline.getRequirementTree(); // Get the tree's root node. RequirementTreeNode root = tree.getRoot(); TraverseTree(root);}

public void TraverseTree(RequirementTreeNode parentNode) {

// Print relevant information about the current node. PrintTreeNode(parentNode);

// Iterate through the parent's collection of children... RequirementTreeNode[] children = parentNode.getChildren(); for (int i = 0; i < children.length; i++) { TraverseTree(children[i]);}}private void PrintTreeNode(RequirementTreeNode node) { StringBuffer sb = new StringBuffer(); for(int i = 0; i < node.getLevel(); i++) { sb.append(“ “); } sb.append(node.getHierarchyNumber()); sb.append(“ “); sb.append(node.getName()); sb.append(“ “); sb.append(node.getSerialNumberTag()); System.out.println(sb);}

X100 Droid 2016412 Business Requirements BR2016416 1 Operating Environment BR1 1.1 Temperature BR2 1.2 Humidity BR3 1.3 Radiation BR4 2 Continuous operation BR5 2.1 Recharge Time BR73 3 Startup time BR6


this point, the following code represents a portion of the code above using the getDepthFirstEnumeration method:

A RequirementTreeNode in a requirement tree can represent either a project, requirement type or requirement. To obtain the ID of the CaliberObject that is associated with a RequirementTreeNode, you should use RequirementTreeNode’s getAssociatedObjectID method. For example:

// Get current baseline's tree.RequirementTree tree = currentBaseline.getRequirementTree();

// Get the tree's root node.RequirementTreeNode root = tree.getRoot();

// Get an enumeration of all of the nodes that descend from the// root.Enumeration nodes = root.getDepthFirstEnumeration();

// Iterate through all nodes...while(nodes.hasMoreElements()) { RequirementTreeNode node = (RequirementTreeNode)nodes.nextElement(); PrintTreeNode(node); }

// Get the ID of the CaliberObject associated with the node.CaliberObjectID coid = node.getAssociatedObjectID();

// Get the CaliberObject using the CaliberObjectID.CaliberObject co = session.get(coid);if(co instanceof Project) { // Print project specific information. Project p = (Project)co; System.out.println(p.getDescription());

} else if(co instanceof RequirementType) { // Print type specific information. RequirementType rt = (RequirementType)co; System.out.println(rt.getTag());

} else { // Print requirement specific information. Requirement r = (Requirement)co; System.out.println(r.getStatus().getSelectedValue());}


You can modify a requirement tree using RequirementTreeNode’s addChild and insertChild methods. The following example uses the addChild method to add the second requirement node in a requirement tree to the first requirement node.

Requirement trees can also be traversed by using baseline’s getRequirements method in conjunction with the requirement’s getChildRequirements method. It should be noted however, that this method of tree traversal is significantly more resource intensive than using RequirementTree and RequirementTreeNode because you are requesting the entire Requirement objects from the remote CaliberRM server.

The following example uses these methods to display the first two levels of a requirement tree.

RequirementTree tree = currentBaseline.getRequirementTree();

// Get the project node. This will always be the root node.RequirementTreeNode projectNode = tree.getRoot();

// Get the first Requirement Type node under the project node.RequirementTreeNode typeNode = projectNode.getChildAt(0);

// Get the 1st and 2nd requirements under the Requirement Type.RequirementTreeNode requirementNode1 = typeNode.getChildAt(0);RequirementTreeNode requirementNode2 = typeNode.getChildAt(1);

// Modify the tree by adding the second node to the first.requirementNode1.addChild(requirementNode2);

// Commit the changes.tree.save();

try { // Get the default/current Baseline Baseline defaultBaseline = project.getDefaultBaseline();

// Get the first-level of Requirements in the Baseline's // Requirement tree. Requirement[] topLvlReqs = defaultBaseline.getRequirements(); // Iterate through the first-level of Requirements

for(int i; i < topLvlReqs.length; i++) { Requirement req = topLvlReqs [i];

System.out.println(req.getName());

// Get the “children” of the current Requirement Requirement[] childReqs = req.getChildRequirements();// Iterate through the children. for(int j; j < childReqs.length; j++) { Requirement childReq = childReqs[j];

System.out.println(“\t” + childReq.getName()); } }}


You can also traverse from child to parent requirement by calling a requirement’s getParentRequirement method. For example, the following code prints the path from a requirement to the root requirement in its tree.

Traditionally, CaliberRM applications display all top-level tree requirements grouped and sorted by requirement type. Therefore, the getRequirements method of a Baseline object always returns requirements sorted and grouped this way.

Note: You can determine a requirement’s project, baseline and type by calling its getProject, getBaseline and getRequirementType methods respectively.

Creating Requirements

The CaliberRM SDK provides two constructors for Requirement objects. The first constructor allows you to create requirements at the top level of a project’s requirement tree hierarchy, and the second is used to create children of an existing requirement. The example below shows the first constructor to create a new requirement.

try{ // Get the latest version of the Requirement with the ID // number of 10. Requirement req = session.getRequirement( 10 );

while(req != null) { System.out.println(req.getName());

req = req.getParent(); }

} catch(RemoteServerException) { rse.printStackTrace();

}

// Get the Session's first Project. Project project = session.getProjects()[0];

// Get the Project's Current Baseline. Baseline currentBaseline = project.getCurrentBaseline();

// Get the first Requirement Type in the Baseline. RequirementType type = currentBaseline.getRequirementTypes()[0];

// Construct the new Requirement. Requirement newRequirement = new Requirement( “New Requirement”, project, type, 0, session); // Save the new Requirement. newRequirement.save();


The next example illustrates how the second constructor is used to create a requirement that is a child of an existing requirement. This new requirement will be called Child Requirement and will be the fourth child in the parent’s child hierarchy.

Requirement Attributes

CaliberRM allows you to define requirements using any number of user-defined attributes (UDAs.) Additionally, requirements always contain the Status and Priority system attributes.

In the CaliberRM SDK, a Requirement object provides a getAttributeValues method for getting its UDA Values and a getStatus and getPriority method for getting its system attribute values. For example, the following code prints the selected value of a requirement’s status, which is an instance of the AttributeValue subclass UDAListValue:

You can also obtain the default value for an attribute by using the getAttributeType( ) method. For example:

It is important to remember that each AttributeValue subclass is associated with a single Attribute subclass. Therefore, UDABooleanValue’s getAttributeType method returns an instance of UDABoolean and UDATextValue’s getAttributeValue method returns an instance of UDAText.

// Get a Requirement that will become the parent of a new // Requirement.

Requirement parentReq = session.getRequirement(125);

// Construct the new Requirement using the parent Requirement. Requirement newRequirement = new Requirement( “Child Requirement”, parentReq, 3, session);

// Save the new Requirement. newRequirement.save();

UDAListValue status = requirement.getStatus();Object selectedValue = status.getSelectedValue();System.out.print("Selected Value: " + selectedValue);

// Get the corresponding attribute type. UDAList attributeType = status.getAttributeType();

// Get the default value object for the attribute type.UDAListValue defaultValue = attributeType.getDefaultValue();

// Get the selected value from the default UDAListValueObject selectedDefaultValue = defaultValue.getSelectedValue();

System.out.print(“Default Value: “ + selectedDefaultValue);


The table below illustrates the relationship between the SDK’s AttributeValue and Attribute classes and CaliberRM attribute types.

Requirement History

The CaliberRM SDK allows for complete access to requirement history records. To obtain a requirement history you can call the getHistory method on any instance of requirement.

The following class diagram illustrates the relationship between the Requirement, History, HistoryRevision, and HistoryChange classes.

AttributeValue Subclasses Attribute Subclasses Application Attribute Type(s)

UDATextValue UDAText Single Text Line

Multiple Line Text Field

UDAIntegerValue UDAInteger Long Integer

UDADurationValue UDADuration Duration

UDAFloatValue UDAFloat Float

UDADateValue UDADate Date

UDABooleanValue UDABoolean Boolean

UDAListValue UDAList Multiple Selection List

Single Selection List

Multiple Selection Group List

Single Selection Group List

Multiple Selection User List

Single Selection User List


The example below demonstrates how these classes can be used to display history information:

TraceabilityIn CaliberRM, a trace relationship can exist between two requirements or between a requirement and an object external to CaliberRM. Likewise, the CaliberRM SDK supports the creation, deletion and modification traces to both CaliberRM requirements and non-requirements software artifacts.

Some of the more important trace-related classes are:

■ Trace: represents a trace relationship between a requirement and some other CaliberRM object. This CaliberRM object can be a requirement or an object external to CaliberRM.

■ TraceManager: provides the functionality for creating, modifying and deleting traces.

■ ExternalObject: an abstract base class that represents all objects external to CaliberRM.

■ File: represents a file system object.

■ SCMFile: represents an object that is managed by a source configuration management tool. Both File and SCMFile reside in the com.starbase.caliber.external.file.

■ XGenericObjectManager: provides the functionality for creating traces between requirements and non-requirements software artifacts.

■ VendorAddIn: represents a reference to an object that resides within the realm of some other application.

// Get the history for a Requirement objectHistory history = req.getHistory();

// Get the revisions that comprise the historyHistoryRevision[] revisions = history.getRevisions();

for(int i = 0; i < revisions.length; i++) { Revision revision = revisions[i]; System.out.println(“Revision: “ + revision.getVersion()); System.out.println(“Date: “ + revision.getDate()); System.out.println(“User: “ + revision.getUserName()); System.out.println(“Comment: “ + revision.getComment()); // Get the changes that comprise the revision HistoryChange[] changes = revision.getChanges(); For(int j = 0; j < changes.length; j++) { Change change = changes[j];

System.out.println(“\tField: “ + change.getFieldName()); System.out.println(“\tOld Value: “ + change.getOldValue());System.out.println(“\tNew Value: “ + change.getNewValue()); }}


Obtaining Traces

Traces can be retrieved at many levels of the CaliberRM object hierarchy. The Session class provides a getTraces method that returns all traces available to the Session. Similarly, the getTraces method of the project class returns all traces that trace to or from the requirements contained within a project.

The requirement class provides two methods for getting traces: getTracesFrom and getTracesTo. The example on the following page uses these methods to print the names of objects tracing to or from a requirement.

Creating Traces Between Requirements

The TraceManager class allows the creation and modification of trace relationships. To obtain an instance of TraceManager, you must call the Session’s getManager method. The following example shows how to obtain an instance of TraceManager:

try{

// The following line will get the latest version of // a Requirement with an ID number of 1. Requirement requirement = session.getRequirement(1);

Trace[] tracesTo = requirement.getTracesTo(); for(int i = 0; i < tracesTo.length; i++) {

// The following Trace is FROM our Requirement

// to some other object. Trace trace = tracesTo[i]; CaliberObject obj = trace.getToObject();

System.out.println(obj.getName()); }

Trace[] tracesFrom = requirement.getTracesFrom(); for(int i = 0; i < tracesFrom.length; i++) {

// The following Trace is TO our Requirement // from some other object.

Trace trace = tracesFrom[i]; CaliberObject obj = trace.getFromObject();

System.out.println(obj.getName()); }

} catch(RemoteServerException) { rse.printStackTrace();

}

TraceManager traceMgr;traceMgr = (TraceManager)session.getManager(Trace.class);


Once you have obtained a TraceManager, you can use it to create traces. The following example creates a trace between two requirements.

Creating Traces to Non-Requirements Software Artifacts

In the previous example, a trace relationship between two objects (both requirements) that reside within the bounds of CaliberRM was created. The following example shows how to create a trace to an object that resides outside of CaliberRM.

To create a reference to an external object, you must first obtain a reference to the appropriate object manager. As previously stated, you can call the getManager method of a Session object to obtain an instance of CaliberObjectManager. In the above example, an instance of om.starbase.caliber.xgeneric.XGenericObjectManager (which manages most objects external to CaliberRM) is obtained:

Notice that the createFileTrace method requires a reference to a requirement as its first parameter:

This is because a reference to an external object can only exist within CaliberRM while that object is participating in a trace relationship with a requirement. Once this relationship is removed, the reference is deleted. The only exceptions to this rule are Mercury TestDirector and Select Enterprise objects, which can be added and removed from CaliberRM without being linked to a requirement.

Requirement req1 = session.getRequirement(1);Requirement req2 = session.getRequirement(2);// The following line creates a trace from req1 to req2.TraceMgr.createTrace(req1, req2, false);

Class clazz = File.class;XGenericObjectManager extGenObjMgr =

(XGenericObjectManager)session.getManager(clazz);

Requirement req1 = session.getRequirement(1);

// The following line creates a File object in the Caliber// system and creates a trace from req1 to the new File.File f = extGenObjMgr.createFileTrace(

Req1, true, “foo.txt”, “C:\\temp\\”);

Class clazz = File.class;FileManager fileMgr = (FileManager)session.getManager(clazz);

File f = fileMgr.createFileTrace( Req1, ...

Chapter 4: Creat ing a Traceabi l i ty Add- in for Cal iberRM 41

C h a p t e r

Chapter4Creating a Traceability Add-in forCaliberRM

IntroductionDeveloping and distributing a traceability add-in is the simplest way to provide your users with a custom solution for CaliberRM. An add-in provides a set of objects to CaliberRM. These objects are displayed through the CaliberRM user interface so users can create trace relationships with requirements. For example, an add-in might display Microsoft Project tasks, or objects from a design tool, or a testing tool.

This document describes how you can use a Microsoft Visual Basic.NET project sample to create a traceability add-in for CaliberRM. The sample files are provided at Program Files\Borland\CaliberRM\Samples\Addins\.

Using the Visual Basic.NET SampleThe CaliberRM installation includes a set of sample files you can use for creating a traceability add-in for CaliberRM in Visual Basic.NET.

Note: You should change all of the GUIDs in the traceability add-in files and Assembly.Info.vb.

By default, the sample project is located at Program Files\Borland\CaliberRM\Samples\Addins\HelloWorld2 VB.NET. You will see the following files:

■ AssemblyInfo.vb

■ HelloWorld2_VBNet.sln

■ HelloWorld2_VBNet.vbproj

■ HelloWorld2_VBNet.vbproj.user

■ Icon1.ico

■ Icon2.ico

■ Icon3.ico

■ Icon4.ico


■ Icon5.ico

■ VendorObject.vb

■ VendorSession.vb

■ VendorView.vb

To create a new traceability add-in, perform the following steps:

1 Create a new Visual Basic project using the "Class Library" template.

2 Copy VendorSession.vb, VendorView.vb, and VendorObject.vb files into the directory of you new VB project. Then add the files to the project using "Add Existing Item…".

3 Change all of the COM GUIDs values in the newly added files using the CreateGUID (menu: Tools->CreateGUID) tool found in VS.NET.

4 Next build your new project. VS.NET will register the newly built DLL at the end of the build. You can register the DLL on other machines by using regasm (.NET Assembly Registration tool) at any command line.

5 Your traceability add-in is now ready to use. You can now implement the properties and methods that are required in the interface.

Traceability Add-in InterfaceTo create an add-in, you need to populate the properties and functions of three classes: VendorSession, VendorView and VendorObject. The following is a detailed description of each of these classes and their procedures.

VendorSession

The VendorSession class provides a context in which CaliberRM clients can interact with your add-in. Subsequently, VendorSession is the only class that must be publicly creatable.

Public ReadOnly Property SupportsViewBuilding() As BooleanIf your add-in allows users to dynamically build custom views, this property should be "true". For example, if you are building an integration with a database, you might want to expose multiple views of data based on a query. Conversely, if you are creating an add-in that only supports default views then this property should be "false".

See “GetVendorViews” on page 43 for more information.

Public WriteOnly Property ConfigFilePath() As StringThe ConfigFilePath property is set by CaliberRM to indicate the path of a configuration file that your add-in uses. This configuration file is specified when you register an add-in in CaliberRM Administrator. See “Registering and Enabling Your Traceability Add-In” on page 45 for information about enabling a new traceability add-in.

Once this configuration file is set, it is managed by CaliberRM and passed to your integration (using the ConfigFilePath property) immediately after the VendorSession class is initialized.

Public Property SilentMode() As BooleanThis property is set by CaliberRM to indicate that an add-in should run silently. In this state, your add-in MUST NOT display any dialog boxes that require user input.


When CaliberRM gets this property, it indicates that the add-in is running in silent mode.

Note: Silent mode allows Datamart reports to be scheduled to generate reports off hours. If your CaliberRM server contains projects in which you established traces to your traceability add-in, when Datamart performs its tasks, it will be looking for credential information but no login dialog should be displayed when the add-in runs in silent mode. It is recommended to store the authentication information in a file or the registry for your add-in to gather that information without displaying a login dialog box.

Public ReadOnly Property InterfaceVersion() As IntegerThis property provides the version of the traceability add-in interface that an add-in implements. Currently CalibeRM supports version 2.0 of this interface, therefore this property should always be 2.

Public Function GetVendorViews(ByVal BuildView As Boolean) As CollectionThis function provides a collection of VendorView objects to CaliberRM. Each of these views is displayed as a tab in CaliberRM’s Traceability Modification window.

When initializing the Traceability Modification window, CaliberRM calls the add-in’s GetVendorViews method with the BuildView parameter set to "false", indicating that CaliberRM is requesting the initial (or default) view(s). If the add-in supports dynamic view building (see “Public ReadOnly Property SupportsViewBuilding() As Boolean” on page 42), the Build View button is enabled. When a user clicks the Build View button, CaliberRM calls GetVendorViews with the BuildView parameter set to “true”. The add-in can show a dialog box asking the user to specify view parameters. Returned views will be appended to existing view tabs.

Public Function GetVendorObject(ID As String) As VendorObjectThe GetVendorObject function is called by CaliberRM to obtain a single VendorObject.

VendorView

As previously stated, a traceability add-in provides a set of VendorView objects through VendorSession's GetVendorViews method. In turn, each VendorView provides a set of VendorObjects that are displayed in the view's tab in CaliberRM's Traceability Modification window.

Public ReadOnly Property ViewName() As StringThis property provides the name for the view.

Public ReadOnly Property IsList() As BooleanCaliberRM can display a collection of add-in objects as a tree or as a list. If this property is "true," CaliberRM displays the view's objects as a list. Otherwise, CaliberRM displays the view's objects as a tree.

Public ReadOnly Property VendorObjects() As CollectionThis property provides the objects that comprise the view. If the view represents a tree of objects (i.e. IsList = "false"), this collection of objects should represent the first level of nodes in the tree.


VendorObject

The VendorObject class represents a single object that is exposed by your add-in. CaliberRM obtains these objects as members of a VendorView or through VendorSession's GetVendorObject method.

Public ReadOnly Property ID() As StringThe ID property provides a unique identifier for an object in CaliberRM. Subsequently, CaliberRM uses this ID when calling VendorSession's GetVendorObject method.

Public ReadOnly Property ObjectName() As StringThe ObjectName property provides a name for the VendorObject.

Public ReadOnly Property ShortObjectName() As StringThis provides CaliberRM an abbreviated name for the object. CaliberRM truncates this name if it exceeds 16 characters in length.

Public ReadOnly Property Icon() As LongThis property provides a windows icon handle for the object.

Public ReadOnly Property Traceable() As BooleanThe Traceable property determines whether or not CaliberRM allows users to create a trace to a VendorObject.

Public ReadOnly Property HasChildren() As BooleanThis property determines whether or not the VendorObject has children. CaliberRM checks this property only if the VendorObject is provided as a tree of objects (see VendorView's IsList property). If this property is "true," CaliberRM displays a symbol next to the object in the object's tree.

Public ReadOnly Property Children() As CollectionThis property makes the children of a VendorObject available to CaliberRM. CaliberRM calls this method if the HasChildren property is "true" and the user has expanded the VendorObject in a tree.

Public ReadOnly Property Operations() As VariantEach VendorObject may expose one or more operations to CaliberRM users through its Operations property. This property should return an array of strings, each of these strings represents an operation that can be performed on the object. For example, if your VendorObject represents a file then you may wish to expose Open and Properties as operations.

Public Sub DoOperation(Operation As String)When a user right-clicks on a VendorObject in CaliberRM, CaliberRM queries the Operations property and displays a pop-up menu that contains the returned strings. Subsequently, when a user selects an operation menu item, CaliberRM calls the VendorObject's DoOperation method and passes in the name of the selected operation.


Public Sub OnTraceCreated(RequirementID As Integer)This method is called by CaliberRM when a trace is created between a CaliberRM requirement and the VendorObject.

Public Sub OnTraceDeleted(RequirementID As Integer)This method is called by CaliberRM when a trace between a CaliberRM requirement and the VendorObject is deleted.

Public Sub OnStatusChange(RequirementID As Integer, MadeSuspect As Boolean)This method is called by CaliberRM when the "suspect" status of a trace between a CaliberRM requirement and the VendorObject changes.

Registering and Enabling Your Traceability Add-InOnce you have coded and compiled your add-in, you should register and enable it for a specific project on a CaliberRM Server as well as deploy it on each CaliberRM client computer.

To register and enable your add-in, perform the following steps:

1 On a CaliberRM Server computer, open CaliberRM Administrator and select a project in the left pane.

2 Select the External Traceability tab in the right pane.

3 Click the New button. The New Integration dialog box is displayed.

4 Type in an Add-in Name (this name appears on the Traceability Modification tab), Library Name (in Visual Basic, this name appears in the Project Name field of your project's Properties dialog box), and choose an icon. You may also specify the location of a configuration file that your add-in uses. CaliberRM automatically distributes this file to all clients that use your integration (see "VendorSession's ConfigFilePath" on page 43 for more information.)

5 Click OK to create the new integration. The new integration is added to the Disabled Integration(s) list box for all CaliberRM projects.

6 To enable the integration, select that integration in the Disabled Integration(s) list box and click the Move Left button.

7 Click File > Save Changes. Your add-in is registered and enabled on the CaliberRM Server.

8 Deploy your add-in on each CaliberRM client machines when users need to trace requirements to your add-in objects. You can use either a setup program or distribute and register the necessary files manually or using the logon script.


Appendix A: Cal iberRM Object Model 47

A p p e n d i x

Appendix ACaliberRM Object ModelThese diagrams can be used as a way to locate the object you want to work with and to understand how that object fits into the overall CaliberRM object model.

The following table shows how objects and collections are represented in the diagrams:

Indicates an object.

Indicates a collection of objects.

Indicates that a complete view of the object hierarchy is located elsewhere in the diagram.


CaliberRM Object Model

Appendix A: Cal iberRM Object Model 49

Documents

CaliberRM 2008 SP1 · 2010. 12. 22. · provides an overview of working with requirement trees, ... Imports Starbase.CaliberRM.Interop ' The Initializer object is responsible for