Email notification when a quiz is submitted

This is a old feature request ([https://tracker.moodle.org/browse/MDL-648 MDL-648]) and there are various patches floating around, but I now want to implement this properly in core, probably for Moodle 2.0, but maybe for Moodle 1.9 if we are lucky.--Tim Hunt 04:59, 21 June 2007 (CDT)

Please discuss this proposal in this forum thread.

Brief description of the requirement

When a student clicks 'Submit all and finish' on a quiz attempt, send an email confirmation to one or both of:

The student themselves.
Any designated 3rd parties - who gets emailed needs to take account of the 'Separate groups' setting, if appropriate.

It should be possible for admins to customise the text of either of these emails.

Design

Controlling who gets emailed

Users will get an email confirmation of their own quiz submission if they have the mod/quiz:emailconfirmsubmission capability on the quiz. (This means that whether confirmations are sent can be controlled for the whole site by changing the role definition, and it can be separately controlled for each quiz using role overrides.)

Similarly, users will get notified of other people submissions if they have the mod/quiz:emailnotifysubmission capability. If a user has both mod/quiz:emailconfirmsubmission and mod/quiz:emailnotifysubmission then they only get one email, the confirmsubmission one.

Interaction with groups mode

If the quiz is set to 'Separate groups', then the notifysubmission email will only be sent to those users who are in the same group as the person who submitted, or who have the moodle/site:accessallgroups capability.

Configuring the text of the emails

The emails will be stored in language strings in the quiz.php lang file. There will be strings emailconfirmsubject, emailconfirmbody, emailnotifysubject and emailnotifybody.

When these strings are loaded, a '$a' variable contining lots of useful information will be passed in which may be used in the message. The fields available will be:

$a->coursename: The name of the course
$a->courseshortname: The shortname of the course
$a->quizname: The name of the quiz
$a->quizreporturl: The URL of the results overview for this quiz (.../mod/quiz/report.php?q=quizid)
$a->quizreportlink: The URL of the results overview URL and quiz name as a HTML link
$a->quizreviewurl: The URL of the review page for this attempt (.../mod/quiz/review.php?attempt=attemptid)
$a->quizreviewlink: The attempt review URL and quiz name as a HTML link
$a->quizurl: The URL of the main page of the quiz (.../mod/quiz/view.php?q=quizid)
$a->quizlink: The URL of the quiz and the quiz name as a HTML link
$a->attemptsubmissiontime: The time the attempt was submitted, formatted using userdate().
$a->timetaken: How long the quiz attempt lasted.
$a->studentname: The name of the person who submitted the quiz.
$a->studentidnumber: The idnumber of the person who submitted the quiz.
$a->studentusername: The username of the person who submitted the quiz.
$a->username: The name of the user the email is being sent to.
$a->useridnumber: The idnumber of the person who submitted the quiz.
$a->userusername: The username of the user the email is being sent to.

When the emails are sent

It is important that if an error occurs during sending of the emails, then this does not prevent the quiz from being submitted. So we will use the Events API to fire an event when the quiz is submitted, and then write an event handler to do the email sending.

Where to implement this

Graham Miller volunteered in the forums to try to implement this, so here are some brief notes on how.

Which version?

Since this is a new feature, it really ought to go into HEAD. However, if we took out the use of the events API, it could be done in essentially the same way in the 1.8 and 1.7 branches and HEAD. That would be OK for a first implementation.

Where should the code go

In /mod/quiz/locallib.php, we need a new quiz_send_notification_emails(...) function to do the work. More on this in a moment.

This new function should then be called from /mod/quiz/attempt.php. Pass in as much as possible if the information that is already available in attemtp.php as function arguments, so we don't have to re-fetch it from the database. The call should be just before the bit

/// Check access to quiz page

    // ... [SNIP]

    if ($finishattempt) {
        redirect('review.php?attempt='.$attempt->id);
    }

The new capabilities need to be added to /mod/quiz/db/access.php as usual, with a bump of the version number in /mod/quiz/db/version.php.

To test whether to send to the student who has just submitted, use has_capability. To get a list of 3rd parties to email, user get_users_by_capability, passing $doanything = false.

To prepare the $a variable, you mostly just need to assemble the right data from the users, quiz and course. For the bits relating to attempts (that is, how to format the times), you can see the code necessary in review.php.

Then you use get_string to generate the email body and subject.

Then you use email_to_user from from lib/moodlelib.php to send the email.

Obviously you need to do deal with any errors that may arise along the way. (The main benefit of using the events api would have been easier error handling.)

Finally, write some teacher-facing documentation at an appropriate place on this wiki.

Examples of the type of email messages people might want to send

OU OpenMark system

Subject: OU online assessment confirmation - $a->quizname

Thank you for submitting your answers to: 

$a->quizname

at:

$a->submissiontime

This email confirms that we have safely received your answers.


Please do not reply to this email, which was generated automatically by the 
OpenMark online assessment system.

OU eTMA system

Subject: Ref: XXXXXX Receipt of assignment ($a->useridnumber $a->courseshortname $a->quizname)

Your assignment, number $a->quizname for course $a->courseshortname, was
received by the eTMA system at $a->submissiontime.
                 
(Your receipt code is: D8CDA7B2).    <--- not relevant to Moodle quiz.
     
		    		    		    		  

Your submission included the following files:  <--- not relevant to Moodle quiz.
Name (Size in Bytes) 

TMA05.doc(114,688 bytes)


**********************************************************************************
The University has to ensure as far as possible that the work submitted by
students is their own and does not contain any unreferenced material from other
sources.  The University statement "What constitutes plagiarism or cheating"
appears in your Assessment Handbook and you are expected to have familiarised
yourself with it. Please be aware that the University may subject your work to a
computerised check for plagiarism. 

This is an automated reply from the Open University eTMA system.  Please do not
reply to this email address as the mailbox is not monitored.  If you have any
queries please email XXX@XXXX.

Documentation