Creating a recording agent

You can use the classes in the customagent_src.zip file to create a custom agent that records metrics data as a user interacts with an application. For information about creating an agent that records and plays back user interactions, see Creating a replaying agent.

The custom agent in the customagent_src.zip file is the CustomAdapter class. This class calls an HTTPService that writes event data out to a database.

Supporting classes for the CustomAdapter class include:

CustomEnvironment class that implements IAutomationEnvironment
CustomAutomationClass that implements IAutomationClass
CustomAutomationEventDescriptor class
CustomAutomationMethodDescriptor class
CustomAutomationPropertyDescriptor class

In addition to these classes, the ZIP file also includes the environment XML file and a utility class that parses that file.

You can also access a RemoteObject from the custom agent that provides user session information. To simplify, this example writes the data out to a trace log rather than to a database.

Using the CustomAdapter class

Follow the step-by-step instructions in this section to create a Flex application that records automation events by using the CustomAdapter class and its supporting files.

You cannot use this custom agent with agents that use different environment information, such as the QTP agent included in the Flex automation feature. So, if you use the agent in this example, do not use QTP to record scripts.

Set up your Flex installation

Before you can create an application that uses the automation API to record automatable events, you must do the following:

Make sure that you are running Flex Builder Professional.
Extract all the files in the customagent_src.zip file to a directory; for example, c:/myfiles/flex3/agent. This file contains the agent and helper classes in the custom.* package. It also includes MySQL and PHP code that you can use to connect your Flex application to a database.
Save the AutomationGenericEnv.xml file at the top level directory where you will put the Flex application. In this case, store it in c:/myfiles/flex3/agent.

After you set up your environment, you can edit the CustomAdapter class to record an interaction with a Flex application.

Edit the CustomAdapter class

The CustomAdapter class handles the RECORD events in the recordHandler() method. The RECORD event has the following properties:

name -- The agent's name of the event that triggered the call to the agent; for example, Click. This is the name as it is defined in the agent's environment.
replayableEvent -- The event that triggered the call to the agent.
automationObject -- The control that triggered the replayableEvent; for example, if the user clicked a button, this property contains a reference to the Button control. You can access the automationObject property by casting it to an IAutomationObject. You can then access properties of that object, such as a Button label property, by using the AutomationManager getProperties() method, as the following example shows:
```
var obj:IAutomationObject = event.automationObject;
var label:String = automationManager.getProperties(obj, ["label"])[0];
```
args -- Additional information about the event, such as the text entered in a TextInput control or whether the Alt key was held down during a mouse click. You can view all of the arguments by using code similar to the following:
```
for (var i:int = 0; i<event.args.length; i++) {
    trace("event.args[" + i + "]: " + event.args[i]);
}
```

The default version of the CustomAdapter recordHandler() method contains code that writes event information to a database. Follow the steps in this section to simplify that method so that you can run the example without configuring a database. After executing these steps, you can go back and create a database and revert the CustomAdapter class's recordHandler() method.

Simplify the CustomAdapter example

Open the CustomAdapter.as file.

Edit the recordHandler() method. Comment out the service access and replace it with trace statements; for example:

trace("automation name:" + obj.automationName);
trace("event name:" + event.name);
trace("replayable event:" + event.replayableEvent);
trace("event target:" + event.target);
// Arguments to be sent are '#' separated.
var arguments:String = event.args.join("#");
trace("args:" + arguments);

// Show all event args.
for (var i:int = 0; i<event.args.length; i++) {
    trace("event.args[" + i + "]: " + event.args[i]);
}
trace("------------------------");

You can later add the database support by uncommenting the service methods.

Edit the constructor. Add a trace() method such as the following:
```
trace("in CustomAdapter constructor") 
```
This ensures that the custom agent is being instantiated when the application starts up.

Compile the custom agent's SWC file. To do this, you use the compc utility and include the classes in the custom package, as the following example shows:

compc -source-path+=c:/myfiles/flex3/agent -include-classes
    custom.CustomAdapter custom.CustomAutomationClass
    custom.CustomAutomationEventDescriptor
    custom.CustomAutomationMethodDescriptor
    custom.CustomAutomationPropertyDescriptor
    custom.CustomEnvironment
    custom.utilities.EnvXMLParser 
    -library-path+=c:/home/dev/depot/flex/sdk/frameworks/libs
    -output=c:/myfiles/flex3/agent/CustomAgent.swc

This creates the CustomAgent.swc file in the c:/myfiles/flex3/agent directory.

Create and run the Flex application

When you use automation with Flex, you must create a Flex application and supporting wrapper files.

Create Main.mxml and store it in the same directory as the CustomAgent.swc file (for example, c:/myfiles/flex3/agent), as the following sample MXML file shows:

<?xml version="1.0"?>
<!-- agent/Main.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" height="100%" width="100%">
    <mx:Script><![CDATA[
        private function changeLabel(newLabel:String):void {
            b1.label = newLabel;
        }        
    ]]></mx:Script>
    <mx:TextInput id="ti1" text=""/>
    <mx:Button id="b1" label="Change Label" click="changeLabel(ti1.text)" />
</mx:Application>

Compile the Flex application. You must include the CustomAgent.swc file as a library, as the following example shows:
```
mxmlc -include-libraries+=c:/myfiles/flex3/agent/CustomAgent.swc        c:/myfiles/flex3/agent/Main.mxml
```
This creates Main.swf in the c:/myfiles/flex3/agent directory.
Flex Builder creates an HTML wrapper for you. If you use the command-line compiler, you must create one manually. In the wrapper, you request the SWF file; if you try to run the SWF file directly, file security errors prevent you from loading the environment XML file. The following example wrapper loads the mysource.js file:
```
<html><body>
<script src="mysource.js"></script>
</body></html>
```

Create a JavaScript file that defines the <OBJECT> and <EMBED> tags that embed your Flex application's SWF file. For example:

document.write("<object id='tempId' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'  height='100%' width='100%'>");
document.write("<param name='src' value='Main.swf'/>");
document.write("<embed name='Main' src='Main.swf' height='100%' width='100%'/>");
document.write("</object>");

Copy the application SWF, wrapper, JavaScript, and environment XML files to a web server. The web server's directory now contains:
- Main.swf
- index-simple.html
- mysource.js
- AutomationGenericEnv.xml
The XML file is loaded at run time, so it must accessible by the SWF file on the web server.
Request the html wrapper from the web server; for example:
```
http://localhost:8100/flex/agent/index-simple.html
```

Run the application and change the name of the label to 42. The trace log should contain something like the following:

in CustomAdapter constructor
automation name:ti1
event name:SelectText
event target:[object AutomationManager]
args:0#0
event.args[0]: 0
event.args[1]: 0
------------------------
automation name:ti1
event name:Input
event target:[object AutomationManager]
args:42
event.args[0]: 42
------------------------
automation name:Change Label
event name:Click
event target:[object AutomationManager]
args:
------------------------

Adobe Flex 3 Help

Creating a recording agent

Using the CustomAdapter class