1. Marks to PDF - Canvas Edition

• 1. Marks to PDF - Canvas Edition
• 2. PDF generation script (MarksToPdf)
  • 2.1. MarksToPdf Examples
  • 2.2. Instructions
  • 2.3. File structure
  • 2.4. Commandline Args and Usage
    • 2.4.1. Emailing Functionality
• 3. Upload Feedback PDFs to Canvas (pdfsToCanvas)
  • 3.1. Instructions
  • 3.2. Commandline Args
  • 3.3. File structure
  • 3.4. Uploaded file requirements
• 4. Contact

These scripts automate the generation and distribution of individual student feedback PDFs via canvas.

2. PDF generation script (MarksToPdf)

This script will generate PDFs feedback rubrics based on a spreadsheet (in CSV format) containing each student's personal details, marks and feedback. It can also email the feedback PDFs to students as they are generated [emailing feature is deprecated and will be removed at some point].

2.1. MarksToPdf Examples

Refer to the COOK10001 example Excel sheet, JSON file, and CanvasSubmissions downloaded assignments folder in /examples

I recommend that you work from the JSON file without comments. MarksToPDF will accept comments in the config JSON file, but JSON validators like https://jsonlint.com won't work if you have comments.

If the tool reports a syntax error in the JSON, use https://jsonlint.com to debug the JSON.

2.2. Instructions

1. You will need Node.js version 12+ and npm installed. If you're on an older version of ubuntu etc, you can use nvm https://github.com/nvm-sh/nvm to get a version of node > 12. I have had success running the script on the Windows Subsystem for Linux on Windows 10, but otherwise installing node from https://nodejs.org/en/ works fine.

2. Before running the script for the first time, run npm install to fetch dependencies.

3. Prepare a CSV file with student marks. This should contain one row for every student (rows with no student number, or an invalid student number, will be ignored). The row containing the maximum available marks for each question should come before the first student row. If you are going to use the email functionality, make sure there is a column that contains student email addresses. Place this file into /input

• If there are students who should not receive feedback (e.g. suspected of academic misconduct), you can either delete their rows from the CSV, or mask the email addresses by prefixing them with XXXX or similar.

4. Prepare a configuration JSON file. There are various example JSON files included in /example, which contain documentation explaining what is required. If you need advice, or you want to do something that does not appear possible, please contact Alan Thomas alan.thomas@unimelb.edu.au. Place this file into /input

5. Run the script. A typical invocation to generate PDFs without emailing them might look like:

$ node markstopdf.mjs --config A1_2021_S1.json --csv A1_2021_S1.csv

• See the 'command line args' section below for more details.

2.3. File structure

The structure (only showing files relevant to marksToPdf) should look as follows (with your own csv and pdf spec from steps 3 and 4, and your student assignments from step 5 in place).

|   .gitignore
|   markstopdf.mjs
|   markstopdfutils.mjs
|   package.json
|   README.md
|
----examples
|   |   COOK10001-example-with-comments.json
|   |   COOK10001-example.`json`
|   |   COOK10001-example.xlsx
|   
|
----fonts
|      ...
|
----input
    |   myPdfSpec.json
    |   myStudentGrades.csv
    |   myLogo.png
    

2.4. Commandline Args and Usage

usage: node markstopdf.mjs [--ids 123456,345678,...] [--mail n] --config config.json --csv marks.csv
--ids list,of,ids     optional: only generate PDFs for the given student IDs
--mail 1, --mail 2    optional: whether to email the generated PDFs
                        --mail 1: send all the emails to the subject coordinator
                        --mail 2: actually send an email to each student
--config config.json  required: the JSON configuration file for this assignment
--csv marks.csv       required: the CSV file containing the marks data

2.4.1. Emailing Functionality

note that the emailing functionality will not work without additional work for accounts with MultiFactor authentication enabled, hence the need for the canvas upload extension.

Eventually the Email functionality will be removed or at least refactored into its own script.

3. Upload Feedback PDFs to Canvas (pdfsToCanvas)

A separate script is included which can upload feedback PDFs (or any file really) to the corresponding feedback page on the canvas assignment for each student.

3.1. Instructions

1. Follow the first 2 steps for the above marksToPDF to setup Node.js
   1. Ensure your node environment is version 12 or later.
2. Generate feedback PDFs or other files (eg using marksToPdf).
3. Place the PDFs in the "./generatedPdfs/" directory (configurable in script args, see below)
4. Create a uploadConfig.json file modelled on the example example-uploadConfig.json located in the examples folder
   1. To create a token for use with canvas, see https://canvas.instructure.com/doc/api/file.oauth.html#manual-token-generation. The 'manual token generation' works fine.
   2. You can find the canvas subject Id and assignment ID from the URL of the assignment, eg https://<canvasUrl>/courses/108072/assignments/204232/ has a subjectID of 108072 and an assignment ID of 204232
5. Place the uploadConfig.json in the input folder (configurable in script args)
6. Run the script as node pdfsToCanvas.jsm

3.2. Commandline Args

usage: node pdfsToCanvas.mjs [--config ./config.json] [--pdfsDir ./pdfs/] [--fileExtension pdf]
  --config ./config.json    optional: The JSON configuration file for this assignment
                                      Defaults to ./input/uploadConfig.json if not provided
  --pdfsDir ./pdfs/         optional: The dir containing the pdfs generated by marksToPdf.
                                      Defaults to ./generatedPdfs/ if not provided"
  --fileExtension           optional: Files with this extension will be uploaded.
                                      This prevents accidental upload of other file types.
                                      Defaults to pdf if not provided.

3.3. File structure

The default structure (only showing files relevant to pdfsToCanvas) should look as follows (with your own uploadConfig.json from step 3, and your feedbackPDFs from step 1&2 in place).

|   .gitignore
|   pdfsToCanvas.mjs
|   uploadSingleFeedbackCanvas.mjs
|   package.json
|   README.md
|
----examples
|   |   example-uploadConfig.json
|   
----generatedPdfs
|   |   Feedback_<canvasId>_Fname1_Lname1.pdf
|   |   Feedback_<canvasId>_Fname2_Lname2.pdf
|   |   ...
|
----input
    |   uploadConfig.json

3.4. Uploaded file requirements

The uploaded files do not need to be PDFs, and in fact do not need to have been generated from marksToPdf (could be any type of feedback file).

However, each file to be uplaoded MUST be named as xxxx_<canvasId>_..., for example, the naming produced by marksToPdf of Feedback_<canvasId>_<studentId>_Fname_Lname.pdf works perfectly.

4. Contact

If you have any questions or feedback, contact Alan Thomas alan.thomas@unimelb.edu.au or <colton.carner ‘at’ unimelb.edu.au>