View source for Development:Email notification when a quiz is submitted

This is a old feature request ([http://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.--[[User:Tim Hunt|Tim Hunt]] 04:59, 21 June 2007 (CDT)

[http://moodle.org/mod/forum/discuss.php?d=74185 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->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.
;$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->quizname
:The name of the quiz
;$a->quizurl
:The URL of the main page of the quiz (...mod/quiz/view.php?q=''quizid'')
;$a->quizreviewurl
:The URL of the reveiw page for this attempt (.../mod/quiz/reveiw.php?attempt=''attemptid'')
;$a->coursename
:The name of the course
;$a->courseshortname
:The shortname of the course
;$a->submissiontime
:The time the quiz was submitted, formatted using userdate().

===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 new [[Development:Events|events API]] to fire an event when the quiz is submitted, and then write an event handler to do the email sending.

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

===OU OpenMark system===

<pre>
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.
</pre>

===OU eTMA system===

<pre>
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.
</pre>

==See also==

* [http://moodle.org/mod/forum/discuss.php?d=74185 Please discuss this proposal in this forum thread]