Enterprise Synthetic Scripting Framework User Guide · 8 Enterprise Synthetic Scripting Framework...

Enterprise Synthetic Scripting FrameworkUser Guide

Release 12.3

http://www.dynatrace.com

Please direct questions about Enterprise Synthetic or comments on this document to:

Customer Supporthttps://community.compuwareapm.com/community/display/SUPPORT

Copyright © 2015 Compuware Corporation. All rights reserved. Unpublished rights reserved under the Copyright Laws of theUnited States.

U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth inCompuware Corporation license agreement and as provided in DFARS 227.7202-1(a) and 227.7202-3(a) (1995), DFARS252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable.Compuware Corporation.

This product contains confidential information and trade secrets of Compuware Corporation. Disclosure is prohibited withoutthe prior express written permission of Compuware Corporation. Use of this product is subject to the terms and conditions of theuser'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, modifiedor changed without the express written consent of Compuware Corporation. Compuware Corporation may change the contentspecified herein at any time, with or without notice. All current Compuware Corporation product documentation can be found athttps://community.compuwareapm.com/community/display/APMDOC.

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: January 14, 2015, 23:37

https://community.compuwareapm.com/community/display/SUPPORT

https://community.compuwareapm.com/community/display/APMDOC

Contents

5Chapter 1 ∙ Enterprise Synthetic Scripting Framework Overview . . . . . . . . . . . . .5Framework Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6Framework Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9Chapter 2 ∙ Installing the Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10Framework Installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10The Agent Recorder Framework Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Setting Up the Framework Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Publish the Database Scripts and Agent Recorder Configuration Files . . . . . . . . . . . . .

17Chapter 3 ∙ Upgrading the Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17Framework Upgrade Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17Importing the Upgrade Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19Publish the Database Scripts and Agent Recorder Configuration Files . . . . . . . . . . . . .

25Chapter 4 ∙ Configuring Framework Features . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Global Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Passwords Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Blackouts Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Holidays Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Email Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29Agents Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30UserDefined Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30Integration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Alerting When an Error Occurs Between Transactions . . . . . . . . . . . . . . . . . . . . . . . .33Agent Auto-login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35Chapter 5 ∙ Framework Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35Framework Script Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Creating a Script Using the Framework Script Template . . . . . . . . . . . . . . . . . . . . . . .40Walkthrough: Creating an Application Driver Script . . . . . . . . . . . . . . . . . . . . . . . . . .40Create a Script and Add the Script Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Extend the Script Template for Expected Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . .41Begin Building the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3Enterprise Synthetic Scripting Framework User Guide

Contents

42Add a Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Run the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Stop the Script When it Pauses at the Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . .43Verify Page Load Success (Synchronization) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Type in the Search Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Record the Setup Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Test the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Record the Timed or Monitored Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Close the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Test the Script Again . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Add the Transaction Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47Document the Script Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Prepare the Script for Use in Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Convert the Script from Self Documentation Mode to Import Mode . . . . . . . . . . . .48Run the Script in Import Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Convert the Script from Import Mode to Application Driver . . . . . . . . . . . . . . . . . .49The Application Driver Give-Up Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

51Chapter 6 ∙ Script and Application Synchronization . . . . . . . . . . . . . . . . . . . . . . .

55Chapter 7 ∙ Framework Scripting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55General Scripting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Thick Client Scripting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Citrix Scripting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58Creating a Citrix Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

63Chapter 8 ∙ Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Agent Recorder FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66Enterprise Synthetic FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Citrix Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77Internet Explorer Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

79Appendix A ∙ Framework Scripting Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . . .

81Appendix B ∙ Framework Functions Reference . . . . . . . . . . . . . . . . . . . . . . . . . . .81Wait Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85General Scripting Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92Enterprise Synthetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94Script Initialization and Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95User Expandability Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98Path, File, and Registry Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

100Internet Explorer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101Framework Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

103Appendix C ∙ Framework Functions Reference Grid . . . . . . . . . . . . . . . . . . . . . . .

107Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Enterprise Synthetic Scripting Framework User Guide4

Contents

C H A P T E R 1

Enterprise Synthetic Scripting FrameworkOverview

The Enterprise Synthetic Scripting Framework is an optional Enterprise Synthetic componentthat facilitates the creation and management of Agent Recorder scripts for use in EnterpriseSynthetic. In addition, the Framework enables the integration of Agent Recorder scripts withsettings in the Enterprise Synthetic Console such as matching wait times with availabilitythreshold settings, taking screen shots on error, importing transactions, and handling transactionswhen they succeed or fail.When configured and used properly, the Framework can produce more reliable scripts andsignificantly reduce the time required to create and maintain Agent Recorder scripts.

IMPORTANTWe recommend contacting Customer Support prior to installing and configuring the Framework.

Framework BenefitsThe primary benefit of using the Framework is the reduction in the amount of time required towrite and maintain Agent Recorder scripts. The Framework is tightly integrated with EnterpriseSynthetic and automatically takes advantage of many of the features offered by EnterpriseSynthetic. For example, when the availability threshold time is changed in the EnterpriseSynthetic Console, the amount of time allowed in the Framework WaitFor functions isautomatically set to reflect the change in the Console.The Framework functions also leverage other Enterprise Synthetic features such as when totake a screen print, mark a transaction unavailable, or display script and transaction health. Ifthe script is between transactions, the Framework offers options for alerting in the event an erroroccurs.The Framework keeps an extensive log of everything a script does, which can greatly help indiagnosing and troubleshooting an issue. It can also insert the script name, application name,and configure transaction details directly into the Enterprise Synthetic Console, thus saving asignificant amount of effort.


An additional benefit of using the Framework is the enhanced usability and performance of theAgent Recorder. Error handling and Wait events are greatly improved in speed, reliability, andease of use. Tasks that would normally take hundreds of lines of code can be performed byadding one Framework function to a script. The Framework function library is extensive andcan be used for most application types including Citrix, web, thick client, and Java applications.

Framework AssetsThe Framework's core components are Agent Recorder assets, which include test script templatesand examples, modules, shared modules, a user form, object maps, and screen events. Theseassets are contained and initially deployed in an Agent Recorder database.In the following example, the default Framework test scripts are shown. The scripts with aCVFW_ prefix are utilities called from production application driver scripts. Scripts that beginwith ZZ_ are example test scripts that demonstrate how to script common monitoring tasks. Formore information, see Framework Script Types [p. 35].

NOTESample scripts mayreference various web pages. As a result, the sample script may not playback properly if the referenced web page has been deleted or modified. If you have problemsrunning a sample script, request help from Customer Support.

Figure 1. Framework Test Scripts in the Agent Recorder


Chapter 1 ∙ Enterprise Synthetic Scripting Framework Overview

While a script runs, the Framework creates and/or updates several files. One such file is theFramework configuration file (CVFW.ini). This file defines the integration between theFramework and Enterprise Synthetic as well as other customizable options such as log filehandling, screen prints for error reporting, and health alert settings.The Framework also includes a web page (kioskmode.htm) that you can use to warn peoplenot to use the Agent machine while scripts are running.



C H A P T E R 2

Installing the Framework

The recommended deployment of the core Enterprise Synthetic components includes a dedicatedAgent on which Agent Recorder scripts are configured and tested prior to deployment to otherAgents. This Agent is referred to as the Master Scripting Agent. After the completion of scripttesting on the Master Scripting Agent, you can deploy the Agent Recorder database using theEnterprise Synthetic script publishing feature.In addition to the Agent Recorder database, you can use the script publishing feature to deployother Framework assets to Agent machines, such as the Framework configuration file.

NOTEOnce you have verified the stability of your scripts, you can also use the Master Scripting Agentto monitor applications.

The installation instructions in this guide assume an Enterprise Synthetic environment thatincludes a Master Scripting Agent on which a remote Enterprise Synthetic Console is installed.The following diagram depicts a typical Enterprise Synthetic environment and highlights thedeployment of the Agent Recorder database from the Master Scripting Agent to other Agentsusing the Enterprise Synthetic script publishing feature.


Figure 2. Enterprise Synthetic Environment with Master Scripting Agent

Framework Installation ChecklistThe Framework installation process includes the steps listed in the following table:

Table 1. Framework Installation Checklist

StepsCompleted

Verify the Agent Recorder Framework database on the Master Scripting Agent. Formore information, see The Agent Recorder Framework Database [p. 10].

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. 11].

Deploy the Agent Recorder Framework database and configuration file to all desiredAgent machines. For more information, see Publish the Database Scripts and AgentRecorder Configuration Files [p. 11].

The Agent Recorder Framework DatabaseWhen the Enterprise Synthetic Agent Manager is installed, the Agent Recorder Frameworkdatabase is created and configured as the default database.


Chapter 2 ∙ Installing the Framework

NOTEAfter you upgrade to a new release or install a service pack for Enterprise Synthetic, you mustupdate the Agent Recorder Framework database with the Framework updates. For moreinformation, see Importing the Upgrade Files [p. 17].

Setting Up the Framework Configuration FileThe Framework configuration file defines common file paths used to store Framework assets,integration settings between the Agent Recorder and Enterprise Synthetic, and other generalscripting 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 Enterprise Synthetic Framework Configuration window appears.

4. Configure the desired settings on each tab, and then click Save.For more information, see Configuring Framework Features [p. 25].

NOTEAll tabs are saved independently from each other. After editing a field on a tab, you mustclick Save to save your changes for that tab.

Your configuration file settings are saved in a CVFW.ini file in the following location onthe 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 whenyou close the Enterprise Synthetic Framework Configuration window.

What to Do Next

After setting up the Framework configuration file on your Master Scripting Agent, you areready to deploy the Agent Recorder database and Framework configuration .zip file to theremaining Agent machines.

Publish the Database Scripts and Agent RecorderConfiguration Files

Before You Begin

• Configure the Agent Recorder database and Framework configuration file on the MasterScripting Agent before deploying these assets to all other Agents.

• On all Agent machines, close the Agent Recorder.



The recommended deployment process for distributing the Agent Recorder database on theMaster Scripting Agent to all other Agent machines requires the use of the Enterprise Syntheticscript publishing feature. This feature allows you to selectively choose which Agents to update.

NOTEAlthough it is not recommended, this version of the Framework continues to support the use ofa shared folder to distribute Framework assets, as directed in previous versions of the Framework.

Publish the Database Scripts

1. On the Master Scripting Agent, start the Enterprise Synthetic 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 3. 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



NOTEFor some operating systems, the Documents folder is hidden. In this instance, click Browse,and then type C:\ProgramData\Documents\Compuware\Recorder\DB\ in the Addressbar 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, thecompressed file is published immediately to the Agent(s), along with any other pendingconfiguration changes. The status of the publish appears in the Publish Report. window,as shown below.

Figure 4. Publish Report

After you publish the scripts, the Status column displays Successful to indicate thedatabase was deployed as intended.

12. Close the Publish Report window.

Publish the Agent Recorder Configuration File

13. Right-click in the Script Publishing grid, and then select Add.The Publish Scripts dialog box appears.



Figure 5. 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

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


If you enabled Publish configuration now, the configuration file is published immediatelyto the Agent(s), along with any other pending configuration changes.

Verify the Database and Configuration File

21. On any Agent machine on which you deployed the database and configuration file, startthe 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_ shouldappear. In the Description field of the ZZ_Release_History test script, you should seethe current version of the Framework listed.

22. To verify that the configuration file was deployed successfully, run the CVFW_Maintenancescript and verify that your settings appear on the various tabs of the Configuration window.



Alternatively, on an Agent machine, you can open the folderC:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData, and verifythe modified date of the CVFW.ini file matches the time the file was published.



C H A P T E R 3

Upgrading the Framework

If you are using the Enterprise Synthetic Scripting Framework and have upgraded EnterpriseSynthetic, you must update the Agent Recorder Framework database. An upgraded Frameworkensures you have access to any new changes in the Framework and support for new featuresintroduced in the current version of Enterprise Synthetic.

NOTEIf you do not upgrade the Framework, the following status message appears when you run atest script: Current Framework version <12.x>. An update is available forRecorder version <12.x>. Review installation instructions. Defaulting to

a wait time of 30".

Framework Upgrade ChecklistThe Framework upgrade process includes the steps listed in the following table.

Table 2. Framework Upgrade Checklist

StepsCompleted

Make a backup of the Agent Recorder database on the Master Scripting Agent fromwhich you will deploy the updated database to all Agent machines.

Import the Framework upgrade files into the Agent Recorder database. For moreinformation, see Importing the Upgrade Files [p. 17].

Deploy the upgraded Agent Recorder database to all Agent machines. For moreinformation, see Publish the Database Scripts and Agent Recorder Configuration Files[p. 11].

Importing the Upgrade FilesThe following Framework upgrade files are copied to the Agent Manager machine during aEnterprise Synthetic installation or when applying an Enterprise Synthetic service pack:


FrameworkUpdates.XMLThis 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.XMLThis is an exported Agent Recorder file that contains a current version of the AgentRecorder CVFW_User_Modifiable_Functions module. This module provides templatefunctions that you can modify to support your environment. If you have previously editedthis module, you must copy your changes out of the module prior to import, and thenmanually merge them back in after importing UserModifiableFunctions.XML. If youdid not edit this module, you should still perform an import of this file to ensure you havethe correct version available.

NOTEAs an alternative to importing UserModifiableFunctions.XML, a text file version(UserModifiableFunctions.txt) is available. To use this version, copy the contentsof the file and manually merge them with your custom changes in the existingCVFW_User_Modifiable_Functions module.

IMPORTANTThe Framework upgrade files do not contain required Agent Recorder settings that are maintainedin the Framework Agent Recorder database. These upgrade files should only be used to upgradean existing Framework Agent Recorder database. Do not use these files to install a newFramework.

Import Framework Updates

Perform the following steps to import all Framework updates with the exception of theCVFW_User_Modifiable_Functions module updates, which are imported in a separateprocedure.

1. Copy the Framework upgrade files from the following location in the Agent Managerinstallation folder to any location on the Master Scripting Agent machine:C:\Program Files(86)\Compuware\Enterprise

Synthetic\Samples\ScriptingFramework\

This example uses C:\Program Files(86)\Compuware\EnterpriseSynthetic\Samples\ScriptingFramework\ but you may use another location.

2. On the Master Scripting Agent, start the 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.XML, and thenclick Next.The Items to Import page appears.


Chapter 3 ∙ Upgrading the Framework

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 theAgent Recorder Import wizard to import the current version of the file. If you made changes tothe CVFW_User_Modifiable_Functions module that you do not want to overwrite, performthe 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.XML.11. Paste your changes back into the newly imported CVFW_User_Modifiable_Functions

module.

TIPYou can create a shared module to store your own functions, and then reference them inthe CVFW_User_Modifiable_Functions module. Additionally, you can log what functionsyou 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 theDescription field for each Framework test script, you should see the current version of theFramework listed.

What to Do Next

Deploy the updated Agent Recorder database to the remaining Agents in your environment.For more information, see Publish the Database Scripts and Agent Recorder Configuration Files[p. 11].

Publish the Database Scripts and Agent RecorderConfiguration Files

Before You Begin

• Configure the Agent Recorder database and Framework configuration file on the MasterScripting Agent before deploying these assets to all other Agents.

• On all Agent machines, close the Agent Recorder.



The recommended deployment process for distributing the Agent Recorder database on theMaster Scripting Agent to all other Agent machines requires the use of the Enterprise Syntheticscript publishing feature. This feature allows you to selectively choose which Agents to update.

NOTEAlthough it is not recommended, this version of the Framework continues to support the use ofa shared folder to distribute Framework assets, as directed in previous versions of the Framework.

Publish the Database Scripts

1. On the Master Scripting Agent, start the Enterprise Synthetic 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 6. 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



NOTEFor some operating systems, the Documents folder is hidden. In this instance, click Browse,and then type C:\ProgramData\Documents\Compuware\Recorder\DB\ in the Addressbar 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


The database file is compressed and, if you enabled Publish configuration now, thecompressed file is published immediately to the Agent(s), along with any other pendingconfiguration changes. The status of the publish appears in the Publish Report. window,as shown below.

Figure 7. Publish Report

After you publish the scripts, the Status column displays Successful to indicate thedatabase was deployed as intended.

12. Close the Publish Report window.

Publish the Agent Recorder Configuration File

13. Right-click in the Script Publishing grid, and then select Add.The Publish Scripts dialog box appears.



Figure 8. 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

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


If you enabled Publish configuration now, the configuration file is published immediatelyto the Agent(s), along with any other pending configuration changes.

Verify the Database and Configuration File

21. On any Agent machine on which you deployed the database and configuration file, startthe 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_ shouldappear. In the Description field of the ZZ_Release_History test script, you should seethe current version of the Framework listed.

22. To verify that the configuration file was deployed successfully, run the CVFW_Maintenancescript and verify that your settings appear on the various tabs of the Configuration window.



Alternatively, on an Agent machine, you can open the folderC:\ProgramData\Compuware\ClientVantage\Data\work\Data\UserData, and verifythe modified date of the CVFW.ini file matches the time the file was published.



C H A P T E R 4

Configuring Framework Features

The Framework configuration file defines common file paths used to store Framework assets,integration settings between the Agent Recorder and Enterprise Synthetic, and other generalscripting behavior settings.To access the configuration file user interface, you must play back the CVFW_Maintenancescript in the Agent Recorder to open the Enterprise Synthetic Framework Configurationdialog box. In this dialog box, you can configure and save the desired Framework features in adistributable configuration file. For more information, see Setting Up the FrameworkConfiguration File [p. 11].This section describes the configurable features of the Framework as they appear on the varioustabs of the Enterprise Synthetic Framework Configuration window.

Scripting in a Non-English Windows Environment

If you are scripting in a non-English Windows operating system environment, you may experienceproblems unless you specify the correct keyboard layout language in the Framework.In the User Expandability functions, you can specify the keyboard layout language in theUserInitAgentDriver function. For more information, see User Expandability Functions [p. 95].

Global TabAgent Manager Path

Although not required, you can create a shared public folder on the Agent Manager serverto store and distribute Framework-specific files. This folder should be under the datadirectory that Enterprise Synthetic uses. The subdirectory should be called Framework.For example: \\AMServer\ProgramData\Compuware\EnterpriseSynthetic\SYMShare\Framework.

Error Handling & PrintscreensExtended Logging

The Framework's logging feature offers an enhanced alternative to the default AgentRecorder logging feature. The Framework offers three logging options, ranging fromnone to fairly extensive. The logs are created in the work folder on the Agent machine


(C:\ProgramData\Compuware\Enterprise Synthetic\Data\work). The logsare named Agent_name- day_of_week.log. For example, XYZ74891N01-Wed.log.By checking the Copy to Share at Script End check box, the log file will be copiedup to the shared folder on the Agent Manager machine at the end of every script. Ifbandwidth is an issue, it may be preferable to have this option disabled. TheGenerations to keep option specifies how many logs are kept on the local harddrive.

By default, the Framework takes a screenshot only if a script encounters an error or if atransaction is running. If, however, you want the Framework to always take a screen shot,select Always take a local print screen. The directory option configures where the filesare placed on the server at the end of the script.There are also options for creating subfolders under that path, depending on yourpreferences. In addition, the Framework can limit the number of screen shots that are takenby the Agent when it encounters consecutive errors. For example, if an applicationencounters the same error more than five times consecutively, another screen shot is notnecessary. The same is true for trace files.

NOTEThe screen shot suppression only affects screen shots created in MS Paint for non-monitoredtransactions.

When an Agent encounters an error for the first time (in any period), it stores an extensivetask list in the log file. The entry shows memory usage, CPU usage, file dates, versionnumbers, 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 ischecked by default.Since the scripts take screen shots of the desktop when an error occurs and the files areplaced on the server, there needs to be a maintenance process to remove files that are acertain age. There are two ways to accomplish this.

• On this screen.

• Or you can create a scheduled task that runs the scriptCVFW_Purge_Old_Printscreens. Set it as a scheduled task or a transaction to runfrom one (and only one) Agent once a day or week, depending on how many filesare created. When it executes, it reads the value set above and deletes .jpg and .bmpfiles older than that value. The default is 10 days, but can be set from 1 to 60.

NOTEThis option is only for screen shots saved by MS Paint for non-monitored transactions. Itdoes not purge screen shots taken by Enterprise Synthetic and stored in the EnterpriseSynthetic database.

BaselinesBaselines are critical to the trace management process. They are also important fortroubleshooting purposes when comparing what happened during a problem versus what


Chapter 4 ∙ Configuring Framework Features

happens in a no or low-load situation. To create a baseline, you can either use the TakeBaseline option in the Add Active Agents section in the Enterprise Synthetic Console oruse the Framework's Take Baseline option.The Framework can use either option. The Enterprise Synthetic Console option forces theAgent to save a baseline when an Enterprise Synthetic script runs on that Agent. Thisresults in a baseline for every application that executes on that Agent. The Frameworkbaseline option selects a time when the Agent will save a baseline. By selecting a time, itsaves a baseline for all applications based on a time selected. This can be when the loadon the network is the lightest resulting in an ideal situation in which all others are compared.The default time is 5:00 a.m., which is often after backup and overnight batch processeshave completed and before employees start logging in.To use the Framework baseline option, select the Take Baseline check box and select thedesired time; for example, 5:00 (it uses 24-hour format). When the Save button is clickedand the file is sent to the shared folder, the Agents will save a baseline the first time thescript runs after 5:00 a.m.. It will not take one again for that day. You can also set it totake 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 notrecommended for times other than the first time while developing the scripts andtransactions.At this time, choosing a specific application and/or specific Agent is not built in to theFramework.

Kiosk ModeEnterprise Synthetic Agents require the desktop to remain unlocked. For security purposes,however, you may want to enable the Kiosk Mode screen, which resembles a “lockeddesktop” screen and can display a message that the Agent machine should not be used foranything other than Enterprise Synthetic tasks. This option is turned on at the end of anapplication script and closed at the beginning.A Kiosk mode web page (KioskPage.htm) is located in the following Agent machineinstallation folder: C:\Program Files\Compuware\EnterpriseSynthetic\Recorder\Samples. Either copy this file to the shared folder on the AgentManager machine or distribute this file to a folder on the Agent. After moving this file tothe 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 propercontact name and phone number (located toward the bottom of the .htm file) by clickingon the Edit button. It will open the file in Notepad and do a search for [Your Name Here]for entering the contact information.

Database ConnectionsThe Framework uses the database connection to get the Agent names that have beenconfigured in the Enterprise Synthetic Console as well as the Enterprise Synthetic database.The Framework also uses the database connection to retrieve the available schedules foruse when importing transactions into the Console (ID and password are encrypted asabove). Be sure to test the connections before proceeding.



Passwords Tab

ID and Password Encryption

While the Agent Recorder can encrypt passwords when recording text in a password field, thisis not always preferred. For example, if a password expires, the database must be modified withthe new password. The other time encryption is not practical is when passwords are recordedwhile typing in a Citrix window. It is plain text at this point. This functionality takes advantageof the Agent Recorder's ability to encrypt and decrypt a password string.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 maybe entered for each application. The Use Check-in/Check-out option is useful for applicationsthat restrict the number of available IDs and passwords. For example, if an application only hastwo IDs available and there are five Agents running the script, three of the Agents would runinto a problem if they all started at the same time. This process uses the shared folder to addand 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 likethis:HTMLEditBox("Name=username").SetText "MyID"

HTMLEditBox("Name=password").SetPasswordText "XXTTFAd371dh37f"

First, replace the ID portion with GetID, passing the application name and then replace theSetPasswordText 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. Ifthe same ID and password can be used for multiple applications, just add the name of theapplication 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 secondapplication, add the number two (surrounded in quotes) after the application name as shownbelow. 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, youcan assign unique IDs to specific Agents. To use this feature, update the Agent list from theAgents 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 AssignID 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 defaultID 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 ifthere 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)

Blackouts TabThe functionality provided on this tab has been incorporated into the core Enterprise Syntheticfeature set. For more information, refer to the Blackout Schedule Overview topic in the EnterpriseSynthetic Console Help.

Holidays TabThe Holidays tab enables you to create a user-defined holiday that can then be used in theScheduling tab in the Enterprise Synthetic Console to suppress the running of scripts on certaindays. Common US holidays are entered by default. The date of Easter is updated automaticallyto show the next occurrence.To add a holiday, type it into the Holiday Name box, select the proper parameters, and thenclick Add.To remove a holiday, select it from the Defined Holidays list, and then click Remove.

Email TabThe Framework provides an optional alerting mechanism that you can use to create conditional,application-specific alert that triggers a notification email. Use the settings on the Email tab toconfigure the Framework alert notification email settings.Under Global Email settings, you can configure the default subject, email recipient, and sender.Under Email Template settings, you can override the default email settings and configure aconditional, application-specific email alert. To create a new template, type the name of thetemplate in the Alerting Template list box. Next, define the desired conditions and emailaddress, and then click Save Template. Finally, select the applications to assign to the template,and then click Apply to App.

NOTEMake sure to use the semi colon (;) to delimit between email addresses.

Agents TabTo use the Framework's Agent features, a list of Agent names is required in the Frameworkconfiguration file. A shared folder and tested connectivity to the databases will make the taskeasier.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 sharedfolder nor the database connectivity was available, the host names can be manually entered.

UserDefined TabSome applications often require fields such as customer numbers, purchase orders, and patientnumbers to be entered into a field to do a search. If the values never change, leaving the recordedvalue is acceptable. If the values can change, however, it is best to use a variable. The valueassigned to a variable can be hard-coded with logic based on the Agent name or some othervalue. Another and often better option is to have the variable read the value from the Frameworkconfiguration file. This avoids the need to change the value in the database and redistribute itevery 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 staticvalue in the Key box, and then type the value in the Value box. An example of how to retrievethe parameter is displayed and can be copied and pasted into the script.

NOTETo copy, use the [Ctrl+Insert] instead of [Ctrl+C]. This is a limitation of the AgentRecorder. 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 pressSave.Another example is using an ID instead of the Agent name. The ID number can be selectedfrom the Framework configuration file (CVFW.ini) and used in the GetID and GetPasswordfunctions. Since the values are stored in the configuration file, they are immediately distributedto 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 TabThe Integration tab configures how the Agent Recorder communicates with Enterprise Synthetic.For most installations, the defaults are sufficient.

Script Health Alert SettingsThis section configures the use of the Enterprise Synthetic Console Health Monitoringfeature. This threshold controls when Enterprise Synthetic reports a script health warningor a script health error status.



Notify EventsThe NotifyEvent section configures the actual NotifyEvent command that is sent to theEnterprise Synthetic Open Script API. Notify events are rarely changed. Keep in mindthat they are case-sensitive and affect transactions.

IMPORTANTThe Framework does not support the use of Script Start and Script Stop to signifythe start and stop of transactions. That practice is highly discouraged. Always useNotifyEvents, which is the default.

By default, spaces are replaced with underscores because of SNMP trap limitations. Ifspaces are required, then check the Allow Spaces check box. Note that this will affect theactual NotifyEvent sent to Enterprise Synthetic and will affect all transactions.

Transaction Import DetailsThis feature controls the way that transactions are imported into the Enterprise SyntheticConsole.Check the Prefix Transaction Names w/Sequence check box to make the reports inVantageView appear in chronological order. This will prepend the transaction names withthe sequence in which they were created. When you select this option, the imported filewill already have the sequence number on them. This only affects the creation of theimport and not the running of the script. The script and timings will all be the sameregardless if this box is checked. This often makes more sense to an application ownerwhen the Launch/Login transaction is displayed before the Display results transaction.The Prefix Transaction Names w/Sequence check box will rarely be checked since itmodifies how the NotifyEvents are triggered. If it is important to match the NotifyEventswith the transaction name, check the box.

NOTEIt is strongly discouraged to check this box because it affects all transactions and sequenceschange if a step is added or removed. In fact, this box affects all transactions duringruntime 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 thetransaction is completed, it takes that execution time and multiplies it by one plus thevalue shown, and the result is displayed as the SLA in the Enterprise Synthetic Console.For example, if a transaction runs for 10 seconds during development, the Frameworkwill multiply that time by 1.5 (the value shown above), giving an SLA of 15 seconds. Ifthe transaction was completed in less than three seconds, however, the SLA Minimumwould 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 NamesMonitoring an application from start to finish is very important, especially if there aresections 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 entryfor importing the Launch-to-Close transaction into the Enterprise Synthetic Console.If this option is not selected, the results could show the transactions that are monitoredperformed as they were supposed to, but the remaining ones never executed and no alertwould occur. For example, the launch of the application could work, but clicking on alink may cause an error because the words changed. By monitoring the launch-to-closetransaction, an alert would be sent due to the error. In addition, a screen shot of the problemwould be created.The numbering of the transaction is useful, especially when using numbering in the normaltransactions. Using the 999_ option moves this transaction to the bottom of the list.Choosing 000_ puts it at the top.

NOTENo traces will be started during this transaction. The script does not execute a StartTracecommand, nor should it be set to use a Statistical CNS. It should only be used foravailability and overall timing of an application.

Transaction File ExportsThe options in this section configure the import file itself. By default, the schedule numberdisplayed in the Default Schedule list is assigned to all scripts regardless of the defaultset in the Console.If the VantageView database was configured, the Get Schedules from VV option isenabled. 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 validvalue is entered and the check box is selected, a duplicate copy of the export file is storedin that path. This allows other machines to use these files to import via the EnterpriseSynthetic Console import feature.

Self Documentation File PathThe Self Documentation feature is a very useful feature of the Framework. If MicrosoftWord is installed on the Agent, the Self Documentation feature can create a MicrosoftWord document that shows all of the steps the script executes. This section sets the locationin which the Microsoft Word file is stored.

Alerting When an Error Occurs Between TransactionsOccasionally, a script can encounter an error condition between transactions. For example, thedeveloper may have changed the name of an object ("Name=q") and the script cannot attach toit. If no transactions are running (or the Enterprise Synthetic Agent is not listening to thetransaction), the script will end without triggering an alert.To ensure that an alert is triggered, you can use the AddTransaction function. In the exampleshown 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 actualerror. While the most common use is to add the next transaction only if there are steps beforethe 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 markedunavailable.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


HTMLButton("Name=btnG").Click

WaitForTextDelimited "Internet Explorer MainWindow", "results,of about"

StopTimerAndTrace "Google_SYM" ' END ^^^^^^^^^^^^^^^

In this case, if an error occurs during the entering of the search criteria, the "Google_SYM" willbe marked unavailable.

Agent Auto-loginWindows computers should be rebooted periodically due to memory leaks and several otherfactors. Enterprise Synthetic and the Agent Recorder require that the computer is logged on inorder to execute any scripts. This creates an issue if the machine is not configured to automaticallylog 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.regfile supplied with the Framework installation. This file can be modified and these entries canbe imported into the registry. The downside of this approach is that the password is stored inplain text. This violates most security policies.To minimize this exposure, the function RebootRobot can enter the password into the registryentry 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 highsecurity solution, it is much better than leaving the password in the registry. The scriptCVFW_Reboot_Driver can be edited and used as a scheduled task to reboot the Agent.



C H A P T E R 5

Framework Scripts

Included in the Framework are several types of scripts, each of which performs the followinggeneral 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 theShowStatusBox function, which acts as a comment as well as an entry in the scriptdocumentation.

2. Start the transaction using the StartTrace function.

3. Perform an action such as clicking on a button or pressing [Enter]. Never start thetransaction 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 TypesThe 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 developmentprocess:


• TEST_ONLY_NoScriptType

• Import Mode

• Self Documentation Mode

TEST_ONLY_NoScriptType is rarely used and is used for testing single lines of code. SelfDocumentation mode and Import mode are used when a script is complete and ready to eithercreate a Word document of what it is doing during run (Self Documentation) or create an importfile for the Enterprise SyntheticConsole.

Development Mode ScriptThis is how all scripts should start. Technically speaking, a Development Mode script isnot really a script type because it does not have initialization or configuration. It simplyruns the code displayed in the script. A Development Mode script should not be used inproduction.

Application Driver Script (Production_App_Driver)An Application Driver is the primary script type and is designed to perform the samefunction as a task in the Enterprise Synthetic Console, which contains one application.An Application Driver script is equivalent to a specific business process. It typicallycontains all of the steps including the launch, login, actionable steps required to monitorthe application, and the logout and close steps.An Application Driver script contains a significant amount of integration with EnterpriseSynthetic. As every transaction is executed, the Framework keeps track of how long eachone executes. It knows how much time is left in a transaction and adjusts the wait timesaccordingly. When a script ends, it checks to make sure that all transactions started andcompleted successfully. If one or more transactions did not complete, it will give a visualalert as well as mark any unfinished transactions as unavailable and create a screen shotfor each of them.The Application Driver script contains the following parts:

InitializeScriptResets the scripting environment to empty. For example, it aborts running trace filesand resets any error conditions if they exist. It initializes the variable called AppNamethat is used throughout the script. The script name ultimately ends up to be theapplication name in the Enterprise Synthetic Console. This is why the script nameis important and should always end with _Driver. Since all transactions are loggedby the Application Driver script, it resets the inventory of transaction details toempty. It takes an inventory of all running applications. It checks to see whether theapplication is in a blackout period and if so, exits the script. If it is not in a blackoutperiod, it calls the UserInitAppDriver function defined in theUser_Modifiable_Functions module.If an Application Driver script calls another Application Driver script, all variableswill be reset. For this reason, do not call an Application Driver script from anotherApplication Driver script.

EndScriptStops the timer of the script, stops all trace files, and checks in any ID that waschecked out during the script. It handles some return to normal functionality and


Chapter 5 ∙ Framework Scripts

calls the UserEndOfAppDriver function defined in theUser_Modifiable_Functions module. It logs the ending status of the script, andmoves any non- Enterprise Syntheticprint screen files to the shared folder (if used).It verifies that all transactions that were started or even configured have reported tothe Enterprise Synthetic Agent.

HandleScriptErrorsIt is very important to leave the HandleScriptErrors as the first line of the errorhandler routine. Do not put anything between the ERRORHANDLER and theHandleScriptErrors lines. This is because it logs and displays the exact error textthat caused the error itself, and then captures a screen shot. If any code is addedbefore the HandleScriptErrors, both the Agent Recorder and VB reset the errorobject and the print screens will display a blank error message.

