From Qedoc

This article relates to features introduced in version 2.7.0.

This article describes how to integrate the Qedoc Quiz Player into any web-based Learning Management System (LMS) or Virtual Learning Environment (VLE). The information can also be used to integrate the Qedoc Quiz Player into simpler websites which fall short of describing themselves as LMS's or VLE's.

If you wish to integrate the Qedoc Quiz Player into your website or web application in this way, we recommend you review all of this material in detail first, and then contact us with your further questions.

Contents 1 Modules which work with the Qedoc Quiz Player 2 Fire-and-forget module launching 3 Intelligent module launching 3.1 Basic HTML form 3.2 General points 3.3 Description of fields 3.3.1 Compulsory fields 3.3.2 Optional fields with no material effect on the Player 3.3.3 Optional fields which affect the Player 3.4 How to test your application 3.5 Notes 3.5.1 Multiple attempts and multiple activities 3.5.2 Suspension and resumption of attempts 4 Permissions 5 FAQ 5.1 What is a VLE or LMS? 5.2 Do I have to have a VLE or LMS to do what this page says? 5.3 Do I have to have a database to do what this page days? 5.4 Which programming languages do I need to know? 5.5 Do I have to understand XML to do what this page says? 5.6 Which LMS's or VLE's already have this kind of thing in them? 5.7 Can you recommend someone who can do this programming for me? 6 See also

Modules which work with the Qedoc Quiz Player

Currently the Qedoc Quiz Player only works with Qedoc-formatted learning modules, of which there are a lot here. You are welcome to make more of them - anyone can become an author. If you have existing content, Qedoc already supports some import formats, and we welcome suggestions for further import formats. The current situation is therefore that you have to convert your content into a Qedoc learning module if you wish to display and interact with this content using the Qedoc Quiz Player as an integral part of your LMS or VLE.

Fire-and-forget module launching

On every learning module page on this website there is a special URL for embedding into web pages (in a box on the right-hand side of the pages). Use this URL on any website or in any LMS or VLE, and it will launch the module directly from your web page, just as if the module and software was installed on your site. This is similar to hotlinking of images - with the difference that we allow it.

We can call this "fire-and-forget", because if you use this method, you have no programmatic interest in getting the results back from the Qedoc software into an application (such as an LMS or VLE) on your side of things. The learner is left with the Qedoc software to interact with, learn from, store results locally and compare with their class within the Qedoc environment alone.

Intelligent module launching

If you wish results to be submitted from the Qedoc software into your LMS or VLE, or if you wish to exert control over the behaviour of the Qedoc software from within your launch script, then you will have to make a few minor changes to the HTML code and write a processing script to enter results back into your LMS/VLE.

We call this intelligent module launching to distinguish it from fire-and-forget module launching. In the framework of intelligent module launching, the Qedoc software and your website remain in communication with each other throughout the period of the Qedoc software's operation.

Basic HTML form

You write something like this into your HTML:

<form method=post action="http://www.qedoc.net/qqp/launch/qp.jnlp">
<input type=hidden name=mod value="http://www.qedoc.com/library/ABCDE_000.zip">
<input type=hidden name=suburl value="http://www.mysite.com/path/QedocResultsParser.php">
<input type=hidden name=lms value="My Personal VLE">
<input type=hidden name=custompostfields value="session/0a1b2c3d4e6f7g8h9i0;id/01234">
<input type=hidden name=cookie value="authenticate/112233rrttmm;key/567opq">
<input type=hidden name=user value="Bob the Builder">
<input type=submit name=submit value="Launch Player">
</form>

General points

• The post action URL: for the moment this is restricted to http://www.qedoc.net/qqp/launch/qp.jnlp. There is a file here which is currently placed at public disposal. The file requires a special server configuration to work. Don't change this section.
• The jnlp file is also equipped to read the values as a query string, so the information can be sent as a simple hyperlink - e.g. http://www.qedoc.net/qqp/launch/qp.jnlp?mod=http://www.qedoc.com/library/ABCDE_000.zip&attempt=0123467890&suburl=http://www.mysite.com/path/QedocResultsParser.php.
• The mod and suburl fields are compulsory. The rest are optional.

Description of fields

All fields offer a way to adapt the behaviour of the Qedoc Quiz Player to the needs of your LMS/VLE.

Compulsory fields

• mod: replace the section "ABCDE_000" with the equivalently formatted name of the module you wish to launch. The module must exist at that location, which means it must be placed there by Qedoc, normally as part of the process of publication. All the modules here can be used in this way. You can add your own modules to this list simply by publishing them using the Qedoc Quiz Maker. The correct URL for the mod field can be obtained by copying the download URL from any module page on this site. That's the download URL, not the launch URL. The download URL ends in .zip.
• suburl: this is the path to a script on your server. The results of any activities used in the Qedoc Quiz Player will be posted to this URL in this format. You are responsible for the content of the processing script. Normally you would write a script which parses the XML and enters the results into the database of your LMS/VLE. The language of your script is unimportant - it could be PHP, but it could be anything else. It just needs to be well-coded. Some LMS's or VLE's will already have scripts for processing Qedoc results - e.g. Moodle.

