diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..d673165 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,11 @@ +Copyright (c) 2015 . All rights reserved. + +Developed by: + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal with the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers. +* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimers in the documentation and/or other materials provided with the distribution. +* Neither the names of nor the names of its contributors may be used to endorse or promote products derived from this Software without specific prior written permission. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 4e59a83..74da6f6 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,73 @@ # student-grades-emailer A Google Apps script for emailing grades to students in a class from a Google Spreadsheet + +## Introduction + +Using a Google Spreadsheet is a great way to manage students' grades for a course. Google Spreadsheets can be easily shared, edited by multiple users simultaneously, and accessed across most devices. Additionally, keping grades in the cloud generally is a safeguard against data loss. + +One disadvtange of using a Google Spreadsheet as a gradebook is that there is no obvious way to allow students to view their grades without sharing the entire spreadsheet with them, which may be undesirable. + +student-grades-emailer is a Google Apps script that solves this problem. When run, the script emails each student their particular set of grades stored in the spreadsheet, without letting them see anyone else's grades and without any headache about giving spreadsheet permissions to all students. + +## Use + +To use student-grades-emailer, follow these steps: + +1. Sign into the Google account from which you want to send emails. +2. Open the spreadsheet (and sheet, in particular) that contains all the students' grades. +3. From the Google Spreadsheets top menu, click `Tools` then `Script editor...` +4. Create a blank project (the name does not matter - `student-grades-emailer` is a simple choice) +5. Import `student-grades-emailer.gs` into your project, or just copy and paste the contents of `student-grades-emailer.gs` into the default code file. (Again, the name of this file does not matter.) +6. Customize all options in the script as desired +7. In the function combo box, make sure `sendEmails` (not `shouldSendRow` or another function) is selected +8. Press the Run (play) button to execute the script + +## Configuration + +There are several important configuration options that must be specified when running the script, as well as some optional customizations that may be made: + +* The `config` object contains the main configuration options: + * `className` - the name of your class, e.g. Econ 301 + * `classWebsite` - a URL for your class (or other email signature) + * `assignmentNames` - an array of names for the course's graded assignments (e.g. `["Quiz 1", "First Homework", "Group Project"]`) + * `assignmentCols` - an array of ints that specify the columns in your sheet that contain the corresponding assignment grades (e.g. following the above, `assignmentCols[0]` should be the column number containing the grade for Quiz 1). Note that column numbers in this variable are zero-indexed relative to `startCol` (see below) + * `startRow` - the first row in your sheet that contains student grades (one-indexed) + * `endRow` - the last row in your sheet that contains student grades (one-indexed) + * `startCol` - the first column in your sheet that contains grades or other needed information (one-indexed) + * `endCol` - the last column in your sheet that contains grades or other needed information (one-indexed) +* `emailAddress` - the student's email address. Defined inside the `sendEmails()` function. The value of `emailAddress` must be changed so that it points to the column in your spreadsheet containing student emails. +* `message` - the body of the email sent to students. This may be customized as desired inside the `sendEmails()` function. +* `subject` - the subject of the email sent to students. This may be customized as desired inside the `sendEmails()` function. +* `shouldSendRow(row)` - this function returns a bool whether or not an email should be sent for a particular row. For example, you may only want to send emails to students whose Quiz 1 score was below a 50. Or you may want to only send scores to students who are still enrolled in the class. + +##Assumptions + +student-grades-emailer makes fairly minimal assumptions about the format of your spreadsheet: + +* The data is organized in rows and columns, where rows are students and columns are assignments or other information fields (name, email address, ID number, etc.) +* Only one student's grades are contained per row +* Every student has an email address entered in the email column +* If a grade field is blank, that value should be replaced by a 0 (this behavior may be changed by editing the expression `row[config.assignmentCols[j]]||"0"` in `sendEmails()`) + +##Example + +`student-grades-emailer.gs` is configured by default with some example options: + +* The course name is set to Econ 301 +* The course website is set to +* The first row with student data in the sheet is 2 +* The last row with student data in the sheet is 4 (so, there are only three students in this class) +* The first column with information we want is 2 (it's perfectly fine to ignore columns if you don't want/need to use them) +* The last colum with information we want is 19 +* The assignment names are as given +* The assignment column numbers are as given (where 0 corresponds to startCol, so the last column is 17) +* Student emails are in the 3rd column of the sheet (i.e. `row[1]`) +* Student names are in the 2nd column of the sheet (i.e. `row[0]`) +* There is extra information we don't use contained in some columns, and potentially some rows + + +##License etc. + +student-grades-emailer, this repository, and everything therein is released under the license specified in LICENSE.md. + +Please report any questions about, comments on, suggestions for, or typos in the code or documentation. \ No newline at end of file diff --git a/student-grades-emailer.gs b/student-grades-emailer.gs new file mode 100644 index 0000000..1bad009 --- /dev/null +++ b/student-grades-emailer.gs @@ -0,0 +1,92 @@ +/** + * Student Grades Emailer + * + * @fileOverview Email grades to students from Google Spreadsheets. Assumes you + * are logged into Google and have the sheet you want to use open + * in another tab/window. Note: emails will send from currently + * logged-in Gmail account. + * @author https://github.com/DABH + * @version 1.0.0 + * @license NCSA + * {@link https://github.com/DABH/student-grades-emailer/blob/master/LICENSE.md} + */ + +// TODO: Change this for your particular course and spreadsheet +var config={ + // Class name + className:"Econ 301", + // Class website (or other email signature) + classWebsite:"https://example.edu/econ301", + // Names of assignments + assignmentNames:["HW0","HW0 Late Days","HW1","HW1 Late Days","HW2", + "HW2 Late Days","HW3","HW3 Late Days","HW4","HW4 Late Days", + "Midterm"], + // Columns that hold the corresponding assignment scores + // NOTE: these indices are zero-indexed relative to startCol + assignmentCols:[8,9,10,11,12,13,14,15,16,17,4], + // Specify which rows and columns student data begin and end on in the sheet + // NOTE: these are one-indexed + startRow:2, + endRow:4, + startCol:2, + endCol:19 +}; + +/** + * Main function for emailing all students a list of their grades + */ +function sendEmails(){ + // Use the currently active spreadsheet sheet + var sheet = SpreadsheetApp.getActiveSheet(); + + // Define the desired range of cells from sheet + var numRows=config.endRow-config.startRow+1; + var numCols=config.endCol-config.startCol+1; + var dataRange=sheet.getRange(config.startRow,config.startCol,numRows,numCols); + + // Fetch the actual values specified by the range above + var data=dataRange.getValues(); + + // Loop over each retrieved row (student), and send an email + for (i in data){ + var row=data[i]; + // Only email this student if we should + if(shouldSendRow(row)){ + // Get student's email address + var emailAddress=row[1]; + + // Define basic message (TODO: customize as desired) + // NOTE: In our example, students' names are in column 2 of the sheet + var message="Hello,\n\nWe are writing to let you know the grades we " + +"have recorded for you for "+config.className+". If you " + +"believe we have made any errors in recording your grades" + +", please let us know ASAP by replying to this email.\n\n" + +"Your Name: "+row[0]+"\n"; + + // Append all assignment names and grades to message + for(j in config.assignmentNames) + message+=config.assignmentNames[j]+": " + +(row[config.assignmentCols[j]]||"0")+"\n"; + + // Append complimentary close and signature to message + message+="\nSincerely,\n\nYour "+config.className+" teaching team\n" + +config.classWebsite; + + // Specify subject of email + var subject=config.className+" Grade Report"; + + // Send email to student + MailApp.sendEmail(emailAddress, subject, message); + } + } +} + +/** + * A helper function for deciding whether to email a particular student (for + * example, the student may no longer be enrolled). In our example, we check + * whether the student has a midterm score recorded. + * @param row - the row (student) in question + */ +function shouldSendRow(row){ + return row[4]!=""; +}