Overview

This PowerLink allows a web form to be displayed to a student and for the data entered to be forwarded as a WebCT mail message. An acknowledgement page may also be displayed to the student after they have submitted the form and a feedback email sent to them. The data entered may be saved before being submitted and also retained for displaying or updating in subsequent tasks. Values from columns in the grade book may be displayed and updated, thereby allowing forms to control selective release criteria. To make effective use of this tool users should be familiar with HTML and preparing web forms.

System requirements

The formSubmission PowerLink is written for WebCT Vista 4.1.1 (or higher) and WebCT Campus Edition 6.1.1 (or higher). The Installation section lists the dependencies on other library files.

Installation

This PowerLink is installed in the same way as any other WebCT Vista 4+ PowerLink:

  1. Create a directory called formSubmission in the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster).
  2. Copy the formSubmission.jar file into the formSubmission directory.
  3. Copy the dependent jar library files into the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster). If desired, an alternative location of the deployablecomponents/common directory may be used for the dependent files; this would allow them to be shared with any other PowerLinks with the same dependencies.
  4. Configure the ProxyToolRegistry utility if it has not already been done (see the ProxyToolRegistry utility page for details)
  5. Restart the WebCT service.
  6. Log into WebCT as serveradmin.
  7. In the Utilities, Settings area click on the link labelled formSubmission module in the System Integration column.
  8. Enable the tool by selecting the radio button labelled True for the enable setting and click on the Save Values button at the bottom of the page.
  9. In the Utilities, PowerLinks Proxy Tools area click on the Add Proxy Tool button.
  10. Select formSubmission module from the drop-down list and click on the Next button.
  11. Enter details as required in the boxes provided; for example:
    • Proxy Tool Name: Form submission
    • Version: 2.0
    • Description: Allow students to submit data via a web form.
    Note: the Proxy Tool Name is what will appear to Section Designers when they add the tool to their sections. Click on the Save button.
  12. In the Utilities, Settings area click on the link labelled with the Proxy Tool Name entered in the previous step which should appear in the Tools column.
  13. Clear the tick in the Lock setting checkbox for the Enable Tool setting. Click on the Save Values button.
  14. Select the settings for the proxy tool again to enable the tool by default so that it is visible under the Add Content Link button within each section. Leaving it disabled will mean that Section Designers must enable the tool in each of their sections before it can be used.

The formSubmission PowerLink depends upon the following Java library files:

Configuration settings

The formSubmission PowerLink has the following custom configuration settings:

Name Required? Default value Comments
Path to HTML form page Yes /path/file.html [See note 1]
Path to HTML acknowledgement page No   This setting is optional; if no acknowledgement file is specified then a standard page containing the text Your form has been submitted by email - a copy can be found in your WebCT Sent Mail folder is displayed. [See note 1]
Path to submission email template file No   This setting is optional; if no email template file is specified then a standard email containing the value of each control submitted is sent. [See note 1]
Format of submission email file No PLAIN_WRAPPED_TEXT WebCT supports emails of the following types:
  • Plain text (PLAIN_TEXT)
  • Plain wrapped text (PLAIN_WRAPPED_TEXT)
  • Simple HTML (SIMPLE_HTML)
For normal use the default setting of plain wrapped text should be suitable.
Mark the submission email as urgent? No No Set this to Yes to flag the submission email message as being high priority.
Subject header for submission email No   Enter a subject for the submission email. If this setting is not specified then the subject will contain the path to the form file prefixed with Submission of; for example Submission of /path/file.html.
Users to receive submission email No Users named in list The following options are available:
  • All section instructors
  • All primary section instructors
  • WebCT IDs in list below
WebCT ID(s) to receive submission email (instructor1,instructor2) No   This setting should contain the WebCT ID of the user to whom the email should be sent containing the data submitted via the form. To have the email sent to more than one user, separate the WebCT IDs with commas. For example, to send the email to users instructor1 and instructor2 enter instructor1,instructor2 into this setting. If the WebCT IDs in list below setting is selected (see above) and this setting is left empty then the email will not be sent.
When email is to be sent Yes For all submissions The following options are available:
  • For all submissions
  • For first submission only
  • For resubmissions only
  • No emails to be sent
Path to feedback email file No   This setting is optional; if no auto-reply email template file is specified then no email is sent back to the student. [See note 1]
Format of feedback email file No PLAIN_WRAPPED_TEXT WebCT supports emails of the following types:
  • Plain text (PLAIN_TEXT)
  • Plain wrapped text (PLAIN_WRAPPED_TEXT)
  • Simple HTML (SIMPLE_HTML)
