Synthetic Monitoring Scripting Framework. User Guide

Transcription

1 Synthetic Monitoring Scripting Framework User Guide

2 Please direct questions about {Compuware Product} or comments on this document to: APM Customer Support FrontLine Support Login Page: Copyright 2014 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright Laws of the United States. U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Compuware Corporation license agreement and as provided in DFARS (a) and (a) (1995), DFARS (c)(1)(ii) (OCT 1988), FAR (a) (1995), FAR , or FAR (ALT III), as applicable. Compuware Corporation. This product contains confidential information and trade secrets of Compuware Corporation. Disclosure is prohibited without the prior express written permission of Compuware Corporation. Use of this product is subject to the terms and conditions of the user's License Agreement with Compuware Corporation. Documentation may only be reproduced by Licensee for internal use. The content of this document may not be altered, modified or changed without the express written consent of Compuware Corporation. Compuware Corporation may change the content specified herein at any time, with or without notice. All current Compuware Corporation product documentation can be found at Adobe Reader is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries. All other company and product names are trademarks or registered trademarks of their respective owners. Build: March 30, 2014, 21:54

3 Contents Contents Chapter 1 Synthetic Monitoring Scripting Framework Overview Framework Benefits Framework Assets Installing the Framework Framework Installation Checklist Configuring the Agent Recorder Framework Database Setting Up the Framework Configuration File Deploying the Framework Upgrading the Framework Framework Upgrade Checklist Importing the Upgrade Files Deploying the Framework Chapter 2 Installing the Framework Framework Installation Checklist Configuring the Agent Recorder Framework Database Setting Up the Framework Configuration File Deploying the Framework Chapter 3 Upgrading the Framework Framework Upgrade Checklist Importing the Upgrade Files Deploying the Framework Chapter 4 Configuring Framework Features Global Tab Passwords Tab Blackouts Tab Holidays Tab Tab Agents Tab UserDefined Tab Integration Tab

4 Contents Alerting When an Error Occurs Between Transactions Agent Auto-login Chapter 5 Framework Scripts Framework Script Types Creating a Script Using the Framework Script Template Walkthrough: Creating an Application Driver Script Create a Script and Add the Script Name Extend the Script Template for Expected Steps Begin Building the Script Add a Breakpoint Run the Script Stop the Script When it Pauses at the Breakpoint Verify Page Load Success (Synchronization) Type in the Search Criteria Record the Setup Step Test the Script Record the Timed or Monitored Action Close the Application Test the Script Again Add the Transaction Names Document the Script Steps Prepare the Script for Use in Production Convert the Script from Self Documentation Mode to Import Mode Run the Script in Import Mode Convert the Script from Import Mode to Application Driver Chapter 6 Script and Application Synchronization Chapter 7 Framework Scripting Tips General Scripting Tips Thick Client Scripting Tips Citrix Scripting Tips Creating a Citrix Script Chapter 8 Frequently Asked Questions Agent Recorder FAQs Synthetic Monitoring FAQs Citrix Frequently Asked Questions Internet Explorer Frequently Asked Questions Appendix A Framework Scripting Checklists Appendix B Framework Functions Reference Wait Functions General Scripting Functions Synthetic Monitoring Functions Script Initialization and Error Handling User Expandability Functions

5 Contents Path, File, and Registry Functions Internet Explorer Functions Framework Properties Appendix C Framework Functions Reference Grid Index

6 Contents 6

7 CHAPTER 1 Synthetic Monitoring Scripting Framework Overview The Synthetic Monitoring Scripting Framework is an optional Synthetic Monitoring component that facilitates the creation and management of Agent Recorder scripts for use in Synthetic Monitoring. In addition, the Framework enables the integration of Agent Recorder scripts with settings in the Synthetic Monitoring Console such as matching wait times with availability threshold settings, taking screen shots on error, importing transactions, and handling transactions when they succeed or fail. When configured and used properly, the Framework can produce more reliable scripts and significantly reduce the time required to create and maintain Agent Recorder scripts. IMPORTANT Compuware recommends contacting Customer Support prior to installing and configuring the Framework. Framework Benefits The primary benefit of using the Framework is the reduction in the amount of time required to write and maintain Agent Recorder scripts. The Framework is tightly integrated with Synthetic Monitoring and automatically takes advantage of many of the features offered by Synthetic Monitoring. For example, when the availability threshold time is changed in the Synthetic Monitoring Console, the amount of time allowed in the Framework WaitFor functions is automatically set to reflect the change in the Console. The Framework functions also leverage other Synthetic Monitoring features such as when to take a screen print, mark a transaction unavailable, or display script and transaction health. If the script is between transactions, the Framework offers options for alerting in the event an error occurs. It can mark the next transaction as unavailable or take a screen shot and save it in a folder on a server that can be viewed in VantageView. The Framework keeps an extensive log of everything a script does, which can greatly help in diagnosing and troubleshooting an issue. It can also insert the script name, application name, 7

8 Chapter 1 Synthetic Monitoring Scripting Framework Overview and configure transaction details directly into the Synthetic Monitoring Console, thus saving a significant amount of effort. An additional benefit of using the Framework is the enhanced usability and performance of Agent Recorder. Error handling and Wait events are greatly improved in speed, reliability, and ease of use. Tasks that would normally take hundreds of lines of code can be performed by adding one Framework function to a script. The Framework function library is extensive and can be used for most application types including Citrix, web, thick client, and Java applications. Framework Assets The Framework's core components are Agent Recorder assets, which include test script templates and examples, modules, shared modules, a user form, object maps, and screen events. These assets are contained and initially deployed in an Agent Recorder database. In the following example, the default Framework test scripts are shown. The scripts with a CVFW_ prefix are utilities called from production application driver scripts. Scripts that begin with ZZ_ are example test scripts that demonstrate how to script common monitoring tasks. For more information, see Framework Script Types [p. 49]. NOTE Sample scripts may reference web pages that are not maintained by Compuware Corporation. As a result, the sample script may not play back properly if the referenced web page has been deleted or modified. If you have problems running a sample script, contact Compuware APM Technical Support. 8

9 Chapter 1 Synthetic Monitoring Scripting Framework Overview Figure 1. Framework Test Scripts in Agent Recorder While a script runs, the Framework creates and/or updates several files. One such file is the Framework configuration file (CVFW.ini). This file defines the integration between the Framework and Synthetic Monitoring as well as other customizable options such as log file handling, screen prints for error reporting, and health alert settings. The Framework also includes a web page (kioskmode.htm) that you can use to warn people not to use the Agent machine while scripts are running. Installing the Framework The recommended deployment of the core Synthetic Monitoring components includes a dedicated Agent on which Agent Recorder scripts are configured and tested prior to deployment to other Agents. This Agent is referred to as the Master Scripting Agent. After the completion of script testing on the Master Scripting Agent, you can deploy the Agent Recorder database using the Synthetic Monitoring script publishing utility. In addition to the Agent Recorder database, you can use the script publishing utility to deploy other Framework assets to Agent machines, such as the Framework configuration file. NOTE Once you have verified the stability of your scripts, you can also use the Master Scripting Agent to monitor applications. 9

10 Chapter 1 Synthetic Monitoring Scripting Framework Overview The installation instructions in this guide assume a Synthetic Monitoring environment that includes a Master Scripting Agent on which a remote Synthetic Monitoring Console is installed. The following diagram depicts a typical Synthetic Monitoring environment and highlights the deployment of the Agent Recorder database from the Master Scripting Agent to other Agents using the Synthetic Monitoring script publishing utility. Figure 2. Synthetic Monitoring Environment with Master Scripting Agent Framework Installation Checklist The Framework installation process includes the steps listed in the following table: Table 1. Framework Installation Checklist Completed Steps Configure the Agent Recorder Framework database on the Master Scripting Agent. For more information, see Configuring the Agent Recorder Framework Database [p. 11]. Verify that the Agent Recorder Framework database was configured correctly. Run the Framework configuration file script and configure the Framework settings. For more information, see Setting Up the Framework Configuration File [p. 12]. Deploy the Agent Recorder Framework database and configuration file to all desired Agent machines. For more information, see Deploying the Framework [p. 13]. 10

11 Chapter 1 Synthetic Monitoring Scripting Framework Overview Configuring the Agent Recorder Framework Database During a Synthetic Monitoring Agent Manager installation, the Agent Recorder Framework database is copied into the Agent Manager installation folder and made available for use pending its configuration in Agent Recorder on the Master Scripting Agent. To configure the Agent Recorder Framework database as the default Agent Recorder database, perform the following steps: Configure the Agent Recorder Framework Database 1. On the Master Scripting Agent, close Agent Recorder. 2. Move the Agent Recorder Framework database from the Agent Manager machine to the Master Scripting Agent: a. On the Agent Manager machine, access the Agent Recorder Framework database (TestPartner.mdb) from the following location: C:\Program Files\Compuware\Synthetic Monitoring\Samples\ScriptingFramework b. On the Master Scripting Agent, move the TestPartner.mdb file to the following location on the Agent Recorder machine: C:\ProgramData\Documents\Compuware\Recorder\DB NOTE On some operating systems, the Documents folder is hidden. To reliably navigate to the DB folder, type %ALLUSERSPROFILE%\Documents\Compuware\Recorder\DB in the Windows Explorer Address bar. c. You are prompted to replace the existing TestPartner.mdb file. Click Yes. Verify That the Agent Recorder Framework Is Configured 3. Start Agent Recorder. 4. Log on to the TestPartner database. The Test script window should open and display the default Framework scripts, which have a prefix of CVFW_ or ZZ_, as shown in the following graphic: 11

12 Chapter 1 Synthetic Monitoring Scripting Framework Overview Figure 3. Framework Test Scripts in Agent Recorder In addition to the default Framework test scripts, the Framework Agent Recorder database is prepopulated with modules, shared modules, a user form, object maps, and screen events. Setting Up the Framework Configuration File The Framework configuration file defines common file paths used to store Framework assets, integration settings between Agent Recorder and Synthetic Monitoring, and other general scripting behavior settings. To set up the Framework configuration file, perform the following steps: 1. Start the Agent Recorder and open the Asset Browser. 2. Select Test scripts, and then open the CVFW_Maintenance script. 3. Click the Playback button on the toolbar and run the script. The Synthetic Monitoring Framework Configuration window appears. 4. Configure the desired settings on each tab, and then click Save. For more information, see Configuring Framework Features [p. 39]. NOTE All tabs are saved independently from each other. After editing a field on a tab, you must click Save to save your changes for that tab. 12

13 Chapter 1 Synthetic Monitoring Scripting Framework Overview Your configuration file settings are saved in a CVFW.ini file in the following location on the Agent machine: C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData A distributable.zip file containing the CVFW.ini file is also created in this folder when you close the Synthetic Monitoring Framework Configuration window. What to Do Next After setting up the Framework configuration file on your Master Scripting Agent, you are ready to deploy the Agent Recorder database and Framework configuration.zip file to the remaining Agent machines. Deploying the Framework Before You Begin In the Synthetic Monitoring Console, add all Agents on which to deploy the database. Configure the Agent Recorder database and Framework configuration file on the Master Scripting Agent before deploying these assets to all other Agents. On all Agent machines, close Agent Recorder. The recommended deployment process for distributing the Framework Agent Recorder database on the Master Scripting Agent to all other Agent machines requires the use of the Synthetic Monitoring script publishing utility. This utility allows you to selectively choose which Agents to update. NOTE Although it is not recommended, this version of the Framework continues to support the use of a shared folder to distribute Framework assets, as directed in previous versions of the Framework. Deploy the Agent Recorder Database 1. On the Master Scripting Agent, start the Synthetic Monitoring Console. 2. Select Scripts from the Navigation pane, then select Script Publishing. 3. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. 13

14 Chapter 1 Synthetic Monitoring Scripting Framework Overview Figure 4. Publish Scripts Dialog Box - Agent Recorder 4. In the Publish Scripts dialog box, type the name of the definition in the Name field. 5. From the Scripting tool/data list, select Agent Recorder. 6. From the Data source list, select TestPartner. 7. In the Master database box, click Browse, and then select the TestPartner.mdb file in the following location: C:\ProgramData\Documents\Compuware\Recorder\DB\TestPartner.mdb NOTE For some operating systems, the Documents folder is hidden. In this instance, click Browse, and then type C:\ProgramData\Documents\Compuware\Recorder\DB\ in the Address bar of the Open dialog box. Next, select TestPartner.mdb, and then click Open. 8. From the Schedule time list, select the timing of when you want to publish. 9. Select the Agents on which to deploy the database. 10. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 11. Click Schedule. The database file is compressed and, if you enabled Publish configuration now, the compressed file is published immediately to the Agent(s), along with any other pending configuration changes. The status of the publish appears in the Publish Report. window, as shown below. 14

