Google Apps Script

Essential Apps Script

Contents

Apps Script Essentials 3

Language 3
Applications 3
Variables 3
Data types 3
Arrays 4
Script Editor 4
Autocomplete 4

Working with Spreadsheets 5

Getting a spreadsheet document 5
Accessing specific sheets 5
Finding the active cell 5
Getting a range of cells 6
Getting cell values 7
Moving data between sheets 7
Appending a row to a sheet 7
Writing data to a sheet - get and set 7
One value written to one cell 7
An array of values written to a range of cells 7
Deleting data 8
Writing a nicely formatted URL 8
'Flush' so you see values written into the spreadsheet 8

Adding a menu 8

Docs and the DocumentApp 10

Opening a document 10
Appending paragraphs to a text document 10
Making a document from a template 10
Document find and replace 11

Repetition and decisions 12

Repetition with ‘For’ 12
Example 12
‘If’ conditional 13
Longer ‘If’ syntax 13

Constructing and sending email 14

University of York 1 Digital Inclusion, Skills and Creativity

 Google Apps Script

Constructing an email body 14

Forms and triggers 15

Form event data 15
Setting Triggers 15
Setting an event trigger manually 16

Creating alerts with ‘toasts’ 17

Folders, Files and permissions 18

Setting permissions 18
Adding access to a file or folder 18
Removing access 18

Calling functions 19

Dates, times and Calendars 20

Current Date and Time 20
Format 20
Making date-time values for Calendars 21
Creating Calendar events 21
Locations, descriptions and guests 22

Troubleshooting 23
Using logs 23
Executions 23
Looking online 23

University of York 2 Digital Inclusion, Skills and Creativity

 Google Apps Script

Apps Script Essentials

Language
The coding language developed by Google to work with Google Workspace is Apps Script. It is based
on a coding language used extensively on the web, called JavaScript. When looking for help, anything
connected to working with Google apps needs Apps Script, but if you need help with more general
things such as working with different types of data, you’ll need to look for JavaScript help.

Applications
Each Google Workspace tool has its own App in Apps Script: CalendarApp, DocumentApp, DriveApp,
SpreadsheetApp etc. Any number of these applications can be used in the same script; you simply use
the App that enables you to do what you want to do.

Variables
Variables are how you save something in your code with a name so you can use it again. They can
contain anything from a single ‘value’ (e.g. number or text) to the entire contents of a spreadsheet or
document.

To make your coding easier to follow, you should choose meaningful variable names that tell you what
information it contains. Variable names cannot contain spaces, so a common approach to allow
multiple words is to use ‘camel case’ (starts lowercase, each new word starts uppercase e.g.
camelCase).

The first time you use a variable, you must tell Apps Script it’s a new variable with the prefix var, and
at this point you can also set its value. This is done using an equals sign, which in coding assigns a
value. If I needed to create a variable containing a starting value of zero, the code might be:

var startingValue = 0;
As the name 'variable' suggests, the value of a variable can be changed, e.g.

startingValue = 1;

would change the value of the variable 'startingValue' to 1.

Data types
Data types tell the computer what kind of data is stored in a variable, such as numbers or text (known
as a string, or a collection of characters that can include numbers and punctuation), or a collection of
values.

Different things can be done with different data types; for example, you can add two numbers
together to get a third number, but adding two strings will concatenate them (join them together).

In Apps Script and JavaScript you can change the data type of a variable simply by assigning it a new
value.

var startingValue = 3;

University of York 3 Digital Inclusion, Skills and Creativity

 Google Apps Script

This variable contains a number, because that’s what you gave it.

startingValue = 'Monday';
This variable now contains a string. It’s the use of quotes (single or double) that makes
it a string.

You will also need to work with collections of values in the form of arrays and objects. These enable
you to store many values in one variable. In Apps Script, you can also store things specific to Google
Apps like a spreadsheet, document body, or slide in a variable.

Arrays
Arrays are a collection of items stored in one variable. In Apps Script the items could be text, a
number or a variable, and you can mix data types in one array. An array will often be the values from
one or more rows of a spreadsheet. The values in the array are enclosed in square brackets.

