Minor upgrades and bug fixes for WBT Manager 1.70.

Date: July 25, 2003

Version affected: v1.70.

Note: This document contains configuration instructions which are not present in the standard WBT Manager 1.70 documentation. Keep a copy of this document with your other WBT Manager documentation.

Contents:

This upgrade patch includes several minor upgrades and bug fixes to the WBT Manager Web Module.

Edit Certificate Program Status
(C2003070307 - Certificate program utilities)
In the current version of WBT Manager there is no interface that allows administrators to directly edit status for assigned Certificate Programs (status is set automatically when course statuses are updated). A full interface similar to the "Enter/Edit Results" function is planned for a future release. In the meantime, here are a few scripts that allow and adminstrative user to select a student and edit the status for any Certificate Programs they are assigned to.
Go here for details .
Scripting Interface to enroll students in Certificate Programs
(C2003070307 - Certificate program utilities)
There is currently no built-in self-enrollment mechanism for Certificate Programs. Here is a set of scripts that adds a Certificate Program enrollment function to the External Scripting Interface tools. It behaves in a manner similar to the course enrollment function.
Go here for details .
Disable specific navigation buttons
(C2003070304 - Allow nav buttons to be disabled)
We often get asked how to remove certain buttons from the WBT Manager navigation bar (most commonly the "Change Password" button). While it is not terribly difficult to do this by editing the navigation bar scripts we decided to add some control flags to do this for the non-programmers out there. This upgrade requires that the new versions of nav1.asp and nav1_old.asp be installed. If you have made changes to these files you will have to re-do your changes.
Go here for details .
Cross-Domain SCORM API work-around
(C2003070306 - Support cross-domain API work-around)
There is a well-known drawback to using the JavaScript API for lesson communication instead of AICC HACP. If the lesson content is not on the same web-site as the LMS, the lesson cannot communicate with the API. There is also a work-around that can be used under some conditions. We have made some modifications to support the work-around.
Go here for details .
Automatically create objective definitions for SCORM lessons
(M2003050101 - SCORM lessons must create objectives automatically)
Unlike the AICC specification the SCORM course interchange specification does not include a place to define objectives and associate them with lessons in the course being imported. This change allows the lesson communications interface to add objectives to a course "on the fly" for objective data sent through the SCORM API.
Go here for details .
Support SkillSoft Business Skills courseware
(C2003070301 - Support Skillsoft objectives_status format)
Several of SkillSoft's courseware lines require that the LMS support the objectives_status group of AICC data elements. We added support for objectives_status in WBT Manager version 1.70. However, SkillSoft's usage of this data group does not match our understanding of the AICC specification. The courseware lines using that data do not work properly with our standard interface. At the request of several clients and potential clients we have added an alternative version of our AICC interface which will work with the SkillSoft Business Skills line of courseware.
Go here for details .
Add context-sensitive help to web module
(C2003070305 - Support context sensitive help in web module)
This upgrade causes the on-line help system in the web module to open the help files to the page associated with the user's current page in WBT Manager. This upgrade requires that the new versions of nav1.asp and nav1_old.asp be installed. If you have made changes to these files you will have to re-do your changes.
Fix missing images referenced by navigation bar
(M2003060603 - Missing graphic files referenced by nav1.asp)
There are a number of button images associated with the navigation bar that are never displayed although they are referenced by code in nav1.asp. This results in 404 errors being logged (user never sees these). The missing files are included in this patch.
Improved menu display performance
(C2003070308 - Improve string processing performance in student and course menus)
We have modified the way that strings are concatenated for the student and course menus. This should provide a minor performance boost for heavily loaded sites.
Enhanced AICC interface debug logging
(C2003071001 - Enhance interface logging)
The AICC interface will now save a log entry if an error occurs during processing even if logging is not enabled for the affected student or lesson. Instead of a single log file individual log files will now be created for each day that an entry is logged (filename will contain date).
Use database transactional processing for interface stats updates
(C2003071002 - Add transaction processing to ExitAU)
Because of limitations with database drivers in the past, DBMS transactions were not used when updating student statistics with data sent through the lesson communications interface. This could result in incomplete data being stored in the student record. This was not a significant problem when the system stored only the lesson status for the most recent lesson attempt but with the advent of comments, tries, and objectives support it became more of a concern. We have added transactional control around the ExitAU function so that partial updates will not take place.
Missing objective status value sent from lesson causes SQL error in interface
(M2003070306 - Blank objective status causes SQL error in interface)
If a lesson sent an empty string to the interface as a status value for an objective then a SQL error would occur if MS Access were used as the database. This has been corrected
AICC API uses SCORM datatype for cmi.comments data element
(M2003071501 - AICC API using wrong data type for comments)
With SCORM 1.2 the definition for cmi.comments changed such that multiple calls to LMSSetValue on that data element result in the concatenation of latest value with the previous values. The AICC API specification still implies that the value will be overwritten. The release 1.7 version of the API uses the SCORM definition for both SCORM and AICC modes. This has been corrected.
GetCourseInfo utility function does not return course PrerequisiteScript property
(M2003071601 - GetCourseInfo() does not always retrieve the course's Prerequisite script)
If opdataPrerequisiteFlag is included in the options flag for a call the GetCourseInfo (see "Installation and Customization" manual for function documentation). The the course object(s) returned will have an empty string for PrerequisiteScript even if opdataPrerequisiteScript is specified. This has been corrected.

See the individual feature instructions below for any additional configuration requirements.

Feature Usage:

Edit Certificate Program Status

As mentioned above, there is no function in the current version of WBT Manager to manually edit Certificate Program results. As a work-around until such functions become available we have created some utility script that can be called by a system-level administrator. The scripts are:

fixcert.asp Allows a student to be selected by entering their login id.

fixcert2.asp Lists the students certificate program assignments and allows user to select one for edit.

fixcert3.asp Allows user to edit assignment date, status, and completion date for certificate program assignment.

Usage:

Log onto WBT Manager as a system administrator
Jump directly to fixcert.asp by entering
http://<yoursite>/<yourwbtmanagerdirectory>/asp/fixcert.asp
Enter a student's login id.
Select a certificate program.
Edit the the certificate properties as desired.

Notes:

This utility is currently available in English only (text is hard-coded in the scripts).
The utility directly edits the certificate program tables. It does not verify the data entered by the user against the status of the courses in the program (course statuses are displayed on the edit form). It is possible to set a program status to "complete" and create a certificate for the program even if the courses within the program are not all completed by the student.

Scripting Interface to enroll students in Certificate Programs

As mentioned above there is no mechanism to allow students to self-enroll in a certificate program in the current version of WBT Manager. We have added a script to the External Scripting Interface Kit to support enrollment in Certificate Programs. This script could be used to create a self-enrollment mechanism for Certificate Programs.

Script name: asp/enrollcertstud.asp
Include file: asp/enrollcertstud1.inc
Sample form: html/enrollcertstud.html

Purpose:

This script is used to enable storefront and other e-commerce applications to enroll students in certificate programs within WBT Manager. It may also be used to create custom self-enrollment mechanisms.

Parameters (must be POST parameters):

loginid

The student’s WBT Manager login ID.

programid

The program's WBT Manager internal ID number (class_id column from classes table).

silent

If set to "1" then the script will not redirect to one of the URLs listed below but instead will return a "text/plain" string containing a status code, followed on the next line by a status message. The status code/message combinations are:

0 "Successful"
1 "Student not found"
2 "The specified program is not valid."
3 "Student already enrolled"
4 "one or more course enrollments failed"
99 "Unexpected error" (may be replaced by a more specific message).

Note: If 99 is returned for the error code then the student may be partially enrolled in the program. The student's record should be examined to determine what corrective measures need to be taken.

Starting on the third line of the response will be a list of the courses contained in the program and the returned status from the attempt to enroll the student in each one. The format of each line is:

<status code>:<course name>

<status code> will contain the same numeric status as would be returned by the enrollstud.asp script for the same course and student. See the WBT Manager Installation and Customization manual for specific values.

The remaining parameters are Result Message Script URLs to which the script will redirect the user depending on the circumstance.

In each case the script will perform the re-direction by creating a page with a form which will automatically submit itself to the specified Result Message Script . A submit button will be included in case the form does not submit itself automatically.

The form will contain hidden fields duplicating the data originally submitted (excluding any fields named "submit"). Error fields errorcode and errortext will also be added containing the status information listed above.

successurl

The Result Message Script to redirect to if the student was enrolled in the certificate program successfully. Defaults to ../msgtemplates/enrollcertstudsuccess.asp.

successurlp

The Result Message Script to redirect to if the student was enrolled in the certificate program but one or more of the associated course enrollments failed. Defaults to ../msgtemplates/enrollcertstudsuccessp.asp.

nostudurl

The Result Message Script to redirect to if the student was not found in the WBT Manager database. Defaults to ../msgtemplates/enrollcdrtstudnostud.asp.

noprogurl

The URL to redirect to if the certificate program was not found in the WBT Manager database. Defaults to customizable file ../msgtemplates/enrollcertstudnoprog.asp.

enrolledurl

The Result Message Script to redirect to if the student was already enrolled in the certificate program. Defaults to ../msgtemplates/enrollcertstudenrolled.asp.

failedurl

The Result Message Script to redirect to if the student could not be enrolled in the certificate program due to an unexpected error. Defaults to ../msgtemplates/enrollcertstudfailed.asp.

An additional user customizable include file called enrollcertstud1.inc is included at the beginning of enrollcertstud.asp. This file can be used to perform additional validation of the request before the student is enrolled in the course. The supplied version of the file contains sample code that restricts the domains from which the script can be called.

By default, all access to the enrollcertstud.asp script is blocked. To enable it you must edit enrollcertstud1.inc and comment out the following code found near the top of the file.

'Response.Write "Function not enabled!"
'Response.End

Script operation:

The script identifies the student.

The WBT Manager database is searched for a student with the specified logonid. If the student is not found the following error is returned:

1 "Student not found"

The script identifies the certificate program.

The database is searched for a certificate program with an internal id number which matches the specified programid . If the certificate program is not found then the following error is returned:

2 "The specified program is not valid"

The script attempts to enroll the student in the certificate program .

The script will return the following error code if the student is already enrolled in the certificate program :

3 "Student already enrolled"

The script attempts to enroll the student in the courses contained within the certificate program. The status for each attempted enrollement is checked and if one or more course enrollments failed (where student was neither enrolled or added to a waiting list for the course) then the following primary error will be returned by the script:

4 "one or more course enrollments failed"

The user’s browser is redirected to a script based on the outcome of the operation or a "text/plain" page containing the status code and message (as described below) are returned.

Redirection mechanism:

In order allow the most flexibility in use the script does not perform an HTTP "redirect". Instead, the script produces an intermediate form that automatically submits itself to the desired Result Message Script. This form will contain hidden input fields holding all of the data that was originally submitted to the interface script (with the exception of any field named "submit"). In addition, hidden input fields called errorcode and errortext will be added to communicate the status of the request.

Using this mechanism allows the initiating form to pass any custom data fields through the interface script to the Result Message Script.

Disable specific navigation buttons

As mentioned above a number of WBT Manager Clients have requested that various buttons be removed from the navigation bar in the web module. This can be done by modifying nav1.asp and nav1_old.asp directly (these files are designated as user customizable files). We have added some control flags to the appsettings.ini file to allow the most common changes to be made without programming experience.

The following text should appear in the "[flags]" group in appsettings.ini (if it does not exist then add it):

;navbuttonmask removes specific buttons from the navigation bar.
; buttons are specified by adding
; the following codes together
;1 - Help Button (student)
;2 - Help Button (administrator)
;128 - Reports Button (student)
;256 - Reports Button (administrator)
;512 - Change PW Button (student)
;1024 - Change PW Button (administrator)
;8192 - Catalog Button (student)
navbuttonmask=0

Set navbuttonmask to the desired value (add the values for the buttons to be disabled) and run the reload.asp script.

Note: This feature requires that the new versions of nav1.asp and nav1_old.asp be loaded from the patch. If you have made customizations to those files you will need to re-do the customizations.

Cross-Domain SCORM API work-around

Under modern browsers (IE5+, NS6+), lessons which use the AICC/SCORM API cannot access the API functions when the lesson content is served from a different host than that on which the LMS resides. For example:

IF your LMS is at lms.yoursite.com/wbtmanager AND
you want to launch some content that resides at content.yoursite.com/courses (in order to distribute the server load perhaps) THEN
the content would experience a JavaScript "permission denied" error when it attempted to locate and call the API functions.

The reason this happens is that browsers protect the HTML and JavaScript components of an HTML page from access by a page from another host to prevent hacking. A discussion of this in regard to IE can be found at http://msdn.microsoft.com/library/default.asp?url=/workshop/author/om/xframe_scripting_security.asp.

The following work-around will allow you to put API content on a host different than the LMS site by telling the browser to the domain name when checking for cross-domain scripting instead of the full host name.

The work-around

The work-around is based on the document.domain property of the HTML DOM (Document Object Model). Both IE and NS allow client-side script code to modify this value from the full host name to the domain name (ie. from lms.yoursite.com to yoursite.com). By setting the domain property this way content on content.yoursite.com will be able to communicate with the API on lms.yoursite.com.

If your content is actually on a host in another domain (as in content.partnersite.com) then this work-around will not work unless you have the capability of mapping the content site to a host name within yourdomain.com by setting up the appropriate DNS mappings.

This work-around has been tested with NS4.5 and IE6 and works correctly. It does not work with NS6+ because of additional applet-level security in that browser. When running under NS6+ the selected lesson will fail to launch. The JavaScript and Java consoles will show an "OriginNotAllowedException". If we are able to identify a work-around for NS6+ we will post it on our "patches" site.

Setup

Because the cross-domain work-around has to be included in content files as well as the lms files (content that does not include the work-around will not operate with the LMS if the work-around is in place on the LMS) the code is controlled by a special menu style.

Start the WBT Manager Site Configuration Tool (utilities\site_configuration\wbtmconfig.exe) and connect to the database.
Select the Menu Styles tab
Click Add
Create a new menu style as below

Cross-Domain API Menu Style settings

crsmenu.asp parameters:

api=1 enables the SCORM API for the menu style.
apidebug=1 sets the API to "debug" mode (remove for production)
xdomainapi=1 sets the menu style to use the cross-domain api work-around.

Now set the course properties to the new menu style for all courses that reside in a different sub-domain.

Set course to new menu style

The menu style settings above will cause the course menu for the affected courses to execute the following code (or its equivalent) on each menu page that must reference the API.

//use crossdomain API work-around?
var sURL = new String(document.location);
sURL.toLowerCase();
if( sURL.indexOf("xdomainapi=1") > 0 )
{
//set to 2nd-level domain
if( document.domain != "undefined")
if( document.domain.indexOf('.') > 0 ) //must have a subdomain
document.domain = document.domain.substring(document.domain.indexOf('.')+1);
}

All content pages that reference the API, and any content pages that reference those pages, must contain the following script or its equivalent.

//use crossdomain API work-around?
//set to 2nd-level domain
if( document.domain != "undefined")
if( document.domain.indexOf('.') > 0 ) //must have a subdomain
document.domain = document.domain.substring(document.domain.indexOf('.')+1);

NOTES:

Once the above code has been added to the content then that content will no longer work with menu styles that do not set the xdomainapi flag. You also cannot mix cross-domain lessons with unmodified lessons in the same course even if the unmodified lessons reside on the same host as WBT Manager.

If the above constraints or the lack of support for NS6+ are an issue then your only standards based option is to use the AICC HACP communication protocol. In order to do this effectively from an HTML page you will need a signed Java Applet or ActiveX component (must be signed to communicate with a host other than the one containing the Applet or component itself). There is some discussion of this approach on the AICC forums at www.aicc.org/cgi-bin/yabb/YaBB.pl.

Automatically create objective definitions for SCORM lessons

As mentioned above the SCORM course structure interchange files do not include objectives definition or assignment information. Objectives can be manually created and associated with lessons in WBT Manager or a new setting can be used to create an objective the first time the interface receives data from the SCORM API for that objective. To enable this "autocreate objectives" feature add the following to the "[flags]" group in appsettings.ini if it does not already exist:

;autoaddscormobjectives controls whether objective records
;are created automatically and assigned
;to lessons when an unrecognized objective id is sent by a lesson.
; NOTE: auto add of objectives is currently supported only for
; lessons using the API in SCORM mode.
; setting this value to anything other than "Y" will
; disable auto add of objectives. Defaults to "N" if missing.
autoaddscormobjectives = N

Set autoaddscormobjectives to "Y" and run reload.asp to enable this feature.

Support SkillSoft Business Skills courseware

As mentioned above, SkillSoft Business Skills courseware requires a special interface to operate properly. Specifically, the [objectives_status] group in the AICC specification must be returned to each lesson exactly as it was sent the previous time the student was in that lesson. (The AICC specification allows for data to be resequenced. The SkillSoft courseware cannot deal with this).

We have added a special mode to our AICC interface to support this non-standard requirement. We call the mode "Echo Objectives" mode. "Echo Objectives" mode is enabled by the lesson calling aicc_int_c1.asp instead of aicc_int.asp to communicate with WBT Manager.

In the current version of WBT Manager (1.70) there is no way to specify a special AICC interface script for a specific lesson. This leaves 2 methods causing the special interface mode to be used.

Modify global.asa so that all lessons use the special interface mode

Open global.asa (in the WBT Manager virtual directory) in a text editor.
Search for "aicc_int.asp" and change it to "aicc_int_c1.asp".

The major drawback to this method is that it may cause courseware other than SkillSoft's that uses objectives to fail.

Create an HTML launch page for each SkillSoft lesson

Install the SkillSoft course and import the structure into WBT Manager
Edit the properties for each lesson in the course and note the URL on the "Startup" tab.
For each lesson:

Find the directory containing the lesson startup page.
Create a new HTML page (name it whatever you want) containing the code shown below (there is a file named wbtroot/courses/aicc_int_c1.html in this patch you can start with).
Modify the launch URL in the lesson's properties to point at the new page instead of the original SkillSoft launch page.

<html>
<head>
<title>WBT Manager - SkillSoft redirector</title>

<script language="javascript">

    //cause SkillSoft content to use custom WBT Manager interface
    //by modifying the AICC_URL parameter and then launching SkillSoft's start
    //page for the lesson.
    var strLessonPage = "comm0606b.htm";  //change this to match the SkillSoft launch page
    var strLoc = document.location + "";
    var i = strLoc.indexOf("?");
    var strParams="";

    //extract the launch parameters
    if( i > 0 )
    {
      strParams = strLoc.substring( i, strLoc.length );
    }

    //alert( strParams );

    //change the interface script from "aicc_int.asp" to "aicc_int_c1.asp"
    strParams = strParams.toLowerCase();
    strParams = strParams.replace( "aicc%5fint%2easp", "aicc%5fint%5fc1%2easp" );

    //alert( strParams );

    //jump to Skillsoft startup page
    //alert( strLessonPage + strParams );
    document.location = strLessonPage + strParams;
</script>

</head><body></body></html>

Version 1.7 Patches

fixcert.asp	Allows a student to be selected by entering their login id.
fixcert2.asp	Lists the students certificate program assignments and allows user to select one for edit.
fixcert3.asp	Allows user to edit assignment date, status, and completion date for certificate program assignment.

loginid	The student’s WBT Manager login ID.
programid	The program's WBT Manager internal ID number (class_id column from classes table).
silent	If set to "1" then the script will not redirect to one of the URLs listed below but instead will return a "text/plain" string containing a status code, followed on the next line by a status message. The status code/message combinations are: 0 "Successful" 1 "Student not found" 2 "The specified program is not valid." 3 "Student already enrolled" 4 "one or more course enrollments failed" 99 "Unexpected error" (may be replaced by a more specific message). Note: If 99 is returned for the error code then the student may be partially enrolled in the program. The student's record should be examined to determine what corrective measures need to be taken. Starting on the third line of the response will be a list of the courses contained in the program and the returned status from the attempt to enroll the student in each one. The format of each line is: <status code>:<course name> <status code> will contain the same numeric status as would be returned by the enrollstud.asp script for the same course and student. See the WBT Manager Installation and Customization manual for specific values.
The remaining parameters are Result Message Script URLs to which the script will redirect the user depending on the circumstance. In each case the script will perform the re-direction by creating a page with a form which will automatically submit itself to the specified Result Message Script . A submit button will be included in case the form does not submit itself automatically. The form will contain hidden fields duplicating the data originally submitted (excluding any fields named "submit"). Error fields errorcode and errortext will also be added containing the status information listed above.
successurl	The Result Message Script to redirect to if the student was enrolled in the certificate program successfully. Defaults to ../msgtemplates/enrollcertstudsuccess.asp.
successurlp	The Result Message Script to redirect to if the student was enrolled in the certificate program but one or more of the associated course enrollments failed. Defaults to ../msgtemplates/enrollcertstudsuccessp.asp.
nostudurl	The Result Message Script to redirect to if the student was not found in the WBT Manager database. Defaults to ../msgtemplates/enrollcdrtstudnostud.asp.
noprogurl	The URL to redirect to if the certificate program was not found in the WBT Manager database. Defaults to customizable file ../msgtemplates/enrollcertstudnoprog.asp.
enrolledurl	The Result Message Script to redirect to if the student was already enrolled in the certificate program. Defaults to ../msgtemplates/enrollcertstudenrolled.asp.
failedurl	The Result Message Script to redirect to if the student could not be enrolled in the certificate program due to an unexpected error. Defaults to ../msgtemplates/enrollcertstudfailed.asp.