Optional fields with no material effect on the Player

These are fields whose primary purpose is simply to be passed back with the results as a form of identification within your LMS/VLE. These fields may be critical to getting a sophisticated LMS/VLE to accept the results as coming from a specific user. It is unlikely you will need them all, but depending on your LMS/VLE, you are likely to need at least one of them.

• cookie: this field contains a "name/value" pair using a / as a separator. If you require several cookies, use the format "name/value; name/value;" - using a semi-colon to separate each pair. The Qedoc Quiz Player does not act on these values; it simply sends them back as cookies in the header sent to the VLE/LMS. Security considerations: if you do not want to send authentication cookies outside your LMS/VLE and you wish to protect against injection, we suggest you create a database table which temporarily holds your internal cookie values indexed against a new cookie value specifically for Qedoc purposes. When the Qedoc cookie is returned, retrieve your internal values, reconstruct the user session and delete the table entry to prevent further use of the cookie.
• custompostfields: this field contains a "name/value" pair using a / as a separator. If you require several items, use the format "name/value; name/value;" - using a semi-colon to separate each pair. The Qedoc Quiz Player does not act on these values other than adding a "qedoc_" prefix to the names for security; otherwise it simply sends them back as additional custom post fields in the post data sent to the VLE/LMS. Example, if you use "custompostfields=sesskey/abc;id/bob", then the post data returned to your VLE/LMS with the results will contain the custom fields $_POST['qedoc_sesskey'] and $_POST['qedoc_id'] with the respective values abc and bob. If you need custom post fields sent back without the security prefix, please contact us.
• customxmlfields: this field contains a "name/value" pair using a / as a separator. If you require several items, use the format "name/value; name/value;" - using a semi-colon to separate each pair. The Qedoc Quiz Player does not act on these values; it simply sends them back as additional custom XML fields in the XML metadata sent to the VLE/LMS. The custom XML fields will be created as child nodes of the metadata tag. See Assessment Results Format.
• name: this is a string which has primarily decorative purposes, but you could use it for an ID as well. The string will be passed back, unprocessed, in the XML-formatted results. It will also display as the current name of the user while the quiz is being attempted. As the name is displayed prominently on the Player interface, you could use this to help examination invigilators check that students are not impersonating each other but are logged in under their own names. Not yet fully implemented.

Optional fields which affect the Player

