Usage
Installation
Within the archive you get from Download page, there is www dir and demo database dump (.local file is for local deployment). In turn, www dir contains remotexam.php script and remotexam dir with demo data.
Import demo DB to MySQL, e.g. using phpMyAdmin, under some name, like sunkware_remotexam, and grant some user all privileges for it; we assume that the username is also sunkware_remotexam. Extract the content of www to intermediate dir somewhere.
Before you move it to the root of your website, few settings have to be adjusted for the script to work properly (and securely). The settings are at the beginning of the script, between "// begin config" and "// end config" lines. Those marked with ∗ here and with ████ in the script should be known only to you:
∗ ADMINPASS_SHA256HASH : choose the Pa5sW#rD (it should be stronger) for admin access and set this to the corresponding SHA-256 hash ("$ echo -n 'Pa5sW#rD' | sha256sum -")
• PARTICIPANT_LINK_PREFIX and PARTICIPANT_EMAIL_SENDER : replace □□□□□□□□.□□□ with yoursite.xyz
• ID_STRING_LENGTH : number of digits in participant's ID. Do not change this after participants have been provided with IDs, or they will get an error
• SALT_STRING_LENGTH : length of code a participant enters to choose a variant
∗ DATABASE_HOST : production host (in case of local deployment, localhost is used regardless of this)
∗ DATABASE_NAME, DATABASE_USER, and DATABASE_PASS : what you chose for DB. Password must be strong
∗ MAX_STORED_IP_ADDRESSES : set to 0 if you do not want to collect and compare IPs, caring about privacy
∗ DATA_PATHDIR : set “random” part so that no one will “guess” URLs to variants' image files. In demo data dir, that part is "qEw78w8uG7ZpOTQiGopiaT3ISzsEtjcR"; if you change it, rename that subdir accordingly
∗ HASHCALC_KEY : without knowing it, participants cannot determine the variant for sure even if they are able to control the server-side time of choice with microsec accuracy
• EMBLEM_HREF : maybe participants without exams will click RE emblem and follow this URL. Set to something useful
• LOCALE_INSTRUCT_CHOICE, LOCALE_NO_EXAM_NOW, LOCALE_PAGE_VISITORS : translate these to the language the participants speak
• OTHER SETTINGS : change them as well if you like
Now you can move the script and data dir to the root of your website, perhaps into www that is already there. In case of local deployment, place .local one level above. Assuming that the URL of your website is https://yoursite.xyz, the participants access their pages using URLs like
https://yoursite.xyz/remotexam.php?id=1..2..3
while you access the admin interface using
https://yoursite.xyz/remotexam.php?admin
and entering the password.
2 dummy participants are included in demo DB. Follow their URLs to check if RemotExam works:
https://yoursite.xyz/remotexam.php?id=59718970178461498483113830407556
(demo exam; enter any code and click OK)
https://yoursite.xyz/remotexam.php?id=11967432254326218709163211991043
(no exam)
Exam preparation, DB & data structure
DB has 2 tables: participants and exams. You must add all participants to the former and provide each with her/his individual URL. The columns of participants table are
• id : unique string that consists of decimal digits. Generate these by e.g. "$ apg -s -a 1 -m 32 -M n". Only you and this participant should know it
• name : ...
• gruppe : group, like RE-2020-1 or RE-2020-2
• email : must be real, individual URLs will be sent there
• linksent : indicates whether URL has been sent
• exam : from exams table (see below). Empty means no exam
• var : index of chosen variant. 0 or more than there are in the exam means no choice done yet
• chtime : time when choice was done
• ips : IPv4/IPv6-s of pagevisits
When you add a participant to this table, you need to set only id, name, gruppe, email; others are by default. After all participants are added, go to admin interface and click “Send links...” button if sendmail PHP extension is installed on the server for your website, otherwise you have to send these links in some other way. In case of local deployment this button does nothing.
Make sure that all participants have received their links. When some have not, change their linksent to 0 and click “Send links...” again. Or send by other means.
Make consequentially numbered .png images of the variants var_1.png, var_2.png, ... (see the ones from www/q...R/demo_exam1 for example) and veil.png, all of the same dimensions. That veil.png is against simple “Save Image As...”: it is just a white rectangle with alpha layer, where alpha of all pixels is 1 (from 0–255 range), you can make it in e.g. GIMP.
Put these images to your_exam_id dir within DATA_PATHDIR on your site. Almost done, what is left is to add the row for this exam to exams table. Its columns are
• exam : set to your_exam_id
• name : title of exam
• comment : participants see this under their variants. Submission rules, email to send papers to, time limits etc. go here
Add dummy participant, set his exam to your_exam_id and test your new exam from a participant's point of view. When all issues are removed, you are ready for
Exam itself
At the beginning, set the required exam for participants whose groups match the template or for participants from selected groups, by clicking on the corresponding button in admin interface and entering needed values. Or, equivalently, run SQL query such as
UPDATE participants SET exam='your_exam_id', var=0, chtime='' WHERE gruppe LIKE 'X%-2020-%'
Clear IPs of previous pagevisits (button in admin interface) and inform the participants that they can now proceed to their pages, choose a variant etc.
During the exam, you probably have to “stay in touch” with participants remotely to deal with emerging issues. If someone has lost her/his inidividual link, send it again to this single participant (there is the button for this in... you guess). If someone has chosen the variant but does not see it, the common advice is to reload page, or quit and launch browser again, or switch to other browser.
At the end, reset all participants to “no exam”, keeping their choices, from admin interface (do not clear choices now, or you won't be able to verify if each participant did the variant she/he actually chose). Alternatively, run
UPDATE participants SET exam='' WHERE 1
Then collect all papers sent from participants' emails, replying to confirm a receipt.
After exam
When you have assessed the papers, clear the choices, using the button in admin interface. Or run
UPDATE participants SET exam='', var=0, chtime='' WHERE 1
You may check IP collisions to see “suspicious” visits, although this is affected much by ISPs in your country/region who provide dynamic IPs, the participants using VPNs or anonymisers like Tor, and other factors, so the collision does not necessarily imply that one participant shared her/his link with another (again, they could just share screenshots). Traces of collective work and other unfair practices would be seen in the papers themselves.