For normal use the default setting of plain wrapped text should be suitable.
Mark the feedback email as urgent? No No Set this to Yes to flag the feedback email message as being high priority.
Subject header for feedback email No   Enter a subject for the feedback email. If this setting is not specified then the subject will be given the same subject as the submission email with a prefix of "Feedback: ".
WebCT ID to use as sender of feedback email No   If not specified no feedback email is sent.
Grade Book columns to update on submission (name1=value1,name2,name3) No   Updating a Grade Book column when a student submits the form allows this tool to be used in conjunction with selective release; for example, to automatically make another tool available. For example, to set a column named My form to a value of Y enter My form=Y into this setting. The Grade Book column will be created if it does not already exist. If the student already has a value in the named column, then no update is made to the Grade Book. The value specified is parsed before being applied and so can contain a special reference (see below); for example, use Form_submitted=$Date to enter the date and time of submission in a column named Form_submitted. Multiple columns can be specified by separating their entries with a comma. Specifying a the name of an existing column without a value (for example, name2) enables it to be updated with data entered into an element on the form with the same name. In these cases any existing values in the column are replaced with the new value.
Secret for inbound authentication Yes SECRET This value is used to secure internal authentication requests made by the PowerLink to itself. It should be set to a non-empty value other than SECRET. It can only be set at the server level (by logging in as serveradmin). Due to a bug in WebCT it should be edited under the System Integration column of the Utilities area and not for the proxy tool itself in the tools column (see the known issues page for details).

Note:

  1. Files should normally be saved in the class files area of the section. Enter the location of the file in the setting; for example, if the file is called file.html and has been saved in a directory called forms then enter /forms/file.html. Note that the setting should start with a / character to reflect that this is an absolute path from the top of the class files area. It is also possible to specify files located at higher levels of the repository by adding the appropriate prefix to the file location setting:
    • Domain: //
    • Institution: //I
    • Division: //D
    • Group: //G
    • Course: //C
    The prefixes are case insensitive and may optionally be extended to the complete name; for example, //C and //course are equivalent. Thus, //DIVISION/forms/file.html would refer to a file named file.html in a directory named forms located at the Division level of the repository and ///forms/file.html refers to a file at the Domain level of the repository. System files may be referenced by prefixing their content ID, or pseudonym from the properties file, with //; for example //123456789 or //sample.

Properties file

The properties file should be located in the same directory as the formSubmission jar file and have the same name but with an extension of .properties.

A system file is normally referenced in WebCT by its content ID. To make it easier to reference shared files, and to make the settings more easily maintained, a pseudonym for a system file can be added to the properties file as follows:

//name=id

where name is the pseudonym and id is the content ID of the system file it refers to. The pseudonym may then be used to refer to this file. For example, if the properties file contains an entry of:

//sample=123456789

then the system file with a content ID of 123456789 can be referred to as:

//sample

in any of the configuration settings requiring the path to a file.

Usage

Follow these steps to add a form to a section:

  1. enable the tool (if it is not already) by selecting the proxy tool from the Manage Course, Settings page
  2. on the Build tab, click on the Add Content Link button and select the form submission proxy tool
  3. select an existing instance of this tool, or click on the Create button to add a new one
  4. enter a title to be displayed on the page and the path to the file containing the form; other settings are optional or have default values
  5. click on the Save button

The settings for each instance of the proxy tool can be changed by clicking on the icon from the Build tab.
Sample view of section designer page

The following guidelines should be followed when preparing a web form (including feedback and resubmission files):

Example

A simple example of a form follows:

<form action="$Action" method="post">
<p>
Entry: <input type="text" name="entry" size="20" maxlength="50" />
<input type="hidden" name="name" value="$User.Firstname $User.Lastname" />
<input type="submit" value="Submit entry" />
</p>
</form>

To the student this form will look something like this:

Entry:

From the Teach tab a section instructor can review the current settings and open the form and feedback files in an edit box. The edit option is an alternative to editing the file using the file manager; access to the HTML editor is not available when editing the file using this tool.
Sample view of section instructor page

When a form is submitted the data entered is sent as an email. Each field appears on a separate line prefixed with -> and the name of the field as specified in the form. The location of the form is used as the subject of the email.
Sample email sent on submission

Flash movie View movie illustration (3:48 minutes)

Any form fields with names starting with GB_ are assumed to refer to columns in the Grade Book. Thus, if a field named GB_Form1 is submitted with a value of 10 the grade book column named Form1 will be set to the value 10 for the current user. (Note that only students have grade book columns so the value will not be saved for other types of user.)