15 Chapter 1 Synthetic Monitoring Scripting Framework Overview Figure 5. Publish Report After running the publish scripts utility, the Status column displays Successful to indicate the database was deployed as intended. 12. Close the Publish Report window. Deploy the Agent Recorder Configuration File 13. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. Figure 6. Publish Scripts Dialog Box - UserData 14. In the Name field, type the name of the definition. 15. From the Scripting tool/data list, select UserData. 15

16 Chapter 1 Synthetic Monitoring Scripting Framework Overview 16. In the User data file box, click Browse, and then select the CVFW.zip file in the following location: C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData NOTE On Windows P machines: C:\Documents and Settings\All Users\Application Data\Compuware\ClientVantage\Data\work\Data\UserData 17. From the Schedule time list, select the timing of when you want to publish. 18. Select the Agents on which to deploy the configuration file. 19. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 20. Click Schedule. If you enabled Publish configuration now, the configuration file is published immediately to the Agent(s), along with any other pending configuration changes. Verify the Deployment of the Database and Configuration File 21. On any Agent machine on which you deployed the database and configuration file, start Agent Recorder and open the Test scripts window of the Asset Browser. A list of default Framework test scripts that start with the prefix CVFW_ and ZZ_ should appear. In the Description field of the ZZ_Release_History test script, you should see the current version of the Framework listed. 22. To verify that the configuration file was deployed successfully, run the CVFW_Maintenance script and verify that your settings appear on the various tabs of the Configuration window. Alternatively, on an Agent machine, you can open the folder C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData, and verify the modified date of the CVFW.ini file matches the time the file was published. Upgrading the Framework If you are using the Synthetic Monitoring Scripting Framework and have upgraded Synthetic Monitoring, an upgrade to the latest release of the Framework is recommended. An upgraded Framework ensures you have access to any new changes in the Framework and support for new features introduced in the current version of Synthetic Monitoring. NOTE If you do not upgrade the Framework, the following status message appears when you run a test script: Current Framework version <12.x>. An update is available for Recorder version <12.x>. Review installation instructions. Defaulting to a wait time of 30". Framework Upgrade Checklist The Framework upgrade process includes the steps listed in the following table. 16

17 Chapter 1 Synthetic Monitoring Scripting Framework Overview Table 2. Framework Upgrade Checklist Completed Steps Make a backup of the Agent Recorder database on the Master Scripting Agent from which you will deploy the updated database to all Agent machines. Import the Framework upgrade files into the Agent Recorder database. For more information, see Importing the Upgrade Files [p. 17]. Deploy the upgraded Agent Recorder database to all Agent machines. For more information, see Deploying the Framework [p. 13]. Importing the Upgrade Files The following Framework upgrade files are copied to the Agent Manager machine during a Synthetic Monitoring installation or when applying a Synthetic Monitoring Service Pack: FrameworkUpdates.ML This is an exported Agent Recorder file that contains the internal Framework scripts, modules, screen events, image maps, and object maps that are necessary for the upgrade. UserModifiableFunctions.ML This is an exported Agent Recorder file that contains a current version of Agent Recorder CVFW_User_Modifiable_Functions module. This module provides template functions that you can modify to support your environment. If you have previously edited this module, you must copy your changes out of the module prior to import, and then manually merge them back in after importing UserModifiableFunctions.ML. If you did not edit this module, you should still perform an import of this file to ensure you have the correct version available. NOTE As an alternative to importing UserModifiableFunctions.ML, a text file version (UserModifiableFunctions.txt) is available. To use this version, copy the contents of the file and manually merge them with your custom changes in the existing CVFW_User_Modifiable_Functions module. IMPORTANT The Framework upgrade files do not contain required Agent Recorder settings which are maintained in the Framework Agent Recorder database. Consequently, these files should only be used to upgrade an existing Framework Agent Recorder database. Do not use these files to install the Framework in a new Framework installation scenario. Import Framework Updates Perform the following steps to import all Framework updates with the exception of the CVFW_User_Modifiable_Functions module updates, which are imported in a separate procedure. 17

18 Chapter 1 Synthetic Monitoring Scripting Framework Overview 1. Copy the Framework upgrade files from the following location in the Agent Manager installation folder to any location on the Master Scripting Agent machine: C:\Program Files\Compuware\Synthetic Monitoring\Samples\ScriptingFramework\ 2. On the Master Scripting Agent, start Agent Recorder. 3. Choose File Import Assets. The Agent Recorder Asset Import Wizard appears. 4. Click Next. The Import File name or Directory page appears. 5. Select Import assets from a single file, browse to FrameworkUpdates.ML, and then click Next. The Items to Import page appears. 6. Select Import all assets, and then click OK. The Conflict Resolution page appears. 7. Accept the default resolution, and then click Next. The Start Importing Assets page appears. 8. Click Next and Finish to start the import process. Import CVFW_User_Modifiable_Functions Module Updates If you did not previously modify the CVFW_User_Modifiable_Functions module, use the Agent Recorder Import wizard to import the current version of the file. If you made changes to the CVFW_User_Modifiable_Functions module that you do not want to overwrite, perform the following steps: 9. Copy your changes out of the CVFW_User_Modifiable_Functions module. 10. Use the Agent Recorder Import wizard described in the previous steps to import UserModifiableFunctions.ML. 11. Paste your changes back into the newly imported CVFW_User_Modifiable_Functions module. TIP You can create a shared module to store your own functions, and then reference them in the CVFW_User_Modifiable_Functions module. Additionally, you can log what functions you changed at the top of the module to quickly identify what you need to modify. Verify That the Agent Recorder Framework Is Configured 12. Start the Agent Recorder and open the Test scripts window of the Asset Browser. In the Description field for each Framework test script, you should see the current version of the Framework listed. 18

19 Chapter 1 Synthetic Monitoring Scripting Framework Overview What to Do Next Deploy the updated Agent Recorder database to the remaining Agents in your environment. For more information, see Deploying the Framework [p. 13]. Deploying the Framework Before You Begin In the Synthetic Monitoring Console, add all Agents on which to deploy the database. Configure the Agent Recorder database and Framework configuration file on the Master Scripting Agent before deploying these assets to all other Agents. On all Agent machines, close Agent Recorder. The recommended deployment process for distributing the Framework Agent Recorder database on the Master Scripting Agent to all other Agent machines requires the use of the Synthetic Monitoring script publishing utility. This utility allows you to selectively choose which Agents to update. NOTE Although it is not recommended, this version of the Framework continues to support the use of a shared folder to distribute Framework assets, as directed in previous versions of the Framework. Deploy the Agent Recorder Database 1. On the Master Scripting Agent, start the Synthetic Monitoring Console. 2. Select Scripts from the Navigation pane, then select Script Publishing. 3. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. 19

20 Chapter 1 Synthetic Monitoring Scripting Framework Overview Figure 7. Publish Scripts Dialog Box - Agent Recorder 4. In the Publish Scripts dialog box, type the name of the definition in the Name field. 5. From the Scripting tool/data list, select Agent Recorder. 6. From the Data source list, select TestPartner. 7. In the Master database box, click Browse, and then select the TestPartner.mdb file in the following location: C:\ProgramData\Documents\Compuware\Recorder\DB\TestPartner.mdb NOTE For some operating systems, the Documents folder is hidden. In this instance, click Browse, and then type C:\ProgramData\Documents\Compuware\Recorder\DB\ in the Address bar of the Open dialog box. Next, select TestPartner.mdb, and then click Open. 8. From the Schedule time list, select the timing of when you want to publish. 9. Select the Agents on which to deploy the database. 10. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 11. Click Schedule. The database file is compressed and, if you enabled Publish configuration now, the compressed file is published immediately to the Agent(s), along with any other pending configuration changes. The status of the publish appears in the Publish Report. window, as shown below. 20

21 Chapter 1 Synthetic Monitoring Scripting Framework Overview Figure 8. Publish Report After running the publish scripts utility, the Status column displays Successful to indicate the database was deployed as intended. 12. Close the Publish Report window. Deploy the Agent Recorder Configuration File 13. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. Figure 9. Publish Scripts Dialog Box - UserData 14. In the Name field, type the name of the definition. 15. From the Scripting tool/data list, select UserData. 21

22 Chapter 1 Synthetic Monitoring Scripting Framework Overview 16. In the User data file box, click Browse, and then select the CVFW.zip file in the following location: C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData NOTE On Windows P machines: C:\Documents and Settings\All Users\Application Data\Compuware\ClientVantage\Data\work\Data\UserData 17. From the Schedule time list, select the timing of when you want to publish. 18. Select the Agents on which to deploy the configuration file. 19. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 20. Click Schedule. If you enabled Publish configuration now, the configuration file is published immediately to the Agent(s), along with any other pending configuration changes. Verify the Deployment of the Database and Configuration File 21. On any Agent machine on which you deployed the database and configuration file, start Agent Recorder and open the Test scripts window of the Asset Browser. A list of default Framework test scripts that start with the prefix CVFW_ and ZZ_ should appear. In the Description field of the ZZ_Release_History test script, you should see the current version of the Framework listed. 22. To verify that the configuration file was deployed successfully, run the CVFW_Maintenance script and verify that your settings appear on the various tabs of the Configuration window. Alternatively, on an Agent machine, you can open the folder C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData, and verify the modified date of the CVFW.ini file matches the time the file was published. 22

23 CHAPTER 2 Installing the Framework The recommended deployment of the core Synthetic Monitoring components includes a dedicated Agent on which Agent Recorder scripts are configured and tested prior to deployment to other Agents. This Agent is referred to as the Master Scripting Agent. After the completion of script testing on the Master Scripting Agent, you can deploy the Agent Recorder database using the Synthetic Monitoring script publishing utility. In addition to the Agent Recorder database, you can use the script publishing utility to deploy other Framework assets to Agent machines, such as the Framework configuration file. NOTE Once you have verified the stability of your scripts, you can also use the Master Scripting Agent to monitor applications. The installation instructions in this guide assume a Synthetic Monitoring environment that includes a Master Scripting Agent on which a remote Synthetic Monitoring Console is installed. The following diagram depicts a typical Synthetic Monitoring environment and highlights the deployment of the Agent Recorder database from the Master Scripting Agent to other Agents using the Synthetic Monitoring script publishing utility. 23

24 Chapter 2 Installing the Framework Figure 10. Synthetic Monitoring Environment with Master Scripting Agent Framework Installation Checklist The Framework installation process includes the steps listed in the following table: Table 3. Framework Installation Checklist Completed Steps Configure the Agent Recorder Framework database on the Master Scripting Agent. For more information, see Configuring the Agent Recorder Framework Database [p. 11]. Verify that the Agent Recorder Framework database was configured correctly. Run the Framework configuration file script and configure the Framework settings. For more information, see Setting Up the Framework Configuration File [p. 12]. Deploy the Agent Recorder Framework database and configuration file to all desired Agent machines. For more information, see Deploying the Framework [p. 13]. Configuring the Agent Recorder Framework Database During a Synthetic Monitoring Agent Manager installation, the Agent Recorder Framework database is copied into the Agent Manager installation folder and made available for use pending its configuration in Agent Recorder on the Master Scripting Agent. To configure the Agent Recorder Framework database as the default Agent Recorder database, perform the following steps: 24

25 Chapter 2 Installing the Framework Configure the Agent Recorder Framework Database 1. On the Master Scripting Agent, close Agent Recorder. 2. Move the Agent Recorder Framework database from the Agent Manager machine to the Master Scripting Agent: a. On the Agent Manager machine, access the Agent Recorder Framework database (TestPartner.mdb) from the following location: C:\Program Files\Compuware\Synthetic Monitoring\Samples\ScriptingFramework b. On the Master Scripting Agent, move the TestPartner.mdb file to the following location on the Agent Recorder machine: C:\ProgramData\Documents\Compuware\Recorder\DB NOTE On some operating systems, the Documents folder is hidden. To reliably navigate to the DB folder, type %ALLUSERSPROFILE%\Documents\Compuware\Recorder\DB in the Windows Explorer Address bar. c. You are prompted to replace the existing TestPartner.mdb file. Click Yes. Verify That the Agent Recorder Framework Is Configured 3. Start Agent Recorder. 4. Log on to the TestPartner database. The Test script window should open and display the default Framework scripts, which have a prefix of CVFW_ or ZZ_, as shown in the following graphic: 25

26 Chapter 2 Installing the Framework Figure 11. Framework Test Scripts in Agent Recorder In addition to the default Framework test scripts, the Framework Agent Recorder database is prepopulated with modules, shared modules, a user form, object maps, and screen events. Setting Up the Framework Configuration File The Framework configuration file defines common file paths used to store Framework assets, integration settings between Agent Recorder and Synthetic Monitoring, and other general scripting behavior settings. To set up the Framework configuration file, perform the following steps: 1. Start the Agent Recorder and open the Asset Browser. 2. Select Test scripts, and then open the CVFW_Maintenance script. 3. Click the Playback button on the toolbar and run the script. The Synthetic Monitoring Framework Configuration window appears. 4. Configure the desired settings on each tab, and then click Save. For more information, see Configuring Framework Features [p. 39]. NOTE All tabs are saved independently from each other. After editing a field on a tab, you must click Save to save your changes for that tab. 26