var student = [901,'Charles','Chang',8];

Arrays can also contain arrays, which creates a 2-dimensional (2-D) array. These contain sets of arrays,
surrounded in square brackets, and then the entire variable is also enclosed in square brackets,
creating:

var studentList = [[901,'Charles','Chang',8], [902,'Jemma','Hamilton',5], [905,'Dan','Marshall',9]];

Items in an array can be referenced using an index number inside square brackets. The index numbers
start from 0, so student[0] would give you 901 and student[1] would give you ‘Charles’.

Tip: Try the Exercises with Arrays to help you get your head around how the index numbers work and
how you can access specific values.

Script Editor
Your code is automatically coloured on input. This is not just to make it look pretty, but helps identify
variables and keywords. As you write code, the Editor will try to indent code as is needed to help you
read it. For example, code within loops or ifs should be indented, to make it clear it is a section. The
Editor will use vertical lines to show the layers of indentation.

When the editing cursor is next to a bracket, both this bracket and its corresponding pair will be
highlighted, so you can check you've closed all brackets.

Autocomplete
As you write code, the autocomplete will suggest Apps Script possibilities. If what you want isn't
listed, it may mean you're not working with the object class you thought you were. If it doesn't trigger
at all, it may mean that it can't recognise what you're working with, which may mean an error.

University of York 4 Digital Inclusion, Skills and Creativity

 Google Apps Script

Working with Spreadsheets

Getting a spreadsheet document

You must always get or open a document before you can do anything with it. Scripts often work with
the spreadsheet file in which they are stored, so you can get the active spreadsheet. If you want to
access a different spreadsheet, you need to know either its ID or URL in order to open it.

