Ever find yourself needing to repeat an action in your Google Sheets?
For example, on a recent client project I wanted to cycle through my spreadsheet data, compare it to another dataset and apply a matching algorithm. To do this and stay within the 6 minute execution limit for Apps Script, I split my data into “blocks” of 10 rows, counted how many blocks I had and then ran the matching algorithm once for each block until they’d all been processed.
By adding time-based triggers, I setup my Google sheet to do this automatically, rather than having me click a button each time.
In this post I’m going to show a skeleton example of this time-based architecture, to which you can add your own functionality.
The entire code file is here on GitHub and the spreadsheet is available here (feel free to make a copy: File > Make a copy… and then you can open the script editor to modify the code).
Time-based triggers with Google Apps Script
In this simple example, I’m going to output a random number in a new line of my spreadsheet every minute until I’ve looped through a set number of times (2 in this case). It’s deliberately basic as the focus is on the trigger/timing architecture.
Here’s a screencast of this simple program in action (speeded up):
Behind the scenes, everything is running on autopilot once I’ve clicked that first Run button.
In the following image, I have two browser windows open. On the left, a Google Sheet containing a simple table of data. In the right browser window, a web page with a d3 chart that displays the data from the Google Sheet and can be refreshed dynamically when the data changes.
Google Apps Script is a cloud based scripting language for extending the functionality of Google Apps and building lightweight web-based applications.
What does this mean in practice: It’s a coding language where you can write small programs performing custom behaviors that go beyond the standard features of Google Apps. The code is stored and executed on Google’s servers.
It means you can do cool stuff like automating repetitive tasks, creating, modifying and emailing documents to people, and linking up your Google Sheets to other data sources. Heck, you can even build complex web forms, use a Google Sheet as your database, programatically create charts and publish it all to the web. In other words, you can build fully featured, lightweight web applications.
In this Google Sheets script tutorial, we’re going to write a script that is bound to our Google Sheet, or you might say contained within our Google Sheet. This is known in the jargon as a container-bound script.
(If you’re looking for more advanced examples and tutorials, check out my full list of Apps Script articles.)
Hello World in Google Apps Script
Let’s write our first, extremely basic program, the classic “Hello world” program beloved of computer teaching departments the world over.
Begin by creating a new Google Sheet.
Then click the menu Tools > Script editor... to open a new tab with the code editor window.
This will open a new tab in your browser, which is the Google Apps Script editor window:
By default, it’ll open with a single Google Script file (code.gs) and a default code block, myFunction():
In the code window, between the curly braces after the function myFunction() syntax, write the following line of code so you have this in your code window:
Your code window should now look like this:
Google Apps Script Authorization
Google have robust security protections to reduce risk from unverified apps, so we go through the authorization workflow when we first authorize our own apps.
When you hit the run button (the black triangle) for the first time, you will be prompted to authorize the app to run:
Clicking Continue pops up another window in turn, showing what permissions your app needs to run. In this instance the app wants to view and manage your spreadsheets in Google Drive, so click Allow (otherwise your script won’t be able to interact with your spreadsheet or do anything):
❗️When your first run your apps script, you may see the “app isn’t verified” screen and warnings about whether you want to continue.
In our case, since we are the creator of the app, we know it’s safe so we do want to continue. Furthermore, the apps script projects in this post are not intended to be published publicly for other users, so we don’t need to submit it to Google for review (although if you want to do that, here’s more information).
Click the “Advanced” button in the bottom left of the review permissions pop-up, and then click the “Go to Starter Script Code (unsafe)” at the bottom of the next screen to continue. Then type in the words “Continue” on the next screen, click Next, and finally review the permissions and click “ALLOW”, as shown in this image (showing different script):
Next, Google Apps Script will show you two status messages to tell you what’s happening.
First this one:
And then this one:
If anything goes wrong with your code, this is stage when you’d see a warning message (instead of the yellow message, you’ll get a red box with an error message in it).
Now, assuming you got those two yellow status messages and they’ve both automatically disappeared from view, then your program has run successfully. Click back on the browser tab with your spreadsheet (most likely the tab to the left of the one we’re in).
You should see the output of your program, a message box popup with the classic “Hello world!” message:
Click on Ok to dismiss.
Great job! You’ve now written your first apps script program.
Functions in Google Apps Script
We should rename our function to something more meaningful.
At present, it’s called myFunction which is the default, generic name generated by Google. Every time I want to call this function (i.e. run it to do something) I would write myFunction(). This isn’t very descriptive, so let’s rename it to helloWorld(), which gives us some context.
So change your code in line 1 from this:
Note, it’s convention in Apps Script to use the CamelCase naming convention, starting with a lowercase letter. Hence, we name our function helloWorld, with a lowercase h at the start of hello and an uppercase W at the start of World.
Adding a custom menu in Google Apps Script
In its current form, our program is pretty useless for many reasons, not least because we can only run it from the script editor window and not from our spreadsheet.
Let’s fix that by adding a custom menu to the menu bar of our spreadsheet, so that a user can run the script within the spreadsheet without needing to open up the editor window.
This is actually surprisingly easy to do, requiring only a few lines of code. Add the following 6 lines of code into the editor window, above the helloWorld() function we created above, as shown here:
ui.createMenu('My Custom Menu')
If you look back at your spreadsheet tab in the browser now, nothing will have changed. You won’t have the custom menu there yet. We need to re-open our spreadsheet (refresh it) or run our onOpen() script first, for the menu to show up.
To run onOpen() from the editor window, first select the onOpen function as shown in this image:
Once you’ve selected the onOpen function, the small triangle button will change from light gray to black, meaning it can be clicked to run your chosen function:
Now, when you return to your spreadsheet you’ll see a new menu on the right side of the Help option, called My Custom Menu. Click on it and it’ll open up to show a choice to run your Hello World program:
Google Apps Script Examples
Macros in Google Sheets
Another great way to get started with Apps Script is by using Macros. Macros are small programs in your Google Sheets that you record so that you can re-use them (for example applying a standard formatting to a table). They use Apps Script under the hood so are a great way to get started in seeing what you can do.
Let’s create a custom function with Apps Script, and also demonstrate the use of the Maps Service. We’ll be creating a small custom function that calculates the driving distance between two points, based on Google Maps Service driving estimates.
The goal is to be able to have two place-names in our spreadsheet, and type the new function in a new cell to get the distance, as follows:
The solution should be:
Copy the following code into the Apps Script editor window and save. First time, you’ll need to run the script once from the editor window and click “Allow” to ensure the script can interact with your spreadsheet.
In this script, I’ve created a custom menu (as we did above) to run my main function. The main function, saveData(), copies the top row of my spreadsheet (the live data) and pastes it to the next blank line below my current data range as text, thereby “saving” a snapshot in time.
Google Apps Script is by no means confined to Sheets only, and is equally applicable in the Google Docs environment. Here’s a quick example of a script that inserts a specific symbol or text string into your Doc wherever your cursor is:
6. You can change the special character in this line
var element = cursor.insertText('§§');
to whatever you want it to be, e.g.
var element = cursor.insertText('( ͡° ͜ʖ ͡°)');
7. Click Save and give your script project a name (doesn’t affect the running so call it what you want e.g. Insert Symbol)
8. Run the script for the first time by clicking on the menu: Run > onOpen
9. Google will recognize the script is not yet authorized and ask you if you want to continue. Click Continue
10. Since this the first run of the script, Google Docs asks you to authorize the script (I called my script “test” which you can see below):
11. Click Allow
12. Return to your Google Doc now.
13. You’ll have a new menu option, so click on it: My Custom Menu > Insert Symbol
14. Click on Insert Symbol and you should see the symbol inserted wherever your cursor is.
Google Apps Script Tip: Use the Logger class
Use the Logger class to output text messages to the log files, to help debug code.
The log files can be accessed after the program has finished running, by going to View > Show Logs (or Cmd + Enter, or Ctrl + Enter (on PC)).
The syntax in its most basic form is Logger.log(something in here). This records the value(s) of variable(s) at different steps of your program.
For example, add this script to a code file your editor window:
Run the script in the editor window, then View > Show Logs and you should see:
Real world examples from my own work
I’ve only scratched the surface of the outermost epidermis, not even millimeters deep, of what’s possible using GAS to extend the Google Apps experience.
Here’s a couple of interesting projects I’m working on:
1) A Sheets/web-app consisting of a custom web form that feeds data into a Google Sheet (including uploading images to Drive and showing thumbnails in the spreadsheet), then creates a PDF copy of the data in the spreadsheet and automatically emails it to the users. And with all the data in a master Google Sheet, it’s possible to perform data analysis, build dashboards showing data in real-time and share/collaborate with other users.
2) A dashboard that connects to a Google Analytics account, pulls in social media data, checks the website status and emails the user if it goes down, and emails a summary screenshot as a PDF at the end of each day.
Going GAS by Bruce Mcpherson is a newly published (i.e. bang up-to-date as of April 2016) book covering the entire GAS ecosystem, with a specific focus on making the transition from Office/VBA into Google Apps/GAS. Even if you don’t use Office or VBA much or at all, it’s still a very useful resource. It’s been a few years since I’ve done any serious VBA work, but I still found the book very helpful and a great overview of the GAS environment.
Imagination and patience to learn are the only limits to what you can do and where you can go with GAS. I hope you feel inspired to try extending your Sheets and Docs and automate those boring, repetitive tasks!
In a different post, I looked at importing social media data into a Google Sheet. Since then, I’ve had a few readers contact me to ask if there’s a way to save the imported data, so that you have a record of the data at set time intervals (e.g. once a day or once a week).
The answer is: Absolutely!
It involves writing a short script but it’s pretty simple and we can even set up the whole shebang to run automatically in the background.
This functionality plays a big part in my online course when we save social media metrics for the digital marketing dashboard project. Check it out here: