WBT Manager External Script Interface Kit
Version 1.5 - Aug 2000
(for WBT Manager 1.5)
Overview of the External Script Interface Kit
The WBT Manager External Script Interface Kit is a set of ASP scripts and server-side components that allow users to integrate WBT Manager with their e-commerce storefronts. The interface supports verifying the existence of a student, adding a new student, enrolling a student in a course, and allowing students to request an email of forgotten passwords.
The kit can also be used to create self-registration forms (sample provided) to allow students to add themselves to the WBT Manager database.
Kit components
Installation
Checking for existing students
Adding a student
Enrolling a student in a course
Emailing forgotten passwords
Customizing the sample files
Adding self-registration IDs
NOTE: This version is compatible with WBT Manager 1.5. If you are still using version 1.3 of WBT Manager you will need to obtain and install version 1 of the External Script Interface Kit from www.ielearning.com.
The WBT Manager External Script Interface Kit consists of three principal ASP scripts, an additional server-side component, and a set of user customizable forms and message scripts.
|
Principal Scripts |
These scripts reside in the "asp" directory. |
|
verstud.asp |
Called to check whether a student already exists in the WBT Manager database. An external web application (such as a storefront) could ask the customer to enter their student login ID and password and verify that the student record exists before attempting to enroll the student in a course. |
|
regstud.asp |
Called to add a student to the WBT Manager database. A storefront could collect the student’s information as part of the on-line purchase process and then create the customer’s student account in WBT Manager automatically. A stand-alone form can also be used to allow self-registration (sample provided). |
|
enrollstud.asp |
Called to enroll a student in a course. After purchase approval a storefront can call this script to add the student to the purchased course. |
| emailpw.asp | Called to email a studen or administrator their login id and password. |
|
Customizable Include Files |
These include files reside in the "asp" directory |
|
regstud.inc |
This script is included in the regstud.asp script just before the function that adds the student. It can be used to provide additional error checking of logging of add requests. The supplied file contains a sample script that restricts calls to regstud.asp to forms and scripts on the WBT Manager site. |
|
enrollstud1.inc |
This script is included in the enrollstud.asp script just before the function that enrolls the student. It can be used to provide additional error checking of logging of requests. The supplied file contains a sample script that restricts calls to enrollstud.asp to forms and scripts on the WBT Manager site. |
| emailpw.inc | This script is included in the emailpw.asp script at the point that the email is to be sent. Customize this this script to change the contents of the email message. |
|
Customizable Result Message Scripts |
These scripts reside in the "msgtemplates" directory. |
|
verstuderror.asp |
verstud.asp will redirect the client’s browser to one of these scripts based upon the outcome of the script. Note: The URLs to these scripts can be overridden in call to verstud.asp. These scripts are ignored if verstud.asp is called in "silent" mode*. |
|
regstuddupemail.asp |
regstud.asp will redirect the client’s browser to one of these scripts based upon the outcome of the script. Note: The URLs to these scripts can be overridden in call to regstud.asp. These scripts are ignored if regstud.asp is called in "silent" mode*. |
|
enrollstudenrolled.asp |
enrollstud.asp will redirect the client’s browser to one of these scripts based upon the outcome of the script. Note: The URLs to these scripts can be overridden in call to enrollstud.asp. These scripts are ignored if enrollstud.asp is called in "silent" mode*. |
| emailpwok.asp emailpwnf.asp emailpwer.asp |
emailpw.asp will redirect the client’s browser to one of these scripts based upon the outcome of the script. Note: The URLs to these scripts can be overridden in call to emailpw.asp. |
|
Customizable Forms |
These forms reside in the "html" directory. |
|
verstud.html |
A sample form with input fields for Login ID and Password. Provided as an example of how to call verstud.asp. |
|
regstud.html |
A sample form with input fields for student registration data. Provided as an example of how to call regstud.asp. Can also be used as the starting point of a self-registration function. |
|
enrollstud.html |
A sample form with input fields for student Login ID and Course Code. Provided as an example of how to call enrollstud.asp. |
| emailpw.html | A sample for with input fields for Login ID or Email Address. Provided as an example of how to call emailpw.asp. |
* "silent" mode – When an interface script is called in silent mode it does not redirect on completion. Instead it returns a "text/plain" page in which the first line is a status code and the second line is a status message. This mode is useful when calling the interface scripts from within other scripts (such as the fulfillment script of a storefront site).
home
important note for Oracle users
The WBT Manager External Script Interface Kit is included in WBT Manager 1.5 and will be installed with the Web Server Application.
The following installed files will not be overwritten by future releases and can be customized.
asp/enrollstud1.inc
asp/regstud.inc
asp/emailpw.inc
html/verstud.html
html/regstud.html
html/enrollstud.html
html/emailpw.html
msgtemplates/verstudfound.asp
msgtemplates/verstudmissing.asp
msgtemplates/verstuderror.asp
msgtemplates/regstudsuccess.asp
msgtemplates/regstudmodlogin.asp
msgtemplates/regstudfailed.asp
msgtemplates/regstudduprefid.asp
msgtemplates/regstudduplogin.asp
msgtemplates/regstuddupemail.asp
msgtemplates/enrollstudsuccess.asp
msgtemplates/enrollstudnostud.asp
msgtemplates/enrollstudnocrs.asp
msgtemplates/enrollstudfailed.asp
msgtemplates/enrollstudenrolled.asp
msgtemplates/emailpwok.asp
msgtemplates/emailpwnf.asp
msgtemplates/emailpwer.asp
Script name: verstud.asp
NOTE: This function is unchanged from version 1
Purpose:
This script is called to verify that a student exists in the WBT Manager database.
Parameters (must be POST parameters):
|
loginid |
The student’s WBT Manager Login ID (required, minimum 4 char.). |
|
password |
The student’s WBT Manager password (required, minimum 4 char.). |
|
silent |
If set to "a1" then the script will not redirect to a Result Message Script (see below). Instead the script will return a "text/plain" page containing a status code, followed on the next line by a status message. The valid code/message combinations are:
|
|
The remaining parameters are Result Message Script URLs to which the script will redirect the user depending on the outcome of the request. 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 URL. 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 field named "submit"). Status fields errorcode and errortext will also be added containing the status information listed above. |
|
|
foundurl |
The Result Message Script to redirect to if the specified loginid and password identify an existing student in the database. Defaults to ../msgtemplates/verstudfound.asp. |
|
newurl |
The Result Message Script to redirect to if the specified loginid and password do not identify an existing student in the database. Note: The specified Login ID may be in use by a student with a different password. Defaults to ../msgtemplates/verstudmissing.asp. |
|
errorurl |
The Result Message Script to redirect to if an unexpected error occurs during processing. Defaults to ../msgtemplates/verstuderror.asp. |
Operation:
The script connects to the WBT Manager database and searches the STUDENTS table for the specified loginid and password.
If a student is found then:
If silent is equal to "1" a "text/plain" page will be returned containing
0<crlf>
foundIf silent is not equal to "1" the script will redirect (as described below) the user’s browser to the Result Message Script specified by the foundurl parameter.
If a student is not found then:
If silent is equal to "1" a "text/plain" page will be returned containing
1<crlf>
missingIf silent is not equal to "1" the script will redirect (as described below) the user’s browser to the Result Message Script specified by the newurl parameter.
If an error occurs then:
If silent is equal to "1" a "text/plain" page will be returned containing
<crlf>99
Unexpected error occurred
If silent is not equal to "1" the script will redirect (as described below) the user’s browser to the Result Message Script specified by the errorurl parameter.
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.
Script name: regstud.asp
NOTE: This function has a new parameter (dname) that was not supported in version 1. Also, WBT Manager 1.5 supports 2 different name formats. The format used will depend on the database configuration set with the site configuration utility.
Purpose:
This script is used to add a new student to the WBT Manager database.
Parameters (must be POST parameters):
|
dcode |
Department self-registration code. A code that uniquely identifies the department into which the student is to be added. See below for behavior if omitted. |
dname |
Department name to place the new student in. If ocode is specified and dcode is ommitted, then a text string in this parameter will specify the name of the department within the organization to which the student is to be added. If no matching department is found then a new one will be added. Under some DBMSs this value is case-sensitive. |
|
ocode |
Organization self-registration code. A code that uniquely identifies the organization into which the student is to be added (ignored if dcode is provided). See below for behavior if omitted. |
|
fname |
The student’s first name (at least one of the name fields must be present). |
|
lname |
The student’s last name (at least one of the name fields must be present). |
|
mname |
The student’s middle name or initial (at least one of the name fields must be present). |
|
sname |
The student’s name suffix (PhD, MD, Jr, etc) (at least one of the name fields must be present). |
|
refid |
An external "Reference ID" which uniquely identifies the student. Typically used to link a student with records in another system such as a HR system. If used, this field must contain a value that is unique to the student throughout the WBT Manager database. If an attempt is made to add a student with an existing refid then an error will occur (see below). |
|
logonid |
The login id to be used to identify the student in WBT Manager (required, minimum 4 char.). The value of this field is required to be unique in the WBT Manager database. If an attempt is made to add a student with an existing login id then the new login id will be modified to make it unique unless warndupl is equal to "1". An ID is made unique by appending a random number. |
|
password |
The password that the student will use to log onto WBT Manager (required, minimum 4 char.). |
|
|
The student’s email address. If warndupe is set to "1" then an attempt to add a student with an email address already in use by another student will result in an error (see below). |
|
text1-text10 |
User defined text fields (maximum 255 char.). These fields may be used as desired. |
|
warndupl |
If this field is set to "1" then the script will issue a warning instead of creating a student record when a matching logonid already exists in the WBT Manager database. Otherwise the script will modify the logonid as described above. |
|
warndupe |
If this field is set to "1" then the script will issue a warning instead of creating a student record when a matching e-mail address already exists in the WBT Manager database. Otherwise the new student record will be added with the specified email address even if it is in use by another student. |
|
silent |
If set to "1" then the script will not redirect to a Result Message Script (see below). Instead the script will return a "text/plain" page containing a status code, followed on the next line by a status message, followed on the next by the loginid actually used if the student is successfully added. The valid code/message combinations are:
|
|
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") with the addition of a new field logonused that will contain the actual logon id that the student was given (in case the logon id had to be changed to make it unique. 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 added successfully. Defaults to ../msgtemplates/regstudsuccess.asp. |
|
modlurl |
The Result Message Script to redirect to if the student was added successfully but their login id was modified. Defaults to ../msgtemplates/regstudmodlogin.asp. |
|
duplurl |
The Result Message Script to redirect to if "warndupl" is set to "1" and a student with the requested logon_id already exists in the WBT Manager database. Defaults to ../msgtemplates/regstudduplogin.asp. |
|
duprurl |
The Result Message Script to redirect to if student with the requested refid already exists in the WBT Manager database. Defaults to ../msgtemplates/regstudduprefid.asp. |
|
dupeurl |
The Result Message Script to redirect to if "warndupe" is set to "1" and a student with the requested e-mail address already exists in the WBT Manager database. Defaults to ../msgtemplates/regstuddupemail.asp. |
|
failurl |
The Result Message Script to redirect to if an unexpected error occurs. Defaults to ../msgtemplates/regstudfailed.asp. |
An additional user customizable include file called regstud.inc is included at the beginning of regstud.asp. This file can be used to perform additional validation of the request before the student is added to the database. The supplied version of the file contains sample code that restricts the domains from which the script can be called.
Operation:
The name fields must not be empty. Individual fields can be empty but not all of the name fields. Total length of the name when it is formatted must not be more than 255 characters. This field can generate the following errors:
7 "Input string too long"
11 "Student name is required"The logonid field must contain at least 4 characters and no more than 255 characters. It must contain no embedded blanks. This field can generate the following errors:
7 "Input string too long"
8 "Logon ID is too short or contains blank"The password field must contain at least 4 characters and no more than 12 characters. This field can generate the following errors:
9 "Password is too short"
10 "Password is too long"The email and text1-text10 fields must contain no more than 255 characters. These fields can generate the following error:
7 "Input string too long"
The final name will be either lname<sp>sname,fname<sp>mname or
fname<sp>mname<sp>lname<sp>sname depending on the name format
setting in the database.
If the desired email address is already assigned to another student and warndupe is equal to "1" then the following error will be returned:
3 "Duplicate e-mail address"
If the desired email address is in use and warndupe is not equal to "1" then the student will be added with the specified email address even though it is used by another student.
If another student is found that is already assigned the specified refid (Reference ID) then the following error will be returned:
2 "Duplicate Reference ID"
If a student already exists with that logonid and warndupl is equal to "1" then the following error will be returned:
1 "Duplicate Logon ID"
If a student already exists and warndupl is not equal to "1" then a unique logonid will be created by appending a random number to the specified logonid.
If dcode was specified in the request then the WBT Manager database is searched for a department with a matching value in the "Registration ID" property. If no matching department is found then the following error will be returned:
4 "Invalid Department registration code"
If dcode was not specified and ocode was then the database is searched for an organization with a matching value in the "Registration ID" property. If no matching organization is found then the following error will be returned:
5 "Invalid Organization registration code"
If the organization is found using ocode then the student is added to that organization to a department named as the year and month the registration occurred (yyyy-mm). This department will be created if necessary.
If neither dcode nor ocode were specified then the student is added to the organization with an internal id of "2" (initialized to "Self-registered students" by database installation scripts). The department used will have a name containing the year and month the registration occurred (yyyy-mm). This department will be created if necessary.
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 logonused, 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.
Script name: enrollstud.asp
NOTE: The behavior of this function has changed slightly from version 1. It is now possible to specify more than one course to enroll the student in.
Purpose:
This script is used to enable storefront and other e-commerce applications to enroll students in courses within WBT Manager. It may also be used to create custom self-enrollment mechanisms.
Important note: enrollstud.asp is dependent on the "Provider’s Course Name" to identify the course if your courseware supplier did not supply a value for this property then use the System Administrator module to apply one ("Provider" tab on the course properties sheet).
Parameters (must be POST parameters):
|
logonid |
The student’s WBT Manager logon ID. |
|
coursecode |
The course’s "Provider’s Course Name" as entered and displayed in the WBT Manager System Administrator Module. This parameter may be repeated to enroll the student in multiple courses in a single request. |
|
cutoffdt |
A date after which the student will no longer be able to enter the course (yyyy-mmm-dd format). |
|
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:
|
|
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 course successfully. Defaults to ../msgtemplates/enrollstudsuccess.asp. |
|
nostudurl |
The Result Message Script to redirect to if the student was not found in the WBT Manager database. Defaults to ../msgtemplates/enrollstudnostud.asp. |
|
nocrsurl |
The URL to redirect to if the course was not found in the WBT Manager database. Defaults to customizable file ../msgtemplates/enrollstudnocrs.asp. |
|
enrolledurl |
The Result Message Script to redirect to if the student was already enrolled in the course. Defaults to ../msgtemplates/enrollstudenrolled.asp. |
|
failedurl |
The Result Message Script to redirect to if the student could not be enrolled in the course due to an unexpected error. Defaults to ../msgtemplates/enrollstudfailed.asp. |
An additional user customizable include file called enrollstud1.inc is included at the beginning of enrollstud.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.
Script operation:
logonid and coursecode must not be empty. cutoffdt must be empty or must contain a valid date (format yyyy-mmm-dd is preferred because it is not susceptible to date regional format problems). These fields can generate the following errors:
4 "Missing required parameters"
5 "Invalid date format"
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 database is searched for a course with a "Provider’s Course Name" which matches the specified coursecode (under some database systems this search is case-sensitive). If the course is not found then the following error is returned:
2 "Course not found"
If more than one instance of coursecode exists then each course will be processed in turn. Any "Course not Found" error encountered will halt the processing of the list of courses and return this error code.
The script will return the following error code if the student is already enrolled in the course:
3 "Student already enrolled"
This error code is ignored until the last course if more than one coursecode is specified.
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.
Script name: emailpw.asp
NOTE: This function is new in version 1.5
Purpose:
This script is called to email a student's login information to their email address.
NOTE: Requires Microsoft SMTP Service to be installed and running on web server. You must also modify the emailpw.inc
file to specify a valid domain in the from address field of the
email.
Parameters (may be either GET or POST parameters):
|
loginid |
The student’s WBT Manager Login ID. |
|
|
The student’s WBT Manager email address. Note: This may be case-sensitive in some databases. Either loginid or email must be specified. |
|
admin |
If this parameter contains any value then the administrator table will be searched rather than the student table |
|
The remaining parameters are Result Message Script URLs to which the script will redirect the user depending on the outcome of the request. 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 URL. 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 field named "submit"). Status fields errorcode and errortext will also be added containing the status information listed above. |
|
|
successurl |
The Result Message Script to redirect to if the login information is successfully emailed. Defaults to ../msgtemplates/emailpwok.asp. |
|
notfoundurl |
The Result Message Script to redirect to if the specified loginid or email address do not identify an existing student in the database. Defaults to ../msgtemplates/emailpwnf.asp. |
|
errorurl |
The Result Message Script to redirect to if an unexpected error occurs during processing. Defaults to ../msgtemplates/emailpwer.asp. |
Operation:
If both are missing then the script redirects to the result message script specified by errorurl (as described below) and passes the following error:
code = 4
text = "Missing required parameter"
If no record is found then the script redirects to the result message script specified by notfounurl and passes the following error:
code = 1
text = "Student not found" or "Administrator not found"
If no email address exists then the script redirects to the result message script specified by notfounurl and passes the following error:
code = 2
text = "Login has no associated email address"
code = 99
text = error specific text
If the email is sent successfully then the script redirects to the result message script specified by successurl .
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.
The WBT Manager External Script Interface Kit is supplied with sample forms and message scripts that you can customize for your own purposes.
, regstud.html, and enrollstud.html are simple forms which call the interface scripts. Modify them as desired.verstud.html
verstuderror.asp, verstudfound.asp, verstudmissing.asp, regstuddupemail.asp, regstudduplogin.asp, regstudduprefid.asp, regstudfailed.asp, regstudmodlogin.asp, regstudsuccess.asp, enrollstudenrolled.asp, enrollstudfailed.asp, enrollstudnocrs.asp, enrollstudnostud.asp, and enrollstudsuccess.asp display the default success or failure messages. You can modify them as desired or (more likely) supply URLs in the original request to redirect to specific scripts in a web store or other web application.
regstud.inc and enrollstud1.inc are included in regstud.asp and enrollstud.asp respectively. They are included after the Result Message Script URLs are set into variables (so you could change them in the include files) but before the requested operation is attempted. The supplied files contain code which checks to see if the request was submitted from the same site as the WBT Manager installation and rejects the request if it comes from another site.
example: setting up a form-based self-registration mechanism:
1. Use the WBT Manager System Administrator Module or the web-based Local Administrator functions to set Self Registration IDs for any departments that you want to place students in. If you don’t use Self Registration IDs the students will go into a default department (see Adding a Student).
2. Modify regstud.html to display the fields that you want the student to fill in. Add validation code as required.
3. Modify the regstud*.asp message scripts as desired.
4. Place a link to the updated regstud.html file somewhere on your site.
5. If you are using Self Registration IDs to link students to departments then distribute them to the appropriate students for use on the registration form.
example: enrolling a student in a course from a web store.
1. At some time during the check-out process ask the student if they already have a WBT Manager account. If so, have them enter their logon id and password. If not, have them enter all the information required to add a new student.
2. From your check-out script, post a request in silent mode to verstud.asp or regstud.asp to ensure that the student has a valid record in WBT Manager.
3. After payment is authorized, post a request in silent mode to enrollstud.asp including the student’s logon id and the course’s "Provider’s Course Name".
The regstud.asp script uses a new field in the database to determine what Organization and Department a student will be added to. This field is called the Self-Registration ID and exists in both the Organization and Department tables. Version 1.5 of WBT Manager supports direct edits to this field (version 1.31 required a separate utility). Use the System Administrator Module (department or organization) or the Local Administrator functions (department only).