Documentation Home

Logging from Flash with the Flash Logging Library

Last updated July 24, 2013

Table of Contents

This page describes how to achieve logging of student-tutor interactions with Flash tutors.

1. Logging with CTAT Example-tracing Tutors

Flash logging parameter flow

Figure-1. The Flash logging process

Logging is natively supported with tutors built with the CTAT Flash components. To log data appropriate to your study, logging must be configured.

To log from a CTAT Flash tutor, the following items in the Flash logging workflow (shown in Figure-1) must be configured and tested:

  • Delivery application: a web application such as OLI or TutorShop that sequences and delivers the tutors in HTML. If not using a delivery application, use the CTAT publishing template.
  • Flashvars: You specify background data for logging using Flashvars, a standard mechanism for passing parameters to Flash movie in HTML. For example, you can specify the experimental condition.
  • Tutor: the CTAT tutor must have a CommShell component that is compatible with the logging library
  • Logging Library: the Flash Logging Library must be in an accessible place—either on the computer delivering the tutor or on a web server. Specify the location of the library with the LoggingLibraryPath flashvar or in the Logging Library property of the CommShell. You can use the hosted logging library at http://learnlab.web.cmu.edu/swf/CommLoggingLibrary.swf.
  • Log Server: a log server must exist and be configured properly to accept log messages. The PSLC log server is designed and maintained for this role. Alternatively, if you are using the Tutoring Service, you may be able to log to disk on the computer running the Tutoring Service. The PSLC log server URLS are:
    Testing: http://pslc-qa.andrew.cmu.edu/log/server
    Studies: http://learnlab.web.cmu.edu/log/server

1.1 Configure Flashvars

As shown in Figure-1 above, logging parameters are specified for a tutor via the FlashVars mechanism.

Flashvars are presented in HTML for the tutor to use, but your delivery environment may require that you specify them in another format. OLI, for example, requires that flashvars are specified in their XML format.

The CTAT_FlashPublish template is supplied to provide a starting point for making the HTML file, and the Flash IDE allows you to choose this template when publishing the tutor.

For more on how to specify flashvars and to see which parameters are required, see the CTAT flashvars reference page.

1.2 Configure CommShell

The CommShell component reads logging parameters from flashvars and makes calls to the logging library during tutoring.

Important: the CommShell version in the tutor must be compatible with the logging library version. If you do not use compatible versions, logging will not occur properly if at all.

Table 1. Logging compatibility
Tutor Message DTD
v2v4
CommShell2.0 or below2.1 or above
Logging Library1.0 or below2.0 or above

In Table 1 above, compatible versions are listed by column.

To find the version of CommShell in your tutor:

  1. Select CommShell on the stage.
  2. Set its Behavior Recorder Mode to AuthorTime in the Parameters tab of the properties panel. The version number should appear in the gray status bar at the top of the CommShell instance (see Figure 2).
    If no status bar appears, your CommShell is likely to be older than version 1.6.
  3. Alternatively, set CommShell's Include Traces parameter to 'true'; then test the movie. A version number trace will appear in the output panel for versions 2.1 and later.
CommShell version

Figure 2. CommShell version information

To find the version of the logging library in use:

  • Open CommLoggingLibrary.swf in the Flash player or web browser and right-click (Windows) or Ctrl+click (Mac) the blank movie. A context menu will appear (versions 2.1+) displaying the version number of the SWF and the DTD version to which it conforms. If no version information appears in the context menu, the version is likely to be 1.x or lower.
Logging library version

Figure 3. CommLoggingLibrary version information

If you need to upgrade CommShell in your tutor, complete the steps below.

To upgrade (or downgrade) the CommShell component in an interface:

  1. Install the desired CommComponents MXP (more detailed instructions).
  2. Opening your existing tutor FLA file
  3. Drag the new CommShell component onto the Flash stage. A "Resolve Component Conflict" prompt will appear.
  4. At the "Resolve Component Conflict" prompt, choose "Replace existing component" and press OK.
  5. Delete the extra CommShell that appeared on the stage.
  6. Repeat steps 2-5 for any other tutor interfaces you wish to modify.

1.3 Set up the logging library