End of the Application Driver ScriptWhether successful or in error, the script attempts to return the desktop to the samestatus it was when the script started. Both the EndScript and HandleScriptErrorsfunctions call a function called CleanUpDesktop which first calls a user-definedfunction UserCleanUpDesktop, which can be used for custom closing steps. AfterUserCleanupDesktop executes, CleanUpDesktop attempts to close all applicationsthat were not running when the script began.

Child ScriptThis is the most basic script type. It is designed to do one or two steps that are called bymore than one application. They execute very few, but still important steps during theInitializeScript, EndOfScript, and HandleScriptErrors function calls. The mostcommon use of a Child script is to launch and log in to an application or web site that isused by several Application Driver scripts. The error handling routine is limited to takinga screen shot and returning a value of false.While Child scripts are common in some other scripting languages, a much more efficientmethod in the Agent Recorder is to use a subroutine (Sub) or function for processes thatare called by more than one application or more than one time in a single application. Forbest results, these routines can be located either at the bottom of the Application scriptitself, in the CVFW_UserModifiable_Functions module or in a shared module.

Agent Driver ScriptAn Agent Driver script was originally used in the ClientVantage 9.x Release that used theWindows scheduler. Since the scheduling mechanism was incorporated into ClientVantage10.0, an Agent Driver is rarely necessary. An Agent Driver script only contains commandsto run one or more Application Driver scripts. For an example, see the ZZ_Agent_Driverscript. It, like a Child script, executes very few, but still important steps during theInitializeScript, 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 handlingroutines such as closing out a Citrix application. For best results, create one shared module that



will contain any process that is necessary for an application that requires a special error handlingprocess.

NOTEMost 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 tobreak each step into its own script, in the Agent Recorder, this is not efficient. Navigatingbetween individual scripts is not optimal.

Creating a Script Using the Framework Script TemplateThe default script template included in the Framework provides the common code required forinitialization, scripting transactions, ending the script, and error handling. This script templateshould always be used when creating new scripts.

1. Stop or disable the Enterprise Synthetic Agent.If scripts are scheduled to run on the Master Scripting Agent, it is usually best to disablethe Agent from the Console to prevent the Agent from running a script while creating anew script or modifying an existing script. Do not forget to publish the configuration.

2. Create a new test script.Choose File ➤ NewThe New Asset dialog box appears.

3. Select Test script, type the name of the script, and then click OK.

TIPVBA prohibits the use of spaces in script names. For best results, end the name with thesuffix _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



'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




' --------------- 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

' -------------- --------------





This example script is set to Development mode. Once the script is completed, you should resetthe mode.The long dotted lines at the top and bottom of the script labeled DO NOT ADD ANYTHING ABOVETHIS 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 foradding the name of the transaction that will follow. Using this greatly improves readability ofthe 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 usefulfor 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 thescript is run in Self Documentation mode.

NOTEDo 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 whenthe recorded script does not contain a control that is easy to identify. The True parameter is aspecial one used to include this line if Self Documentation mode is invoked.



The StartTrace function is used to start the transaction. By default, it is the name of thetransaction configured in the Enterprise Synthetic Console. It starts the network packet captureand the timer associated with it. In addition, it reads the configuration from the EnterpriseSynthetic Console to set the amount of time the transaction used in the WaitFor functions.

IMPORTANTStartTimer does not affect wait times.

The blank line is where the steps will be recorded. Scripts are easier to follow if the action isgrouped and the verification is grouped as shown above.The WaitForText line is the place where the script verifies (or synchronizes) the result of theaction 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 fromwhich to choose, depending on the type of application being scripted. The WaitforText is thefastest and most commonly used function. For more information, see Wait Functions [p. 81].The StopTimerAndTrace line tells Enterprise Synthetic to stop the network packet capture andtimer that it started above. Ensure that the text entered in the StartTrace matches the text inthe StopTimerAndTrace. The Framework will alert you if there are unmatched transactions.

Walkthrough: Creating an Application Driver ScriptThis walkthrough demonstrates the process of creating an Application Driver script that containsthe necessary code to monitor a typical web application.A completed script of this walkthrough, ZZ_Google_Driver, is included in the defaultinstallation of the Framework. In addition, the general steps of this walkthrough are documentedin the Framework Scripting checklists. For more information, see Framework Scripting Checklists[p. 79].

Create a Script and Add the Script NameCreate a new test script using the Framework script template. For more information, see Creatinga Script Using the Framework Script Template [p. 38].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. Itrequires that a variable be declared before it is used. It protects from typographical errors aswell as from trying to put the wrong type of data into a variable when running a script. If thereare no variables created for this script, then it is not necessary. The Dim ScriptType line isused 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 StepsIf 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



retype the required code for each action. The script template code for an action appears afterthe dotted line separator, as shown in the following code sample:' ********** Duplicate the section below as the prototype for your transactions.

' Then delete this line. **********

' -------------- --------------





'

