HKDSE 2020 PDF Split and Mail

Download and use the Script

The Script can be downloaded from here.

Save the script in a folder (e.g. D:\HKDSE\)

Usage:

hkdse-split.py split --sourcepdf=<sourcepdf> --outputfolder=<outputfolder> --hkid [(--generatezip --secretfile=<secretfile>)]

hkdse-split.py split --sourcepdf=<sourcepdf> --outputfolder=<outputfolder> --candidateno [(--generatezip --secretfile=<secretfile>)]

hkdse-split.py split --sourcepdf=<sourcepdf> --outputfolder=<outputfolder> --studentname [(--generatezip --secretfile=<secretfile>)]

hkdse-split.py split --sourcepdf=<sourcepdf> --outputfolder=<outputfolder> (--frommapping --mapfile=<mapfile>) [(--generatezip --secretfile=<secretfile>)]

hkdse-split.py sendfile --inputfolder=<inputfolder> --emailfile=<emailfile> --oauth2_file=<path_to_oauth2_creds.json> --sender=<senderemail> --templatefile=<template> --subject=<mailsubject>

hkdse-split.py setupemail --oauth2_file=<path_to_oauth2_creds.json> --sender=<senderemail>

hkdse-split.py (-h | --help)

hkdse-split.py version

Options:

-h --help Show this screen.

--sourcepdf=<PATH of Source PDF> Path to the HKDSE Results PDF file from HKEAA

--outputfolder=<Output Folder> Folder used to store the splitted PDF files

--hkid Use the extracted HKID as filenames for splitted PDF files

--candidateno Use the extracted Candidate No as filenames for splitted PDF files

--studentname Use the extracted Student Name (English) as filenames for splitted PDF files

--frommapping Use the FILENAME column specified in the map file as filenames for splitted PDF files

--mapfile=<mapfile> CSV file containing the HKID to FILENAME mapping

--generatezip Use Candidate Number as filenames

--secretfile=<secretfile> CSV file containing the HKID to SECRET mapping

--emailfile=<emailfile> CSV file containing the HKID to EMAIL and other merging variables used in the template mapping

--oauth2_file=<file> JSON file containinng the OAuth2 Credentials

--sender=<senderemail> EMAIL address of the sender

--templatefile=<file> The email message template file

--subject=<emailsubject> The email subject

Commands:

split split the HKDSE Results PDF file from HKEAA

sendfile Send the files stored in inputfolder through email to the students,

according to the filename stored in the mapping file

setupmail Setup OAuth2 for GMail (To be implemented)

Examples:

Spliting by HKID

Files will be splitted and named by the extracted HKID

python hkdse-split.py split --sourcepdf="D:\HKDSE2020\HKDSE.pdf" --outputfolder="D:\HKDSE2020\Output" --hkid

Spliting by Student Name

Files will be splitted and named by the extracted Student Name

python hkdse-split.py split --sourcepdf="D:\HKDSE2020\HKDSE.pdf" --outputfolder="D:\HKDSE2020\Output" --studentname

Spliting by Candidate Number

Files will be splitted and named by the extracted Candidate Number

python hkdse-split.py split --sourcepdf="D:\HKDSE2020\HKDSE.pdf" --outputfolder="D:\HKDSE2020\Output" --candidateno

Spliting by Customized Filenames

Files will be splitted and named by FILENAME column in the mapping file matched by HKID

python hkdse-split.py split --sourcepdf="D:\HKDSE2020\HKDSE.pdf" --outputfolder="D:\HKDSE2020\Output" --frommapping --mapfile="mapping.csv"

The mapfile (e.g. mapping.csv) should contains AT LEAST 2 columns, HKID and FILENAME

Please note that the mapping file MUST BE a CSV file, EXCEL file is NOT currently supported.

Mail Merge

The script supports simple mail merge function.

Template variables are enclosed using the curly braces {{ }}.

Example template file (template.txt):

Dear {{LASTNAME}}, {{FIRSTNAME}},

Attached is a zip file containing the HKDSE Result file.

The password to open the zip file is the same as your HKID (e.g. A1234567).

Attachment: {{FILENAME}}.zip

Best Wishes,

Your Teacher

When performing mail merge, you must also specify the data source file containing at least the following fields:

• EMAIL - The email address of the recipient

• FILENAME - the file name of the attachment (e.g. A1234567.zip)

• Other fields to be merged. Please note that all field names are case-sensitive and SHOULD ONLY contains alphabets and digits (no spaces or special character)

Example data source file (email.csv)

HKID,LASTNAME,FIRSTNAME,EMAIL,SECRET,CLS,CLSNO,FILENAME

Y0583437,CHAN1,JACKY1,huichunkit+01@gmail.com,1NAHC1YKCAJ,6A,1,6A01_CHAN1_JACKY1.pdf

Y4848275,CHAN2,JACKY2,huichunkit+02@gmail.com,2NAHC2YKCAJ,6A,2,6A02_CHAN2_JACKY2.pdf

To execute mail merge, use the following command (all in one line)

python hkdse-split.py sendfile --inputfolder=students/pdfs --emailfile=<email.csv> --oauth2_file=oauth2.json --sender=<youremail@yourdomain.com> --templatefile=<template.txt> --subject="HKDSE Result"

where

• --sender specifies the sender email address, must be the same as the email address used to create the Google OAuth2 project

Please NOTE that Google imposed a limit of sending emails through SMTPS. Please refer to here for more details.

For GSuite EDU users, you may want to take a look at the following limits

Sending multiple attachments

Mutliple attachments (up to 4) can be sent to the students.

To send multiple attachments:

• Put the files in specified in the inputfolder parameter (same as the original PDF / ZIP)

• Add the columns FILENAME02, FILENAME03 and FILENAME04 to the CSV file specified by the emailfile parameter