Special references

As seen above, when creating form, feedback and email template files there are a number of pre-defined special references which can be inserted into the content. All references are prefixed by a dollar sign ($). The following references are currently supported:

Name Description
$Date The current date and time using a format of d-MMM-yyyy HH:mm
$Action The URL to be used for the action parameter to the form tag
$URL The URL of the proxy tool request excluding any query string
$ID The ID of the proxy tool instance
$Base The URL of the location of the file being displayed (when located in the class files area) or the URL without a value for the contentID parameter (when located outside the class files area). This value can be used to specify a base URL to enable relative references to be made to other files; for example, in a base tag (<base href="$Base">) or as a prefix to a relative reference (... href="${Base}../images/header.jpg"...) or file in the system files area(... href="${Base}123456789"...)
$CancelJS A JavaScript string which can be used as an event parameter (such as an OnClick event) which will return the user to their previous location
$SubmitButton The name to be used for any button which is to submit the form data to the instructors
$SaveOnlyButton The name to be used for any button which is to only perform a save of the form data and not submit the data to the instructors
$SaveSubmitButton The name to be used for any button which is to both perform a save of the form data and to submit the data to the instructors
$CancelButton The name to be used for any button which is to cancel the form submission
$UpdateSettings The name to be given to a hidden input field to prevent any existing setting values from being deleted when new settings are to be saved; omit an input field of this name to delete any existing setting values before saving new ones
$User The org.oscelot.webct.dao.UserVO object for the user
$Section The org.oscelot.webct.dao.LearningContextVO object for the section
$Course The org.oscelot.webct.dao.LearningContextVO object for the parent course
$Form A map of the values entered by the user (including any previously saved) with the special characters of ", &, < and > replaced with their HTML code; on submission of forms newlines are also replaced with their HTML break codes (<br>)
$FormRaw A map of the values entered by the user (including any previously saved) with no encoding
$GradeBook A map of the values from each column of the Grade Book for the user

Displaying property values

When creating form, feedback and email template files it is possible to insert references to a User object which refers to the current user. Objects for the current section and parent course are also available. The feedback and email template files may also refer to values entered on the form by using the Form object. References to properties of these objects use the following syntax: $Object.Property, where Object is the name of the object and Property is the name of the property.

The User object supports properties such as:

The Section and Course objects support properties such as:

A full list of the properties and methods supported by the User, Section and Course objects can be found in the WebCTDAO documentation.

The Form object will contain a property for each control completed by the student on the form. For example, the value entered into a control called Name can be referenced as $Form.Name. If the control name contains spaces (which is not recommended) then its value can be referenced in the following manner: $Form.get("Your name"). Prefixing object names with an exclamation mark will prevent the reference from being displayed in the output when the property does not exist; this is a wise precaution to take especially for any optional fields which may not have a value. Multiple values for a parameter (as might be the case with a set of checkbox controls) are joined together into a single value separated with commas.

Below is a sample email template file for a form containing controls named Your name, Email and Telephone:

Thank you for your submission $User.Firstname $User.Lastname ($User.UserId).

You entered the following data:
1. Your name: $!Form.get("Your name")
2. Email: $!Form.Email
3. Telephone: $!Form.Telephone

We will provide feedback as soon as possible.

The resulting email will look something like this:

Thank you for your submission George Brown (gbrown).

You entered the following data:
1. Your name: G Brown
2. Email: gbrown@myemail.com
3. Telephone: 123 456789

We will provide feedback as soon as possible.

Note that the case of property names can be significant so it is best to enter them exactly as shown above or as used in the form. Anyone wishing to prepare more complex template files should refer to the User Guide for the Apache Velocity Project. This tool permits the use of conditional and looping statements. For example, the default template file is defined as follows:

Submission by $User.Firstname $User.Lastname ($User.UserId)

#foreach ( $name in $Form.keySet() )
-> $name: $Form.get($name)
#end

Troubleshooting

If you experience any problems using this PowerLink try the following to trace the cause:

Version history

VersionDateDescription
1.0.0022 September 2007Initial release
1.1.0023 September 2007
  • Added email options for:
    • template file
    • priority
    • format
    • subject header
1.1.013 October 2007
  • Encoded "|" characters in cookie string for URLs
  • Replace \ with / in file paths
  • Fix bug with Auditor access
  • Added Action variable to Velocity Context to use as form action