27 Chapter 2 Installing the Framework Your configuration file settings are saved in a CVFW.ini file in the following location on the Agent machine: C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData A distributable.zip file containing the CVFW.ini file is also created in this folder when you close the Synthetic Monitoring Framework Configuration window. What to Do Next After setting up the Framework configuration file on your Master Scripting Agent, you are ready to deploy the Agent Recorder database and Framework configuration.zip file to the remaining Agent machines. Deploying the Framework Before You Begin In the Synthetic Monitoring Console, add all Agents on which to deploy the database. Configure the Agent Recorder database and Framework configuration file on the Master Scripting Agent before deploying these assets to all other Agents. On all Agent machines, close Agent Recorder. The recommended deployment process for distributing the Framework Agent Recorder database on the Master Scripting Agent to all other Agent machines requires the use of the Synthetic Monitoring script publishing utility. This utility allows you to selectively choose which Agents to update. NOTE Although it is not recommended, this version of the Framework continues to support the use of a shared folder to distribute Framework assets, as directed in previous versions of the Framework. Deploy the Agent Recorder Database 1. On the Master Scripting Agent, start the Synthetic Monitoring Console. 2. Select Scripts from the Navigation pane, then select Script Publishing. 3. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. 27

28 Chapter 2 Installing the Framework Figure 12. Publish Scripts Dialog Box - Agent Recorder 4. In the Publish Scripts dialog box, type the name of the definition in the Name field. 5. From the Scripting tool/data list, select Agent Recorder. 6. From the Data source list, select TestPartner. 7. In the Master database box, click Browse, and then select the TestPartner.mdb file in the following location: C:\ProgramData\Documents\Compuware\Recorder\DB\TestPartner.mdb NOTE For some operating systems, the Documents folder is hidden. In this instance, click Browse, and then type C:\ProgramData\Documents\Compuware\Recorder\DB\ in the Address bar of the Open dialog box. Next, select TestPartner.mdb, and then click Open. 8. From the Schedule time list, select the timing of when you want to publish. 9. Select the Agents on which to deploy the database. 10. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 11. Click Schedule. The database file is compressed and, if you enabled Publish configuration now, the compressed file is published immediately to the Agent(s), along with any other pending configuration changes. The status of the publish appears in the Publish Report. window, as shown below. 28

29 Chapter 2 Installing the Framework Figure 13. Publish Report After running the publish scripts utility, the Status column displays Successful to indicate the database was deployed as intended. 12. Close the Publish Report window. Deploy the Agent Recorder Configuration File 13. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. Figure 14. Publish Scripts Dialog Box - UserData 14. In the Name field, type the name of the definition. 15. From the Scripting tool/data list, select UserData. 29

30 Chapter 2 Installing the Framework 16. In the User data file box, click Browse, and then select the CVFW.zip file in the following location: C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData NOTE On Windows P machines: C:\Documents and Settings\All Users\Application Data\Compuware\ClientVantage\Data\work\Data\UserData 17. From the Schedule time list, select the timing of when you want to publish. 18. Select the Agents on which to deploy the configuration file. 19. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 20. Click Schedule. If you enabled Publish configuration now, the configuration file is published immediately to the Agent(s), along with any other pending configuration changes. Verify the Deployment of the Database and Configuration File 21. On any Agent machine on which you deployed the database and configuration file, start Agent Recorder and open the Test scripts window of the Asset Browser. A list of default Framework test scripts that start with the prefix CVFW_ and ZZ_ should appear. In the Description field of the ZZ_Release_History test script, you should see the current version of the Framework listed. 22. To verify that the configuration file was deployed successfully, run the CVFW_Maintenance script and verify that your settings appear on the various tabs of the Configuration window. Alternatively, on an Agent machine, you can open the folder C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData, and verify the modified date of the CVFW.ini file matches the time the file was published. 30

31 CHAPTER 3 Upgrading the Framework If you are using the Synthetic Monitoring Scripting Framework and have upgraded Synthetic Monitoring, an upgrade to the latest release of the Framework is recommended. An upgraded Framework ensures you have access to any new changes in the Framework and support for new features introduced in the current version of Synthetic Monitoring. NOTE If you do not upgrade the Framework, the following status message appears when you run a test script: Current Framework version <12.x>. An update is available for Recorder version <12.x>. Review installation instructions. Defaulting to a wait time of 30". Framework Upgrade Checklist The Framework upgrade process includes the steps listed in the following table. Table 4. Framework Upgrade Checklist Completed Steps Make a backup of the Agent Recorder database on the Master Scripting Agent from which you will deploy the updated database to all Agent machines. Import the Framework upgrade files into the Agent Recorder database. For more information, see Importing the Upgrade Files [p. 17]. Deploy the upgraded Agent Recorder database to all Agent machines. For more information, see Deploying the Framework [p. 13]. Importing the Upgrade Files The following Framework upgrade files are copied to the Agent Manager machine during a Synthetic Monitoring installation or when applying a Synthetic Monitoring Service Pack: 31

32 Chapter 3 Upgrading the Framework FrameworkUpdates.ML This is an exported Agent Recorder file that contains the internal Framework scripts, modules, screen events, image maps, and object maps that are necessary for the upgrade. UserModifiableFunctions.ML This is an exported Agent Recorder file that contains a current version of Agent Recorder CVFW_User_Modifiable_Functions module. This module provides template functions that you can modify to support your environment. If you have previously edited this module, you must copy your changes out of the module prior to import, and then manually merge them back in after importing UserModifiableFunctions.ML. If you did not edit this module, you should still perform an import of this file to ensure you have the correct version available. NOTE As an alternative to importing UserModifiableFunctions.ML, a text file version (UserModifiableFunctions.txt) is available. To use this version, copy the contents of the file and manually merge them with your custom changes in the existing CVFW_User_Modifiable_Functions module. IMPORTANT The Framework upgrade files do not contain required Agent Recorder settings which are maintained in the Framework Agent Recorder database. Consequently, these files should only be used to upgrade an existing Framework Agent Recorder database. Do not use these files to install the Framework in a new Framework installation scenario. Import Framework Updates Perform the following steps to import all Framework updates with the exception of the CVFW_User_Modifiable_Functions module updates, which are imported in a separate procedure. 1. Copy the Framework upgrade files from the following location in the Agent Manager installation folder to any location on the Master Scripting Agent machine: C:\Program Files\Compuware\Synthetic Monitoring\Samples\ScriptingFramework\ 2. On the Master Scripting Agent, start Agent Recorder. 3. Choose File Import Assets. The Agent Recorder Asset Import Wizard appears. 4. Click Next. The Import File name or Directory page appears. 5. Select Import assets from a single file, browse to FrameworkUpdates.ML, and then click Next. The Items to Import page appears. 6. Select Import all assets, and then click OK. 32

33 Chapter 3 Upgrading the Framework The Conflict Resolution page appears. 7. Accept the default resolution, and then click Next. The Start Importing Assets page appears. 8. Click Next and Finish to start the import process. Import CVFW_User_Modifiable_Functions Module Updates If you did not previously modify the CVFW_User_Modifiable_Functions module, use the Agent Recorder Import wizard to import the current version of the file. If you made changes to the CVFW_User_Modifiable_Functions module that you do not want to overwrite, perform the following steps: 9. Copy your changes out of the CVFW_User_Modifiable_Functions module. 10. Use the Agent Recorder Import wizard described in the previous steps to import UserModifiableFunctions.ML. 11. Paste your changes back into the newly imported CVFW_User_Modifiable_Functions module. TIP You can create a shared module to store your own functions, and then reference them in the CVFW_User_Modifiable_Functions module. Additionally, you can log what functions you changed at the top of the module to quickly identify what you need to modify. Verify That the Agent Recorder Framework Is Configured 12. Start the Agent Recorder and open the Test scripts window of the Asset Browser. In the Description field for each Framework test script, you should see the current version of the Framework listed. What to Do Next Deploy the updated Agent Recorder database to the remaining Agents in your environment. For more information, see Deploying the Framework [p. 13]. Deploying the Framework Before You Begin In the Synthetic Monitoring Console, add all Agents on which to deploy the database. Configure the Agent Recorder database and Framework configuration file on the Master Scripting Agent before deploying these assets to all other Agents. On all Agent machines, close Agent Recorder. The recommended deployment process for distributing the Framework Agent Recorder database on the Master Scripting Agent to all other Agent machines requires the use of the Synthetic Monitoring script publishing utility. This utility allows you to selectively choose which Agents to update. 33

34 Chapter 3 Upgrading the Framework NOTE Although it is not recommended, this version of the Framework continues to support the use of a shared folder to distribute Framework assets, as directed in previous versions of the Framework. Deploy the Agent Recorder Database 1. On the Master Scripting Agent, start the Synthetic Monitoring Console. 2. Select Scripts from the Navigation pane, then select Script Publishing. 3. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. Figure 15. Publish Scripts Dialog Box - Agent Recorder 4. In the Publish Scripts dialog box, type the name of the definition in the Name field. 5. From the Scripting tool/data list, select Agent Recorder. 6. From the Data source list, select TestPartner. 7. In the Master database box, click Browse, and then select the TestPartner.mdb file in the following location: C:\ProgramData\Documents\Compuware\Recorder\DB\TestPartner.mdb NOTE For some operating systems, the Documents folder is hidden. In this instance, click Browse, and then type C:\ProgramData\Documents\Compuware\Recorder\DB\ in the Address bar of the Open dialog box. Next, select TestPartner.mdb, and then click Open. 34

35 Chapter 3 Upgrading the Framework 8. From the Schedule time list, select the timing of when you want to publish. 9. Select the Agents on which to deploy the database. 10. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 11. Click Schedule. The database file is compressed and, if you enabled Publish configuration now, the compressed file is published immediately to the Agent(s), along with any other pending configuration changes. The status of the publish appears in the Publish Report. window, as shown below. Figure 16. Publish Report After running the publish scripts utility, the Status column displays Successful to indicate the database was deployed as intended. 12. Close the Publish Report window. Deploy the Agent Recorder Configuration File 13. Right-click in the Script Publishing grid, and then select Add. The Publish Scripts dialog box appears. 35

36 Chapter 3 Upgrading the Framework Figure 17. Publish Scripts Dialog Box - UserData 14. In the Name field, type the name of the definition. 15. From the Scripting tool/data list, select UserData. 16. In the User data file box, click Browse, and then select the CVFW.zip file in the following location: C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData NOTE On Windows P machines: C:\Documents and Settings\All Users\Application Data\Compuware\ClientVantage\Data\work\Data\UserData 17. From the Schedule time list, select the timing of when you want to publish. 18. Select the Agents on which to deploy the configuration file. 19. Optionally, select the Publish configuration now check box to immediately publish to all selected Agents. 20. Click Schedule. If you enabled Publish configuration now, the configuration file is published immediately to the Agent(s), along with any other pending configuration changes. Verify the Deployment of the Database and Configuration File 21. On any Agent machine on which you deployed the database and configuration file, start Agent Recorder and open the Test scripts window of the Asset Browser. A list of default Framework test scripts that start with the prefix CVFW_ and ZZ_ should appear. In the Description field of the ZZ_Release_History test script, you should see the current version of the Framework listed. 36

37 Chapter 3 Upgrading the Framework 22. To verify that the configuration file was deployed successfully, run the CVFW_Maintenance script and verify that your settings appear on the various tabs of the Configuration window. Alternatively, on an Agent machine, you can open the folder C:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData, and verify the modified date of the CVFW.ini file matches the time the file was published. 37

38 Chapter 3 Upgrading the Framework 38

39 CHAPTER 4 Configuring Framework Features The Framework configuration file defines common file paths used to store Framework assets, integration settings between Agent Recorder and Synthetic Monitoring, and other general scripting behavior settings. To access the configuration file user interface, you must play back the CVFW_Maintenance script in Agent Recorder to open the Synthetic Monitoring Framework Configuration dialog box. In this dialog box, you can configure and save the desired Framework features in a distributable configuration file. For more information, see Setting Up the Framework Configuration File [p. 12]. This section describes the configurable features of the Framework as they appear on the various tabs of the Synthetic Monitoring Framework Configuration window. Global Tab Agent Manager Path Although not required, you can create a shared public folder on the Agent Manager server to store and distribute Framework-specific files. This folder should be under the data directory that Synthetic Monitoring uses. The subdirectory should be called Framework. For example: \\AMServer\ProgramData\Compuware\Synthetic Monitoring\SYMShare\Framework. Error Handling & Printscreens Extended Logging The Framework's logging feature offers an enhanced alternative to the default Agent Recorder logging feature. The Framework offers three logging options, ranging from none to fairly extensive. The logs are created in the work folder on the Agent machine (C:\ProgramData\Compuware\ClientVantage\Data\work). The logs are named [Agent name]-[day of week].log. For example, YZ74891N01-Wed.log. By checking the Copy to Share at Script End check box, the log file will be copied up to the shared folder on the Agent Manager machine at the end of every script. If bandwidth is an issue, it may be preferable to have this option disabled. The Generations to keep option specifies how many logs are kept on the local hard drive. 39