You will put the spreadsheet document into a suitable variable - ‘ss’ is a common variable name for a
spreadsheet document.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var ssAnother = SpreadsheetApp.openById(‘1xYBSgcvv6eXfeEVQ... etc’);
var ssAnotherOne = SpreadsheetApp.openByUrl(‘https://docs.google.com… etc’);
You can find the ID from the URL in the browser address bar when a document is open:

The variable now contains the entire spreadsheet document for the script to make use of.

Accessing specific sheets

After obtaining a spreadsheet document (see above getting a spreadsheet document) you will usually
need to get specific sheets (tabs), as these will contain the data. You can get the currently active
sheet, which is the one the user is currently working on when the script runs; or you can get a sheet
by its name, which must be enclosed in single or double quotes. You would store it in a variable -
‘sheet’ is a common variable name for a worksheet.

var firstSheet = ss.getActiveSheet();

var secondSheet = ss.getSheetByName(‘mySheet’);
You can combine getting the spreadsheet and sheet into one line:

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(‘mySheet’);

Only do that if you will not need to get other sheets or make alert messages and dialogue boxes, as
then you'll need to get the spreadsheet as a variable on its own.

Finding the active cell

In order to get the active cell, you first obtain the spreadsheet and sheet (see getting a spreadsheet
document and accessing specific sheets). After that, you get the active cell from the sheet.

var activeCell = sheet.getActiveCell();

Note: this does not read the value from the cell, but just gets the cell itself, which has many
properties. You must explicitly get the value.

University of York 5 Digital Inclusion, Skills and Creativity

 Google Apps Script

Getting a range of cells

In Apps Script a range of cells is almost always a 2-dimensional array of values, even if it’s just one
row or one column; the exception is a single cell.

First obtain the spreadsheet and sheet containing the range of cells, then either:

● get the range containing data

● get a specified range

The Data range is the collection of cells that the script identifies as containing data. If you use this
you don’t need to set the start or finish points of your data, but you might get a much larger array
than you need if you have a lot of data:

var theData = firstSheet.getDataRange();

You can also specify the range using getRange with 2, 3 or 4 values, in which case you do need to
know how many rows and columns are used (or use getLastColumn and getLastRow to make Apps
Script find these first):

var theData = firstSheet.getRange(startRow, startColumn, numRows, numColumns);

Specifying 2 values gets one cell, the position indicated by startRow and startColumn

Specifying 3 or 4 values will get a 2-D range, starting from startRow, startColumn

Note that getDataRange() and getRange() do not read the value(s) from the cell - you must explicitly
get the value.

Getting the last column and row

When using getRange or other features of Apps Script, you often need to know the last column and
row on the sheet that contain data. Manually inputting these numbers makes your code harder to
update and less flexible, but luckily there's methods built into Apps Script so you can get these values
and store them in variables to use.

University of York 6 Digital Inclusion, Skills and Creativity

 Google Apps Script

To get the last column, you use getLastColumn:

var lastColumn = firstSheet.getLastColumn();

And unsurprisingly, to get the lastRow, use getLastRow:

var lastRow = firstSheet.getLastRow();

Both of these output a number that corresponds to the number of the row or column. Once you have
these values stored in variables, you can use them in your getRange (or other commands) where you
would usually add a numerical value.

Getting cell values

You must first get either a single cell or a range of cells.

● use getValue() for a single cell

● use getValues() for a range

var cellValue = theCell.getValue();

var rangeValues = theRange.getValues();
Using getValues() always results in a 2-dimensional array. If you should only have a 1-dimensional
array (e.g. you're getting a single row of data), put [0] after .getValues() to only use the first element
in the array.

Moving data between sheets

Moving data to another spreadsheet destination can be done in several ways - here we'll look at a
couple of common ones - appending a row and writing the data by 'getting' the values and then
'setting' other cells to be those values - but there are other methods too.

Appending a row to a sheet

if you need simply to copy data to the next available row in a destination sheet, you can use append
instead rather than specifying the row where the data should go.

This is used to add one row of values to the next available row of the destination sheet. The values,
however, must be in a 1-dimensional array, whereas getRange(...).getValues() will result in a
2-dimensional array. To get a 1-dimensional range of values, you must get the first element of the 2-D
values array (that’s the [0] at the end of the first line):

var sourceValues = sourceSheet.getRange(startRow, startCol, numRow, numCols).getValues()[0];

destinationSheet.appendRow(sourceValues);

Writing data to a sheet - get and set

To write values to a sheet, from the destination sheet first get the range and then set the value(s).

Having got the source sheet and destination sheet, get the values in the defined source range, then
set these values in the destination range. For this to work, the source and destination ranges must be
the same dimensions - numCols and numRows must be the same.

var sourceValues = sourceSheet.getRange(startRow, startCol, numRow, numCols).getValues();

University of York 7 Digital Inclusion, Skills and Creativity

 Google Apps Script

destinationSheet.getRange(startRow, startCol, numRow, numCols).setValues();

One value written to one cell

If the value is held in theValue:

destinationSheet.getRange(row, col).setValue(theValue);

An array of values written to a range of cells

If a 2-D array is held in theValues:

destinationSheet.getRange(row, col, numRows, numCols).setValues(theValues);

A 2-dimensional array of values must be written to a 2-D range of the same dimensions.

Deleting data
Both rows and columns can be deleted from a sheet very easily, using just the row or column number.
Deleting removes the entire row/column and closes up the ‘gap’. You must first have obtained the
sheet:

dataSheet.deleteRow(rowNum);
dataSheet.deleteColumn(colNum);
Both these also have ‘plural’ versions for deleting several rows or columns:

dataSheet.deleteRows(rowNum, numRows);
dataSheet.deleteColumns(colNum, numRows);

Writing a nicely formatted URL

Using the below code you can insert a link to a Google Drive file that uses its name rather than the
long URL, which is shorter and more meaningful:

var hyperlink = '=HYPERLINK("' + docUrl + '","' + docName + '")';

destinationSheet.getRange(row, col, numRows, numCols).setFormula(hyperlink);

'Flush' so you see values written into the spreadsheet

When you're writing values to a spreadsheet, especially when you're writing a series of values using a
loop, you may notice that you don't see those values straight away, and sometimes you may need to
refresh the whole spreadsheet to see them.

To avoid this, you can add SpreadsheetApp.flush() after you update a spreadsheet in code, which
forces any updates to appear. Putting this inside the loop after you write the value means you will see
each value appear one by one, rather than at the end, which makes it easier to see progress.

Adding a menu
Custom menus allow you to run scripts from the spreadsheet, instead of opening the script editor. This
is much more user-friendly and avoids anyone accidentally changing the scripts. The menu must be
built by running a function each time the spreadsheet opens, but you can do this by naming the

University of York 8 Digital Inclusion, Skills and Creativity

 Google Apps Script

function onOpen() and it is then always run when the spreadsheet file opens.

There are several ways of constructing menus; this one generally works fine for simple menus:

function onOpen() {
var ui = SpreadsheetApp.getUi();
ui.createMenu('MenuName')
.addItem('First item name', 'first item function name')

.addItem('Second item', ‘second item function name')

.addToUi();

Note the ‘punctuation’ - the last 4 lines are all one expression.

In this context:

● getUi() gets the user interface

● createMenu(‘...’) creates a new menu object with the name given (in quotes)
● addItem(‘...’,’...’) adds an item to the menu - the first parameter is the item name, the
second is the name of the function to be run when this item is chosen
● addToUi() adds the new menu to the user interface

University of York 9 Digital Inclusion, Skills and Creativity

 Google Apps Script

Docs and the DocumentApp

Opening a document
If a document (docs, sheets etc) already exists, open it from either its URL or ID. You will normally
need to put it into a variable:

var theDocument = DocumentApp.openByUrl(‘URL of document’);

var theSpreadsheet = SpreadsheetApp.openById(‘id of document’);
The ID can be found from the URL:

Appending paragraphs to a text document

A Google Doc consists of several sections, with the main content being in the document body. This is
where you add paragraphs, tables etc.

You must first open the document - you can do this from the URL or ID, or you may have newly created
it or copied from a template. You then need to get the document body and then you can append
paragraphs to it. Paragraphs can be included in the expression, but it is often more useful to construct
the paragraph first:

var documentBody = document.getBody();

var paragraphContent = ‘Little Miss Muffet sat on her tuffet’;
documentBody.appendParagraph(paragraphContent);
documentBody.appendParagraph(‘Eating her curds and whey’);
Note: appendParagraph always adds a new paragraph below the last item in the body.

Making a document from a template

It is often best to make a copy of a pre-configured template document so the formatting is already set
up. You can define a name and destination folder for the new copy.

You will need to know the IDs for the template file and for the destination folder (these may be in
existing variables).

Note: if you're making the document in a separate function, you can open the template file and send
it to that function, but you'll need to only send the folder ID to the second function, and then use the
DriveApp in that second function to open the folder, to ensure that Google gives the right Drive
authorisation.

First, get the template file and destination folder using the DriveApp:

University of York 10 Digital Inclusion, Skills and Creativity

 Google Apps Script

var template = DriveApp.getFileById(id_of_template_file);

var destinationFolder = DriveApp.getFolderById(id_of_folder);
Then you make a copy of the template file, specifying the new filename and the folder:

template.makeCopy(fileName, destinationFolder)
You will frequently also need the URL or ID of the new document, and this can be obtained in the
same step:

var newFileUrl = template.makeCopy(fileName, destinationFolder).getUrl();

or …..getId();

Document find and replace

Apps Script includes a ‘Find and replace’ method for the document body. It takes two parameters: the
text to find, and what to replace it with.

documentBody.replaceText(‘text_to_find’, ‘replace_with_this’);
Both the find and replace text can be either literal text (in quotes) or a variable containing text.

One common use is replacing placeholders in a document with values taken from a set of data. If the
variable studentName contains ‘Eric’, you could replace a placeholder of <<name>> in a document
body using:

documentBody.replaceText(‘<<name>>’, studentName);

University of York 11 Digital Inclusion, Skills and Creativity

 Google Apps Script

Repetition and decisions

Repetition with ‘For’

Performing an action repeatedly without getting bored is something computers are particularly good
at, and there are several ways to make a script ‘loop’ through lines of code several times. There must
always be some way to end the loop - infinite loops are very easy to make, and will keep going until
the script hits Google’s time limit for a script.

One kind of loop is a 'for' loop, which runs 'for' a set of values. A ‘for’ loop looks like this:

for (var i = 0; i < someValue; i++) {

code to be run in the loop

The portion in brackets defines the values the loop should run 'for' and contains three critical parts:

var i = 0 ‘i’ is first defined as a new variable, to be used as a counter, with an initial
value of zero (variable name can be anything, but ‘i’ is typically used)

i < someValue this defines a condition, and the loop will continue as long as it is true -
usually testing for ‘i’ reaching a certain value (often the size of your
dataset)

i++ indicates that on each pass of the loop the value of ‘i’ is increased by 1
i++ is shorthand for i = i + 1

The code inside the loop can then make use of the changing value of ‘i’ to define which row/array
value is used on each iteration.

Tip: You can find out the size of an array using .length which allows you to store the 'length' of an
array (so how many items it has in it) in a variable and then use this as the condition for the loop to
test, so the loop never runs for longer than the amount of data you have.

Example
I have a 2-D array called myData, which is a range from a spreadsheet, and I want to repeat an action
for each row. I first need to find out how many rows there are, and then loop up to this value:

var numberOfRows = myData.length;

for (var i=0; i<=numberOfRows; i++) {
var singleValue = myData[i][0];
Logger.log(singleValue);
}

In this example, myData[i][0] will always get the array value from the first column, but the row will
depend on ‘i’.

University of York 12 Digital Inclusion, Skills and Creativity

 Google Apps Script

‘If’ conditional
Conditions are used to decide if a portion of code should run. A statement is evaluated and, if true,
the code inside the curly braces will run. The syntax is:

if (condition to test) {
one or more lines of code
}
Examples of conditions:

name == ‘eric’ is the content of the variable name equal to ‘eric’?

name != ‘eric’ is the content of the variable name not equal to ‘eric’?

shoeSize == 6 is the content of the variable shoeSize equal to ‘6’?

shoeSize > 6 is the content of the variable shoeSize greater than ‘6’?

shoeSize <= 6 is the content of the variable shoeSize less than or equal to ‘6’?

Tip: the use of a double ‘==’ for ‘equal to’. This is because a single ‘=’ in Apps Script assigns a value
to a variable.

Conditions can be combined logically:

&& And (shoeSize > 6 && shoeSize < 10) any value above 6 but below 10 is true

|| Or (name == ‘eric’ || name == ‘mary’) a name of ‘eric’ or ‘mary’ is true

! Not !(name == ‘eric’) is the same as name != ‘eric’

Longer ‘If’ syntax

The longer version allows you to define lines of code that will be run if the condition is not true:
if (condition) {
lines of code if condition is true
} else {
lines of code if condition is not true
}
The full version of ‘If’ enables you to test more than one condition, and also to define code to use if
none of your tests produce a ‘true’ condition.

if (condition 1) {
code block 1
} else if (condition 2) {
code block 2
} else {
final code block
}

University of York 13 Digital Inclusion, Skills and Creativity

 Google Apps Script

Constructing and sending email

There are two ways to work with email in Apps Script:

● The GmailApp gives access to all aspects of your email account - message threads, labels,
attachments etc
● The MailApp script service is designed specifically for sending email and finding your remaining
daily quota - nothing else

If you need simply to send email in a script, usually the MailApp is the best choice.

There are several ways of using it, but all use the same method. The difference lies in what other
parameters you provide. The most useful syntax is:

MailApp.sendEmail(recipient, subject, body, options);

recipient the address the email is to be sent to

subject the subject of the email

body the plain text content of the email

options these let you define cc/bcc addresses, set noReply, set a reply address,
define an html body etc

All four parameters can be written directly into the statement, but you are likely to use variables for
some (if not all), especially the options.

var options = {noReply: true, cc: ‘mickey.mouse@gmale.com’};

MailApp.sendEmail(userEmail, ‘Details of visit’, mailBody, options);

In this example, userEmail and mailBody are both variables defined elsewhere in the script; options
is defined specifically for sending the email, and sets ‘noReply’ and a cc address.

More on MailApp: https://developers.google.com/apps-script/reference/mail/mail-app

Constructing an email body

When creating an email body, you will need to construct a text string that can be sent as plain text.
The simplest way to do this is to break it up into sections, such as:

var mailBody = 'Dear user \n \n'

mailBody += 'This is an automated email to say a script did something good. \n \n'
mailBody += 'All the best, the person who wrote the script'
The ‘+=’ adds more content to the variable mailBody rather than reassigning the value. The ‘\n’ means a new
line, so needs to be used twice to leave a blank line between text.

University of York 14 Digital Inclusion, Skills and Creativity

 Google Apps Script

Forms and triggers

Form event data

When a completed Google Form is submitted, an event object is generated containing values relating
to the submission. In the related spreadsheet, a script can be triggered to make use of the values.

This portion of script will get all the Form values, extract two individual values and then determine
which spreadsheet row the data is written to.

function onFormSubmit(e) {
// get the collection of Form values
var formValues = e.namedValues;
// get Email address and Date
var userEmail = formValues[‘Email address’][0];
var date = formValues[‘Date’][0];
// find row the values have been written to
var row = e.range.getRow();
…
}
The function must include the event object as a parameter; this is usually shown as an ‘e’ for
‘event’. Many users will name the function onFormSubmit, but this is not essential as the Trigger
determines which function is run.

e.namedValues can be used to obtain all the values submitted on the Form.

Individual values are then obtained using the Form field names (and a [0] to show you only want the
first item in the array):

formValues[‘field name’][0]

In the example above, Email address and Date are Form fields and column headers in the spreadsheet.

The Form values can also be obtained as a 1-D array, but the method above allows you to retrieve
values using the field names, rather than the order on the Form.

The event range (e.range) is the range of cells the data is written to on the spreadsheet. This means
you can find the row number using:

e.range.getRow()

Finding the row is very useful if you need to write extra data to the correct row in the script.

Setting Triggers
A trigger runs a function in response to a specified event. Some triggers (‘simple’ Triggers) are
permanent: a function called onOpen() will always run when a document is opened. Others
(‘installable’ triggers) need to be set by the user.

University of York 15 Digital Inclusion, Skills and Creativity

 Google Apps Script

Triggers can be configured manually or by using scripts; to make a script run when a Form is
submitted, you would set it manually, as it only needs setting once.

Setting an event trigger manually

In the Script Editor, hover over the sidebar to see a Triggers option. A new page opens listing any
current triggers, but note that by default it shows only those you have set; if you want to see if others
have already set a trigger, remove the Owned by: Me filter.

This example sets a trigger to run a function when a Form is submitted:

1. Choose + Add Trigger - a dialogue opens.

2. Complete the dialogue
a. Choose the function you want to run
b. Deployment: Head
c. Event source: From Spreadsheet
d. Event type: On form submit
e. Set the failure notification frequency you want
3. Select Save

This trigger will now run the defined function each time the Form is submitted. Bear in mind,
however, that the script still needs to be authorised before the Form is submitted for the first time.
Plus if you add any further Apps (DriveApp, Spreadsheet App, etc) you will need to go into the Trigger,
‘Edit Trigger’ and click ‘Save’ again - to get the authorisation popup.

University of York 16 Digital Inclusion, Skills and Creativity

 Google Apps Script

Creating alerts with ‘toasts’

A ‘toast’ is a type of alert built into Apps Script that allows you to show a popup window in the lower
right corner of a spreadsheet, containing a message that can be customised. These are used with
scripts running from spreadsheets to display the progress the script is making, particularly when
looping through data. This allows the user to know the progress of the script and which tasks have
been completed.

The most basic syntax is:

SpreadsheetApp.getActiveSpreadsheet().toast('string message');
If you’ve already got the active spreadsheet, you can use ss.toast(message) instead. You can also add
additional parameters to toast() to also display a title for the message and a number of seconds to
show it for.

ss.getActiveSpreadsheet().toast('string message', 'string title', numberOfSeconds);

Apps Script Developers site on toast():
https://developers.google.com/apps-script/reference/spreadsheet/spreadsheet#toastmsg

University of York 17 Digital Inclusion, Skills and Creativity

 Google Apps Script

Folders, Files and permissions

Setting permissions
Permissions are set for a ‘file’ or ‘folder’, which means you must use the DriveApp, not the
Spreadsheet or Document App. One quirk is that you must get the file by its ID, not the URL.

Assuming the ID of the document is docId:

var newDocFile = DriveApp.getFileById(docId);

You would use this for any type of file.

The equivalent for a folder:

var theFolder = DriveApp.getFolderById(folderId);

The permissions are then set on this folder/file, using the method for the level of permission needed.
Files can have viewers, commenters and editors:

Adding access to a file or folder

newDocFile.addViewer(emailAddress);

newDocFile.addCommenter(emailAddress);

newDocFile.addEditor(emailAddress);

For adding multiple users, there are plural versions of these methods too, which need an array of
email addresses. If a user already has access, adding higher permissions will promote them.

Removing access
Again, it works the same for files and folders:

newDocFile.removeViewer(emailAddress);

newDocFile.removeCommenter(emailAddress);

newDocFile.removeEditor(emailAddress);

For more details, see the File class and the Folder class in the Apps Script Reference.

University of York 18 Digital Inclusion, Skills and Creativity

 Google Apps Script

Calling functions
Long, continuous scripts can be difficult to work with. Creating several separate functions makes
things more manageable and can enable them to be used in different contexts: a function that creates
a Calendar event from a single spreadsheet row could be used to create one from the ‘current row’,
or called from within a loop to create multiple events.

When you 'call' a different function, you can 'pass' values to it that you've already got, like variables.
Values generated in the ‘called’ function can then be ‘returned’ (passed back) to the ‘calling’ function
and stored in a variable for further use.

In this example script, one line of code calls the function ‘calendarEvent’, passing the values for the
event title, start date-time, end data-time and guest emails.

The function ‘calendarEvent’ uses these passed values to create an event and then returns the eventId
to the original function.

University of York 19 Digital Inclusion, Skills and Creativity

 Google Apps Script

Dates, times and Calendars

Current Date and Time

In theory, to get the current date you simply make a new date object. The easy bit, getting and
putting it into a variable, would be:

var todaysDate = new Date();

Although it’s called Date, it does in fact get the current time too.

Format
If a spreadsheet cell contains the date 08/05/1997, when logged in a script or written from script to a
document, it will appear as something like:

Thu May 08 00:00:00 GMT+01:00 1997

When written to a spreadsheet cell, however, it will use the default date format and look OK.

This means you may have to reformat a date to write it to a document; this is done using an Apps
Script Utilities service and has the syntax:

var formattedDate = Utilities.formatDate(new Date(suppliedDate), timeZone, format);

new Date(suppliedDate) This creates a new date object using the date you supply

timeZone To ensure the correct date, the time zone needs to be supplied.
This can be obtained using the Session service:
var timeZone = Session.getScriptTimeZone();

format This is a text string (in quotes) of the desired date format, using
d, M, y for the date elements and h, m, s for the time.

If you have a script that works with dates/times frequently, one approach is to write a short function
that can be called whenever you want to format a date/time:

function formatDate(suppliedDate, format) {

//find script timezone (to ensure time matches user's setup)
var timeZone = Session.getScriptTimeZone();
//generate formatted date
var formattedDate = Utilities.formatDate(new Date(suppliedDate), timeZone, format);
//return to function that called this one
return formattedDate
}
This can then be called from other functions using:

var formattedDate = formatDate(date, 'dd/MM/yyyy');

...where date is either a variable containing a date, or could be new Date() for the current date/time.

University of York 20 Digital Inclusion, Skills and Creativity

 Google Apps Script

Making date-time values for Calendars

Apps Script does not work with separate Date and Time values, but with combined Date-Time. This
makes some things easier, but they can be tricky to work with.

If I have a Date value (eg collected from a Sheets file or Form) and separate Times for start and end,
these must be combined to make two Date-Time values if I want to use them to create a Calendar
event.

The process is a bit long-winded, as it involves several steps to make the Date-Time objects and then
set the hours and minutes. Once you’ve got the code, however, you can just adapt it each time you
need to convert into Date-Times.

If we have three variables eventDate, startTime and endTime, collected from a Sheet/Form:

//create a new Date-Time object for the event start

var startDateTime = new Date(eventDate);

var startTimeHours = startTime.getHours()
var startTimeMinutes = startTime.getMinutes()
startDateTime.setHours();
startDateTime.setMinutes();
//do the same for the event end

var endDateTime = new Date(eventDate);

var endTimeHours = endTime.getHours()
var endTimeMinutes = endTime.getMinutes()
endDateTime.setHours();
endDateTime.setMinutes();
startDateTime and endDateTime can now be used when creating a Calendar event.

Creating Calendar events

The CalendarApp is used to work with Calendars. Creating a simple event needs:

● The ID of the Calendar to be used

● A Start Date-Time and an End Date-time
● An event title

See also making date-time values for Calendars above.

Assuming the ID of the calendar is held in calendarId:

//first get the Calendar using its ID

var calendar = CalendarApp.getCalendarById(calendarId);

//create calendar event

calendar.createEvent(eventTitle, startDateTime, endDateTime);

University of York 21 Digital Inclusion, Skills and Creativity

 Google Apps Script

This will create an event, but if you may wish to do something else with it (like delete it) it is useful
to record its ID, so a better way is:

//create calendar event

var eventId = calendar.createEvent(eventTitle, startDateTime, endDateTime).getId();

You would then need to record this ID somewhere suitable.

Locations, descriptions and guests

If you want to include a location, description or invite guests, you need to configure further options.
Although you can write these direct into createEvent(...), it is less confusing if you define these
separately first.

You create a new ‘object’ containing label-value pairs; curly brackets are used. You just include the
options you need - you don’t have to set all of them. In this example, we already have variables
containing the description, location and a comma-separated list of guest email addresses.
‘sendInvites’ is set to false in this case, so an email invite will not be sent.

//configure options

var options = {'description':eventDescription, 'location':where, 'guests':tutors, 'sendInvites':false};

The options are then included when the event is created:

//create calendar event

var eventId = calendar.createEvent(eventTitle, startDateTime, endDateTime, options).getId();

University of York 22 Digital Inclusion, Skills and Creativity

 Google Apps Script

Troubleshooting
Everyone who works with Apps Script will come across errors and bugs in their scripts frequently. It is a
crucial part of writing code in any language, and there are a number of ways to get help.

Using logs
You can tell your scripts to ‘log’ certain values as a way of checking what is happening at certain
points in the script. For example, you can log the value of a certain variable to ensure that you’re
picking up the values you expect.

var theData = firstSheet.getDataRange().getValues();

Logger.log(theData);
In this example, logging the variable theData allows you to check that you’re getting the right values
from the spreadsheet before doing anything with them. To check the logs in the Script Editor, go to
View > Logs.

When your script has an error or you don’t get the result you expect, checking the logs if you’ve
logged values can be a useful way of checking that you’re working with the values you expect.

Executions
The Executions page and Execution log shows you each time the script was run along with a duration.
It will display any Logger.log values you have outputted. If the execution fails, it details at which line
in the script that occurred and often has a message saying why the script failed. This can provide clues
about how to fix your script.

You can either view the Execution log from the button at the top of the Script Editor (for the current
'run' of the script) or use the Executions button on the lefthand toolbar to open the Executions page
and see details of all script runs.

Looking online
The Apps Script Developer site is often the best place to start when you’re having issues with Apps
Script, as it allows you to check what different services are supposed to do and what they need. For
example, an error when trying to send an email might involve checking the MailApp pages to check
your syntax and what information is required to use it.

Searching online for the error message you’re getting in the execution log or at the top of the Script
Editor is another good way to try and find a solution for errors. Sometimes the responses can be
daunting, but skimming through answers can sometimes help you think of things to try even if you
don’t understand every word.

University of York 23 Digital Inclusion, Skills and Creativity