The logging library sends appropriate log data to a logging server (such as the PSLC's) as directed by the Flash tutor.

The logging library, itself a SWF file, must be accessible by the tutor at the time of tutoring for log actions to be recorded. You can use the logging library in place on the LearnLab server (this is the version 2 SWF corresponding to DTD version 4), or you can download and copy the logging library to a location of your choice.

To use the hosted logging library:

  • Set the flashvars variable LoggingLibraryPath to: http://learnlab.web.cmu.edu/swf/CommLoggingLibrary.swf

To use the logging library locally or on your own web server:

  1. Download the logging library (FlashLoggingLibrary2.0.zip). This file is also included in the CTAT installation in the Flash subdirectory of your CTAT installation folder.
  2. Extract the logging library SWF (CommLoggingLibrary.swf), located in the /Installation subdirectory of the zip file, to a location where your tutor can access it.
  3. Modify FlashVars in your published HTML document to include values for two variables:
    • log_service_url: the URL of the logging service server; this is the URL to LearnLab's server by default
    • LoggingLibraryPath: the relative path from the HTML document to the logging library SWF, including the name of the logging library file. You may want to place the logging library SWF in its own directory. In this case, you would refer to the path and the file (e.g., webContent/CommLoggingLibrary.swf).
      Note that when running from a web environment such as the OLI online course delivery system, it is common practice to put the HTML (learning pages) inside one directory and the media files (e.g., .SWF, .GIF, etc.) inside another directory (e.g., WebContent). You should modify the path accordingly.

1.4 Test and troubleshoot logging

Important: You should test and verify that you are logging from your delivery environment, and that this data is accurate and expected.

For a complete discussion of testing and troubleshooting logging, see Troubleshooting logging from Flash tutors. Also, see CTAT FlashVars documentation for a description of all logging parameters.

2. Logging with educational tools built in Flash

CTAT provides the Flash Logging Library (download) for logging data from Flash educational applications that don't use the CTAT components. This library supports logging to the LearnLab logging servers:

  • Testing: http://pslc-qa.andrew.cmu.edu/log/server
  • Studies: http://learnlab.web.cmu.edu/log/server

The logging library comes in the form of a SWF file named CommLoggingLibrary.SWF. This library has a public API for sending logging messages. ActionScript calls to this API are necessary to invoke logging.

To log from an educational tool built with Flash:

  1. Download the logging library (FlashLoggingLibrary2.0.zip).
  2. Extract the logging library SWF (CommLoggingLibrary.swf)—located in the Installation subdirectory of the zip file—to a location where your SWF can access it.
  3. Include the CommLoggingLibrary in your Flash movie by using the MovieClipLoader() class: 
    // create a movie clip into which we'll load the library
_level0.createEmptyMovieClip("LoggingLibrary_mc", 999);
 
// Create a loader object.
var my_mcl:MovieClipLoader = new MovieClipLoader(); 
 
// Create an event listener object
var myListener:Object = new Object();
 
// In the following methods, the use of mx.utils.Delegate 
// overcomes a scoping problem with event handlers.
 
// call onLoadInit, author defined method, when the library has been
// initialized and is ready to use.
myListener.onLoadInit = mx.utils.Delegate.create(this, onLoadInit);
 
// call onLoadStart, author defined method, when loading starts.
// Useful for a pre-loader.
myListener.onLoadStart = mx.utils.Delegate.create(this, onLoadStart); 
 
// call onLoadError, author defined method, if an error occurs when
// loading the library.
myListener.onLoadError = mx.utils.Delegate.create(this, onLoadError); 
my_mcl.addListener(myListener);
 
// loads the clip
my_mcl.loadClip(LoggingLibraryPath, LoggingLibrary_mc);
  4. Log messages with the logging methods; this documentation is also located in the Documentation folder that comes with the logging library. The library includes several methods for logging.

Sample application for learning how to use the logging library

The CTAT Logging Library comes with a sample Flash application that implements logging with standard Macromedia components. This sample application is named SamplewithCommLoggingLibrary and can be found in the /Sample directory of the logging library ZIP, or the /Flash/Sample subdirectory of the CTAT installation. The ActionScript for this sample is available in Frame 1 of the sample file (.FLA).

View the ActionScript source code for the sample logging movie

A sample application for learning how to call the CTAT Logging Library.