40 Chapter 4 Configuring Framework Features The Framework takes a screen shot if a script encounters an error or if a transaction is running. If desired, however, the Framework can always take a screen shot by selecting the box Always take a local print screen. The directory option configures where the files are placed on the server at the end of the script. There are also options for creating subfolders under that path, depending on your preferences. In addition, the Framework can limit the number of screen shots that are taken by the Agent when it encounters consecutive errors. For example, if an application encounters the same error more than five times consecutively, another screen shot is not necessary. The same is true for trace files. NOTE The screen shot suppression only affects screen shots created in MS Paint for non-monitored transactions. When an Agent encounters an error for the first time (in any period), it stores an extensive task list in the log file. The entry shows memory usage, CPU usage, file dates, version numbers, file locations, etc. This can be a valuable aid to troubleshooting a problem Agent. To enable this option, select the Log running tasks on first abend check box. This is checked by default. Since the scripts take screen shots of the desktop when an error occurs and the files are placed on the server, there needs to be a maintenance process to remove files that are a certain age. There are two ways to accomplish this. First, it can be done from this screen. An alternative method is to create a scheduled task that runs the script CVFW_Purge_Old_Printscreens. Set it as a scheduled task or a transaction to run from one (and only one) Agent once a day or week, depending on how many files are created. When it executes, it reads the value set above and deletes.jpg and.bmp files older than that value. The default is 10 days, but can be set from 1 to 60. NOTE This option is only for screen shots saved by MS Paint for non-monitored transactions. It does not purge screen shots taken by Synthetic Monitoring and stored in the Synthetic Monitoring database. Baselines Baselines are critical to the trace management process. They are also important for troubleshooting purposes when comparing what happened during a problem versus what happens in a no or low-load situation. To create a baseline, you can either use the Take Baseline option in the Add Active Agents section in the Synthetic Monitoring Console or use the Framework's Take Baseline option. The Framework can use either option. The Synthetic Monitoring Console option forces the Agent to save a baseline when a script runs on that Agent. This results in a baseline for every application that executes on that Agent. The Framework baseline option selects a time when the Agent will save a baseline. By selecting a time, it saves a baseline for all applications based on a time selected. This can be when the load on the network is the lightest resulting in an ideal situation in which all others are compared. The default time 40

41 Chapter 4 Configuring Framework Features is 5:00 AM, which is often after backup and overnight batch processes have completed and before employees start logging in. To use the Framework baseline option, select the Take Baseline check box and select the desired time; for example, 5:00 (it uses 24-hour format). When the Save button is clicked and the file is sent to the shared folder, the Agents will save a baseline the first time the script runs after 5:00 am. It will not take one again for that day. You can also set it to take a baseline the first run after a time on a specific day. The While Checked value will save a baseline every time the script runs. This is not recommended for times other than the first time while developing the scripts and transactions. At this time, choosing a specific application and/or specific Agent is not built in to the Framework. Kiosk Mode Since Synthetic Monitoring Agents require the desktop to remain unlocked, displaying a splash screen web page warning people not to use the machine can give the illusion of the desktop being locked. It can also warn people not to use the Agent for things other than Synthetic Monitoring. This option is turned on at the end of an application script and closed at the beginning. A Kiosk mode web page (KioskPage.htm) is located in the following Agent machine installation folder: C:\Program Files\Compuware\Synthetic Monitoring\Recorder\Samples. Either copy this file to the shared folder on the Agent Manager machine or distribute this file to a folder on the Agent. After moving this file to the desired location, specify the path in the Display this File box. The Kiosk page included with the Framework can be edited in Notepad with the proper contact name and phone number (located toward the bottom of the.htm file) by clicking on the Edit button. It will open the file in Notepad and do a search for [Your Name Here] for entering the contact information. Database Connections The Framework uses the database connection to get the Agent names that have been configured in the Synthetic Monitoring Console as well as the Synthetic Monitoring database. It is also used to retrieve the available schedules for use when importing transactions into the Console (ID and password are encrypted as above). Be sure to test the connections before proceeding. Passwords Tab ID and Password Encryption While Agent Recorder can encrypt passwords when recording text in a password field, this is not always preferred. For example, if a password expires, the database must be modified with the new password. The other time encryption is not practical is when passwords are recorded while typing in a Citrix window. It is plain text at this point. This functionality takes advantage of Agent Recorder's ability to encrypt and decrypt a password string. 41