You can either copy and paste the script template code for as many steps as you expect to havein the script or use the keyboard. To use the keyboard, put the cursor on the dotted line, thenpress [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 theempty line below it. Press [Ctrl+C] to copy. Use the down arrow and press [Ctrl+V] andpaste for each transaction. Using this method, you will not have to adjust the lines to line themup.Delete the ********** Duplicate the section below as the prototype... line. Thisline 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 nameof the process, such as Launch, Search, Close, etc., that will be performed in that section ofthe script. This greatly enhances the readability of a script, especially for applications that requireseveral steps.'LaunchIE

'ShowStatusBox "Navigating to ''...", False

' -------------- Launch --------------


'GoToPage ""



' -------------- Enter criteria (not part of a transaction) --------------

'ShowStatusBox "Entering criteria...", False

' -------------- Search --------------





' -------------- Close --------------




'StopTimerAndTrace ""

Begin Building the ScriptWhile it is acceptable to begin recording at this point, it is much more efficient to take advantageof the functions supplied in the Framework. For example, to launch Internet Explorer to a blankweb page, use the function in the prototype called LaunchIE. In addition to launching theapplication, it also maximizes the browser.



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 whatit 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, theShowStatusBox function displays a box with text at the top of the screen that shows what stepsare executing during script execution. Most of the Framework functions such as GoToPage usethis feature by default.

NOTEThe True or False parameter of ShowStatusBox is used to turn on/off the print screen capabilitywhen a script is set to Self Documentation mode. For more information, see Document theScript Steps [p. 47].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 searchcriteria.

The next step is to add GoToPage. This navigates Internet Explorer to the desired web page. Italso contains logging and some minor error handling. You do not need to add http:// in front.You do, however, need to add https:// if the web site requires it.For thick client applications or applications that require a passed parameter, use the functionLaunchApp or LaunchAppWithParm.LaunchIE ' This launches IE to a blank web page.

' -------------- Navigate to Google--------------

ShowStatusBox "Navigating to 'Google'...", False


GoToPage "www.google.com"



NOTEStartTrace and StopTimerTrace are used to specify the transaction name. WaitForText isa verification function. Each will be discussed later in this walkthrough.

Add a BreakpointAt this point, the script should be able to run. To stop the script at a certain point, either clickon the left grey margin on a non-commented line of the script or move your cursor to the lineto 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



Run the ScriptTo run the script, either press the Playback button in the toolbar or press the [F5] key. Oncethe script runs, Internet Explorer should display the Google home page in a maximized state.

Stop the Script When it Pauses at the BreakpointThe script executes to the launching of the Google Search page, then the Agent Recorderreappears and what was a dark red line now has yellow highlighting around the text, as shownin the figure.

The yellow highlight indicates that the script has paused at that line. Press the Stop button tostop 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 abutton 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 FrameworkWait function. The most common Wait function is WaitForText. This function requires twoparameters and has a third optional parameter. The first is the object (or window) name andsecond is the text to look for. Since this is a web application, the Internet Explorer main windowis the preferred window. The text to look for should be something that will always be visiblewhen the page is loaded. In this case, the text on the Google Search button. This text iscase-sensitive. For best results, try to copy and paste from the Internet Explorer window.

NOTEWhile the default Agent Recorder Wait methods provide similar functionality to the Framework'sWait functions, they require an If/Then statement to verify success or failure, and they lackany integration with the times set in the Enterprise Synthetic Console. In addition, the fastesttime an Agent Recorder Wait method can complete is approximately 2 seconds. The Waitfunctions 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 "www.google.com"

WaitForText "Internet Explorer MainWindow", "Google Search"

NOTEIt is important that the text used to verify that the page loaded properly is unique to that pageand did not exist on the previous page.



Type in the Search CriteriaA setup step in a script, also called a preparation or navigation step performs an action, suchas entering text into a search box. A setup step does not create network traffic. As a result, itdoes not need to be part of a transaction. Since many applications include a portion whereentering an ID and password or criteria as a setup step, the script template provides a sectionfor this. In this walkthrough, we will enter the text Dynatrace Enterprise Synthetic inthe Google search box.

NOTEBecause the Google web page is constantly changing, you may need to adapt this walkthroughscript 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 shownbelow:' ----- Enter criteria (not part of a transaction) ------

ShowStatusBox "Entering Dynatrace Enterprise Synthetic as Search Criteria ", False

|

' -------------- Search Active --------------


Record the Setup StepMake sure your cursor is on the line after the ShowStatusBox ‘Enter Dynatrace EnterpriseSynthetic as Search Criteria’ line.Click the Record button and type the text to search for in the Google search box, but do notpress [Enter]. Searching for the specified text will be performed and measured in a subsequentstep.To stop recording, click the flashing Agent Recorder button on the taskbar. The recorded scriptcode should appear immediately after the 'ShowStatusBox function, as shown in the followingcode sample:' -------------- Enter criteria (not part of a transaction) --------------

'ShowStatusBox "Entering Dynatrace Enterprise Synthetic as Search Criteria", False



HTMLEditBox("Name=q").SetText "Dynatrace Enterprise Synthetic"

NOTEIn most cases, the HTMLBrowser line can be commented out. The Agent Recorder usually recordsthis, but based on hundreds of tests, this line is not usually required. Keep in mind that everyAttach statement takes time. Since this is performance monitoring, the amount of attaches ofchild windows should be reduced to a minimum. In this case, the following line should becommented first, then the script tested. If it works without the following line, then delete it.HTMLBrowser("Internet Explorer ChildWindow").Attach



Test the ScriptUncomment the following ShowStatusBox line and set a breakpoint. Close Internet Explorerand 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 ActionSince the next step creates network traffic, it should be a monitored transaction. Enter what thescript will do next in the ShowStatusBox line where the breakpoint is set. Next, place the cursorafter 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





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 whatwas expected. The most common and reliable way to verify an expected result is to look forspecific text. It is important to look for text that will always be there when the action wassuccessful 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 donein the Google Home page, the text can be either highlighted and copied or manually typed into the WaitForText line that appears after the recorded button click commands.

NOTEWhen verifying the action, do not look for the text you typed because it was already there beforeyou clicked the button.

WaitForTextDelimited "Internet Explorer MainWindow", "results",


TIPRefer to the ZZ_Google_Advanced_Driver script for other search examples.

Close the ApplicationThe Google Search functionality has been verified at this point, so now it is time to close theapplication and return the desktop to an empty state. There are several ways to do this, such asrecording the clicking of the ‘X‘ in the upper right hand corner of the browser. An alternativeis to use one of the functions supplied, called CloseIE. The advantage of using this function isthat the script will close all instances of Internet Explorer (except for WebEx sessions) andrecord all instances to the script log. If the application requires a logout procedure, it may be



best to either try the LogOutAndCloseIE function or record the steps required to log out of theapplication. In this case, just closing IE is sufficient.' -------------------- Close IE --------------------

Call CloseIE

Test the Script AgainRemove all breakpoints, make sure Internet Explorer is closed, and run the script. The scriptshould run from beginning to end. If the script is completed as expected, any commentedHTMLBrowser lines can be deleted.

Add the Transaction NamesThe first priority is to get the script running correctly. Once the script runs successfully, fill inthe 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


WaitForText "Internet Explorer MainWindow", "Google Search", True

StopTimerAndTrace "Google_Launch" ' END ^^^^^^^^^^^^^^^

' -------------- Enter Search Criteria --------------

ShowStatusBox "Entering Dynatrace Enterprise Synthetic as Search Criteria...", False




' -------------- Click Search Button --------------

ShowStatusBox "Clicking on the Google Search button...", True

StartTrace "Google_SYMSearch" ' START vvvvvvvvvvvvv




WaitForText "Internet Explorer MainWindow", "results", True

StopTimerAndTrace "Google_SYMSearch" ' END ^^^^^^^^^^^^^^^

' -------------- Close IE --------------

Call CloseIE

The StartTrace and StopTimerAndTrace functions tell the Enterprise Synthetic Agent tostart and stop transactions. The transaction names in the scripts must be unique to the entireenvironment. This means that the StartTrace “Launch” must not be used in more than oneapplication. 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 beenimported into the Enterprise Synthetic Console, however, the displayed transaction names canbe changed.SinceEnterprise Syntheticstores traces using the Windows folder structure, there are charactersthat the Framework will automatically substitute for you. For example, the characters“:,*,?,>,<|” are invalid characters to use in transaction names, so they will be replaced witheither a semicolon (;), a colon (:), or underscores for the other characters.The StartTrace and StopTimerAndTrace functions must also be matched and are casesensitive. In other words, if the start of a transaction is StartTrace Google_Launch, thematching StopTimerAndTrace must also be Google_Launch and not Google_launch



This is what the entire completed script should look like at this point. It should run to completionwithout any errors. It is not ready to deploy in Enterprise Synthetic 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


WaitForText "Internet Explorer MainWindow", "Google Search", True

StopTimerAndTrace "Google_Launch" ' END ^^^^^^^^^^^^^^^

' -------------- Enter Search Criteria --------------

ShowStatusBox "EnteringDynatrace Enterprise Synthetic as Search Criteria...", False




' -------------- Click Search Button --------------

ShowStatusBox "Clicking on the Google Search button...", True

StartTrace "Google_SYMSearch" ' START vvvvvvvvvvvvv




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 StepsThe creation of a document that displays and description and print screen of each step that thescript executes can be of great value, especially when someone other than the person who wrote



the script is troubleshooting an error. Instead of manually building this document, the Frameworkcontains a feature that will automatically create a Word document when the script runs.

NOTETo 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 thendouble-click on the words Development_Mode.Press the [Delete] key, and then press the [Ctrl] key and [Space] bar together. This willdisplay the appropriate values. Select SelfDocumentation_Mode and press the [Tab] key. Thefollowing should appear:ScriptType = SelfDocumentation_Mode

When the script runs, it will perform just as it would in production mode, but will also create aWord document in the background as it runs, documenting each step.

Prepare the Script for Use in ProductionAt this point, Enterprise Synthetic still has no knowledge of the application or transactions thatwere entered in the script. To update Enterprise Synthetic about the applications and transactionsin the script, use the import feature available in the Enterprise Synthetic Console. The importfeature creates the entries of the script name, application name, and transaction names in theEnterprise Synthetic environment. While this can be done manually, the Framework offers aneasy import feature.To import the information, the Enterprise Synthetic Console needs to be open before runningthe script in Import mode.

Convert the Script from Self Documentation Mode to Import ModeThe Framework provides a feature to generate an import file from information contained in thescript. With this import file, you can automate the creation of an application and transactiondefinitions in Enterprise Synthetic.To create the import file, you must change the script mode to Import_Mode. To change thescript 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, andthen press the [Tab] key. The following should appear:ScriptType = Import_Mode

Run the Script in Import ModeWhen you run the script in Import mode, it creates the required import XML file and puts thename and path of this file on the clipboard so it can be pasted into the Import field of theEnterprise Synthetic Console. The default location in which the import file is saved is:C:\ProgramData\Compuware\ClientVantage\Data\work\Scripts. The file name is thefirst part of the script name with the word Import appended. For example,



ZZ_Google_Import.xml. A supplemental .txt version, which provides for an easy-to-readformat, is also generated.

The script and transactions are now ready to import into the Enterprise Synthetic Console.

Convert the Script from Import Mode to Application DriverThis is the final step that makes the script ready for deployment. The script mode now needs tochange from Import mode into a mode that is a fully contained application script. This is firstdone by changing the script type to an Application Driver script. To do this, find the followingline 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 displaysthe appropriate values. Select Production_App_Driver and press the [Tab] key. The followingshould appear:ScriptType = Production_App_Driver

The script is now ready for to be deployed and run in a production environment.

NOTETo view the general scripting process, see Framework Scripting Checklists [p. 79].

The Application Driver Give-Up ScriptThis demonstrates the process of creating an Application Driver script that contains the necessarycode to perform a Google search on invalid text to demonstrate a transaction give-up.A completed script of ZZ_Google_Driver_Unavailable is included in the default installationof the Framework. In addition, the general script process is documented in the FrameworkScripting Checklists [p. 79] .

1. Convert the Script from Self Documentation Mode to Import Mode [p. 48].

2. Run the Script in Import Mode [p. 48].

3. Convert the Script from Import Mode to Application Driver [p. 49].

4. Publish Scripts and Change Configuration in the Enterprise Synthetic Help.



5. Go the CAS to access Integrated EUE Reporting in the Enterprise Synthetic Help. Fromhere you can access the Unavailable Transactions report.



C H A P T E R 6

Script and Application Synchronization

When a script is run on an Agent without human intervention, it is imperative to synchronizethe application with the script. The Agent Recorder provides basic events to accomplish this.They include Bitmap, Date/Time, Key, Menu, Mouse, Screen, and Window events. In the QAenvironment, these are all useful depending on the application. Scripting in an EnterpriseSynthetic environment, however, is different in that scripts typically run every 10, 15, or 20minutes 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 ofbitmaps. Some require the hourglass to disappear before going to the next step. Some have novisual interface (for example, VPN) but use logs to show success or failure.To accommodate these various applications, the Framework includes a number of Wait functionsthat extend the default functionality of the Agent Recorder events by doing the following:

• Match the give-up time to what is set in Enterprise Synthetic.

• 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 looksfor specified text to exist or not exist on a given window. It is reliable because it is not dependenton video card models, color depth, or screen resolution.Bitmap events are most often used when scripting Citrix applications. While they are useful insome environments, they are extremely limited in practical use in Enterprise Synthetic. Thevideo cards on all of the Agents must be exactly the same brand and model as well as havingthe 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 EnterpriseSynthetic environment.


When to Use Whenever Events

A Whenever event is a way of handling unexpected situations as a script is running. It can beuseful 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 canpotentially cause issues. For example, if a Page Not Found is encountered, it may be desirableto refresh the page once to see if the page will load properly the second time. If a Wheneverevent is configured to refresh the page, the page cannot be displayed page could potentiallyoccur as fast as the script can press the refresh key, causing an endless loop if the page is trulynot 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. Forexample, if a popup window appears asking to remember passwords or to Turn onAutoComplete, the script should always answer No. To facilitate this, the Framework functioncalled HandleStandardIEPopups can be used to process many of these common popupwindows.To use this function, place the following code after the long dotted line when creating a newscript: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 whathappened. For example, when the script runs from one location, it may need to enter a proxyID and password; in other locations, it may not. An application may have a password that willexpire in the next few days. In this case, a custom password change routine may be called andthen 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 bedisplayed message; or in some cases, a proxy window may pop up to enable the script toaccess 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 Refreshbutton 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" ' START vvvvvvvvvvvvv

LaunchToPage "www.google.com"

For iCnt = 1 To 4 ' Loop up to 3 times to get the page to appear.

' Capture the return value of the WaitForAny function


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.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 ^^^^^^^^^^^^^^^



C H A P T E R 7

Framework Scripting Tips

General Scripting Tips

Make StartTrace and StopTimerAndTrace Names Unique

Although transaction names within the Enterprise Synthetic Console can be identical (but it isnot not recommended), it is required that all StartTraces and StopTimerAndTraces beunique to the environment. This is because the Enterprise Synthetic Agent listens to the textwithin those functions and has no concept of what application is running. This is by design soyou can reuse the same transaction for multiple scripts. If App1_Driver includes StartTrace"Login" and App2_Driver also has the same StartTrace "Login", Enterprise Syntheticwill 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 suggestedto use numbers that increment by 10 instead of letters. This is helpful if transactions are insertedor removed, or the order changes. It is much easier to add step 015 between 010 and 020 thanto renumber steps 1, 2, 3, etc.

SNMP Alerting Tips

Most SNMP collectors use spaces as delimiters. Since parameters sent from Enterprise Syntheticare 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. Ifa screen saver cannot be disabled, schedule the script CVFW_MouseMoveOnly at an interval thatis less time than it takes for the screen saver to start. Kiosk mode can help give the illusion oflocking the screen. For more information, see Kiosk Mode [p. 27].


Use Autologon and Reboot the Robots Daily

The Framework contains a function that can set the registry settings for you and populate thepassword in the registry only when necessary. In addition, all Windows machines seem to havememory leaks caused by applications. Rebooting helps clear up memory issues to help themrun more efficiently.

Configure Windows for Best Performance

By default, Windows sets its desktop for visual appearance, not performance. To configureWindows 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 rememberingpasswords and turning off auto complete should be done. Some sites may need to be added tothe trusted list. If possible, the Master Scripting Agent should have all applications installed tomake scripting development much easier.

Use Visual Tests in the Agent Recorder

The Agent Recorder offers an asset called Visual Tests. This enables recording and playbackin the basic QA environment to follow a visual scripting approach. This works well in a verycontrolled environment that does not require accessing anything that is not available in theVisual Scripting environment. In the Enterprise Synthetic environment, however, it is necessaryto 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 toan external log file or creating an error handling routine necessary for monitoring requires callinga test script.Because script database size is important due to the frequency of the scripts running, all built-inAgent Recorder logging should be turned off. Even with that setting, Visual scripting still doesextensive 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 byWebEx itself.


Chapter 7 ∙ Framework Scripting Tips

Another issue is that WebEx usually uses Internet Explorer. At the end of a script, the Frameworkattempts to end all processes that were not started when the script began. This is usually not anissue 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 MDIFrame. When that application is launched, create an object for the window that includes all ofthe child windows.For example, the Agent Recorder is an MDI application. The outside window with the titleAgent 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 andsometimes 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 windowand try again.

Handling Multiple Windows

Create a new object of each window as they are encountered. This means login windows, parentwindows, and other popup windows. As you create the objects, be sure to follow a namingconvention that easily associates a window with the application. For example, a window withthe 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 theverification (or synchronization) step. If WaitForText does not work, or the text to wait for isin multiple windows, such as a PopupWindow and MainWindow, then screen events are thepreferred method. Window and bitmap events should rarely be used, if ever.

Citrix Scripting TipsWhen scripting against Citrix applications, standard bitmap style Wait events are acceptable touse if the bitmaps never move and if the hardware is exactly the same. If, however, the videocards are not identical on the Agent machine, the bitmap wait will fail.Additionally, when trying to capture an image map from the Agent Recorder, the applicationstays out of focus just enough to affect the image quality on objects such as command buttonswith a beveled edge, so that during script playback, the Agent Recorder does not detect themas the same. In Citrix, it is even more important to use key strokes instead of clicking. If theapplication offers speed keys to perform functions (such as [F5] or [Ctrl+K]), make sure toutilize them.Alternately, you can use the Optical Character Recognition (OCR) feature which convertsimages into readable text.



This is a different approach designed to be created on any one brand of computer and deployedon any other brand, even laptop to desktop. The only restriction of this approach is that themonitors need to use the same resolution (e.g.1024x768) and same color depth (e.g. 32-bitcolor).

NOTEDo not use or modify the Framework object Citrix PopupWindow. This object is too genericto use in scripts. It is used internally by the Framework for other purposes.

Creating a Citrix Script1. Navigate to the window to record.

When writing the Citrix script, it is important to treat every window that appears (designatedby the title or caption of the window) as a different window object. For example, when anICA file is launched or a link is clicked on an Internet Explorer “launch page” and anapplication login page appears, create an object for that login window before recordingtyping in the ID or password. If you record typing the ID and password first, The AgentRecorder will record:Window("Citrix PopupWindow").Attach

Alternately, you can use the Optical Character Recognition (OCR) feature which convertsimages into readable text.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 IDand 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 isselected. A portion of the caption can be wildcarded with an asterisk, but make sure that itincludes 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

Once the object map is created, record the action as necessary. This action can be typingin the ID and password, clicking a control, or pressing the [Enter] key. Once that step isrecorded, verify that the object you created was recorded in the script itself. You may needto 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 isnot 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, thiswas done with the WaitForText function. In Citrix, there is no text to capture or checkfor. Everything is an image. While looking for the window title can sometimes work, it isbest 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 scriptitself.

6. Create a new image map entry.When the object map is created, an image map needs to be captured on that window. It isoften preferred to add _IMG to the end of an image map entry to more easily identify theimage maps.

7. Capture the image by selecting a meaningful section of the window.

IMPORTANTDo not select the title bar of the window, but anything under it can be used. A commonpractice is to select an image of what will be clicked on next. Be careful not to use anythingthat has a 3D border, such as buttons. In addition, be careful when capturing text on buttonsto make sure the dotted focus box is not included in the image.



8. Verify that the Agent Recorder can find the image.Sometimes the focus of the window can affect the ability to capture an image. Thedifferences are usually very subtle. You can test if the capture worked by clicking on theLocate button.

9. Use the WaitForImage function to verify.Once the image is found within the window, use the WaitForWindow function to performthe verification stepsWaitForImage " McKesson_Login_PopupWindow", "McKesson_Login_OK_Btn_IMG"

NOTEIf an image is not found by the Identify utility, it will most likely be necessary to useMicrosoft Paint to capture the images. This procedure is shown below.

a. If the Agent Recorder cannot find the image it captured, press [Alt+Prnt Scrn].This is most likely because of focus. To let the Agent Recorder try to capture thewindow, use Paint as a medium. Press [Alt + Prnt Scrn] to put an image of theactive 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 theCitrix application.

d. Capture the image.Capture a section of the window from Paint that is meaningful by pressing the Capturebutton. Do not select the title bar of the window you captured in the image map. Choosesomething to be clicked next or something that will never change appearance. Becareful 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 thename 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 RemoteDesktop, use the Remote_Desktop_ChildWindow.

f. Save and close the object.



C H A P T E R 8

Frequently Asked Questions

Agent Recorder FAQsHow do I troubleshoot an error on an Agent?

The Framework can keep extensive logs when the Framework functions are used. Everytime 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, ittakes a task list complete with loaded programs, file paths, release numbers, etc. Dependingon what the error was, it can also log the text that was found on the screen to comparewith the wait event. Other things that are available are the Enterprise Synthetic versionand build, the Agent Recorder version and build, the Framework version, and the userdatabase version if configured.

Where is the script log file?By default, it is in the work folder of the Agent. You should have a shortcut to this pathif the installation instructions were followed. The file name ismachine-name_day-of-week.log. For example, if the Agent's machine name isCVAgent1 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 underFramework\Printscreens\Logfiles. This copy can be suppressed by choosing thatoption 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 isstill loading.

How do I turn off Java cups in the system tray?Call the function DisableJavaCups one time anywhere in any script. From that pointon, unless some other process turns them back on, they will not reappear.

Why should I use the Framework's Wait functions and not the 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, youalso get these features:


• Complete integration with Enterprise Synthetic. The Framework wait events knowhow long is left in the transaction so it adjusts accordingly. Enterprise Synthetic offersthe ability to adjust Give-up times by location. They adjust automatically.

• Speed. Several Framework functions return results significantly faster than waitevents.

• Logging. The Framework functions log what they were looking for, and how long ittook to find it.

• Extensive, automatic error handling. If the wait event fails, the function will placethe text of the window in the log so it can be reviewed later to see what the problemwas. The wait function requires extra code to handle the instances when a wait eventdoes not succeed.

• The ability to look for one of “x” number of events. Many of the Framework functionsoften allow several events, objects, strings, or bitmaps to be waited for and return thevalue of the event that occurred.

How do I add my own database version and how can I see what Agent is using whatversion?

When maintaining script databases, it is advantageous to keep a versioning system. Thatway you can keep track of what Agent has what version of the database. That can be setin the property called UserDataBaseVersion, which is located in theCVFW_User_Modifiable_Functions module. Any string can be used, whether a dateor some other method. To tell what database version is being used on an Agent, look inthe script log file on the Agent and in the top section: there will be an entry that lists thatversion.

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 arecommon. For an example of how to do this, refer the ZZ_Independent_Step_Driverscript.To place a common launch and login process or error handling that will be called bymultiple scripts, it is best to place that functionality in a shared module. That way it isavailable to all scripts.The advantages of using a subroutine or function instead of a child script include theIntellisense 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. Mostmenu items can be selected with shortcut keys. For most applications, there are keyboardequivalents. Often a key can be used to highlight and icon and [Enter] can be used tolaunch the application, even with Citrix apps. The [Alt] key activates the menu, the arrowkeys can navigate and typing the first letter of a menu item brings the cursor to that menuitem.

When do I need to create an object?The Agent Recorder creates an object for almost every window it encounters. The namewill usually be the caption of the window. This can be confusing with windows that have


Chapter 8 ∙ Frequently Asked Questions

generic captions, such as Login. Each application can have its own Login window, butwindows created by the Agent Recorder will create a new caption for each window itencounters, but number them uniquely.The automatic recording process also makes it difficult to group objects by applicationname. As a rule of thumb, create a new object for any new window that is significantlydifferent from others. While recording a script, stop recording everytime you encountera new window, and then create a new object for that new window. Then continue recordingfrom 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 ispossible 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 presentationmode Citrix applications, create them before you start recording the portion of the scriptthat uses them. If possible, make them generic enough to be useful for other parts of thescript, but not so generic that they are not usable. In the following example, the Captionproperty is unselected and the value contains the wildcard asterisk character (*). Thisobject map can be used for the bitmap select, but is too generic to be useful for most Citrixapplications.

When creating objects, try to avoid having a version number in the Caption propertyunder the Properties tab. If the version is specified, the window may not be found whenthe next version comes out. Be careful to have at least three properties as significant,however. The most common are Application, ClassName, and TypeName. Sometimesthe caption can be included when it contains words that exist in every window of thattype. For example, the Internet Explorer MainWindow contains the textInternet Explorer, but it has an asterisk on either end of it.

When I record, the Agent Recorder adds multiple attach statements. Do I need them all?In an effort to be as reliable in as many environments as possible, the Agent Recorderoften will attach to the MainWindow, then the ChildWindow, and sometimes even a framewithin the ChildWindow. Each attach takes up to a half second; when measuring transactiontimes, this can be significant. Often attaches to the Frame and Child windows can be



ignored, but not always. The most common time the attaches are necessary is inmulti-lingual applications.If you decide to eliminate unnecessary attach statements, make sure you comment thecode you intend to delete and run the script before deleting it altogether, just in case it isnecessary for the application to work properly. For example, the attach to the InternetExplorer ChildWindow is often not necessary. If this line is commented, it may be necessaryto also change the command HTMLBrowser.Type "{Tab}" to IEWindow.Type "{Tab}"because that was the last type of object the script attached to.IEWindow("Internet Explorer MainWindow").Attach

'HTMLBrowser("Internet Explorer ChildWindow").Attach

HTMLEditBox("Name=q").SetText "Dynatrace Enterprise Synthetic "

'HTMLBrowser.Type "{Tab}"

IEWindow.Type "{Tab}"

When should window events be used?Never use the Agent Recorder Window events. Window events, especially create anddestroy events, have proven to be unreliable.Use the Framework functions WaitForWindow or WaitForObj to wait for a window orobject to exist or not exist.

When should bitmap events be used?Citrix and Remote Desktop applications require the use of images to do any verification.As with window events, bitmap wait events are tightly tied to video card brand and evenmodel. The resolution and color depth can be exactly the same, but they may not workbetween Agents. The WaitForImage function provides a more reliable method.To use this function, create bitmap objects before recording the desired step, because iconscan occasionally change colors. You can also name bitmap select statements to make moresense. For best results, do not include the 3D frame around objects such as buttons. Theychange appearance when out of focus.

Enterprise Synthetic FAQsHow do I make my transactions as fast as possible?

The key to accurate transactions is to isolate a transaction to a specific task, such as clickingon the OK button and waiting for specific text in the resulting screen. Any typing of textshould be avoided, such as combining the Launch and Login steps together into onetransaction.A login transaction should not include the time it takes to type in the ID and password.To isolate just that step, insert the StartTrace line after the typing steps. Notice thatthere is another attach to the window right after the StartTrace command. This is becauseoccasionally the Agent Recorder may attach to the Status bar instead.Window("Internet Explorer PopupWindow").Attach

ComboBox("Parent.Label='&User name:'").SetText GetID("VPN")

Sleep 250, tpPauseMilliSeconds

EditBox("Label='&Password:'").SetText GetPassword("VPN")

StartTrace ("VPN_Login")

Window("Internet Explorer PopupWindow").Attach

Button("Caption=OK").Click



Another thing that can make transactions faster is using the WaitForText orWaitForWindow functions. Both of these are capable of transaction times shorter thanone second, and are faster than the Agent Recorder's Wait eventsYou can also use the optional feature of the attach command called tpAttachNoWait.This will reduce the amount of time it takes to perform an action on a control. For bestresults, however, it is preferred to use the tpAttachNoWait after a regular attach wasperformed. To take advantage of this feature, the attach line changes from this:Window("Internet Explorer PopupWindow").Attach

to this:Window("Internet Explorer PopupWindow", tpAttachNoWait).Attach

How do I know if a script error occurred between transactions?By default, you will not know if an error occurred. There are a few alternatives to detecterrors.The best way is to monitor the Launch_To_Close transaction. It only succeeds if theentire script succeeds.Another way is to take advantage of the AddTransaction function. This tells the scriptthat a transaction will be starting in the future, but not quite yet. If the script has to dosome preparatory steps before the actual transaction, such as typing in an ID and password,use AddTransaction to make sure the transaction will get a result.AddTransaction "Google_Search"

ShowStatusBox "Entering search criteria...", True



IEWindow.Type "{tab}"

ShowStatusBox "Clicking on the 'Google Search' button...", True

StartTrace "Google_Search"

How do I add sequence numbers to the transactions in my reports?Run the CVFW_Maintenance script, then navigate to the Integration tab and select thePrefix Transaction Name w/Sequence check box. From that point on, all transactionsthat are imported into the Console will be numbered with a sequence incremented by 10.

NOTEAfter a script is already configured in the Enterprise Synthetic Console and a transactionis added, do not use the DevMode function because it will add new numbers. Manuallyconfigure the transaction name with a number between the existing ones. The existingtransactions will continue to be recorded, even if you change the transaction names in theEnterprise Synthetic Console.

How do I add an application prefix to my transaction names in the Enterprise SyntheticConsole?

It is often desirable to prefix the number with a unique identifier, such asSAP_010_SAP_Launch. This results in all SAP applications being sorted together if youare displaying a list of transactions for a time period. To accomplish this, set the desiredprefix as a parameter in the InitializeScript function. For example:Call InitializeScript(ScriptType, Me.Name, "SAP")



When imported into the Enterprise Synthetic Console, it will prefix the event with SAP asthe first characters. The events will look like this:SAP_010_SAP_Launch

SAP_020_SAP_Login

Adding that parameter will not affect anything that has already been configured.How can I close an application if an error occurs before the default error handler takesover?

Many applications require a graceful logout. The default error handler will terminate anyapplication that was not running when the script started.

IMPORTANTDo not put any error handling before the HandleScriptErrors line. That functionperforms the capture of the actual error that occurred and displays it so it can be capturedby the Agent. The best way is to add your own logout process by placing it in theUserCleanUpDesktop function located in the CVFW_User_Modifiable_Functionsmodule. A good example of how to create a clean up routine is the sub calledUserCloseCitrix located in the CVFW_User_Modifiable_Functions module.

How am I alerted when a screen saver is active on the Agent?As a script starts, it automatically checks to see if a screen saver is active. If theLaunch_To_Close transaction is not being monitored, then no alerts will be triggered.The script never makes it past the InitializeScript line. To send an alert, mark thefirst transaction as unavailable. The function UserScreenSaverActive in theCVFW_User_Modifiable_Functions module contains an example of how to use thismethod.

How do I set up alerting by application instead of transaction?Using the built-in SMTP email in the Enterprise Synthetic Console is the best way. IfEnterprise Rules are required, however, use the Launch_To_Close transaction. If thistransaction is configured, set all alerts for availability to that. When the script fails at anypoint, it will trigger an alert. If it succeeds, it will trigger the return to normal, but not untilit succeeds.

How do I stagger the start times of a script by Agent?This can easily be accomplished in the Enterprise Synthetic Console. Create differentschedules that start at different times and adjust the tasks to specific start times by Agent.

Why does the Launch To Close transaction always show a timeout, but the script does noterror?

The most likely culprit is the give-up time set in the Enterprise Synthetic Console. To getan idea of how long it should be set, look in the log file on the Agent and find how longthe script ran. The last time the script ran is recorded toward the top of the file in theTransaction Details section. For example:[Transaction Details]

ZZ_Google,App_ZZ_Google = Ended at: 6:20:28 PM, in 33 seconds.

ZZ_Google,ZZ_Google_Launch= Ended at: 6:20:19 PM, in 2 seconds.

ZZ_Google,ZZ_Google_Search= Ended at: 6:20:22 PM, in 5 seconds

In this case, the script ran 33 seconds. If the Availability was set to 30, it would show aviolation. In this case, it may be more useful to set it to 45 or 60 seconds, depending on



the application and number of transactions. The more transactions that are included in ascript, the more the times can vary.

How do I mark the remaining transactions as unavailable if an application fails in themiddle?

Sometimes it is preferable to mark all transactions that could not execute because of aproblem in the middle of the script as unavailable. There needs to be a process that letsthe script know what transactions it expects to see. That way, at the end of the script, itcan compare what it actually triggered against what it thought it was supposed to trigger.This can easily be accomplished by using the AddTransaction function before the scriptbegins its normal steps.This function does not actually start a transaction, it just makes the script aware of whatis supposed to happen. For example, you can add the AddTransaction lines before thescript performs the launch and if anything fails along the way, any transaction that didn'tcomplete will automatically be marked as unavailable. On Error GoTo ErrorHandler

Call InitializeScript(ScriptType, Me.Name)

' -----------------------------------------------------------------------------

AddTransaction "ZZ-Google_Launch"

AddTransaction "ZZ-Google_Search"

StartTrace ("ZZ-Google_Launch")

LaunchToPage ("www.google.com")

This can also be useful if you only want to alert on the upcoming transaction when anerror occurs in a preparatory step. In the Google Search example script, that step wouldbe typing in the search text Dynatrace Enterprise Synthetic. In this case, you wantto mark the ZZ-Google_Search transaction as unavailable, even though it never officiallystarted. The following example shows how that can be accomplished:StartTrace ("ZZ-Google_Launch")

LaunchToPage ("www.google.com")

'Look for 'Google Search'

WaitForAny ("ZZ-Google_Home_Page")

StopTimerAndTrace ("ZZ-Google_Launch")

AddTransaction "ZZ-Google_Search"

' -------------------- Type in text to search for --------------------

ShowStatusBox ("Typing in 'Dynatrace Enterprise Synthetic '")



IEWindow.Type "{Tab}"

' -------------------- Click on the 'Google Search' button --------------------

ShowStatusBox ("Pressing 'Google Search' button...")

StartTrace ("ZZ-Google_Search")

If the script fails anywhere between the end of the ZZ-Google_Launch transaction andthe end of the ZZ-Google_Search transaction, then the ZZ-Google_Search transactionwill be marked unavailable. Another way is to take advantage of theMarkTransUnavailable function. This is most commonly used in error handling routinesor in the UserScreenSaverActive functions.

Do I have to have a shared folder on the Agent Manager?No. If you do not use a shared folder, however, some features may not be available. Totake advantage of the passwords configured in the CVFW_Maintenance window, the .inifile must be distributed. This would require the use of the Publish Scripts feature in the



Enterprise Synthetic Console. To view Framework log files, you will need to look in theAgent's work folder instead of the shared folder.

If a transaction fails, how can I get it to retry?There are times when retrying a transaction is beneficial. For example, when a web pageload results in a Page Cannot Be Displayed error. The Framework offers two functions,called WaitForTextWithRefresh and WaitForImageWithRefresh, that greatly simplifythe process. These functions wait for the text in the window, but if text does not appearwithin a period of time, the Refresh button is pressed once by default. Some exampleuses are provided below.In this example, only the first two parameters are required. The last three are the default.WaitForTextWithRefresh "Internet Explorer MainWindow", "Home",

1, PressAKey, "{F5}"

In this example, you cannot specify control type, such as HTMLSpan, which may limit theuse of it.WaitForTextWithRefresh "Internet Explorer MainWindow",

"dynatrace.com", 1, ClickOnControl, "Caption=Search"

In this example, make sure the text is unique.WaitForTextWithRefresh "Internet Explorer MainWindow",

"dynatrace.com", 1, ClickOnText, "Search"

Since this example is searching for text, this is rarely used.WaitForTextWithRefresh "Internet Explorer MainWindow", "Home",

1, ClickOnImage, "Google_Search_Button_IMG"

How do I make the first run after rebooting an Agent not register its execution time?Some applications perform poorly immediately after a reboot. Because of that, it issometimes desirable to ignore that transaction. It is often best to never even record thattransaction. For example, the first run (at 5:00 AM after a 4:50 AM reboot) of thetransaction ZZ-Google_Launch always takes 12 seconds, but normally the transactiontakes 3 seconds. If the 12-second transaction was recorded, the averages would be off,and an alert might be sent.In this case, it is preferred to run the script first to “initiate” the transactions on the firstrun but not report the times. Every run after that should report the times. Assume that inthe Enterprise Synthetic Console, the transaction starts with a NotifyEventZZ-Google_Launch-Start and ends with a ZZ-Google_Launch-Stop. To effectivelyignore that transaction, all that is necessary is to not trigger the expected transaction. Whilethis can be accomplished by transaction, a far easier method is to use is a built-in featurecalled PassedParm. By setting a value to this property, each NotifyEvent adds this tothe event. This effectively triggers events that Enterprise Synthetic is not listening for,and therefore does not report.To force Enterprise Synthetic to ignore any transaction between 5:00 AM and 5:10 AM,add the following line in the script as the first line after Sub Main.

If (Hour(Now()) = 5) And (Minute(Now()) < 10) Then PassedParm = "Z"

InitAppDriver Me.Name '

----------------------------------------------------------------------------

When the script runs, it first looks at the time. If it is between 5:00 and 5:10am, it adds Zto each NotifyEvent. For example, the transactions would change to



ZZ-Google_Launch_Z-Start and ZZ-Google_Launch_Z-Stop, respectively. The Agentdoes not know what those mean, so it ignores them. The script ran, but no transactionswere recorded.

NOTEThis may trigger script health alerts.

How do I handle using fewer IDs than the number of Agents running the script?The Framework offers a checkout/checkin option. It requires a shared folder which theAgents can read and write to.In the CVFW_Maintenance Configuration window, navigate to the Passwords tab. Onthe left side, select the application name. Enter the IDs and passwords for the application,then select the Use Check-in/Check-out check box.In the script, use the GetID and GetPassword functions. As these functions work, theywill use an .ini file in the Framework folder to check out and check in an ID as it needsto. When the script uses GetID, it checks out the ID; when the script ends for any reason,it will check it back in. If there are no IDs available, the GetID function will keep checkingevery few seconds until the number of seconds configured in the drop-down box is reached.If the time expires before an ID becomes available, it triggers an error. If the Agent alreadyhas an ID checked out, it will not check out another one. It will just re-use it.If you have your own method of checkout/checkin, the Framework can work with thatinstead. Write the procedure you want to use in the UserIDCheckIn and UserIDCheckOutfunctions located in the CVFW_User_Modifiable_Functions module.

NOTEThe default method used here is not as reliable as a database style checkout/checkinmethod. This is because it uses .ini files, which means that concurrent start times mayyield unexpected results. To minimize this effect, it is best to stagger the start times of thescripts in the Enterprise Synthetic Console.

How do I make a blackout for times and days that are not provided by EnterpriseSynthetic?

While the preferred way is to use the blackouts provided in the Enterprise SyntheticConsole, there are certain scenarios that are not available in the Console. For example,holidays or UTC-sensitive times are not available. The Framework allows several typesof blackout periods, all available using UTC times. To configure them, run theCVFW_Maintenance script and navigate to the Blackouts tab. There are several optionsavailable. If the application name is not listed, add it in the Passwords tab,If data health is enabled on the Agent, a script that does not run may trigger a EnterpriseSynthetic data health alert.

How can I apply a blackout period to just one or more transactions within a script?The Enterprise Synthetic Console offers script-level blackouts, but not transaction-level.The Framework offers two ways to do this. The first is through the AddTransactionfunction and the other is through the StartTrace function. To implement this feature, itmust be configured in the CVFW_Maintenance script. Navigate to the Passwords tab,



enter the name of the desired transaction as an application, and click the Add button. Thennavigate to the blackout tab and add the desired blackout entries.In the script, use IF/THEN logic to determine if the action should be executed. TheStartTrace function returns True if the transaction should run and the AddTransactionreturns a value > 0 if it should run. Here are some examples:If AddTransaction("ZZ-Google_Search") >= 0 Then

' execute the steps necessary for the searchtransaction

End If

Or:If StartTrace("ZZ-Google_Search") = True Then

' execute the steps necessary for the searchtransaction

End If

How can I have the script enter random account numbers?There are times when you need to monitor cached transactions as caching can show muchbetter than realistic performance. To minimize this scenario, it may be important torandomize input parameters such as names, zip codes, or order numbers. These parameterscan either be hard-coded into the script or placed in a file. The easiest way is to use theCVFW_Maintenance script since it can be updated without changing the database and itis automatically distributed every time a script runs.Use the CVFW_Maintenance script to enter the parameters you want under the UserDefinedtab. In this case, you may want to enter any one of five names. This CVFW.ini file containsthese items:

• [My_App]

• Name1=Smith

• Name2=Jones

• Name3=Johnson

• Name4=Brown

• Name5=Adams

To retrieve those items, you can use the following code. Each time the script runs, it willenter one of the five names in a random order. The AppIniFile is a variable that refersto the CVFW.ini file.Dim sRandomNbr As String

sRandomNbr =Trim(GetRandomNumber(1, 5))


HTMLEditBox("CustName").SetTextReadini(AppIniFile, "My_App", "Name" &

sRandomNbr)

What is the best way to reboot the Agents daily if Auto Login is not allowed?Since the Agents are Windows based and memory leaks are common when applicationsare started and terminated, it is important to reboot the Agents daily. In order to enable amachine to automatically log on, however, several things need to be set (or removed). Forexample, the disclaimer screen that often pops up while logging in must be removed. Thebiggest issue, however, is the password set in plain text in the registry. To lessen (noteliminate) the exposure, the function RebootRobot enables you to encrypt a password inthe CVFW.ini file using the Password tab to temporarily put the password in the registryand remove it right after the reboot. To do this, in the CVFW_Maintenance window, go



to the Passwords tab and create an application called AgentLogin. Set the ID andpassword, then save this information and copy it to the server. Make a copy of theCVFW_Reboot__Driver and edit the line that calls RebootRobot to read as follows:Call RebootRobot("AgentLogin", 1, True)

Then create a scheduled task to run at a time when you want the Agent to reboot. Be verycareful that you do not have a script running at this time. For example, you may want toschedule the reboot at 11:55 PM if your scripts start at midnight. The syntax in thescheduled task is:tp -u admin -p admin -s My_Reboot__Driver

Another (and preferred) alternative is to use the Microsoft TweakUI. That utility enablesautomatic login without putting a plain text password in the registry.

Citrix Frequently Asked QuestionsHow do I get and keep focus on my Citrix window?

Occasionally, a Citrix window gains focus but then loses focus. This can lead to inconsistentbehavior. Even with using the activate option on the window, it still occasionally losesfocus again. This is one time that mouse clicks are useful. There is a function availablein the Framework that clicks on the title bar of the window to put keyboard focus on it.This function is called WindowActivate. This will attach to the window and put keyboardfocus on the window. Here is how to use that function:WindowActivate ("McKesson_MainWindow")

Window.BitmapSelect "McKesson_OK_Button_IMG", tpMouseSingleClick

How do I handle a script that skips steps after login?You can use the function LookForAnyImages. The return value will be the one it found.If it finds more than one return value, it will return the first one it finds. If it does not findany, it returns 0 (zero). It does not raise an error like Wait events do.For example, the following code will return 1 if the image of the OK button exists or 2if the image of the Yes button exists. If neither one exists, it will return 0. It does not wait. iReturnVal = LookForAnyImages("Citrix

PopupWindow", "Citrix OK Button", "Citrix Yes Button")

If you have separate windows for each step (which is recommended for non-publisheddesktop implementations), you can use the IsWindow function in an if statement.If IsWindow("Citrix_Login", "Enabled") = True Then

'[whatever necessary]

ElseIf IsWindow("Citrix_Home", "Enabled") = True Then


ElseIf IsWindow("Citrix_SearchWindow", "Enabled") = True Then


ElseIf IsWindow("Citrix_ErrorWindow", "Enabled") = True Then


Else

' Error handling?

End If

Any one of a number of images can exist. Which one do I click?If the application can produce one of a number of images based on backgrounds, etc., andall of them do the same thing, you can just click on the image that is there by using the



function ClickOnOneImage. It returns which image it found, so you can branch accordinglyif necessary.iRetVal = ClickOnOneImage("Citrix PopupWindow", "Grey Plus Icon", "White Plus

Icon")

If iRetVal = 1 Then

' [the process if the grey plus was clicked]

Else

' [the process if the white plus was clicked]

End If

How do I make sure all Citrix sessions are logged off at the end of the script?There is a function called UserCitrixLogoff in the CVFW_User_Modifiable_Functionsmodule. This function tries to take advantage of the default Citrix session logoff feature.This sends the [Ctrl+F1] key sequence to the Citrix server to display the Server Logoffwindow, which is similar to pressing [Ctrl+Alt+Del] on a Windows workstation. SomeCitrix administrators disable this feature, however.Another option is to create a function (or Sub) in your own shared module and call it fromthe UserCleanUpDesktop function, which is located in theCVFW_User_Modifiable_Functions module. When calling this function, it is importantto test to see if a window exists before simply trying to close a window. An example ofhow to write this function is illustrated in the Sub UserCloseCitrix, which is also locatedin the CVFW_User_Modifiable_Functions module. Use this as a template for eachCitrix application.For example, add this to the UserCleanUpDesktop:Call MyCo.SharedModule.MyCo_CloseAll_Apps

In the shared module, the Sub called MyCo_CloseAll_Apps will look something like this:Sub MyCo_CloseAll_Apps ()

On Error Resume Next

Call CitrixCloseApp1



WaitUntilGone "WFICA32.EXE", 45, True

End Sub ‘MyCo_CloseAll_Apps

Sub CitrixCloseApp1 ()

Dim iCnt As Integer

On Error Resume Next

For iCnt = 1 To 3

If IsWindow("CitrixApp1_Window_3") = True Then

Window("CitrixApp1_Window_3").Attach

Window.Close

WaitForWindow "CitrixApp1_Window_3", DoesNotExist

End If



Window.Close


End If



Window.Close


End If

Next

End Sub ‘CitrixCloseApp1



How do I know what Citrix server the Agent connected to when it ran a script?When scripting Citrix or other load-balanced applications, it is often advantageous toknow what server the Agent is connected to. This information can help in diagnosing aproblem if a script intermittently has problems. This can be done by uncommenting theline that looks like the following, in the Sub called UserStopTrace, which is located inthe module CVFW_User_Modifiable_Functions.GetServer

By default, it looks for connections on the typical Citrix ports of 1494 and 2598. If theport the application uses is anything other than that, the GetServer function can take anoptional parameter of which port to look for.When this function is called, it will display the IP address of the server in a yellow boxin the lower right corner of the desktop. In addition, it will log the IP address in the scriptlog.

Why does entering text in form fields cause a script error?Entering text in a form field can occasionally cause errors because the script is faster thanthe application. This can happen if the field does an edit check, meaning that it eitherverifies what was entered or fills in another control with values to select. For example, aform that uses city and state may fill in available cities automatically when a state ischosen.In this case, put a sleep for 250 or 500 tpPauseMilliSeconds to let the application catchup before continuing with the script.Window("Internet Explorer PopupWindow").Attach

ComboBox("Parent.Label='&State:'").SetText "MN"

Sleep 250, tpPauseMilliSeconds

EditBox("Label='&City:'").SetText "St. Paul"

Button("Caption=OK").Click

There are other options, however. The Framework offers a feature calledSetTextAndVerify which replaces this line:HTMLEditBox("Name=physicalCity").SetText "Wilson"

with this line:SetTextAndVerify "Name=physicalCity", "Wilson"

This will try multiple ways to verify that the text typed actually exists on the control.Another function often used in Citrix environments is the Slowtype function. It slowsdown the type rate of the characters on the screen and has three parameters. The first isto type it with the default 100ms delay between characters. The second allows a differentdelay between characters. The third parameter sets how long the script will wait after thelast character is typed.Window("MyWindow").Attach

SlowType "Wilson" ' pauses the default 100ms between each character

or

SlowType "Wilson", 50 ' pauses 50ms between each character

or

SlowType "Wilson", 100, 250 ' pauses 100ms between each character, then

250ms at the end

How should I close Adobe Acrobat and Citrix applications?Adobe Acrobat, WFICA32.exe (the Citrix client), and few other applications do not removethemselves from memory when the window disappears. There are usually several tasks



that the application performs before it eventually disappears from memory. With Citrix,this process may include terminating the session on the server. Because these processesmay be critical to the stability of the Agent, it is beneficial to wait until they are out ofmemory before terminating them with KillApp or a similar function.Use the WaitUntilGone function to do this. This function takes three arguments. Thefirst is the executable, such as WFICA32.exe. The second is how long to wait. A commonwait time for WFICA32.exe is between 45 and 60 seconds. The third parameter is whetheror not to force the application to be terminated when the time expires. Usually the valueis true (force termination), but sometimes it may be necessary to perform some othertask instead.Another alternative for Citrix is to try the function UserCitrixLogoff in theCVFW_User_Modifiable_Functions module.

When is a mouse click preferred over a keyboard?In most environments, keystrokes are much more reliable than mouse movements. Mostmenu items can be selected with shortcut keys. For most applications, there are keyboardequivalents. Often a key can be used to highlight an icon and [Enter] can be used tolaunch the application, even with Citrix applications. Pressing the [Alt] key activatesthe menu, pressing arrow keys can navigate, and typing the first letter of a menu itembrings the cursor to that menu item.

When should bitmap events be used?Citrix and Remote Desktop applications require the use of images to do any verification.As with window events, bitmap wait events are tightly tied to video card brand and evenmodel. The resolution and color depth can be exactly the same, but they may not workbetween Agents. The WaitForImage function provides a more reliable method.To use this function, create bitmap objects before recording the desired step, because iconscan occasionally change colors. You can also name bitmap select statements to make moresense. For best results, do not include the 3D frame around objects such as buttons. Theychange appearance when out of focus.The Wait functions IEWait and WaitForAny will not work with bitmap events.

How can I close an application if an error occurs before the default error handler takesover?

Many applications require a graceful logout. The default error handler will terminate anyapplication that was not running when the script started.

IMPORTANTDo not put error handling before the HandleScriptErrors line. That function performsthe capture of the actual error that occurred and displays it so it can be captured by theAgent. The best way is to add your own logout process by placing it in theUserCleanUpDesktop function located in the CVFW_User_Modifiable_Functionsmodule. A good example of how to create a clean p routine is the sub calledUserCloseCitrix located in the CVFW_User_Modifiable_Functions module.



Internet Explorer Frequently Asked QuestionsHow do I handle secondary Internet Explorer windows?

The Framework provides a very generic Internet Explorer window object. While thisworks very well 99% of the time, there are times where performing an action in one InternetExplorer window launches a second window. It is highly recommended to create a secondInternet Explorer object for the particular application. While that second window exists,explicitly use it for using Wait events, etc.To do this, run the application until the new browser is launched and stop the script. Createa new object using the Object Map Entry section. Select the entire window (if practical)by clicking on the title bar of the window. If it is an Internet Explorer window, the defaultname will be Internet Explorer MainWindow. It is very important to change the nameto start with the application name, and then modify the attributes of the object to matchthis window. For example, name it something like MSN_News_Window orCNN_MainWindow. What will set this apart from the generic window are the properties,with the most common property being the caption. The name can include an asterisk torepresent characters that may change.

IMPORTANTBe sure not to include version numbers in the significant fields. This would cause problemswhen a new version is released, even if the screen is not changed in the newer release.

How do I clear the cache, cookies, etc. in Internet Explorer?Many IT departments disable the ability to change the cache settings in Internet Explorer.There are also times when it is desirable to clear the cache, so the page needs to fullyreload every time a script runs. This can be easily accomplished by using the ClearIEfunction.

What is the best way to verify that the page loaded?Looking for specific text on a window is the easiest and fastest way. There are severalalternatives offered by the Framework. The easiest is the WaitForText function.Traditional screen events can also be used, but they require extra steps to create. If theWaitForAny function is used, the only events it supports are screen events. This is bydesign since all other event types are not as reliable. Also, do not use the word Done atthe bottom of the Internet Explorer Window. If the page includes frames, there is a highprobability that the word Done will appear after each frame loads.

NOTEDo not use WaitUntilIEReady for verification. Keep in mind that the message The pagecannot be displayed also returns True.

There are situations where there is no text to capture, such as in Flash pages. In this case,it is necessary to use image maps. Image maps can be used by the WaitForImage function.



A P P E N D I X A

Framework Scripting Checklists

The Framework scripting checklists serve as a comprehensive guide for creating scripts, importingscripts and transactions into Enterprise Synthetic, and maintaining your scripting environment.

NOTEThese checklists assume you use an Enterprise Synthetic environment with a Master ScriptingAgent and remote Enterprise Synthetic Console to develop, test, and deploy scripts.

Table 3. Create the Script

StepsCompleted

In the Agent Recorder, create your script. Make sure to use unique transaction names.

Run the script and verify that it runs without error.

Optional: Change ScriptType to SelfDocumentation_Mode, and then run the scriptto create the MS Word file.

Change ScriptType to Import_Mode, and then run the script to create the file toimport.

Table 4. Import the Script and Assign and Deploy the Transactions

StepsCompleted

In the Enterprise Synthetic Console, select File ➤ Import Data.

Paste the file name that was copied onto the clipboard by the import script into the filename box.

Click Preview and verify the file data is imported correctly.

Click Import. Review the Import Status report, and then click OK.

Optional: Change the schedule if it is other than the default.


Table 4. Import the Script and Assign and Deploy the Transactions (continued)

StepsCompleted

Select Assign Locations from the Getting Started: Active Navigation pane. Assignall application/transactions to the desired locations and Agents. Include the MasterScripting Agent.

Select Deploy Transactions from the Getting Started: Active Navigation pane.Deploy the transactions on the Agents you want to run the scripts. Exclude the MasterScripting Agent.

Table 5. Configure the Script for Production and Clean Up the Database

StepsCompleted

Optional: If the script uses any parameters stored in the CVFW.ini file, then run theCVFW_Maintenance script.Select Yes when prompted to use the local file. The new script adds its applicationname to the local CVFW.ini file when it is run.

Change ScriptType to Production_App_Driver.

Optional: Close all scripts, but not the Agent Recorder. Select File ➤ Purge AssetVersions, and then select the desired versions to delete.

Close the Agent Recorder.

In the Agent Recorder's Database Maintenance utility, run the database integrity check,clear connected users, unlock records, and compact the database.

After completing the steps described in these checklists, you are ready to deploy the scriptdatabase from the Master Scripting Agent to the rest of the Agents in your environment. Formore information, see Publish the Database Scripts and Agent Recorder Configuration Files[p. 11].


Appendix A ∙ Framework Scripting Checklists

A P P E N D I X B

Framework Functions Reference

This section lists the available functions provided in the Framework.

Wait FunctionsThis topic contains a list of Wait functions that you can use in an Agent Recorder script. Theamount of time they wait is defaulted to 30 seconds and is modified by setting the propertyWaitTime to the number of desired seconds. For example, setting the line WaitTime = 60before the StartTrace line sets the default wait time for WaitFor functions to succeed to 60seconds before going into error handling. The property JustInCaseWaitTime is used only fortheJustInCase functions.

DescriptionReturnsFunction/Sub

Waits for the specific IE event as well as the Page Not Foundevent, in which case, the script goes into an error condition. UsesWaitForAny.

IntegerIEWait

Example:IEWait ("ZZ-Google_Home_Page")

Waits for text to appear in a specific window and assumes the firstparameter is the Internet Explorer MainWindow.

IntegerIEWaitForText

Example: To wait for the text 'Password' to appear use:IEWaitForText "Password", True

Or to wait for the text 'Working' to disappear, use:IEWaitForText "Working", False

Waits for events without triggering error handling by callingWaitForAny but suppressing all errors. Use this function when

IntegerJustInCaseWait

waiting for unpredictable dialog boxes to appear or securityconfirmation screens. Since this adds time to the transaction, it ispreferred to include the event in a For loop that uses theWaitForAny function instead.Example:If JustInCaseWait (“MyApp Password Expired") = 1 then



Waits for text within one window without triggering error handling.Similar to function WaitForTextDelimited which checks for one

IntegerJustInCaseWaitForText

or more strings within one window. Use this function when waitingfor unpredictable strings such as Page Cannot Be Displayed orPassword has expired. This may add time to the transaction,because it waits the amount of time designated by theJustInCaseWaitTime value.Example:If JustInCaseWaitForText (“Internet Explorer MainWindow ?,

“Expired,will expire) = 1 then

Waits a specified time for specified Agent Recorder screen waitevents to occur. The number of events to wait for should be limited,

IntegerWaitForAny

however, since the function may wait approximately 200ms perevent as it cycles through them.Examples:WaitForAny ("ZZ-Google_Home_Page")

iRet = WaitForAny “MyApp_Login_Page", “MyApp Password Expired"

Waits for the window object to exist, then for any one of the passedimage maps to exist. If one of them succeeds, the function returns

IntegerWaitForAnyImages

the number of the image found. The result starts with 1 for the first,etc.. Similar to WaitForObject, but waits for more than one image.Example:WaitForAnyImages("Citrix MyApp Login PopupWindow ",

"MyApp_Login",

"MyApp_Password_Expired")

This is similar to the WaitForText function, but it checks for thetext in any window that gets focus. This may work as an alternative

IntegerWaitForAnyText

to creating screen wait events and using WaitForAny. The firstparameter tells the function to be case sensitive.Example:iRet = WaitForAnyText(True, "Synthetic Monitoring", "Cannot

be

displayed", "Password")

Same as WaitForAnyText, but it will look for one of a list ofstrings. The default delimiter is a comma, but it can be overridden

IntegerWaitForAnyTextDelimited

by populating the optional third parameter. Leading spaces arecounted as characters are not stripped since they are legitimatecharacters to search for.Examples:iRet = WaitForAnyTextDelimited ("of about,Travel,Executive",

",") Example: If

WaitForWindow("Notepad MainWindow", DoesExist) = True Then...

Waits for any of the passed windows to appear. Especially usefulif more than one window can appear and branching needs to bedone based on which one exists.

IntegerWaitForAnyWindow


Appendix B ∙ Framework Functions Reference


Example:If WaitForAnyWindow("MyApp_MainWindow", "Application Error

Window")

= 2 Then…

This waits for the CPU to drop below a certain percentage. This isespecially useful when working with Java (e.g. Oracle Forms)applications.

BooleanWaitForCPU

IMPORTANTDo not use WaitForCPU for verification purposes.

Example:WaitForCPU 30, WaitTime

Use instead of Bitmap Wait events, which are reliable only if theyare deployed on Agents that have exactly the same hardware. This

BooleanWaitForImage

function requires only the same resolution and color depth. It checksto see if a bitmap exists on the window specified.Example:WaitForImage “Citrix MyApp Login PopupWindow“,

“Citrix MyApp PasswordImage"

Checks for the cursor to change from an hourglass. Usually usedfor Java applications and before a text type WaitFor function.

BooleanWaitForNoHourGlass


Example:Call WaitForNoHourGlass

Waits for a object to exist, not exist, be enabled, etc.BooleanWaitForObjectExample:WaitForObject "InnerText='Login'", IsEnabled

Waits for a specified text string to appear or disappear in a controlthat supports text selection.

BooleanWaitForSelectableText

The control is specified by the first parameter, which may requirewatching for text in a control, such as MozillaBrowser orHTMLBrowser.Optionally, this function sends a mouse click to the specified point(x, y) to avoid capturing text from inner controls that are capableof gaining keyboard focus. For example, edit box or radio buttons.In contrast with other functions, this one periodically sends a selectall [(Ctrl+A)] and copy to clipboard [(Ctrl+C)] shortcut keycombination to the specified control.




Syntax:Function WaitForSelectableText(oObject, sText

As String, Optional bExists As Boolean = True, Optional

ShouldClick = True, Optional x = 3,

Optional y = 115) As Integer

Example:For more information, refer to theZZ_FF_WaitForSelectableText sample script.

Waits for text to appear in a specific window. This is similar to adynamic wait event and requires less effort and works faster thanAgent Recorder Screen events.

IntegerWaitForText

Example: To wait for the text 'Password' to appear, use:WaitForText "Internet Explorer MainWindow", "Password", True

Or to wait for the text 'Working' to disappear:WaitForText "Internet Explorer MainWindow", "Working", False

Checks for any of the strings passed and returns the number of thestring. Similar to WaitForText. The default delimiter is the comma.

IntegerWaitForTextDelimited

Leading spaces are counted as characters are not stripped since theyare legitimate characters to search for.Example:iRet = WaitForTextDelimited ("Internet Explorer MainWindow",

"Password, Expired") returns 2 if the text “ Expired" is found

Waits for an allotted time period for text to appear in the window.If the text does not appear, or if the OCR engine does not recognizethe text, it times out and follows the current Framework error path.

IntegerWaitForTextOCR

Pass in the Rectin parameter to limit the amount of text the OCRengine has to process and obtain the coordinates of the text.WaitForTextOCR (oObject, Optional ByRef rSubRect As

TRectangle = vbEmpty)

Waits for a window to have specific attributes. Useful instead ofwindow wait events. Select from the list of options such as:

BooleanWaitForWindow

DoesExist, DoesNotExist, IsDisabled, IsEnabled,IsInvisible and IsVisible.

Waits until an application is out of memory. Especially useful withapplications such as SAP or Citrix that do not perform well when

BooleanWaitUntilGone

forced to close. The last parameter is to force the executable closedif it is still in memory when time runs out. Make sure to add theapplication to the kill list if the application is expected to be forcedto close.Example:WaitUntilGone "SAPGUI.EXE", 20, True

Waits up to either the passed number of seconds or WaitTime untilany IE browser is still loading. It does not raise an error if it times

BooleanWaitUntilIEReady




out. All verifications should either be of type text or image. This isoften used before a new StartTrace is called.


Example:WaitUntilIEReady

General Scripting FunctionsThis topic contains a list of general scripting functions that you can use in an Agent Recorderscript.

DescriptionReturnValue

Function

Returns the string of the window that is accepting keystrokes.StringActiveWindowExample:Window(ActiveWindow()).Attach

Adds days to a date.DateAddDaysExample:dNewDate = AddDays(Now(), 3)

Adds an application to a list of application to not terminate.NoneAddToDoNotKillListExample:AddToDoNotKillList "PCAW32.EXE"

Adds an application to the list of applications to terminate.NoneAddToKillListExample:AddToKillList "IEXPLORE.EXE"

Returns the name of the computer that is retrieved from theoperating system.

StringAgentName

Example:HTMLEditBox("Name=UserID").SetText AgentName

Adds an item to an array.NoneArrayPushExample:ArrayPush ServerArray, “:123”

Closes a Found New Hardware window, which may openwhen roaming profile changes are not saved upon logoff.

NoneClearHardwareWizard

Example:ClearHardwareWizard




Function

Clears the Legal Notice setting that appears when rebooting.This can be called at the end of the script to clear thedisclaimer notice to help with auto login.

NoneClearLegalNotice

NOTEOften local policies will replace the notice upon reboot, sothe effectiveness of this function is not guaranteed.

Example:ClearLegalNotice


StringComputerName

Example:HTMLEditBox("Name=UserID").SetText ComputerName

Creates a path an arbitrary number of levels deep.BooleanCreateFilePathExample:If CreateFilePath (“D:\Data\MyApp\NewFolder”) = False

then

Runs a script and returns true or false, depending on howit ran.

BooleanCVRun

Example:If CVRun("ZZ_Google_Launch") = False

Then...

Removes an application from the list to not terminate(DoNotKillList).

NoneDeleteFromDoNotKillList

Example:DeleteFromDoNotKillList "WFICA32.EXE"

Removes an application from the list to make sure toterminate.

NoneDeleteFromKillList

Example:DeleteFromKillList "PCAW32.EXE"

Suppresses the Java coffee cups from appearing in the taskbar.NoneDisableJavaCupsExample:DisableJavaCups

Returns the three-character English text of the Weekdayfunction.

StringDOWText

Example:sDOW = DOWText("11/7/2012")

This is the equivalent of the QARun function.IntegerFindStr




Function

Example:iRet = FindStr(“Find it in this”, “it”, 1)

Looks for a string of text in an object. Returns true if found.Make sure the keyboard focus is not on a text input typecontrol. It uses the [Page Down] key to navigate.

BooleanFindTextInWindow

Example:bRet = FindTextInWindow ("Internet Explorer MainWindow",

“string to look for”).Related function:

NavigateToTextInWindow

Creates a password based on the pattern given. Valid lettersare A or U for upper case, b or l for lower case, and 0 for a

StringGeneratePassword

number between 0 and 9. All letters are English. This returnsa string in this format: X5w0i31c.Example:sNewPassword = GeneratePassword("A0b0b00b")

Gets the handle to the window in the foreground. Similar toActiveWindow, but uses the Windows API instead of theAgent Recorder keyboard focus.

LongGetForegroundWindow

Decrypts the ID saved in the CVFW.ini file. If no parameteris passed, it assumes the current value of AppName.

StringGetID

Example:HTMLEditBox("Name=username").SetText GetID()

This is designed to get the last work day prior to either todayor the optional date passed. It assumes that weekends are notworkdays, nor are defined company holidays.

StringGetLastWorkday

Example:sLastWorkday = GetLastWorkday OR sLastWorkday =

GetLastWorkday("1/1/2012")

Decrypts the password saved in the CVFW.ini file. If noparameter is passed, it assumes the current value of AppName.

StringGetPassword

Example:HTMLEditBox("Name=password").SetText

GetPassword()HTMLEditBox("Name=username").SetText

GetPassword(“MyApp”)

HTMLEditBox("Name=username").SetText GetPassword(“MyApp”,

2)

Returns a random number between the lower and upper valuespassed.

LongGetRandomNumber

Example:lMyNumber = GetRandomNumber (1, 10)

Returns the IP Address of the server the machine is using onthat port. The most useful application of this is for Citrix. It

StringGetServer




Function

stores the result in the CVTransactions(0).sServer. Ifthe result is not empty, it will be displayed in the lower rightcorner of the screen.Example:GetServer("1494")

This is useful when a script runs into several errors and it ishard to know what is running on the Agent. Call this function

NoneGetTaskList

in the UserOnAppError function, especially if an applicationerrors randomly. The result is placed in the log file stored inthe Enterprise Synthetic/Log folder. It is only stored ifthe logging level is set to 2.Example:Call GetTaskList

Returns the day of the week as a string.StringGetWeekDayExample:sDayOfWeek = GetWeekDay()

Determines if an image exists on a window. This is especiallyuseful when scripting Citrix applications. It can be used in

BooleanIsImage

the logout or close portions of a script, but is most valuablein an error handling routine.Example:If IsImage("Citrix Outlook MainWindow",

"Citrix_Outlook_Inbox") =

True Then...

Determines if an object exists. The object can be a control,link, window, etc..

BooleanIsObj

Example:If IsObj("InnerText=’Login’", Does_Exist) = True then...

Returns a Boolean value of True if the application is running.BooleanIsRunningExample:If IsRunning(“IEXPLORE.EXE”) = true then...

Determines if the window actually exists or is enabled.BooleanIsWindowExample:If IsWindow("Internet Explorer MainWindow", "Exists") =

True

then...

Terminates an application at the end of script execution if itis running. KillApp should be used with caution. While it

BooleanKillApp

closes an application, it may leave sessions open, which cancause issues on the next run. Sometimes it is also preferableto wait for an application to finish closing on its own.




Function

For example, SAP and Citrix will usually be removed frommemory up to 60 seconds after closing the last window. Withapplications such as this, useWaitUntilGone ("WFICA32.EXE", 60, True) to wait upto 60 seconds, then force the application to close. Be sure toadd the application to terminate using the AddToKillListfunction, otherwise the application may not terminate if itwas running before the script started.

CAUTIONIf possible, avoid killing IExplore.exe, because it is sointegrated with the operating system. Use the CloseIEfunction instead.

Example:KillApp ”Notepad.EXE”

Launches an application with no parameters.BooleanLaunchAppExample:LaunchApp "Notepad.exe"

Executes an application with a parameter. If a startingdirectory is passed, the Agent Recorder changes to thatdirectory first.

BooleanLaunchAppWithParm

Example:LaunchAppWithParm “Notepad.exe”, “c:\autoexec.bat”

Emulates the QARun attach command to make a stringlower case.

StringLower

Example:sRet = Lower(“This should be lower case”)

If configured properly, this sends a notification email to anaddress using the Enterprise Synthetic alerting mechanism.

BooleanMailIt

While sections already exist in the file, this is manually editedat this time.It is not intended to replace the Enterprise Synthetic alertingmechanism, however, in some cases it can provide moreprecision in defining certain conditions in which an alert issent.Example:MailIt("[email protected]", "Test Subject",

"[email protected]", "This is a message",

"smtp.MyCo.com", "c:\files\printscreenfile.jpg", "25")

Displays a popup window that appears to be a dialog box,but that disappears in a specified amount of time. Different

IntegerMsgboxWithTimeout




Function

buttons are allowed. It returns a value based on what buttonwas pressed.Example:iRet = MsgboxWithTimeout("This is an important message.

", 5, "This is a title", OKCancel, ExclamationMark)

Continues to type [Page Down] until it finds the desired textin a window. Returns true if found. Be sure that the keyboard

BooleanNavigateToTextInWindow

focus is in such a place that [Page Down] performs a pagedown on the screen. Text boxes typically are not goodcandidates. For best results in a web browser, click on somestatic text (not a hyperlink) before calling this function.Example:bRet = NavigateToTextInWindow "Internet Explorer

MainWindow", “Find this text”

Similar to the format function. This pads a string with leadingcharacters to make it a desired length.

StringPad

Example: MyString = Pad(str(1), "0", 3) ‘results in “001”

Especially useful if a specific value is needed from a set ofvalues that are contained within a single string.

StringParseAttributeValue

Example:sRet = ParseAttributeValue("Server=Vtgsrv,

Database=CVDB, UserID=interval", "Database") 'results

in "CVDB"

Makes a string camelCase, defined as a compound wordhaving one or more internal uppercase letters. This conventionis used in naming Framework functions.

StringProperCase

Example:sRet = ProperCase(“this should have the first letters

capitalized”)

Simplifies the error raising process. Instead of addingnumbers, source, etc., just use the text to show up in the errordescription.

NoneRaiseError

Example:RaiseError (“The event did not happen in 30 seconds”)

Calls Shutdown.exe with a 20 second pause. Optionally canset the registry with the ID and password and other settings

BooleanRebootRobot

required to log the Agent back in after reboot. The lastparameter clears the registry of the passwords.Examples:Call RebootRobot or

Call RebootRobot("Robot_Login", 2, True)




Function

Cleans up ghost icons in the system tray by moving the mouseover the system icons from left to right. Can be run to resetthe “no activity” clock to prohibit a screen saver from starting.

NoneRemoveGhostIcons

Example:Call RemoveGhostIcons


StringRobotName

Example:HTMLEditBox("Name=UserID").SetText RobotName

Determines if a screen saver is active. Returns true if it is.BooleanScreenSaverActiveExample:If ScreenSaverActive = True Then

Presses [Page Down] on a page until it finds the expectedtext.

BooleanScrollToText

Example: bFoundIt = ScrollToText ("Internet Explorer MainWindow",

"Item

#12345")

Sends an email to a designated email server. Uses the MailItfunction.

NoneSendEmail

Example:Call SendEmail(sSubject:=UserName & ":JDE Error",

sMessage:=sMessage,

sAttachment:=LocalPrintScreenFile)

Displays “where I am” and “what I am doing” messages onthe screen of the current script that is running and what eventsare being waited for.

NoneShowStatusBox

The True or False parameter of ShowStatusBox is used toturn on/off the print screen capability when a script is set toSelf Documentation mode. For more information, seeDocument the Script Steps [p. 47].Example:ShowStatusBox "Clicking on the 'Go' Button..."

Displays text from the foreground window along with screencoordinates of the text location on the screen.

NoneShowTextFromOCR

Pass in the Rectin parameter to limit the amount of text theOCR engine has to process and obtain the coordinates of thetext.ShowTxtFromOCR (oObject, Optional ByRef rSubRect

As TRectangle=vbEmpty

Waits for a specified number of seconds. It displays acountdown as it executes.

NoneSleepFor




Function

Example:SleepFor 2 or SleepFor 2, “To let the window refresh”

Takes a print screen of the desktop and saves it as[scriptname] on [date]@[time].jpg from MicrosoftPaint. A file name is an optional parameter if desired.

NoneTakePrintScreen

Example:TakePrintScreen (“C:\Screenshot.jpg”)

This is used in Release 9.x. only. It sends the keystroke[Ctrl+Alt+S] to the desktop to trigger the Snapdumpfeature.

NoneTakeSnapDump

Example:Call TakeSnapDump()

Simplifies the error raising process. Instead of addingnumbers, source, etc., just use the text in the error description.

NoneThrowError

Example:ThrowError(“The event did not happen in 30 seconds”)

Reads the CVFW.ini file to determine if the transaction shouldrun. This is designed to be used if there are individualblackout periods for a transaction.

BooleanTransCheckSchedule

Example:If TransCheckSchedule(”MyApp_Application”) = True then...

Emulates the QARun attach command to make a stringupper case.

StringUpper

Example:sRet = Upper(“This should be Upper case”)

Returns the ID of the user currently logged in.StringUserNameExample:HTMLEditBox("Name=UserID").SetText

UserNameHTMLEditBox("Name=username").SetText

GetID(“MyApp”)HTMLEditBox("Name=username").SetText

GetID(“MyApp”, 2)

Enterprise Synthetic FunctionsWhen using theEnterprise Synthetic functions, several timings are maintained, including waittimes. The log files in the Enterprise Synthetic \work directory can show timings of whathappened on the Agent at various times. Enterprise Synthetic supplies an API to start and stoptransactions. Using these functions alone may lead to some unexpected results, especially whena give-up occurred on the previous run. These functions use that API, but do several additionalsteps that help strengthen the integrity of the times and especially the trace files.



NOTEBy default, when calling these functions, spaces and illegal characters (such as / \ | * : ?)are replaced with underscores; colons (:) and single quotes (') are removed.


Function

The value of Agent Attribute 1 assigned by EnterpriseSynthetic to an Agent.

StringAgentAttribute1

Example:sValue = AgentAttribute1

The value of Agent Attribute 2 assigned by EnterpriseSynthetic to an Agent.

StringAgentAttribute2

Example:sValue = AgentAttribute2

Returns the value of where the Framework data is being stored.It may or may not be where the Enterprise Synthetic data isbeing stored.

StringCVShareDir

Example:sDir = CVShareDir

The folder in which Enterprise Synthetic places its workingfiles. It is also where the Framework places its log files.

StringCVWorkDir

Marks a transaction as unavailable. This is useful in errorhandling.

NothingMarkTransUnavailable

Performs a NotifyEvent. This is useful for nested timingswhere trace files are not necessary. It does not adjust the waittimes within transactions.

NothingStartTimer

Example:StartTimer ("ZZ-Google_Launch")

Starts both a Trace and a NotifyEvent from a script. Thetraces are automatically stopped when the script enters an

NothingStartTrace

error condition or when stopped with the StopTimerAndTracefunction. While the function StopTrace exists, it should notneed to be explicitly called. This sets the times for all WaitForfunctions within the transaction.Example:StartTrace ("ZZ-Google_Launch ")

Stops a timer via NotifyEvent. It important to use the samename as the StartTimer function.

NothingStopTimer

Example:StopTimer ("ZZ-Google_Launch")




Function

Calls StopTimer and StopTrace. It important to use the samename as the StartTrace command.

NothingStopTimerAndTrace

NOTEThe wait times for WaitFor functions return to the defaultvalue after this line is executed.

Example:StopTimerAndTrace ("ZZ-Google_Launch")

Do not use this function. It is designed to be called internally.NothingStopTrace

Script Initialization and Error HandlingFor specific error routines for Agent and Application Driver scripts and child scripts, the actualerror text appears at the top of the screen. The Agent then captures a screen print and saves itto the hard drive. It also creates a log of all errors from that Agent in a local text file.

NOTEMost of the following functions are called internally by the InitializeScript, EndScript,and HandleScriptErrors methods used in the template.

DescriptionReturn ValueFunction

Called by the Agent Driver script at the successfulconclusion.

nothingEndOfAgentDriver

Example:Call EndOfAgentDriver

Called at the successful run of an application.NothingEndOfAppDriverExample:Call EndOfAppDriver

Called at the successful run of a child script.NothingEndOfChildExample:Call EndOfChild

Suggested call by a script when exiting a subroutine thatuses the PassedParm variable. This executes a subset ofthe EndOfAppDriver routine.

NothingEndOfPassedParmApp

Example:Call EndOfPassedParmApp

Called by the Agent Driver script at the beginning of theAgent Driver script.

nothingInitAgentDriver




Example:InitAgentDriver Me.Name

Called when the Application Driver script is started.NothingInitAppDriverExample:InitAppDriver Me.Name

Called when a child script starts.NothingInitChildExample:InitChild Me.Name

Suggested call by a script when entering a subroutine thatuses the PassedParm property. This executes a subset ofthe InitAppDriver routine but does not take a parameter.

NothingInitPassedParmApp

Example:Call InitPassedParmApp

Called by the Agent Driver script when there is an error.nothingOnAgentDriverErrorExample:Call OnAgentDriverError

Error handling for Application Driver scripts.NothingOnAppDriverErrorExample:Call OnAppDriverError

Called when a child script goes into error handling.NothingOnChildScriptErrorExample:Call OnChildScriptError

Suggested call by a script when an error is encounteredwhile executing inside a subroutine that uses the

NothingOnPassedParmAppError

PassedParm property. This executes a subset of theOnAppDriverError routine.Be sure to include the On Error GoTo ErrorHandler atthe beginning of the routine. For examples of using thePassedParm routines, see the scriptZZ_Passed_Parm_Example_Driver.Example: Call OnPassedParmAppError

The contents of both the VB error and Agent Recorder errorobjects. Used by error handling.

StringScriptErrorText

User Expandability FunctionsEntry points are provided to enable specific functionality depending on the application orenvironment. These are provided in the module CVFW_User_Modifiable_Functions.



DescriptionReturn ValueFunctions

This is run after InventoryExes is run. It is added so userscan explicitly name an application to leave open when runningthe CleanUpDesktop function.

NothingUserAddCleanupExemption

This overrides any blackout period set by the CheckSchedulefunction (which is called by the InitAppDriver function). Use

BooleanUserCheckSchedule

it to implement your own blackout periods. It can also be usedto always run a script on the development Agent.

This is one way to log off Citrix sessions. It may or may notwork, depending on the environment.

NothingUserCitrixLogoff

This is a prototype that logs off the Citrix server that the Agentis connected to.

NothingUserCitrixLogoff

This is the first thing that is run when the CleanUpDesktop isrun. It is used in case an application needs to be exited gracefullyinstead of forcefully in CleanUpDesktop.

NothingUserCleanUpDesktop

This gives an example of how to close a Citrix session. It canbe used as is as long as the Citrix application can be forced toclose without repercussions.

NothingUserCloseCitrix

Calling the function IsImage or IsWindow can be useful todetermine where the application is.

This is a prototype meant to be a starting point to close openCitrix windows. It can be used in conjunction withUserCitrixLogoff.

NothingUserCloseCitrix

This is an optional value that is set in the moduleCVFW_User_Modifiable_Functions. It can be valuable to

StringUserDataBaseVersion

track which Agent is using what version of the scriptingdatabase.Example:sRet = UserDataBaseVersion

This is the first thing that is run when the EndOfAgentDriveris run.

NothingUserEndOfAgentDriver

This is the first thing that is run when the EndOfAppDriver isrun.

NothingUserEndOfAppDriver

This is the first thing that is run when the EndOfChild is run.NothingUserEndOfChild

This is called as the first thing that theHandleStandardIEPopups function calls. It enables customWhenever event handling before the default one executes.

NothingUserHandleIEPopups

This is the same as UserHandleIEPopups, except it is calledfrom HandleStandardJAVAPopups.

NothingUserHandleJAVAPopups

This is the first thing run when the Agent driver is invoked. Itis called by InitAgentDriver, and is only run once per run.

NothingUserInitAgentDriver




When scripting in a non-English Windows environment, thisfunction enables the support of a non-English Windowskeyboard layout.This function is set to English - US by default. You can onlyspecify one language for this function.Uncomment the single quote and specify the language inparenthesis.For example, when supporting the French language keyboardlayout:Call SetKeyBoard(French)

The supported keyboard layout languages are:

• English - US (default)

• French

• German

This is the first thing run when an application driver is invoked.It is called by InitAppDriver, and It is run every time an appis started.

NothingUserInitAppDriver

This is one of the first things run when the InitChild is run.Initializing of some variables precedes this call.

NothingUserInitChild

This is called when the Agent Driver script first goes into error.NothingUserOnAgentError

This is called when the application first goes into error.NothingUserOnAppError

Put your code here to handle error handling routines that arespecific to your needs. It is called by the OnChildScriptError

NothingUserOnChildError

This is used for handling errors without triggering the fullCleantUpDesktop routine.

NothingUserOnPassedParmTransError

This is used for doing things like taking a screen shot after asuccessful wait event. The value WaitCount might be valuable

NothingUserPostWait

at this point. That is the number of wait events used from thetime that application was initialized.

This allows customization of the action taken when a screensaver is found to be active. It can add transactions to show asunavailable.

NothingUserScreenSaverActive

Us this to define the keyboard if it does not have a defaultdefinition in the Framework. Current default languages are USEnglish, German, and French.

NothingUserSetKeyboard

This is called just before the Enterprise Synthetic timer startsby the "StartTimer function.

NothingUserStartTimer

This is called by the function StartTrace just before thetransaction trace begins.

NothingUserStartTrace




This is called just after the timer starts by the StopTimerfunction.

NothingUserStopTimer

This is called from StopTrace just after the A/V trace ends.NothingUserStopTrace

This allows third party screen shot tools to be used instead ofMicrosoft Paint to take screen shots.

BooleanUserTakePrintscreen

This is used if it is necessary to use a third party .zip program.If the return value is True, that tells the Framework that the.zip file was created.

BooleanUserZipFile

Path, File, and Registry FunctionsThis topic contains functions related to file handling.


Creates a registry key. Returns True if the key alreadyexisted, False if it was created.

BooleanCreateRegistryKey

Example:CreateRegistryKey HKEY_LOCAL_MACHINE,

"SOFTWARE\Compuware\test"

Deletes a file.BooleanDeleteFileExample:If DeleteFile (“c:\myfile.txt”) = false then

Deletes a registry key. It will not delete the key if it containssub keys.

BooleanDeleteRegistryKey

Example: DeleteRegistryKey HKEY_LOCAL_MACHINE,

"SOFTWARE\Compuware\test"

Determines if a drive is ready.BooleanDriveReadyExample:If DriveReady(“L:”) = True then

Returns True if the specified file exists and False if it doesnot.

BooleanFileExists

Example:If FileExists(“C:\boot.ini”) = false then

Removes a folder and its contents.BooleanFolderDeleteExample:FolderDelete "C:\files\"

Empties a folder of just the files (not subfolders).BooleanFolderDeleteFilesExample:FolderDeleteFiles "C:\files\"




Returns True if a folder exists and False if not.BooleanFolderExistsExample:If FolderExists(“C:\Program Files\”) = false then

Maps a network drive.BooleanMapNetworkDriveExample:MapNetworkDrive "L", \\PEServer\PEShare

Reads a value from an .ini file.StringReadIniExample:sRet = ReadIni(AppIniFile, "Global",

"ExtendedLogLevel", 0)

Gets the value from a registry key.StringRegReadExample: RegRead("HKEY_LOCAL_MACHINE\SOFTWARE\Compuware\

Enterprise Synthetic\CurrentVersion\InstallDir")

Updates the value in the registry.StringRegWriteExample:RegWrite( path, value,"Reg_SZ"

("HKEY_LOCAL_MACHINE\SOFTWARE\MyPath\Value,

"MyValue","Reg_SZ")

Replaces the original file with the new file.BooleanReplaceFileExample:ReplaceFile "\\MyServer\PEShare\Framework\MyFile.txt",

"C:\files\MyFile.txt"

Writes to the system log.BooleanSysLogExample:SysLog SysLog_Error, AppName & " error was:" &

ScriptErrorText

Disconnects a mapped network drive.BooleanUnMapNetworkDriveExample:UnMapNetworkDrive "L"

Writes a value to the .ini file. Creates the .ini file in theWindows directory if the passed file name does not exist.

NothingWriteIni

Example:WriteIni LocalLogFile, "App1", "Status", “Success”

Appends the passed text to a file.IntegerWriteLineExample:WriteLine (“c:\myfile.txt”, “append this text”)

Calls WriteLogSteps.NothingWriteLog

Writes out to the LocalLogfile. Possible values are:NothingWriteLogSteps




• 0: No logging

• 1: App start/stop, script start/stop and errors

• 2: Includes 0 and 1, plus wait events and file transfers

Example:Call WriteLogSteps(2, Space(8) & "This is text to be

logged”)

Zips a single file using native Windows compression.BooleanZipFileExample: ZipFile "C:\files\RawFile.txt", "C:\files\RawFile.zip"

Internet Explorer FunctionsThis topic contains functions related to monitoring applications running in an Internet Explorerbrowser.


Allows the script to clear specific attributes of InternetExplorer, such as cache, cookies, history, recent sites, or allof the above.

NothingClearIE

Example:Call ClearIE(IECache) or Call ClearIE(IEAll)

Navigates Internet Explorer to About:Blank if it exists. Ifit is not in memory, it launches Internet Explorer to a blankpage.

BooleanGoToBlank

Example:GoToBlank

Navigates Internet Explorer to the page that the firstparameter speficies. Optionally, it waits for Internet Explorer

BooleanGoToPage

to finish the navigation. To change the default behavior,make the second parameter equal to False.You may not want to wait for the navigation to finish if itrequires user input to finish, such as authentication. If youset the second parameter to False, it allows the script toenter user input.Example:GoToPage ("community.compuwareapm.com/")

Use as a Whenever function to handle standard InternetExplorer popups.

BooleanHandleStandardIEPopups

Example:Whenever "IE-PopupWindow"

Private Sub Script_Whenever(ByVal TheEvent As

TPEvents.TEventGroup)

If HandleStandardIEPopups(TheEvent.Name) = False




Then '[your code here because a nonstandard one

occurred]

End If

End Sub

Handles standard Java popups in Internet Explorer.BooleanHandleStandardJAVAPopupsExample:Whenever "IE-Java_PopupWindow"

Private Sub Script_Whenever(ByVal TheEvent As

TPEvents.TEventGroup)

If HandleStandardJAVAPopups(TheEvent.Name) = False

Then '[your code here because a nonstandard one

occurred]

End If

End Sub

Clears the cache or other items from Internet Explorer. Thefunction ClearIE may be preferable over this, because

NothingIEClear

ClearIE offers a drop-down list instead of knowing whattext to type in. This function requires the Microsoft ScriptingRuntime library in the Visual Basic References dialog box.Example:Call IEClear("Cache")

Launches Internet Explorer to a blank page.BooleanLaunchIEExample:LaunchIE

Launches Internet Explorer to a specified page.BooleanLaunchToPageExample:LaunchToPage ("community.compuwareapm.com/")

Clicks on typical logoff links, then closes Internet Explorer.It looks for strings such as Log Out, Log Off, Sign Off,and Sign Out.

NothingLogOutAndCloseIE

Example:Call LogOutAndCloseIE(False) ' (false leaves WebEx

windows open)

Framework PropertiesThe Framework contains a number of properties to define specific types of data used in thevarious Framework functions. Most Framework functions are used internally. This topic listsonly the available properties that you can use in scripts.

DescriptionReturn ValueProperty

Automatically populated. The name of the application thatis currently running. The variable is derived from the script

StringAppName

name. If the script is called ZZ_Google__Driver the__Driver is removed, leaving ZZ_Google as the AppName.



DescriptionReturn ValueProperty

When this is set to true, the script creates a combinationof .awl, .csv, .sql and .txt files, depending on the

BooleanDevMode

version of Enterprise Synthetic. These files are used forcreating transactions in Enterprise Synthetic. This value isset when the script is in Import mode.

Sets the number of seconds to wait for a given function.The value should not be set below 3.

IntegerJustInCaseWaitTime

The name of the local screen print file that was just created.This is useful if it is necessary to do something with a screenprint file that is not part of the default file handling process.

StringLocalPrintScreenFile

Enables the same script to create multiple transactionswithout having to re-code the application. The Framework

StringPassedParm

automatically appends the value to the timers and traces atruntime. For instance, if PassedParm is set to Server1 andthe script includes:StartTrace "MyApp_Launch"

The resulting transaction will be: MyApp_Launch_Server1_START

.

.

MyApp_Launch_Server1_STOP

The value forPassedParm is automatically reset to emptywhen the function EndOfAppDriver is called, usually atthe end of an Application Driver script.

Number of seconds for wait events to wait. This can be setat any time. The value remains until it is changed again.

IntegerWaitTime



A P P E N D I X C

Framework Functions Reference Grid


Tabl

e 6.

Initi

aliz

eScr

ipt F

unct

ions

Prod

uctio

n_A

pp_D

rive

rC

hild

_Scr

ipt

Age

nt_D

rive

rTa

sk

Cal

l InitAgentDriver

(If n

ot d

one

alre

ady)

Cal

l InitAppDriver

(if n

o ap

p is

set)

Initi

al st

ep

XX

XR

eset

err

or o

bjec

ts

XX

XA

bort

all r

unni

ng tr

aces

XVe

rifies

regi

stry

setti

ngs

XX

Turn

off

Kio

sk m

ode

XU

pdat

es lo

g fil

e .ini

ent

ries

XC

reat

e ne

w a

rray

of T

rans

actio

ns (u

sed

byEndAllTransactions

)

XIn

itial

ize

Envi

ronm

ent

XC

opy CVFW.ini

from

shar

ed fo

lder

(if sc

ript n

ame

does

not

end

with

_Driver

, set

s to

all u

pper

cas

e)Po

pula

te AppName

pro

perty

XC

heck

for b

lack

out (

also

cal

lUserCheckSchedule

)

XIn

vent

ory

runn

ing

apps

UserInitAppDriver

UserInitChild

UserInitAgentDriver

Cal

ls in

CVFW_User_Modifiable_Functions

App_[ScriptName]

Script_[script name]

StartTimer

for s

crip

t


Appendix C ∙ Framework Functions Reference Grid

Tabl

e 7.

End

Scrip

t (Su

cces

s) o

r Han

dleS

crip

tErr

ors (

Erro

r) F

unct

ions

Err

orSu

cces

sE

rror

Succ

ess

Err

orSu

cces

sTa

sk

XX

XC

aptu

re e

rror

text

XX

XD

ispl

ay e

rror

XX

XX

XX

Stop

(not

abo

rt) ru

nnin

g tra

ce

XX

Che

ck in

ID

On

first

err

orLo

g ta

sk li

st (o

n fir

st c

onse

cutiv

e er

ror)

Incr

emen

tR

eset

to 0

(if

high

er)

Set e

rror

cou

nt

XX

XTr

igge

rs A

gent

to ta

ke a

scre

en c

aptu

re

XPo

pula

te e

rror

text

on

runn

ing

and

confi

gure

d,bu

t uns

tarte

d tra

nsac

tions

)

XX

Ends

all

confi

gure

d tra

nsac

tions

(dis

play

s err

orte

xt a

nd tr

igge

rs sc

reen

shot

s, se

ts h

ealth

err

or)

UserOnAppError

UserEndOfAppDriver

UserOnChild

Erro

rUserEndOfChild

UserOnAgentError

UserEndOfAgent

Driv

erC

all C

VFW_User_Modifiable_Functions

XX

Stop

tim

er fo

r scr

ipt

Bas

ed o

n ru

les

On

first

succ

ess

Emai

l (A

gent

-initi

ated

onl

y, if

con

figur

ed)

XX

Res

et d

eskt

op e

nviro

nmen

t to

orig

inal

stat

us

XX

XX

CleanupDesktop

(cal

ls UserCleanupDesktop

)

Impo

rt m

ode

only

Expo

rt tra

nsac

tion

defin

ition

file

s

XX

XZi

p an

d co

py lo

g fil

e to

shar

ed fo

lder

XX

XSe

t Kio

sk m

ode



Tabl

e 8.

Sta

rtTim

er, S

tartT

race

, and

Add

Tran

sact

ion

Func

tions

Add

Tran

sact

ion

Star

tTra

ceSt

artT

imer

Task

XX

XAddTransaction

Verif

y tra

nsac

tion

nam

e, re

mov

e in

valid

char

acte

rs

App

end PassedParm

pro

perty

to e

nd o

ftra

nsac

tion

nam

e

Add

pre

fix to

tran

sact

ion

nam

e

Add

tran

sact

ion

to tr

ansa

ctio

n ar

ray

XX

Che

ck fo

r tra

nsac

tion

blac

kout

XA

bort

trace

XSe

t WaitTime

bas

ed o

n C

onso

le av

aila

bilit

y tim

e

Self

Doc

umen

tatio

n m

ode

only

Self

Doc

umen

tatio

n m

ode

scre

en sh

ot

UserStartTrace

UserStartTimer

Cal

l CVFW_User_Modifiable_Functions

1Ve

rify

if to

take

trac

e

XVe

rify

if to

take

bas

elin

e

XFireSyntheticStartScript

(sta

rts N

etw

ork

Pack

et C

aptu

re)

XX

StartTimer

(set

star

t tim

e in

arr

ay,

NotifyEvent [TransName]START

XStartTraceTimer

(pop

ulat

e TraceInProcess

varia

ble)

XSe

ts th

e Dyn

atra

ce A

pplic

atio

n M

onito

ring

Tim

erna

me

to th

e tra

nsac

tion

disp

laye

d in

the

Con

sole



Index

AAgent

33auto-login 33

Agents tab 29alerting 32auto-login 33

BBlackouts tab 29

Cchecklist

10, 79Framework installation 10Framework scripting 79

Configuration file25, 28–30

Agents tab 29Blackouts tab 29Email tab 29Global tab 25Holidays tab 29Integration tab 30Passwords tab 28UserDefined tab 30

configuring25

Framework 25

Ddatabase

10Framework 10

Deploying11, 19

Framework 11, 19

EEmail tab 29

FFAQs

63, 66, 73, 77Agent Recorder 63Citrix 73Enterprise Synthetic 66Internet Explorer 77

file functions 98Framework

5–6, 9–11, 17, 19, 25, 35, 38, 101assets 6benefits 5configuration file 25database 10deploying 11, 19installation checklist 10installing 9, 11non-English locale 25overview 5properties 101script template 38script types 35scripts 35upgrade 17upgrade checklist 17upgrade files 17

functions81, 85, 92, 94, 98

error handling 94file 98general scripting functions 85overview 81path 98registry 98script initialization 94script initialization and error handling 94


Index

functions (continued)Wait functions 81

Functions95, 100, 103

Internet Explorer 100reference grid 103user expandability 95

Ggeneral scripting functions 85Give-up script process 49Global tab 25

HHolidays tab 29

IInstallation checklist

10Framework 10

installing9, 11

Framework 9, 11Integration tab 30Internet Explorer functions 100

Ooperating system

95non-English locale 95

PPasswords tab 28path functions 98properties 101

Rregistry functions 98

Sscript and application synchronization 51

script initialization and error handling functions 94script template

38Framework 38

script types35

Framework 35scripting

79checklists 79

Scripting tips 55synchronization

51script and application 51

TThick client scripting tips 57Tips

55, 57–58Citrix 57creating a Citrix script 58Framework 55scripting 55thick client 57

Uunavailability script process 49upgrade

17Framework 17

Upgrade checklist17

Framework 17Upgrade files

17Framework 17

user expandability functions 95UserDefined tab 30

WWait functions 81Walkthrough

40–49overview 40


Index

Enterprise Synthetic Scripting Framework User Guide · 8 Enterprise Synthetic Scripting Framework...

Documents

Transcript of Enterprise Synthetic Scripting Framework User Guide · 8 Enterprise Synthetic Scripting Framework...