1.1.0218 November 2007
  • Simplified method for locating jar file
  • Separated multiple form field values with a comma (rather than new line)
  • Changed to use WebCTSSOContext.getWebCTId() rather than WebCTSSOContext.getUserId() because of SDK bug
  • Added use of nullToEmpty in getSetting() to trim values
  • Added Cancel variable to Velocity Context as a URL for returning users to the home page of the section
  • Added logger messages
2.0.0013 December 2010
  • Emails may automatically be sent to all section instructors (or all primary section instructors)
  • Added Section and Course objects for use within a form file
  • Added option to update GradeBook columns on submission
  • Data may be saved with or without being submitted
  • Forms may display (and optionally allow updating of) previously saved data
  • Files may be located at higher levels of the learning context hierarchy and shared by all sections
  • An auto-reply email may be sent back to the student on submission of their data
  • Added $FormRaw special variable and encoded values in $Form

Upgrade instructions

The following instructions provide a guide to the process of upgrading to a later release of this PowerLink. You are, however, strongly advised to follow them in conjunction with the installation instructions above, the administrator documentation provided for your release of WebCT, and to first try them on a test server.

Upgrading from version 1.0 to version 1.1

  1. Shut down WebCT
  2. Remove the old PowerLink jar file
  3. Add the new PowerLink jar file
  4. Restart WebCT
  5. Log into WebCT as serveradmin
  6. In the Utilities, Settings area click on the link labelled formSubmission Module in the System Integration column
  7. Enable the tool by selecting the radio button labelled True for the enable setting and click on the Save Values button at the bottom of the page

After following the above steps. existing proxy tool instances should continue to work but none of the new settings will be available. To enable the new settings continue as follows:

  1. In the Utilities, PowerLinks Proxy Tools area click on the Proxy Tool Name for a proxy tool created based on this PowerLink
  2. Do not change the values of any settings but just click on the Save button at the bottom of the page
  3. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
  4. Tick the Unlock this setting box against the Enable Tool setting
  5. Click on the Save button at the bottom of the page
  6. Repeat the above steps for all proxy tools based on this PowerLink

The above steps will leave the proxy tool disabled in each section irrespective of any previous setting. It may be enabled for all sections as follows:

  1. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
  2. Select True for the Enable Tool setting
  3. Click on the Save button at the bottom of the page

The enable setting may also be changed at lower levels of the learning context hierarchy (for example, at the section level). However, there is no known way of restoring the values for the enable setting as they existed before the upgrade.

Upgrading version 1.1 to a later release of version 1.1

  1. Shut down WebCT
  2. Remove the old PowerLink jar file
  3. Add the new PowerLink jar file
  4. Restart WebCT

Any existing proxy tool instances should continue working as before.

Upgrading to version 2

  1. Shut down WebCT
  2. Remove the old PowerLink jar file
  3. Add the new PowerLink jar file
  4. Ensure the ProxyToolRegistry utility file is available and configured on the server
  5. Ensure the WebctDAO (version 2.3) utility file is available on the server
  6. Restart WebCT
  7. Log into WebCT as serveradmin
  8. In the Utilities, Settings area click on the link labelled formSubmission Module in the System Integration column
  9. Enable the tool by selecting the radio button labelled True for the enable setting, enter a value for the shared secret setting and click on the Save Values button at the bottom of the page

After following the above steps. existing proxy tool instances should continue to work but none of the new settings will be available. To enable the new settings continue as follows:

  1. In the Utilities, PowerLinks Proxy Tools area click on the Proxy Tool Name for a proxy tool created based on this PowerLink
  2. Do not change the values of any settings but just click on the Save button at the bottom of the page
  3. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
  4. Tick the Unlock this setting box against the Enable Tool setting
  5. Click on the Save button at the bottom of the page
  6. Repeat the above steps for all proxy tools based on this PowerLink

The above steps will leave the proxy tool disabled in each section irrespective of any previous setting. It may be enabled for all sections as follows:

  1. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
  2. Select True for the Enable Tool setting
  3. Click on the Save button at the bottom of the page

The enable setting may also be changed at lower levels of the learning context hierarchy (for example, at the section level). However, there is no known way of restoring the values for the enable setting as they existed before the upgrade.

Licence

Creative Commons License This work is written by Stephen Vickers (in collaboration with Tim Squires and Kim Picozzi) and is released under a Creative Commons GNU General Public Licence. The formSubmission PowerLink can be downloaded from OSCELOT where it is also possible to report bugs and submit feature requests.

Valid XHTML 1.0 Strict