• lmsname: any name of your choosing. This provides the Player with a user-friendly name for your LMS or VLE, which is used in Player interface reports about results submission. For example, you could use "lmsname=University of Cahokia Self-Compiled VLE". You are advised to specify a name, otherwise the Player will refer to your app as "Unknown VLE/LMS".
• activity: [zero-based integer]. In multi-activity modules, this will force the Player to load a particular activity when started. By default, the Player starts in do-as-you-like mode, where the student can browse results and activities, or load a different module [passing note: in case the student loads a different module, the attempt ID needs to be wiped from the Player on every module load]. Not yet fully implemented.
• onAbandon: submit/close/submitandclose/noaction. By default, the Player does not notify abandoned attempts and allows the student to restart. You can set the Player to notify an abandonment, or to notify and close down as well, preventing any re-attempt. Not yet fully implemented.
• onSubmit: close/noaction. Causes the Qedoc Quiz Player to shut down as soon as an activity is submitted. This will prevent the usual results display in the Qedoc Quiz Player (because it's not running any more) and will also limit the number of attempts to one. Otherwise the student could just go on forever with fresh attempts. Not yet fully implemented.
• permitLocalSaving: yes/no. By default, the Player saves all completed attempts locally ("yes"), which enables the students to check out their results in subsequent sessions, and also enables the Player to submit cumulative scores on each new attempt. You may wish to prevent local saving. Not yet fully implemented.

How to test your application

1. Create a page in your LMS/VLE which contains the above code, either as a form or as a URL with a query string.
2. Create a QedocResultsParser.php script (using whatever name you prefer) for your VLE or LMS to receive the results data. Ensure that the script is not protected by any login requirements or passwords - you can use the ID parameter to confirm identities. Remember that the Quiz Player will post the data to this script and that the data will be the argument of a parameter known as "data" - i.e. if you do a raw output of the post data, it will start off with "data=" followed by the XML content.
3. Remember that to get the Qedoc Quiz Player to submit anything, you have to complete one activity in the Player. You don't need to answer the questions. Just start an activity and then immediately submit it. Submission to your URL occurs at exactly the time you press the activity submit button.
4. Experiment initially with a QedocResultsParser.php which simply writes the raw post data to a text file on the server. As QedocResultsParser.php cannot have a GUI, there's no point in trying to output anything to the browser. In fact, any standard output from the script will be returned to the Qedoc Quiz Player as if the Player itself was the browser. So use text files for debugging and checking.
5. Once you've got the hang of receiving the data, it should be plain sailing to get the data entered into your database.

Here's a sample script for QedocResultsParser.php which we cooked up before the show. Please use this to start off with, and/or to test if you are getting your XML submitted correctly. If you modify the script to output the name of the key which has the data, you'll find the key is called "data".

<?php
$fp = fopen('dump.txt', 'w');
foreach ($_POST as $key=>$value)
{
   fwrite($fp, $value);
}		
fclose($fp);
?>

Notes

Multiple attempts and multiple activities

Normally a Qedoc module will contain several activities which can be attempted any number of times during a session. On average, as of March 2009 when we had just short of 1000 modules available, the average module had 4 activities with a total of a little more than 3950 activities, pretty well all of which could be attempted unlimited numbers of times. In other words, for a single "attempt ID" (or launch initiated from your LMS/VLE), remember that several submissions could come back from the Quiz Player, both for different activities and for different attempts. The content of the submissions will allow you to distinguish these different attempts and different activities. You may wish to write your results processing script to bear this in mind and either allow only one successful submission per "attempt ID" issued by your VLE, or allow multiple submissions and process these accordingly. We have added some fields (above) with which you can control the behaviour of the Qedoc Quiz Player in relation to multiple attempts and multiple activities.

If you wish your LMS/VLE to support Qedoc modules with multiple activities, it may also make sense to allow the facilitator to enter the number of activities in the module when configuring the test. In future integration scenarios, it may be possible for your LMS/VLE to auto-detect the number of activities in the Qedoc module.

Suspension and resumption of attempts

Some VLE's, such as Moodle, have a concept of "attempt suspension and resumption", where a learner can suspend the current attempt and continue work on it later (after a visit to the library). This can make sense with an online system - for example, in case the network connection is lost. The Qedoc Quiz Player runs on the desktop and does not require an internet connection, except when loading a module from the web and when submitting results. The Player can save results locally (not half-finished ones, but fully finished ones), so even if the network connection goes down for a long time, a student does not need to worry about loss of work. The Qedoc Quiz Player therefore has no concept of "suspension and resumption". A quiz can only be "started" and then "submitted", "timed out" (timed tests are rare) or "abandoned".

Permissions

This section answers the question "who is allowed to use the software in this way, and under what conditions?".

1. The entire process of LMS/VLE integration is rather experimental at the current time, so it is quite possible that we will change anything or everything, including the conditions under which these features can be accessed. In particular, we have to look hard at the costs which ensue if specific modules or files are very heavily downloaded from our servers. In the long term, we would prefer to reserve the Qedoc servers for occasional users and individuals who do not have the expertise to set up their own JNLP delivery system.
2. The Qedoc principle always has been one of favouring zero cost for open content. That means that we will endeavour, within our means, to offer this service free to anyone who publishes their educational content openly on this site and makes it available for everyone else to share.
3. If you prefer to keep your content away from the public, we can offer the same service on a fee-paying basis. Please contact us with a description of your needs.

FAQ

Some things people have asked after reading this page.

What is a VLE or LMS?

A VLE is a Virtual Learning Environment. That's a web application or website which organizes lots of people's learning. School boards and universities sometimes have Virtual Learning Environments. Teachers can use the VLE's to manage course materials and grades, while students can log on and find out about the progress of their studies, download materials, take tests, etc. See http://en.wikipedia.org/wiki/Virtual_learning_environment.

An LMS (Learning Management System) is the same thing. See http://en.wikipedia.org/wiki/Learning_management_system.

An example of a free and popular VLE is Moodle.

Do I have to have a VLE or LMS to do what this page says?

No. You can put together your own scripts into something much smaller. See Data import and export for alternative ways of doing similar things, or read on.

Do I have to have a database to do what this page days?

No.

It is true that this page largely assumes you have a database, but this is not actually necessary. A minimal script for processing results would turn the results into an email and send the email back to you. Here is an example. The following script just reads the data posted back by the Player and turns it into an email.

<?php
$message = "Here are some Qedoc results.\n\n";
foreach ($_POST as $key=>$value)
{
   $message .= "$key: $value\n";
}		
mail($message);
?>

The above script assumes you already have a PHP function which emails the message. We've left that bit up to you.

Which programming languages do I need to know?

Any you like. We've mainly worked with PHP. However the same principles will apply easily to ASP, .NET, JSP or any other kind of script-driven websites.

Do I have to understand XML to do what this page says?

Not really.

It helps.

However if you use the minimal script for mailing results back to you, you don't actually have to programme any XML-processing scripts. Your email will contain some rather XML-like code in it. But the basics of the XML (e.g. student name and overall score) are human-readable.

If you want to have results from different students combined together and displayed in tables and graphs, then either you will have to do a lot of paperwork with the emails that come back to you, or you'll need a database. If you don't want to get your hands dirty with this kind of thing, then use an LMS or VLE which already has Qedoc integration.

Which LMS's or VLE's already have this kind of thing in them?

• Moodle may have this in an upcoming release.
• You may wish to encourage the manufacturer of your favourite LMS or VLE to do the same.

Can you recommend someone who can do this programming for me?

Yes. Contact us.

See also

• Assessment Results Format