Resolution Reminders with Google Apps

In an attempt to increase my chances of success, I've decided this year to set up a periodic email reminder of my new year's resolutions.  This may backfire and only serve to remind me of my failure, but I shall choose optimism at the outset and sally forth bravely!  I've been using Google Docs lately for most of my word processing and spreadsheet needs, and I noticed recently that it is possible to add scripts to spreadsheets.  I wanted to try it out, and this email reminder job sounds like a good opportunity to do so.

So I created a new document containing my resolutions.  Now I need to email this doc to myself periodically.  Unfortunately you can't yet create scripts on docs.  You have to use a spreadsheet, so I'll have to create a new spreadsheet as well and access my script from there.

From my spreadsheet, I open the Tools → Script editor... menu, and a new window opens.  This is the Google Apps Script Editor.

Scripts (which also seem to be referred to as "projects", especially when referring to the naming of the script/project) are a bit more complex than normal Google files like docs or spreadsheets.  Each script is associated with one (and only one) spreadsheet, although one spreadsheet may have multiple scripts (accessible through the Script manager also under the Tools menu).  If I was interested in doing fancy things triggered by various events in a fancy spreadsheet, I could use multiple scripts to do so, but for the task at hand I really only need one script.

A script itself may contain any number of "files".  This allows complex scripts to be broken up in a somewhat modular way.  The script in question, though, is again simple enough that I only need the single file that Google creates by default, named "Code".  I'll also give my script a name by clicking on the "Untitled project" title field.  Now I'm ready to do some scripting!

In the main text area, the Code file is open, and Google has created a default function named myFunction, which I'll go ahead and change to remindMe.  The main task of this function will be to send me an email. Let's see if I can get a simple email sending off.

The Google Apps Script Guide contains a very handy reference of the classes and methods available to Google Apps Scripts.  The MailApp class from Mail Services looks like just the thing I'm looking for.  The simplest invocation of the MailApp.sendEmail method takes a recipient, a subject, and a message body.  I'll try a quick throw-away email to see if something works:

function remindMe() {
  MailApp.sendEmail("xxxx@xxxx.com", "testing123", "did this work?");
}

Now I'll click Run → remindMe to run the script.  But what's this?

Ah, Google needs me to authorize the script to run, and gives me some useful information about the kinds of things the script is doing (note the bottom bit about requiring the ability to send email).  Ok, so authorize away.  Now try running again...and check my email...and it works!  There's an email in my inbox with the subject and message that I was expecting:

Great!

So now to send the contents of my resolutions file.  Well, there is also the DocumentApp class, which gives me access to the Google Docs application.  The main method I'm interested in is openById.  But I need the id of my resolutions doc.  Well, if I load the doc in my browser and take a look at the address bar, I see a big string of random-looking symbols.

I bet this is the id I'm looking for.  Let's see...

function remindMe() {
  var doc = DocumentApp.openById("1qNQQbExvz_vB-0mQILu91846gySwA_ceN52cVz8GjcE");

  var subject = "Reminder: " + doc.getName();

  MailApp.sendEmail("xxxx@xxxx.com", "testing123", "did this work?");
}

Now here's a cool thing about the script editor:  there is a debugger, and I can set break points in my script by clicking with my mouse on the line number on the left side of the text area for the open script file.  When I do so, a little red dot appears, indicating that a breakpoint has been set.  If I click on the same line number again, the dot disappears, indicating that I have removed the breakpoint.  Let's see what happens if I set a breakpoint on the MailApp.sendEmail line.  This time, instead of clicking the Run button, I'll click the Debug button (the little bug icon next to the Run button).  When I do so, four new panes appear at the bottom of the script editor.

The leftmost pane shows me the file, function, and line number I'm on (note that the line number corresponds to the line on which I put the breakpoint).  The next pane lists the variables that are visible.  Oh look!  There are the doc and subject variables, and in the next two panes I can see the type and value of these variables, respectively.  As you can see, the subject string contains the title of my resolutions file, which I obtained using the getName method on the doc that I opened using the openById method and the id I found in my browser's address bar.  It looks like we've got the right file!  Beautiful.

Finally, I want to include an easy way to view my doc from my email.  I can do this in one of two ways:  include the link for the doc as part of the message body using the, or include the doc as an attachment.  I'll go with the link, as there's no need to fill my inbox with copies of my doc, but I'll show you how to do the attachment as it's a little more interesting.

The sendMail method has an optional Advanced Arguments parameter, through which key/value pairs can be passed.  The advanced arguments parameter for sendMail accepts an "attachments" key with the value being an object to attach to the email.  In this case, I can simply use the doc variable and Google will automagically package my doc as a pdf and send it along in the email as an attachment.

So here's my final code (including both the link and the attachment):

function remindMe() {
  var doc = DocumentApp.openById("1qNQQbExvz_vB-0mQILu91846gySwA_ceN52cVz8GjcE");

  var subject = "Reminder: " + doc.getName();

  MailApp.sendEmail("rod@pennyjar.ca", subject, "Have you been a good boy? " + doc.getUrl(), {attachments: doc});
}

But there's one more thing to do.  I want this email to come at me once every week to remind me of my resolutions regularly.  I can do this by adding a "trigger" to the script.  I'll click on Triggers → Current script's triggers... and then clicking on Add a new trigger.  I'll chose the remindMe function to run, and I'll make it a "Time-driven" event rather than "From spreadsheet", and set the time period to my liking.

Finally, I'll click the Save button, save my script, and save my spreadsheet, and I'm done!  Now I'll be getting a weekly reminder of my new year's resolutions.  I think I'll be wanting to lower that frequency to monthly, but it appears that weekly is as long as Google will allow me to go for the moment...

Google Apps Scripts look quite powerful.  With the additional feature that you can make your scripts public as services (Share → Publish as service... from the script editor), and the script gallery (Tools → Script gallery... from the spreadsheet editor), a lot of advanced activities in Google's suite of applications become possible and even easy.  I like it!