42 Chapter 4 Configuring Framework Features Select the application name for which to enter the ID and password. Enter the ID and password. The Save button is enabled when both password fields match. Up to 99 IDs and passwords may be entered for each application. The Use Check-in/Check-out option is useful for applications that restrict the number of available IDs and passwords. For example, if an application only has two IDs available and there are five Agents running the script, three of the Agents would run into a problem if they all started at the same time. This process uses the shared folder to add and delete the use of IDs. To utilize the password functionality in a script, use the GetID and GetPassword functions. Locate the part of the script that types the ID and password. It will usually look something like this: HTMLEditBox("Name=username").SetText "MyID" HTMLEditBox("Name=password").SetPasswordText "TTFAd371dh37f" First, replace the ID portion with GetID, passing the application name and then replace the SetPasswordText with SetText and use the GetPassword function as shown below: ShowStatusBox ("Entering in the ID and Password...") Window("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLEditBox("Name=username").SetText GetID( "MyApp") HTMLEditBox("Name=password").SetText GetPassword("MyApp") There are a few variations that can be used for both the GetID and GetPassword functions. If the same ID and password can be used for multiple applications, just add the name of the application that it is sharing the ID. HTMLEditBox("Name=username").SetText GetID("MyOtherApp") Another feature is multiple IDs and passwords for the same application. To select the second application, add the number two (surrounded in quotes) after the application name as shown below. HTMLEditBox("Name=username").SetText GetID("MyOtherApp", "2") Assigning IDs by Agent If the databases are configured in the Database Connections section on the Global tab, you can assign unique IDs to specific Agents. To use this feature, update the Agent list from the Agents tab. The list of Agents appears on the right side of the screen. Select the application, enter the IDs to use (saving after each entry), and then select the Assign ID by HostName check box. The Agent list will be enabled on the right side of the screen. Select each Agent and the ID number to use, by clicking the Update button for each one. Optionally, you can have the script trigger an error if no ID is assigned or it can use a default ID number. This option can be set in the section above the Agent list. To take advantage of this feature in a script, use the GetID and GetPassword functions as if there were only one ID. HTMLEditBox("Name=username").SetText GetID("MyOtherApp") You can also use this syntax, which will make it clearer when editing the script. HTMLEditBox("Name=username").SetText GetID("MyOtherApp", AgentName) 42

43 Blackouts Tab The functionality provided on this tab has been incorporated into the core Synthetic Monitoring feature set. For more information, refer to the Blackout Schedule Overview topic in the Synthetic Monitoring Console Help. Holidays Tab Tab The Holidays tab enables you to create a user-defined holiday that can then be used in the Scheduling tab in the Synthetic Monitoring Console to suppress the running of scripts on certain days. Common US holidays are entered by default. The date of Easter is updated automatically to show the next occurrence. To add a holiday, type it into the Holiday Name box, select the proper parameters, and then click Add. To remove a holiday, select it from the Defined Holidays list, and then click Remove. The Framework provides an optional alerting mechanism that you can use to create conditional, application-specific alert that triggers a notification . Use the settings on the tab to configure the Framework alert notification settings. Under Global settings, you can configure the default subject, recipient, and sender. Under Template settings, you can override the default settings and configure a conditional, application-specific alert. To create a new template, type the name of the template in the Alerting Template list box. Next, define the desired conditions and address, and then click Save Template. Finally, select the applications to assign to the template, and then click Apply to App. NOTE Make sure to use the semi colon (;) to delimit between addresses. Chapter 4 Configuring Framework Features Agents Tab To use the Framework's Agent features, a list of Agent names is required in the Framework configuration file. A shared folder and tested connectivity to the databases will make the task easier. Select the Agents tab. If the shared folder and/or the database connections have been configured, press the Update Agent List button. The list of Agents will appear in the box on the left. These names will need to be edited if IP addresses were used in the Console. If neither the shared folder nor the database connectivity was available, the host names can be manually entered. UserDefined Tab Some applications often require fields such as customer numbers, purchase orders, and patient numbers to be entered into a field to do a search. If the values never change, leaving the recorded 43

44 Chapter 4 Configuring Framework Features value is acceptable. If the values can change, however, it is best to use a variable. The value assigned to a variable can be hard-coded with logic based on the Agent name or some other value. Another and often better option is to have the variable read the value from the Framework configuration file. This avoids the need to change the value in the database and redistribute it every time the value changes, or worse yet have a specific script database for each Agent. To use a variable in the parameter file, select the application on the list on the left, type a static value in the Key box, and then type the value in the Value box. An example of how to retrieve the parameter is displayed and can be copied and pasted into the script. NOTE To copy, use the [Ctrl+Insert] instead of [Ctrl+C]. This is a limitation of Agent Recorder. Be sure to save after entering every entry. To delete a value, select it from the Existing Entries box. Clear the Value field, and then press Save. Another example is using an ID instead of the Agent name. The ID number can be selected from the Framework configuration file (CVFW.ini) and used in the GetID and GetPassword functions. Since the values are stored in the configuration file, they are immediately distributed to all the Agents as they run a script. Some of the common built-in properties that are available to you are: AppIniFile The entire path and file name of the parameter file. AgentName The name of the Agent machine the script is running on. CVLocation The location assigned to the Agent in the Console. AgentAttribute1 The value set in the Console. AgentAttribute2 The value set in the Console. Integration Tab The Integration tab configures how Agent Recorder communicates with Synthetic Monitoring. For most installations, the defaults are sufficient. Script Health Alert Settings This section configures the use of the Synthetic Monitoring Console Health Monitoring feature. This threshold controls when Synthetic Monitoring reports a script health warning or a script health error status. Notify Events The NotifyEvent section configures the actual NotifyEvent command that is sent to the Synthetic Monitoring Open Script API. Notify events are rarely changed. Keep in mind that they are case-sensitive and affect transactions. IMPORTANT The Framework does not support the use of Script Start and Script Stop to signify the start and stop of transactions. That practice is highly discouraged. Always use NotifyEvents, which is the default. 44

45 Chapter 4 Configuring Framework Features By default, spaces are replaced with underscores because of SNMP trap limitations. If spaces are required, then check the Allow Spaces check box. Note that this will affect the actual NotifyEvent sent to Synthetic Monitoring and will affect all transactions. Transaction Import Details This feature controls the way that transactions are imported into the Synthetic Monitoring Console. Check the Prefix Transaction Names w/sequence check box to make the reports in VantageView appear in chronological order. This will prepend the transaction names with the sequence in which they were created. When you select this option, the imported file will already have the sequence number on them. This only affects the creation of the import and not the running of the script. The script and timings will all be the same regardless if this box is checked. This often makes more sense to an application owner when the Launch/Login transaction is displayed before the Display results transaction. The Prefix Transaction Names w/sequence check box will rarely be checked since it modifies how the NotifyEvents are triggered. If it is important to match the NotifyEvents with the transaction name, check the box. NOTE It is strongly discouraged to check this box because it affects all transactions and sequences change if a step is added or removed. In fact, this box affects all transactions during runtime as well as the import file and can adversely all transactions The SLA multiplier can be helpful when trying to decide how long an SLA should be. During run time, the script keeps track of how long each transaction ran. When the transaction is completed, it takes that execution time and multiplies it by one plus the value shown, and the result is displayed as the SLA in the Synthetic Monitoring Console. For example, if a transaction runs for 10 seconds during development, the Framework will multiply that time by 1.5 (the value shown above), giving an SLA of 15 seconds. If the transaction was completed in less than three seconds, however, the SLA Minimum would take effect and would set the SLA to a minimum of 5 seconds. All values are rounded to the next 5 seconds during import. Launch to Close Transaction Numbers and Names Monitoring an application from start to finish is very important, especially if there are sections within the script that are not being actively monitored. This allows for the capture of errors with disabled controls, links not existing, etc. This section helps create the entry for importing the Launch-to-Close transaction into the Synthetic Monitoring Console. If this option is not selected, the results could show the transactions that are monitored performed as they were supposed to, but the remaining ones never executed and no alert would occur. For example, the launch of the application could work, but clicking on a link may cause an error because the words changed. By monitoring the launch-to-close transaction, an alert would be sent due to the error. In addition, a screen shot of the problem would be created. The numbering of the transaction is useful, especially when using numbering in the normal transactions. Using the 999_ option moves this transaction to the bottom of the list. Choosing 000_ puts it at the top. 45

46 Chapter 4 Configuring Framework Features NOTE No traces will be started during this transaction. The script does not execute a StartTrace command, nor should it be set to use a Statistical CNS. It should only be used for availability and overall timing of an application. Transaction File Exports The options in this section configure the import file itself. By default, the schedule number displayed in the Default Schedule list is assigned to all scripts regardless of the default set in the Console. If the VantageView database was configured, the Get Schedules from VV option is enabled. This option selects the names of the schedules as well as the default schedule. In the Path box, you can specify an additional location to store the export file. If a valid value is entered and the check box is selected, a duplicate copy of the export file is stored in that path. This allows other machines to use these files to import via the Synthetic Monitoring Console import feature. Self Documentation File Path The Self Documentation feature is a very useful feature of the Framework. If Microsoft Word is installed on the Agent, the Self Documentation feature can create a Microsoft Word document that shows all of the steps the script executes. This section sets the location in which the Microsoft Word file is stored. Alerting When an Error Occurs Between Transactions Occasionally, a script can encounter an error condition between transactions. For example, the developer may have changed the name of an object ("Name=q") and the script cannot attach to it. If no transactions are running (or the Synthetic Monitoring Agent is not listening to the transaction), the script will end without triggering an alert. To ensure that an alert is triggered, you can use the AddTransaction function. In the example shown below, if an error occurs during the typing in of the search criteria, the transaction "Google_SYM" will be marked unavailable and a screen shot will be taken displaying the actual error. While the most common use is to add the next transaction only if there are steps before the next StartTrace, it is also acceptable to add all transactions before the launch step. The results of that practice is all transactions that follow the transaction in error will also be marked unavailable. StopTimerAndTrace "Google_Launch" ' END ^^^^^^^^^^ ' Active AddTransaction "Google_SYM" ShowStatusBox "Entering search criteria...", True IEWindow("Internet Explorer MainWindow").Attach HTMLEditBox("Name=q").SetText "compuware synthetic monitoring" ShowStatusBox "Clicking on the 'Google Search' button...", True StartTrace "Google_SYM" ' START vvvvvvvvvvvvv IEWindow("Internet Explorer MainWindow").Attach HTMLButton("Name=btnG").Click WaitForTextDelimited "Internet Explorer MainWindow", "results,of about" StopTimerAndTrace "Google_SYM" ' END ^^^^^^^^^^^^^^^ 46

47 Chapter 4 Configuring Framework Features In this case, if an error occurs during the entering of the search criteria, the "Google_SYM" will be marked unavailable. Agent Auto-login Windows computers should be rebooted periodically due to memory leaks and several other factors. Synthetic Monitoring and the Agent Recorder require that the computer is logged on in order to execute any scripts. This creates an issue if the machine is not configured to automatically log back on when it is rebooted. There are a few ways to configure the machines to log in every time it is rebooted. By default, Windows reads certain registry entries on startup. These entries are listed in the Autologin.reg file supplied with the Framework installation. This file can be modified and these entries can be imported into the registry. The downside of this approach is that the password is stored in plain text. This violates most security policies. To minimize this exposure, the function RebootRobot can enter the password into the registry entry just before the machine is rebooted. It has an optional parameter that, when set to True, will blank the password field in the registry as the Agent is logged back in. While not a high security solution, it is much better than leaving the password in the registry. The script CVFW_Reboot_Driver can be edited and used as a scheduled task to reboot the Agent. Another alternative is to use the TweakUI.exe from Microsoft. It will configure the machine to log in without a plain text password. This utility can be downloaded directly from Microsoft. 47

48 Chapter 4 Configuring Framework Features 48

49 CHAPTER 5 Framework Scripts Included in the Framework are several types of scripts, each of which performs the following general tasks: Initialize the environment. Perform a business process that includes transactions. Clean up and return the Agent to the original state. The common steps of a transaction are: 1. Determine what script is running and what events are being waited for by using the ShowStatusBox function, which acts as a comment as well as an entry in the script documentation. 2. Start the transaction using the StartTrace function. 3. Perform an action such as clicking on a button or pressing [Enter]. Never start the transaction after the action. 4. Verify the results using a verification function such as WaitForText or WaitForImage. Always verify before continuing to the next step. 5. Stop the transaction using the StopTimerAndTrace function. Framework Script Types The Framework supports the following types of basic scripts: Development Mode Script Application Driver Script (Production_App_Driver) Child Script Agent Driver Script Most scripts start out as Development Mode scripts and end up as an Application Driver script, also known as a Production_App_Driver script. A script can be in any of the following modes, which are used at various times in the development process: 49

50 Chapter 5 Framework Scripts TEST_ONLY_NoScriptType Import Mode Self Documentation Mode TEST_ONLY_NoScriptType is rarely used and is used for testing single lines of code. Self Documentation mode and Import mode are used when a script is complete and ready to either create a Word document of what it is doing during run (Self Documentation) or create an import file for the Synthetic Monitoring Console. Development Mode Script This is how all scripts should start. Technically speaking, a Development Mode script is not really a script type because it does not have initialization or configuration. It simply runs the code displayed in the script. A Development Mode script should not be used in production. Application Driver Script (Production_App_Driver) An Application Driver is the primary script type and is designed to perform the same function as a task in the Synthetic Monitoring Console, which contains one application. An Application Driver script is equivalent to a specific business process. It typically contains all of the steps including the launch, login, actionable steps required to monitor the application, and the logout and close steps. An Application Driver script contains a significant amount of integration with Synthetic Monitoring. As every transaction is executed, the Framework keeps track of how long each one executes. It knows how much time is left in a transaction and adjusts the wait times accordingly. When a script ends, it checks to make sure that all transactions started and completed successfully. If one or more transactions did not complete, it will give a visual alert as well as mark any unfinished transactions as unavailable and create a screen shot for each of them. The Application Driver script contains the following parts: InitializeScript Resets the scripting environment to empty. For example, it aborts running trace files and resets any error conditions if they exist. It initializes the variable called AppName that is used throughout the script. The script name ultimately ends up to be the application name in the Synthetic Monitoring Console. This is why the script name is important and should always end with _Driver. Since all transactions are logged by the Application Driver script, it resets the inventory of transaction details to empty. It takes an inventory of all running applications. It checks to see whether the application is in a blackout period and if so, exits the script. If it is not in a blackout period, it calls the UserInitAppDriver function defined in the User_Modifiable_Functions module. If an Application Driver script calls another Application Driver script, all variables will be reset. For this reason, do not call an Application Driver script from another Application Driver script. EndScript Stops the timer of the script, stops all trace files, and checks in any ID that was checked out during the script. It handles some return to normal functionality and 50

51 Chapter 5 Framework Scripts calls the UserEndOfAppDriver function defined in the User_Modifiable_Functions module. It logs the ending status of the script, and moves any non- Synthetic Monitoring print screen files to the shared folder (if used). It verifies that all transactions that were started or even configured have reported to the Synthetic Monitoring Agent. HandleScriptErrors It is very important to leave the HandleScriptErrors as the first line of the error handler routine. Do not put anything between the ERRORHANDLER and the HandleScriptErrors lines. This is because it logs and displays the exact error text that caused the error itself, and then captures a screen shot. If any code is added before the HandleScriptErrors, both the Agent Recorder and VB reset the error object and the print screens will display a blank error message. End of the Application Driver Script Whether successful or in error, the script attempts to return the desktop to the same status it was when the script started. Both the EndScript and HandleScriptErrors functions call a function called CleanUpDesktop which first calls a user-defined function UserCleanUpDesktop, which can be used for custom closing steps. After UserCleanupDesktop executes, CleanUpDesktop attempts to close all applications that were not running when the script began. Child Script This is the most basic script type. It is designed to do one or two steps that are called by more than one application. They execute very few, but still important steps during the InitializeScript, EndOfScript, and HandleScriptErrors function calls. The most common use of a Child script is to launch and log in to an application or web site that is used by several Application Driver scripts. The error handling routine is limited to taking a screen shot and returning a value of false. While Child scripts are common in some other scripting languages, a much more efficient method in the Agent Recorder is to use a subroutine (Sub) or function for processes that are called by more than one application or more than one time in a single application. For best results, these routines can be located either at the bottom of the Application script itself, in the CVFW_UserModifiable_Functions module or in a shared module. Agent Driver Script An Agent Driver script was originally used in the ClientVantage 9.x Release that used the Windows scheduler. Since the scheduling mechanism was incorporated into ClientVantage 10.0, an Agent Driver is rarely necessary. An Agent Driver script only contains commands to run one or more Application Driver scripts. For an example, see the ZZ_Agent_Driver script. It, like a Child script, executes very few, but still important steps during the InitializeScript, EndOfScript as well as the HandleScriptErrors function calls. It is not intended to be used for combining the steps of an application. Storing Scripts in Shared Modules The advantage of a shared module is that it does not need to be explicitly included in any script. All of the functions are available to all scripts. This makes it ideal for complex error handling routines such as closing out a Citrix application. For best results, create one shared module that 51

52 Chapter 5 Framework Scripts will contain any process that is necessary for an application that requires a special error handling process. NOTE Most applications can be scripted in one Application Driver script. Most applications are the same as a business process. While in some tools it is preferable to break each step into its own script, in the Agent Recorder, this is not efficient. Navigating between individual scripts is not optimal. Creating a Script Using the Framework Script Template The default script template included in the Framework provides the common code required for initialization, scripting transactions, ending the script, and error handling. This script template should always be used when creating new scripts. 1. Stop or disable the Synthetic Monitoring Agent. If scripts are scheduled to run on the Master Scripting Agent, it is usually best to disable the Agent from the Console to prevent the Agent from running a script while creating a new script or modifying an existing script. Do not forget to publish the configuration. 2. Create a new test script. Choose File New The New Asset dialog box appears. 3. Select Test script, type the name of the script, and then click OK. TIP VBA prohibits the use of spaces in script names. For best results, end the name with the suffix _Driver. The View code window opens and displays the following template script. 'Script Name: Option Explicit 'Requires variables to be declared ahead of time (debugging aid) Dim ScriptType As ScriptTypes 'Simplifies script type determination Sub Main() On Error GoTo ErrorHandler ' Always start with ScriptType=Development_Mode.! Change to Production_App_Driver when ready to deploy. ' To change the type, delete the existing value ' then press Ctrl+Space to choose the desired option. ScriptType = Development_Mode '**** Only change this line to add an optional app acronym **** Call InitializeScript(ScriptType, Me.Name) ' DO NOT ADD ANYTHING ABOVE THIS LINE ' This launches IE to an empty page. Delete this line if it's not an IE app 'LaunchIE 'ShowStatusBox "Navigating to ''...", False ' Launch 'StartTrace "" ' START vvvvvvvvvvvvv 52

53 Chapter 5 Framework Scripts 'GoToPage "" 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ ' Enter criteria (not part of a transaction) 'ShowStatusBox "Entering login criteria...", False ' ****** Duplicate the section below as the prototype for your transactions! & delete this line**** ' 'ShowStatusBox "Clicking on the '' button...", True 'StartTrace "" ' START vvvvvvvvvvvvv 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ ' DO NOT ADD ANYTHING BELOW THIS LINE Call EndScript(ScriptType) ' **** Do not change this line **** Exit Sub ErrorHandler: 'Don't put anything in this section. Put your custom error handling in 'UserCleanupDesktop instead. **** HandleScriptErrors (ScriptType) ' **** Do not change this line. **** End Sub 'Transaction template ' 'ShowStatusBox "Clicking on the '' button...", True 'StartTrace "" ' START vvvvvvvvvvvvv 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ This example script is set to Development mode. Once the script is completed, you should reset the mode. The long dotted lines at the top and bottom of the script labeled DO NOT ADD ANYTHING ABOVE THIS LINE and DO NOT ANYTHING BELOW THIS LINE signify restricted areas of the script. With very few exceptions, you should only add code between these lines. The line with two dashed sections is the label the section separator. This is usually used for adding the name of the transaction that will follow. Using this greatly improves readability of the script. The ShowStatusBox line serves three purposes: It helps comment the script. When the script executes, it displays the text at the top of the screen. This is very useful for knowing what the script is doing when the scripts execute on the Agents. The last parameter determines whether the step will be included in the document when the script is run in Self Documentation mode. NOTE Do not use a generic description such as Starting transaction 1. This serves very little purpose. Create a description that provides specific details about what the script is doing: for example, Clicking the OK button or Entering the ID and password. This is especially useful when the recorded script does not contain a control that is easy to identify. The True parameter is a special one used to include this line if Self Documentation mode is invoked. 53

54 Chapter 5 Framework Scripts The StartTrace function is used to start the transaction. By default, it is the name of the transaction configured in the Synthetic Monitoring Console. It starts the network packet capture and the timer associated with it. In addition, it reads the configuration from the Synthetic Monitoring Console to set the amount of time the transaction used in the WaitFor functions. IMPORTANT StartTimer does not affect wait times. The blank line is where the steps will be recorded. Scripts are easier to follow if the action is grouped and the verification is grouped as shown above. The WaitForText line is the place where the script verifies (or synchronizes) the result of the action that was just performed. This function waits up to the remaining time left in the transaction (as defined by the StartTrace) before it gives up. There are several WaitFor functions from which to choose, depending on the type of application being scripted. The WaitforText is the fastest and most commonly used function. For more information, see Wait Functions [p. 93]. The StopTimerAndTrace line tells Synthetic Monitoring to stop the network packet capture and timer that it started above. Ensure that the text entered in the StartTrace matches the text in the StopTimerAndTrace. The Framework will alert you if there are unmatched transactions. Walkthrough: Creating an Application Driver Script This walkthrough demonstrates the process of creating an Application Driver script that contains the necessary code to monitor a typical web application. A completed script of this walkthrough, ZZ_Google_Driver, is included in the default installation of the Framework. In addition, the general steps of this walkthrough are documented in the Framework Scripting checklists. For more information, see Framework Scripting Checklists [p. 91]. Create a Script and Add the Script Name Create a new test script using the Framework script template. For more information, see Creating a Script Using the Framework Script Template [p. 52]. Typing the script name at the top of the script helps identify the script, especially if it is printed. The Option Explicit parameter is helpful when variables need to be declared in a script. It requires that a variable be declared before it is used. It protects from typographical errors as well as from trying to put the wrong type of data into a variable when running a script. If there are no variables created for this script, then it is not necessary. The Dim ScriptType line is used for managing what the script needs to do during execution. 'Script Name: ZZ_Google_Driver Option Explicit 'Verifies that variables are declared ahead of time (debugging aid) Dim ScriptType As ScriptTypes 'Simplifies script type identification Extend the Script Template for Expected Steps If your script will contain a number of actions to perform against the monitored application, such as launch, login, and search, you can extend the script template code to avoid having to 54

55 Chapter 5 Framework Scripts retype the required code for each action. The script template code for an action appears after the dotted line separator, as shown in the following code sample: ' ********** Duplicate the section below as the prototype for your transactions. ' Then delete this line. ********** ' 'ShowStatusBox "Clicking on the '' button...", True 'StartTrace "" ' START vvvvvvvvvvvvv 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ ' You can either copy and paste the script template code for as many steps as you expect to have in the script or use the keyboard. To use the keyboard, put the cursor on the dotted line, then press [Home] twice. This puts the cursor on the far left. Press and hold the [Shift] key down, and then use the down arrow to highlight not only the StopTimerAndTrace line, but also the empty line below it. Press [Ctrl+C] to copy. Use the down arrow and press [Ctrl+V] and paste for each transaction. Using this method, you will not have to adjust the lines to line them up. Delete the ********** Duplicate the section below as the prototype... line. This line is not needed. It is only included as a reminder. In each separator line of the duplicated prototype lines, a good practice is to type in the name of the process, such as Launch, Search, Close, etc., that will be performed in that section of the script. This greatly enhances the readability of a script, especially for applications that require several steps. 'LaunchIE 'ShowStatusBox "Navigating to ''...", False ' Launch 'StartTrace "" 'GoToPage "" ' START vvvvvvvvvvvvv 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ ' Enter criteria (not part of a transaction) 'ShowStatusBox "Entering criteria...", False ' Search 'ShowStatusBox "Clicking on the '' button...", True 'StartTrace "" ' START vvvvvvvvvvvvv 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ ' Close 'ShowStatusBox "Clicking on the '' button...", True 'StartTrace "" ' START vvvvvvvvvvvvv 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" Begin Building the Script While it is acceptable to begin recording at this point, it is much more efficient to take advantage of the functions supplied in the Framework. For example, to launch Internet Explorer to a blank web page, use the function in the prototype called LaunchIE. In addition to launching the application, it also maximizes the browser. 55

56 Chapter 5 Framework Scripts Next, uncomment the ShowStatusBox line and replace the default text with "Navigating to 'Google'...". What is ShowStatusBox and why use it? As the script is running, it is very useful to show what it is doing at the time. By default, the Agent Recorder executes the steps without visual feedback. This can be confusing when trying to watch or debug the script. To help with this, the ShowStatusBox function displays a box with text at the top of the screen that shows what steps are executing during script execution. Most of the Framework functions such as GoToPage use this feature by default. NOTE The True or False parameter of ShowStatusBox is used to turn on/off the print screen capability when a script is set to Self Documentation mode. For more information, see Document the Script Steps [p. 61]. A status such as Starting the search Active transaction is typically not very helpful. Provide a descriptive status, such as Pressing the OK button or Typing in the search criteria. The next step is to add GoToPage. This navigates Internet Explorer to the desired web page. It also contains logging and some minor error handling. You do not need to add in front. You do, however, need to add if the web site requires it. For thick client applications or applications that require a passed parameter, use the function LaunchApp or LaunchAppWithParm. LaunchIE ' This launches IE to a blank web page. ' Navigate to Google ShowStatusBox "Navigating to 'Google'...", False 'StartTrace "" ' START vvvvvvvvvvvvv GoToPage " 'WaitForText "Internet Explorer MainWindow", "", True 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ NOTE StartTrace and StopTimerTrace are used to specify the transaction name. WaitForText is a verification function. Each will be discussed later in this walkthrough. Add a Breakpoint At this point, the script should be able to run. To stop the script at a certain point, either click on the left grey margin on a non-commented line of the script or move your cursor to the line to stop at and press [F9]. In this example, uncomment the ShowStatusBox line that appears after the GoToPage function, put your cursor anywhere on the line, and press [F9]. The line will turn red. ShowStatusBox "Entering login criteria...", False 56

57 Run the Script To run the script, either press the Playback button in the toolbar or press the [F5] key. Once the script runs, Internet Explorer should display the Google home page in a maximized state. Stop the Script When it Pauses at the Breakpoint Chapter 5 Framework Scripts The script will execute to the launching of the Google Search page, then the Agent Recorder will reappear and what was a dark red line will now have yellow highlighting around the text and will look similar to this: The yellow highlight indicates that the script has paused at that line. Press the Stop button to stop the script from continuing. Verify Page Load Success (Synchronization) Before continuing to the next step, it is important to verify that every time an action (such as a button or link click) happens, the results that were expected actually happened. In other words, synchronize the application step with the script step. Never assume it will always work. In this case, you must verify that the Google web page loaded successfully using a Framework Wait function. The most common Wait function is WaitForText. This function requires two parameters and has a third optional parameter. The first is the object (or window) name and second is the text to look for. Since this is a web application, the Internet Explorer main window is the preferred window. The text to look for should be something that will always be visible when the page is loaded. In this case, the text on the Google Search button. This text is case-sensitive. For best results, try to copy and paste from the Internet Explorer window. NOTE While the default Agent Recorder Wait methods provide similar functionality to the Framework's Wait functions, they require an If/Then statement to verify success or failure, and they lack any integration with the times set in the Synthetic Monitoring Console. In addition, the fastest time a Agent Recorder Wait method can complete is approximately 2 seconds. The Wait functions in the Framework can execute in as little as.2 seconds. Add the WaitForText function after the GoToPage function. To populate the second parameter, you can either copy and paste the text to verify from the web page or manually type the text. GoToPage " WaitForText "Internet Explorer MainWindow", "Google Search" NOTE It is important that the text used to verify that the page loaded properly is unique to that page and did not exist on the previous page. 57

58 Chapter 5 Framework Scripts Type in the Search Criteria A setup step in a script, also called a preparation or navigation step performs an action, such as entering text into a search box. A setup step does not create network traffic. As a result, it does not need to be part of a transaction. Since many applications include a portion where entering an ID and password or criteria as a setup step, the script template provides a section for this. In this walkthrough, we will enter the text Compuware Synthetic Monitoring in the Google search box. NOTE Because the Google web page is constantly changing, you may need to adapt this walkthrough script to allow for recent changes to the Google web page functionality. For this example, make sure the browser's auto search feature is disabled. First, revise the ShowStatusBox label text, and then place your cursor after this line, as shown below: ' Enter criteria (not part of a transaction) ShowStatusBox "Entering Compuware Synthetic Monitoring as Search Criteria ", False ' Search Active 'ShowStatusBox "Clicking on the '' button...", True Record the Setup Step Make sure your cursor is on the line after the ShowStatusBox Enter Compuware Synthetic Monitoring as Search Criteria line. Click the Record button and type the text to search for in the Google search box, but do not press [Enter]. Searching for the specified text will be performed and measured in a subsequent step. To stop recording, click the flashing Agent Recorder button on the taskbar. The recorded script code should appear immediately after the 'ShowStatusBox function, as shown in the following code sample: ' Enter criteria (not part of a transaction) 'ShowStatusBox "Entering Compuware Synthetic Monitoring as Search Criteria", False IEWindow("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLEditBox("Name=q").SetText "Compuware Synthetic Monitoring" TIP In most cases, the HTMLBrowser line can be commented out. Agent Recorder usually records this, but based on hundreds of tests, this line is not usually required. Keep in mind that every Attach statement takes time. Since this is performance monitoring, the amount of attaches of child windows should be reduced to a minimum. In this case, the following line should be commented first, then the script tested. If it works without the following line, then delete it. HTMLBrowser("Internet Explorer ChildWindow").Attach 58

59 Test the Script Uncomment the following ShowStatusBox line and set a breakpoint. Close Internet Explorer and run the script. The script should run properly and stop when it reaches this line. 'ShowStatusBox "Clicking on the '' button...", True At this point, stop the playback. Record the Timed or Monitored Action Since the next step creates network traffic, it should be a monitored transaction. Enter what the script will do next in the ShowStatusBox line where the breakpoint is set. Next, place the cursor after the next StartTrace line, then record the click of the Google Search button. After recording this action, the following lines should appear after 'StartTrace "": ShowStatusBox "Clicking on the 'Google Search' button...", True 'StartTrace "" ' START vvvvvvvvvvvvv IEWindow("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLButton("Name=btnG").Click Again, the HTMLBrowser line can usually be commented out or removed. Since the script executed an action, it is important to verify that the result of the action was what was expected. The most common and reliable way to verify an expected result is to look for specific text. It is important to look for text that will always be there when the action was successful and also it is important that the text did not appear on the previous page. In this case, the text results usually appears on the Google search results page. As was done in the Google Home page, the text can be either highlighted and copied or manually typed in to the WaitForText line that appears after the recorded button click commands. NOTE Chapter 5 Framework Scripts When verifying the action, do not look for the text you typed because it was already there before you clicked the button. WaitForTextDelimited "Internet Explorer MainWindow", "results", 'StopTimerAndTrace "" ' END ^^^^^^^^^^^^^^^ TIP Refer to the ZZ_Google_Advanced_Driver script for other search examples. Close the Application The Google Search functionality has been verified at this point, so now it is time to close the application and return the desktop to an empty state. There are several ways to do this, such as recording the clicking of the in the upper right hand corner of the browser. An alternative is to use one of the functions supplied, called CloseIE. The advantage of using this function is that the script will close all instances of Internet Explorer (except for WebEx sessions) and record all instances to the script log. If the application requires a logout procedure, it may be 59

60 Chapter 5 Framework Scripts best to either try the LogOutAndCloseIE function or record the steps required to log out of the application. In this case, just closing IE is sufficient. ' Close IE Call CloseIE Test the Script Again Remove all breakpoints, make sure Internet Explorer is closed, and run the script. The script should run from beginning to end. If the script is completed as expected, any commented HTMLBrowser lines can be deleted. Add the Transaction Names The first priority is to get the script running correctly. Once the script runs successfully, fill in the StartTrace and StopTimerAndTrace lines. The script should look similar to this: LaunchIE ' This launches IE to a blank web page. ' Navigate to Google ShowStatusBox "Navigating to Google...", False StartTrace "Google_Launch" ' START vvvvvvvvvvvvv GoToPage " WaitForText "Internet Explorer MainWindow", "Google Search", True StopTimerAndTrace "Google_Launch" ' END ^^^^^^^^^^^^^^^ ' Enter Search Criteria ShowStatusBox "Entering Compuware Synthetic Monitoring as Search Criteria...", False IEWindow("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLEditBox("Name=q").SetText "Compuware Synthetic Monitoring" ' Click Search Button ShowStatusBox "Clicking on the Google Search button...", True StartTrace "Google_SYMSearch" ' START vvvvvvvvvvvvv IEWindow("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLButton("Name=btnG").Click WaitForText "Internet Explorer MainWindow", "results", True StopTimerAndTrace "Google_SYMSearch" ' END ^^^^^^^^^^^^^^^ ' Close IE Call CloseIE The StartTrace and StopTimerAndTrace functions tell the Synthetic Monitoring Agent to start and stop transactions. The transaction names in the scripts must be unique to the entire environment. This means that the StartTrace Launch must not be used in more than one application. For this reason, it is best to prefix the transaction name with the application name: in this case, Google_Launch and Google_SYMSearch. Once the transaction names have been imported into the Synthetic Monitoring Console, however, the displayed transaction names can be changed. Since Synthetic Monitoring stores traces using the Windows folder structure, there are characters that the Framework will automatically substitute for you. For example, the characters :,*,?,>,< are invalid characters to use in transaction names, so they will be replaced with either a semicolon (;), a colon (:), or underscores for the other characters. The StartTrace and StopTimerAndTrace functions must also be matched and are case sensitive. In other words, if the start of a transaction is StartTrace Google_Launch, the matching StopTimerAndTrace must also be Google_Launch and not Google_launch 60

61 Chapter 5 Framework Scripts This is what the entire completed script should look like at this point. It should run to completion without any errors. It is not ready to deploy in Synthetic Monitoring at this time, however. 'Script Name: ZZ_Google_Driver Option Explicit ' Requires that variables are declared ahead of time. Dim ScriptType As ScriptTypes ' Simplifies the script type determination. Sub Main() On Error GoTo ErrorHandler ' *** Always start with ScriptType = Development_Mode. Change to Production_App_Driver ' when ready to deploy. ' *** To change the type, delete the existing value then press Ctrl+Space to choose 'the desired option. ScriptType = Development_Mode Call InitializeScript(ScriptType, Me.Name) ' ** Don't change this line except to ' add an optional app acronym **** ' DO NOT ADD ANYTHING ABOVE THIS LINE LaunchIE ' This launches IE to a blank web page. ' Navigate to Google ShowStatusBox "Navigating to Google...", False StartTrace "Google_Launch" ' START vvvvvvvvvvvvv GoToPage " WaitForText "Internet Explorer MainWindow", "Google Search", True StopTimerAndTrace "Google_Launch" ' END ^^^^^^^^^^^^^^^ ' Enter Search Criteria ShowStatusBox "Entering Compuware Synthetic Monitoring as Search Criteria...", False IEWindow("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLEditBox("Name=q").SetText "Compuware Synthetic Monitoring" ' Click Search Button ShowStatusBox "Clicking on the Google Search button...", True StartTrace "Google_SYMSearch" ' START vvvvvvvvvvvvv IEWindow("Internet Explorer MainWindow").Attach HTMLBrowser("Internet Explorer ChildWindow").Attach HTMLButton("Name=btnG").Click WaitForText "Internet Explorer MainWindow", "results", True StopTimerAndTrace "Google_SYMSearch" ' END ^^^^^^^^^^^^^^^ ' Close IE Call CloseIE ' DO NOT ADD ANYTHING BELOW THIS LINE Call EndScript(ScriptType) ' **** Do not change this line **** Exit Sub ErrorHandler: 'Do NOT put anything in this section. Put your custom error handling in 'UserCleanupDesktop instead. **** HandleScriptErrors (ScriptType) ' **** Do not change this line. **** End Sub Document the Script Steps The creation of a document that displays and description and print screen of each step that the script executes can be of great value, especially when someone other than the person who wrote 61

62 Chapter 5 Framework Scripts the script is troubleshooting an error. Instead of manually building this document, the Framework contains a feature that will automatically create a Word document when the script runs. NOTE To use this feature, Microsoft Word must be installed on the Master Scripting Agent. To convert the script to Self Documentation mode, find the following line of code, and then double-click on the words Development_Mode. Press the [Delete] key, and then press the [Ctrl] key and [Space] bar together. This will display the appropriate values. Select SelfDocumentation_Mode and press the [Tab] key. The following should appear: ScriptType = SelfDocumentation_Mode When the script runs, it will perform just as it would in production mode, but will also create a Word document in the background as it runs, documenting each step. Prepare the Script for Use in Production At this point, Synthetic Monitoring still has no knowledge of the application or transactions that were entered in the script. To update Synthetic Monitoring about the applications and transactions in the script, use the import feature available in the Synthetic Monitoring Console. The import feature creates the entries of the script name, application name, and transaction names in the Synthetic Monitoring environment. While this can be done manually, the Framework offers an easy import feature. To import the information, the Synthetic Monitoring Console needs to be open before running the script in Import mode. Convert the Script from Self Documentation Mode to Import Mode The Framework provides a feature to generate an import file from information contained in the script. With this import file, you can automate the creation of an application and transaction definitions in Synthetic Monitoring. To create the import file, you must change the script mode to Import_Mode. To change the script mode, find the following line of code: ScriptType = SelfDocumentation_Mode Double-click SelfDocumentation_Mode. Press the [Delete] key, and then press the [Ctrl] key and [Space] bar together. This displays the appropriate values. Select Import_Mode, and then press the [Tab] key. The following should appear: ScriptType = Import_Mode Run the Script in Import Mode When you run the script in Import mode, it creates the required import ML file and puts the name and path of this file on the clipboard so it can be pasted into the Import field of the Synthetic Monitoring Console. The default location in which the import file is saved is: C:\ProgramData\Compuware\ClientVantage\Data\work\Scripts. The file name is the first part of the script name with the word Import appended. For example, 62

63 Chapter 5 Framework Scripts ZZ_Google_Import.xml. A supplemental.txt version, which provides for an easy-to-read format, is also generated. The script and transactions are now ready to import into the Synthetic Monitoring Console. Convert the Script from Import Mode to Application Driver This is the final step that makes the script ready for deployment. The script mode now needs to change from Import mode into a mode that is a fully contained application script. This is first done by changing the script type to an Application Driver script. To do this, find the following line of code, and then double-click the words Import_Mode. ScriptType = Import_Mode Press the [Delete] key, then press the [Ctrl] key and [Space] bar together. This displays the appropriate values. Select Production_App_Driver and press the [Tab] key. The following should appear: ScriptType = Production_App_Driver The script is now ready for to be deployed and run in a production environment. NOTE To view a checklist of the steps described in this walkthrough, see Framework Scripting Checklists [p. 91]. 63

64 Chapter 5 Framework Scripts 64

65 CHAPTER 6 Script and Application Synchronization When a script is run on a Agent without human intervention, it is imperative to synchronize the application with the script. Agent Recorder provides basic events to accomplish this. They include Bitmap, Date/Time, Key, Menu, Mouse, Screen, and Window events. In the QA environment, these are all useful depending on the application. Scripting in a Synthetic Monitoring environment, however, is different in that scripts typically run every 10, 15, or 20 minutes with no human intervention. To complicate things further, Agents may or may not use the same hardware. Additionally, every application is unique. Some require only screen events, while others require the use of bitmaps. Some require the hourglass to disappear before going to the next step. Some have no visual interface (for example, VPN) but use logs to show success or failure. To accommodate these various applications, the Framework includes a number of Wait functions that extend the default functionality of the Agent Recorder events by doing the following: Match the give-up time to what is set in Synthetic Monitoring. Log start and finish of the event. Raise an error if the event does not complete as expected. Keep track of how long a wait event is processed. Logs diagnostic output if it fails. In general, it is always best to use the WaitForAny Framework function. This function looks for specified text to exist or not exist on a given window. It is reliable because it is not dependent on video card models, color depth, or screen resolution. Bitmap events are most often used when scripting Citrix applications. While they are useful in some environments, they are extremely limited in practical use in Synthetic Monitoring. The video cards on all of the Agents must be exactly the same brand and model as well as having the same screen resolution and color depth. The WaitForImage function is much more robust. Date/Time, Menu, Key, Window, and mouse events are typically not used in the Synthetic Monitoring environment. 65

66 Chapter 6 Script and Application Synchronization When to Use Whenever Events A Whenever event is a way of handling unexpected situations as a script is running. It can be useful but it can also cause some issues at runtime. Every time a Whenever event is triggered, the script executes whatever is placed in that section. While at first that sounds desirable, it can potentially cause issues. For example, if a Page Not Found is encountered, it may be desirable to refresh the page once to see if the page will load properly the second time. If a Whenever event is configured to refresh the page, the page cannot be displayed page could potentially occur as fast as the script can press the refresh key, causing an endless loop if the page is truly not available if some counter or exit logic was not used. It is best to restrict Whenever events to just the ones with which the action is consistent. For example, if a popup window appears asking to remember passwords or to Turn on AutoComplete, the script should always answer No. To facilitate this, the Framework function called HandleStandardIEPopups can be used to process many of these common popup windows. To use this function, place the following code after the long dotted line when creating a new script: Whenever "IE-PopupWindow" ' Looks for the letter 'a' in an Internet Explorer PopupWindow At the end of the script, on the line right after End Sub, put these lines: Private Sub Script_Whenever(ByVal TheEvent As TPEvents.TEventGroup) Call HandleStandardIEPopups(TheEvent.Name) [additional code can be put here if desired to handle non-standard events] End Sub When Not to Use Whenever Events A Whenever event is not desired, however, in the case of a script branching based on what happened. For example, when the script runs from one location, it may need to enter a proxy ID and password; in other locations, it may not. An application may have a password that will expire in the next few days. In this case, a custom password change routine may be called and then the script can continue. Use the return value of the Framework WaitFor functions instead. They return a number based on which event occurred. Handling Multiple Events There are times when a script can encounter one of several events when the same link is clicked. For example, the application could display a password will expire or a Page cannot be displayed message; or in some cases, a proxy window may pop up to enable the script to access the internet. Based on which event occurred, the script needs to do different things. For example, if a Page Not Found event occurs, you may want to simply press the Refresh button up to two times to see if that will fix the problem. The following code implements that functionality. ' Since Option Explicit is set, it is necessary to declare (Dim) variables Dim iretval As Integer ' The value returned by the function Dim icnt As Integer ' A counter StartTrace "ZZ-Google_Launch" LaunchToPage " ' START vvvvvvvvvvvvv For icnt = 1 To 4 ' Loop up to 3 times to get the page to appear. ' Capture the return value of the WaitForAny function 66

67 Chapter 6 Script and Application Synchronization iretval = WaitForAny("ZZ-Google_Home_Page", "IE-Page_Not_Found") ' Perform steps based on which event occurred. Several events can be checked for. Select Case iretval Case 1 '"ZZ-Google_Home_Page" ' If this occurred, then we are done. Just exit the 'For' loop Exit For Case 2 '"IE-Page_Not_Found" ' If this occurred, Log it, then do a refresh on the browser to see if it will appear. WriteLogSteps 1, Space(8) & "The Google Home page reached a Page Not Found error. Page was refreshed." ShowStatusBox ("Pressing F5 to Refresh") IEWindow("Internet Explorer MainWindow").Attach IEWindow.Type "{F5}" ' IMPORTANT: Let the browser have a chance to clear the page and start re-loading Sleep 1 End Select If icnt = 4 Then ' This occurred too many times, so we need to raise an error condition RaiseError "The Google Home Page could not be loaded." End If Next ' Try again. ' If the script gets to here, it ended successfully. StopTimerAndTrace "ZZ-Google_Launch" ' END ^^^^^^^^^^^^^^^ 67

68 Chapter 6 Script and Application Synchronization 68

69 CHAPTER 7 Framework Scripting Tips General Scripting Tips Make StartTrace and StopTimerAndTrace Names Unique Although transaction names within the Synthetic Monitoring Console can be identical (but it is not not recommended), it is required that all StartTraces and StopTimerAndTraces be unique to the environment. This is because the Synthetic Monitoring Agent listens to the text within those functions and has no concept of what application is running. This is by design so you can reuse the same transaction for multiple scripts. If App1_Driver includes StartTrace "Login" and App2_Driver also has the same StartTrace "Login", Synthetic Monitoring will record the transaction to the first application that was defined. Use Numbers and Letters in Transaction Names To view transactions in chronological order, a common practice is to number them. It is suggested to use numbers that increment by 10 instead of letters. This is helpful if transactions are inserted or removed, or the order changes. It is much easier to add step 015 between 010 and 020 than to renumber steps 1, 2, 3, etc. SNMP Alerting Tips Most SNMP collectors use spaces as delimiters. Since parameters sent from Synthetic Monitoring are not enclosed in quotes, avoid using spaces in application or transaction names. Disable Screen Savers The Agent Recorder, as well as any other GUI scripting tool, cannot send a [Ctrl+Alt+Del] key combination to the Agent because the operating system intercepts the set of keystrokes. If a screen saver cannot be disabled, schedule the script CVFW_MouseMoveOnly at an interval that is less time than it takes for the screen saver to start. Kiosk mode can help give the illusion of locking the screen. For more information, see Kiosk Mode [p. 41]. 69

70 Chapter 7 Framework Scripting Tips Use Autologon and Reboot the Robots Daily The Framework contains a function that can set the registry settings for you and populate the password in the registry only when necessary. In addition, all Windows machines seem to have memory leaks caused by applications. Rebooting helps clear up memory issues to help them run more efficiently. Configure Windows for Best Performance By default, Windows sets its desktop for visual appearance, not performance. To configure Windows for best performance: 1. Access the Windows System Properties dialog box. 2. Click the Advanced tab. 3. Under Performance, click Settings. 4. Select the option for best performance, and then click OK. Install the Applications to be Monitored Each Agent should be able to run the applications you want to monitor before deploying a script. Web applications normally do not require installation; however, settings such as remembering passwords and turning off auto complete should be done. Some sites may need to be added to the trusted list. If possible, the Master Scripting Agent should have all applications installed to make scripting development much easier. Using Visual Tests in the Agent Recorder Agent Recorder offers an asset called Visual Tests. This enables recording and playback in the basic QA environment to follow a visual scripting approach. This works well in a very controlled environment that does not require accessing anything that is not available in the Visual Scripting environment. In the Synthetic Monitoring environment, however, it is necessary to use processes and functions that are above and beyond the basic Agent Recorder functionality. To execute anything that is not built in such as starting and stopping a transaction, writing to an external log file or creating an error handling routine necessary for monitoring requires calling a test script. Because script database size is important due to the frequency of the scripts running, all built-in Agent Recorder logging should be turned off. Even with that setting, Visual scripting still does extensive internal logging in the script database, making it too large in a relatively short time. The Framework uses external logging instead to keep the database as small as possible. WebEx Considerations WebEx is the preferred method of communicating with Customer Support for help with issues. WebEx works very well for most scripts if screen events are used. Bitmap processes, however, may not work if a WebEx session is in process. This is due to the change of color depth by WebEx itself. 70

71 Chapter 7 Framework Scripting Tips Another issue is that WebEx usually uses Internet Explorer. At the end of a script, the Framework attempts to end all processes that were not started when the script began. This is usually not an issue unless Kiosk mode is enabled. Thick Client Scripting Tips Scripting a Multi-Document-Interface (MDI) Application MDI applications are best handled if the objects that are used for screen events are the MDI Frame. When that application is launched, create an object for the window that includes all of the child windows. For example, Agent Recorder is an MDI application. The outside window with the title Agent Recorder is the MDI frame. That should be the window you use for all screen events. Each window within the frame is a child window, which is not as reliable for Wait events and sometimes other steps. Oracle Forms can often be an MDI application. If there are issues with the script timing out, comment the second attach to the child window and try again. Handling Multiple Windows Create a new object of each window as they are encountered. This means login windows, parent windows, and other popup windows. As you create the objects, be sure to follow a naming convention that easily associates a window with the application. For example, a window with the title Login can be created by several applications, but there are only a few that have the.exe name associated with the window. Are Screen Events Still Preferred? WaitForText or WaitForTextDelimited are the easiest and fastest ways to perform the verification (or synchronization) step. If WaitForText does not work, or the text to wait for is in multiple windows, such as a PopupWindow and MainWindow, then screen events are the preferred method. Window and bitmap events should rarely be used, if ever. Citrix Scripting Tips When scripting against Citrix applications, standard bitmap style Wait events are acceptable to use if the bitmaps never move and if the hardware is exactly the same. If, however, the video cards are not identical on the Agent machine, the bitmap wait will fail. Additionally, when trying to capture an image map from Agent Recorder, the application stays out of focus just enough to affect the image quality on objects such as command buttons with a beveled edge, so that during script playback, the Agent Recorder does not detect them as the same. In Citrix, it is even more important to use key strokes instead of clicking. If the application offers speed keys to perform functions (such as [F5] or [Ctrl+K]), make sure to utilize them. This is a different approach designed to be created on any one brand of computer and deployed on any other brand, even laptop to desktop. The only restriction of this approach is that the 71

72 Chapter 7 Framework Scripting Tips monitors need to use the same resolution (e.g.1024x768) and same color depth (e.g. 32-bit color). NOTE Do not use or modify the Framework object Citrix PopupWindow. This object is too generic to use in scripts. It is used internally by the Framework for other purposes. Creating a Citrix Script 1. Navigate to the window to record. When writing the Citrix script, it is important to treat every window that appears (designated by the title or caption of the window) as a different window object. For example, when an ICA file is launched or a link is clicked on an Internet Explorer launch page and an application login page appears, create an object for that login window before recording typing in the ID or password. If you record typing the ID and password first, The Agent Recorder will record: Window( Citrix PopupWindow ).Attach This is not recommended, especially if the application has multiple windows that appear. Once the object is created, then recording the next steps (for example, typing in of the ID and password) should record the object that was just created. Window( CitrixApp1_Window_1 ).Attach 2. Create a new object map entry. For best results, always include the type of object in the name, such as PopupWindow, Window. Additionally, on the Properties tab, verify that that the Caption property is selected. A portion of the caption can be wildcarded with an asterisk, but make sure that it includes text that will differentiate this window from others. 3. Click the Locate button to verify that it can find the window. 4. Record the action 72

73 Chapter 7 Framework Scripting Tips Once the object map is created, record the action as necessary. This action can be typing in the ID and password, clicking a control, or pressing the [Enter] key. Once that step is recorded, verify that the object you created was recorded in the script itself. You may need to manually modify the entry. 5. Verify the results. If the Caption stays the same after the action is done on the window, then a new object is not needed. If a different window appears, then create a new object map for that window. As always, make sure that all reactions are verified. In thick client or web applications, this was done with the WaitForText function. In Citrix, there is no text to capture or check for. Everything is an image. While looking for the window title can sometimes work, it is best to look for an image within the window. This means that once the object map is created, record the action as necessary. Verify that the object you created was recorded in the script itself. 6. Create a new image map entry. When the object map is created, an image map needs to be captured on that window. It is often preferred to add _IMG to the end of an image map entry to more easily identify the image maps. 7. Capture the image by selecting a meaningful section of the window. IMPORTANT Do not select the title bar of the window, but anything under it can be used. A common practice is to select an image of what will be clicked on next. Be careful not to use anything that has a 3D border, such as buttons. In addition, be careful when capturing text on buttons to make sure the dotted focus box is not included in the image. 8. Verify that Agent Recorder can find the image. Sometimes the focus of the window can affect the ability to capture an image. The differences are usually very subtle. You can test if the capture worked by clicking on the Locate button. 9. Use the WaitForImage function to verify. 73

74 Chapter 7 Framework Scripting Tips Once the image is found within the window, use the WaitForWindow function to perform the verification steps WaitForImage " McKesson_Login_PopupWindow", "McKesson_Login_OK_Btn_IMG" NOTE If an image is not found by the Identify utility, it will most likely be necessary to use Microsoft Paint to capture the images. This procedure is shown below. a. If Agent Recorder cannot find the image it captured, press [Alt+Prnt Scrn]. This is most likely because of focus. To let Agent Recorder try to capture the window, use Paint as a medium. Press [Alt + Prnt Scrn] to put an image of the active window in the clipboard. b. Start Microsoft Paint. c. Verify that Paint is the active window behind the Agent Recorder. Make sure that when you press [Alt+Tab], Paint is the application in focus, not the Citrix application. d. Capture the image. Capture a section of the window from Paint that is meaningful by pressing the Capture button. Do not select the title bar of the window you captured in the image map. Choose something to be clicked next or something that will never change appearance. Be careful not to use buttons with the dotted focus boxes in them. e. Modify the object map name. Once the image is captured from Paint, the object name will be Paint. Change the name to something meaningful, such as Remote_Desktop_Login. Change the object to the real object you will be using in the script. In this example, since it is Remote Desktop, use the Remote_Desktop_ChildWindow. f. Save and close the object. 74

75 CHAPTER 8 Frequently Asked Questions Agent Recorder FAQs How do I troubleshoot an error on an Agent? The Framework can keep extensive logs when the Framework functions are used. Every time a script runs, it stores when the script started, when transactions started and stopped, when wait events started and stopped, what text was found, etc. If an error occurred, it takes a task list complete with loaded programs, file paths, release numbers, etc. Depending on what the error was, it can also log the text that was found on the screen to compare with the wait event. Other things that are available are Synthetic Monitoring version and build, Agent Recorder version and build, Framework version, and if configured, user database version. Where is the script log file? By default, it is in the work folder of the Agent. You should have a shortcut to this path if the installation instructions were followed. The file name is machine-name_day-of-week.log. For example, if the Agent's machine name is CVAgent1 and the day is Monday, the file name will be CVAgent1_Mon.log. By default, this log file will be in a zip file that is transferred up to the shared folder under Framework\Printscreens\Logfiles. This copy can be suppressed by choosing that option in the CVFW_Maintenance window Why does the Wait finish before I see the text I m looking for? This is most likely because the Wait event finishes in less than a second, but the page is still loading. How do I turn off Java cups in the system tray? Call the function DisableJavaCups one time anywhere in any script. From that point on, unless some other process turns them back on, they will not reappear. Why should I use the Framework's Wait functions and not Agent Recorder's? While the Wait functions are built into the product, they are not optimal for monitoring. They are usually significantly slower and can be less reliable. Screen events can be used, but all other event types should be avoided. In addition to reliability and ease of use, you also get these features: 75

76 Chapter 8 Frequently Asked Questions Complete integration with Synthetic Monitoring. The Framework wait events know how long is left in the transaction so it adjusts accordingly. Synthetic Monitoring offers the ability to adjust Give-up times by location. They adjust automatically. Speed. Several Framework functions return results significantly faster than wait events. Logging. The Framework functions log what they were looking for, and how long it took to find it. Extensive, automatic error handling. If the wait event fails, the function will place the text of the window in the log so it can be reviewed later to see what the problem was. The wait function requires extra code to handle the instances when a wait event does not succeed. The ability to look for one of x number of events. Many of the Framework functions often allow several events, objects, strings, or bitmaps to be waited for and return the value of the event that occurred. How do I add my own database version and how can I see what Agent is using what version? When maintaining script databases, it is advantageous to keep a versioning system. That way you can keep track of what Agent has what version of the database. That can be set in the property called UserDataBaseVersion, which is located in the CVFW_User_Modifiable_Functions module. Any string can be used, whether a date or some other method. To tell what database version is being used on an Agent, look in the script log file on the Agent and in the top section: there will be an entry that lists that version. What is the best way to write common procedures such as Launch and Login? Several applications have separate processes to monitor, but have some processes that are common. For an example of how to do this, refer the ZZ_Independent_Step_Driver script. To place a common launch and login process or error handling that will be called by multiple scripts, it is best to place that functionality in a shared module. That way it is available to all scripts. The advantages of using a subroutine or function instead of a child script include the Intellisense feature, which provides a drop-down list of available methods and attributes. Navigation to child scripts is cumbersome and hard to debug. Are keystrokes preferred over mouse clicks? In most environments, keystrokes are much more reliable than mouse movements. Most menu items can be selected with shortcut keys. For most applications, there are keyboard equivalents. Often a key can be used to highlight and icon and [Enter] can be used to launch the application, even with Citrix apps. The [Alt] key activates the menu, the arrow keys can navigate and typing the first letter of a menu item brings the cursor to that menu item. When do I need to create an object? Agent Recorder creates an object for almost every window it encounters. The name will usually be the caption of the window. This can be confusing with windows that have 76

77 Chapter 8 Frequently Asked Questions generic captions, such as Login. Each application can have its own Login window, but windows created by Agent Recorder will create a new caption for each window it encounters, but number them uniquely. The automatic recording process also makes it difficult to group objects by application name. As a rule of thumb, create a new object for any new window that is significantly different from others. While recording a script, stop recording everytime you encounter a new window, and then create a new object for that new window. Then continue recording from that point. If the application can have two or more windows open at a time, this is even more critical. If the application uses the same window, but only the caption changes slightly, then it is possible to create only one object for the application. What is the best way to create objects? If the application requires new objects, such as thick client applications or presentation mode Citrix applications, create them before you start recording the portion of the script that uses them. If possible, make them generic enough to be useful for other parts of the script, but not so generic that they are not usable. In the following example, the Caption property is unselected and the value contains the wildcard asterisk character (*). This object map can be used for the bitmap select, but is too generic to be useful for most Citrix applications. When creating objects, try to avoid having a version number in the Caption property under the Properties tab. If the version is specified, the window may not be found when the next version comes out. Be careful to have at least three properties as significant, however. The most common are Application, ClassName, and TypeName. Sometimes the caption can be included when it contains words that exist in every window of that type. For example, the Internet Explorer MainWindow contains the text Internet Explorer, but it has an asterisk on either end of it. When I record, Agent Recorder adds multiple attach statements. Do I need them all? In an effort to be as reliable in as many environments as possible, Agent Recorder often will attach to the MainWindow, then the ChildWindow, and sometimes even a frame within the ChildWindow. Each attach takes up to a half second; when measuring transaction times, this can be significant. Often attaches to the Frame and Child windows can be 77