Setting up existing HP ALM projects

Existing HP ALM projects require some customizations to effectively to work with CLM projects.

Before you begin

Make sure the Rational® Adapter for HP ALM is installed and that the server that hosts the adapter is set up.

About this task

To effectively interface with the Rational Adapter for HP ALM, you must first customize your HP ALM projects to communicate with the Rational Adapter for HP ALM. Project customizations include updates to project workflow, adding toolbar buttons to call the adapter and setting a site parameter for the adapter URL. Revised workflow scripts are provided. See 5.

Procedure

  1. For new or existing projects where no workflow customizations have been done you can copy the demo workflow code into the project using the Script Editor tool. For information about the exported HP ALM project, see Setting up new HP ALM projects. The download project contains all the customizations described here but this section assumes you are modifying an existing project without access to the site administration tools for creating a new project from an exported .qcp file.
  2. To modify a project with existing workflow you will need to modify your project to include the functions and toolbar buttons that communicate with the Rational Adapter for HP ALM. The following sections explain the process for incorporating the workflow and other steps required. The functions used in the adapter calls are all named starting with GB_ so unless your naming conventions also start with that prefix you can add these functions to your workflow without affecting the existing code.
    1. Verify no existing function starts with the prefix GB_. If any do you can modify the demo functions to have a unique prefix but make sure to change any function calling them to use the new name.
    2. The demo functions should be as self contained as possible and there are usually several other ways to accomplish the same action. Comment the code enough so that it is clear what input is expected and what value(s) they return. The demo functions can be modified or adapted as needed if you have matching script that accomplishes the same result.
    3. Other than the functions all the script is contained in the Common Script section and depends on the built-in ActionCanExecute function. This function acts on the events triggered in the UI (Action Name) to handle toolbar, refresh, and other events in the user interface.
      Important: If you are using HP ALM project templates, you must change the Template_ActionCanExecute function instead of the ActionCanExecute function.
    4. Update the workflow script with the provided demo workflow code and the Toolbar buttons defined in the following section.
  3. Add the new toolbar icons that enable users to call the adapter links from the adapter modules. These links include Requirements, Test Plan, Test Lab, Manual Run, and Defects. The demo project includes all the options but it is possible to incorporate only the functions that are needed on a project by project basis. When you add buttons only the value for Action Name is critical as it must match the event name in the workflow script.
    1. From the Project Customization age, access the Toolbar Button Editor to add each toolbar icon.
      For example, to add a toolbar icon for a resource landing page, complete the Toolbar Button Editor page as follows:
      • Command Bar: Requirements
      • Caption: Resource Landing Page
      • Hint: Open in Rational Adapter for HP ALM
      • Action Name: Resource_Landing_Page_REQ
      • Image: 223

      The result of adding a toolbar icon for the resource landing page:

      Resource Landing Page

      The result of adding a toolbar icon for the RM Dashboard:

      RM Dashboard

      The result of adding a toolbar icon for the CM Dashboard:

      CM Dashboard

      The following table lists all the toolbar buttons that you can set up for your HP ALM project.
      Table 1. All Toolbar Buttons
      Command bar Caption Hint Action Name Image
      Requirements RM Dashboard Open Rational Requirements Management RM_Dashboard 145
      Requirements CM Dashboard Open Rational Change and Configuration Management CM_Dashboard 12
      Requirements Resource Landing Page Open in Rational Adapter for HP ALM Resource_Landing_Page_REQ 223
      TestPlan RM Dashboard Open Rational Requirements Management RM_Dashboard 145
      TestPlan CM Dashboard Open Rational Change and Configuration Management CM_Dashboard 12
      TestPlan Resource Landing Page Open in Rational Adapter for HP ALM Resource_Landing_Page_TP 223
      TestLab RM Dashboard Open Rational Requirements Management RM_Dashboard 145
      TestLab CM Dashboard Open Rational Change and Configuration Management CM_Dashboard 12
      TestLab Resource Landing Page Open in Rational Adapter for HP ALM Resource_Landing_Page_TL 223
      ManualRun RM Dashboard Open Rational Requirements Management RM_Dashboard 145
      ManualRun CM Dashboard Open Rational Change and Configuration Management CM_Dashboard 12
      ManualRun Resource Landing Page Open in Rational Adapter for HP ALM Resource_Landing_Page_MAN 223
      Defects RM Dashboard Open Rational Requirements Management RM_Dashboard 145
      Defects CM Dashboard Open Rational Change and Configuration Management CM_Dashboard 12
      Defects Resource Landing Page Open in Rational Adapter for HP ALM Resource_Landing_Page_DEF 223
  4. Calls to the Rational Adapter for HP ALM require the workflow to know the URL of the server hosting the adapter. The custom function GB_Get_TDParams returns this site parameter value that would have been set by the TDAdmin. Assuming you do not have access to configure this parameter outside of the project, you can code the required value directly into the script.
    In the function Function ActionCanExecute(ActionName) replace the line:
    strBaseURL = GB_Get_TDParams("GB_BASE_URL")  
    with
    strBaseURL = https://[YourRationalAdapterforHPALMURL]:[YourPort]/hpqm/
  5. Revised workflow code.
    '==================================
    '- COMMON MODULE
    '==================================
    
    '--------------
    '- log settings
    '--------------
    Public gLogFile
    Public gLogPurge
    
    gLogFile = "C:\GB_Eventlog.txt"
    gLogPurge = False
    
    '-------------------
    '- work flow version
    '-------------------
    Public gVersion
    gVersion = "2013-03-06"
    
    '--------------------------------------------------------------
    '- ActionCanExecute
    '-
    '-  DESCRIPTION: Built in function that handles all actions
    '-        INPUT: ActionName (system provided)
    '-               Name of action that has been triggered
    '-       OUTPUT: Return True if an action should execute, False if not
    '- EXAMPLE CALL: not called from script - invoked by QC program
    '--------------------------------------------------------------
    Function ActionCanExecute(ActionName)
    
       '- set error handler
       'On Error Resume Next
    
       '- default return value
       ActionCanExecute = DefaultRes
    
    	'- handle events based on ActionName
       Select Case ActionName
    		'- execute any existing customer functions
    
    		Case Else
    			'- if the ActionName event was not handled above then test for HPQM actions
    			GB_HPQM_Action ActionName '- handle HPQM functions
    
    	End Select
    
    	'- handle events based on ActiveModule
       Select Case ActiveModule
    		'- execute any existing customer functions
    
    		Case Else
    			'- if the ActiveModule event was not handled above then test for HPQM actions
    			GB_HPQM_Action ActiveModule '- handle HPQM functions
    
     	End Select
    
    End Function
    
    
    '--------------------------------------------------------------
    '- GB_HPQM_Action
    '-
    '-  DESCRIPTION: Handle HPQM specific events such as toolbar buttons
    '-        INPUT: strActionName (ActionName system provided, passed to this function)
    '-               Name of action that has been triggered
    '-       OUTPUT: none
    '- EXAMPLE CALL: GB_HPQM_Action ActionName '- handle HPQM functions
    '--------------------------------------------------------------
    Sub GB_HPQM_Action(strActionName)
       '-------------------------------------
       '- get Properties for the landing page
       '-------------------------------------
    	Dim strUrl
    	Dim strBaseURL
    	Dim strDomain
    	Dim strProject
    	Dim strDomainProject '- domain & project
    
    	'- call GB_AdapterURL to get the HPQM Adapter URL
    	strBaseURL = GB_AdapterURL
    
       strDomain = TDConnection.DomainName
       strProject = TDConnection.ProjectName
       strDomainProject = strDomain & "/projects/" & strProject
    
       Select Case strActionName
    		'- Handle events for HPQM defined icons
    
          '-------------------------------------
          '- Handle Landing Page Request
          '-------------------------------------
          '- build string for landing page:
          Case "UserDefinedActions.Resource_Landing_Page_REQ" '- Requirements icon 223
             '- Navigation: Requirements > Requirements
             strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    				"/requirements/" & Req_Fields("RQ_REQ_ID").Value & "?alt=html"
             GB_Browser strURL, False, 1000, 600 '- open browser
             GB_WriteLog "INFORMATION", "Requirements > Requirements > Landing Page ", strURL
    
          Case "UserDefinedActions.Resource_Landing_Page_TP" '- Test Plan icon 223
    	      If Test_Fields("TS_TEST_ID").Value = "" Then
    				'- no selection yet, default to base page
    	         strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	            "/testPlans/dashboard"
    			Else
    	         '- Navigation: Testing > Test Plan
    	         strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	            "/testCases/" & Test_Fields("TS_TEST_ID").Value
    			End If
             GB_Browser strURL, False, 1000, 600 '- open browser width, height
             GB_WriteLog "INFORMATION", "Testing > Test Plan > Landing Page ", strURL
    
          '- action event for Manual run is recognized in 11.5 only
          '- no longer using the overload in Test Lab - retain for ALM 11
          Case "UserDefinedActions.Resource_Landing_Page_MAN" '- Test Lab icon 223
    		      If Run_Fields("RN_RUN_ID").Value = "" Then
    	            '- no selection yet, default to base page
    	            strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	               "/testSets/dashboard"
    				Else
    	            '- Navigation: Testing > Test Lab > Test Runs > Continue Manual Run
    	            strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	               "/testRuns/" & Run_Fields.Field("RN_RUN_ID").Value
    				End If
                GB_Browser strURL, False, 1000, 600  '- open browser
                GB_WriteLog "INFORMATION", "Testing > Test Lab > Test Runs > Continue Manual Run > Landing Page ", strURL
    
          Case "UserDefinedActions.Resource_Landing_Page_TL" '- Test Lab icon 223
    
     			If ActiveModule = "Test Lab" Then
    		      If TestSet_Fields("CY_CYCLE_ID").Value = "" Then
    	            '- no selection yet, default to base page
    	            strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	               "/testSets/dashboard"
    				Else
    	            '- Navigation: Testing > Test Lab > Test Sets
    	            strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	               "/testSets/" & TestSet_Fields("CY_CYCLE_ID").Value
    				End If
                GB_Browser strURL, False, 1000, 600  '- open browser
                GB_WriteLog "INFORMATION", "Testing > Test Lab > Test Sets > Landing Page ", strURL
    
    			ElseIf ActiveModule = "ManualRun" Then
    		      If Run_Fields("RN_RUN_ID").Value = "" Then
    	            '- no selection yet, default to base page
    	            strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	               "/testSets/dashboard"
    				Else
    	            '- Navigation: Testing > Test Lab > Test Runs > Continue Manual Run
    	            strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	               "/testRuns/" & Run_Fields.Field("RN_RUN_ID").Value
    				End If
                GB_Browser strURL, False, 1000, 600  '- open browser
                GB_WriteLog "INFORMATION", "Testing > Test Lab > Test Runs > Continue Manual Run > Landing Page ", strURL
    			End If
    
          Case "UserDefinedActions.Resource_Landing_Page_DEF" '- Defects icon 223
    	      If Bug_Fields("BG_BUG_ID").Value = "" Then
    				'- no selection yet, default to base page
    	         strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	            "/defects/dashboard"
    			Else
    	         '- Navigation: Defects
    	         strUrl = strBaseURL & "rest/domains/" & strDomainProject & _
    	            "/defects/" & Bug_Fields("BG_BUG_ID").Value
    			End If
             GB_Browser strURL, False, 1000, 600 '- open browser
             GB_WriteLog "INFORMATION", "Defects > Landing Page ", strURL
    
          '-------------------------------------
          '- Handle Dashboard Request
          '-------------------------------------
          Case "UserDefinedActions.CM_Dashboard" '- icon 12
             '- CM Dashboard URL
             strURL = strBaseURL & "rest/domains/" & strDomainProject & "/cm/dashboards"
    
             GB_Browser strURL, False, 1000, 650
             GB_WriteLog "INFORMATION", "Dashboard: " & strDashboard, strURL
    
          Case "UserDefinedActions.QM_Dashboard" '- icon 123
             '- QM Dashboard URL
             strURL = strBaseURL & "qm/web/console/" & strProject & " (Quality%20Management)#action=com.ibm.rqm.planning.home.actionDispatcher &subAction=viewUserHome"
    
             GB_Browser strURL, False, 1000, 650  '- open browser
             GB_WriteLog "INFORMATION", "Dashboard: " & strDashboard, strURL
    
          Case "UserDefinedActions.RM_Dashboard" '- icon 145
             '- RM Dashboard URL
             strURL = strBaseURL & "rest/domains/" & strDomainProject & "/rm/dashboards"
    
             GB_Browser strURL, False, 1000, 600  '- open browser
             GB_WriteLog "INFORMATION", "Dashboard: " & strDashboard, strURL
    
       End Select
    
    End Sub
    
    
    '--------------------------------------------------------------
    '- GB_HPQM_Action
    '-
    '-  DESCRIPTION: Handle HPQM specific events such as refresh events
    '-        INPUT: strActiveModule (ActiveModule system provided, passed to this function)
    '-               Name of the Active Module
    '-       OUTPUT: none
    '- EXAMPLE CALL: GB_HPQM_Action ActiveModule '- handle HPQM functions
    '--------------------------------------------------------------
    Sub GB_HPQM_Module(strActiveModule)
       '-------------------------------------
       '- get Properties for the landing page
       '-------------------------------------
    	Dim strUrl
    	Dim strBaseURL
    	Dim strDomain
    	Dim strProject
    	Dim strDomainProject '- domain & project
    
    	'- call the local function GB_AdapterURL to get the Rational Adapter URL
    	strBaseURL = GB_AdapterURL
    
       strDomain = TDConnection.DomainName
       strProject = TDConnection.ProjectName
       strDomainProject = strDomain & "/projects/" & strProject
    
       '- Handle events based on current module
       Select Case strActiveModule
    
          Case "Test Plan"
    			Select Case ActionName
    
    	         Case "RequirementCoverage.SelectReq"
    	            strURL = strBaseURL & "rest/domains/" & strDomainProject & _
    						"/rm/requirement/selector?testCase=" & Test_Fields("TS_TEST_ID").value
    
    	            GB_Browser strURL, True, 1000, 650  '- open browser
    	            GB_WriteLog "INFORMATION", "Dashboard: " & strDashboard, strURL
    
              		'- don't execute default function
    	            ActionCanExecute = False
    
    			End Select
    
       End Select
    
    End Sub
    
    '--------------------------------------------------------------
    '- GB_Get_TDParams
    '-
    '-      UPDATED: 9-5-2012 (mts) corrected header and output note
    '-  DESCRIPTION: Get values from Site Admin Properties
    '-        INPUT: strParam
    '-       OUTPUT: strParamValue
    '- EXAMPLE CALL: strBaseURL = GB_Get_TDParams("GB_BASE_URL")
    '--------------------------------------------------------------
    Function GB_Get_TDParams(strParam)
    
    	Dim strParamValue
    
    	'- set error handler
    	On Error Resume Next
    
    	'- initialize return
    	GB_Get_TDParams = ""
    
    	'- get value from Site Admin
    	strParamValue = TDConnection.TDParams(strParam)
    	If strParamValue = "" Then
    	   '- debug/log
    	   MsgBox "Missing Parameter " & strParam & " in Site Configuration" & vbCrLf & _
    	   	"This setting is required for integration",,"ERROR"
    	   Exit Function
    	End If
    
    	'- return parameter
    	GB_Get_TDParams = strParamValue
    
    End Function
    
    '==============================================================
    '- GB_Browser
    '-
    '-     UPDATED: 9-5-2012 (mts) corrected header and output note
    '- DESCRIPTION: Gearbox browser - launch IE window or tab
    '-       INPUT: strURL - URL or file name to send to IE
    '-            : bConfig - Change settings True/False
    '-            : width - width dimension (pixels)
    '-            : height - height dimension (pixels)
    '-      OUTPUT: Launch IE browser - no return value
    '-     EXAMPLE: GB_Browser strInput, 1, 800, 600
    '==============================================================
    Function GB_Browser(strURL, bConfig, width, height)
    
       Dim objShell
       Dim objIE
    
       Set objShell = CreateObject("WScript.Shell")
       Set objIE = CreateObject("InternetExplorer.Application")
    
       '- default settings
       objIE.Visible = True
       objIE.width = width
       objIE.height = height
    
       '- set window position
       objIE.left = 10
       objIE.top = 10
    
       If bConfig Then
          '- browser settings when different than RQ Integration
          objIE.AddressBar = 0
          objIE.MenuBar = 0
          objIE.ToolBar = 0
          objIE.Resizable = 1
          objIE.StatusBar = 0
       End If
    
       '- open browser
       objIE.Navigate strURL
    
       '- wait while ie is navigating or downloading
      n = 0
      Do While objIE.Busy
         '- do something meaningless while the window loads
         n = n+1
      Loop
    
       '- Use AppActivate to set the new browser window on top
       objIE.Visible = 1
       objShell.AppActivate objIE
    
    End Function
    
    '==============================================================
    '- GB_WriteLog
    '-
    '-  DESCRIPTION: Write value to Gearbox Logging file - append or overwrite
    '-        INPUT: strLevel  - INFORMATION, WARNING, ERROR or SEVERE
    '-             : strModule - Function or Sub
    '-             : strEvent  - Action or Event performed
    '-      EXAMPLE: GB_WriteLog "INFORMATION", "Testing > Test Plan > Landing Page ", strURL
    '==============================================================
    Sub GB_WriteLog(strLevel, strModule, strEvent)
    
       Dim fso1
       Dim tf1
    	Dim strLogEntry
    
       Set fso1 = CreateObject("Scripting.FileSystemObject")
    
       If gLogPurge Then
          Set tf1 = fso1.CreateTextFile(gLogFile, True)
       Else
          Set tf1 = fso1.OpenTextFile(gLogFile, 8, True)
       End If
    
    	'- build message
    	strLogEntry = gVersion & " " & Now() & " [Module: " & strModule & "] Event: " & strEvent
    
    	tf1.WriteLine (strLogEntry) '- write to log
    
    	'- release objects
    	Set fso1 = Nothing
    	Set tf1 = Nothing
    
    End Sub
    
    Function GB_AdapterURL
    
    	'- change GB_AdapterURL here to your Rational HPQM adapter URL
       '- If you are not using the default value from Site Admin
       '- Note: DO NOT forget the final "/"
       '- For example:
       '-   GB_AdapterURL = "https://adapter_host:port/hpqm/"
       GB_AdapterURL = GB_Get_TDParams("GB_BASE_URL")
    
    End Function

What to do next

Complete server friending and project associations, see Integrating applications.

Feedback