Event Objects

Simple triggers and installable triggers let Apps Script run a function automatically if a certain event occurs. When a trigger fires, Apps Script passes the function an event object as an argument, typically called e. The event object contains information about the context that caused the trigger to fire. For example, the sample code below shows a simple onEdit(e) trigger for a Google Sheets script that uses the event object to determine which cell was edited.

function onEdit(e){
  // Set a comment on the edited cell to indicate when it was changed.
  var range = e.range;
  range.setNote('Last modified: ' + new Date());
}

This page details the fields in the event object for different types of triggers.

Google Sheets events

The various Google Sheets-specific triggers let scripts respond to a user's actions in a spreadsheet.

Open

(simple and installable)
authMode

A value from the ScriptApp.AuthMode enum

LIMITED
source

A Spreadsheet object, representing the Google Sheets file to which the script is bound

Spreadsheet
user

A User object, representing the owner of the spreadsheet (only available in simple triggers, and only if the current user is allowed to know the owner's email address, depending on a complex set of security restrictions)

amin@example.com

Change

(installable)
authMode

A value from the ScriptApp.AuthMode enum

FULL
changeType

The type of change (EDIT, INSERT_ROW, INSERT_COLUMN, REMOVE_ROW, REMOVE_COLUMN, INSERT_GRID, REMOVE_GRID, FORMAT, or OTHER)

INSERT_ROW
user

A User object, representing the owner of the spreadsheet (only available in simple triggers, and only if the current user is allowed to know the owner's email address, depending on a complex set of security restrictions)

amin@example.com

Edit

(simple and installable)
authMode

A value from the ScriptApp.AuthMode enum

LIMITED
user

A User object, representing the owner of the spreadsheet (only available in simple triggers, and only if the current user is allowed to know the owner's email address, depending on a complex set of security restrictions)

amin@example.com
source

A Spreadsheet object, representing the Google Sheets file to which the script is bound

Spreadsheet
range

A Range object, representing the cell or range of cells that were edited

Range
value

New cell value after the edit. Only available if the edited range is a single cell.

10
oldValue

Cell value prior to the edit, if any. Only available if the edited range is a single cell. Will be undefined if the cell had no previous content.

1234

Form submit

(installable)
authMode

A value from the ScriptApp.AuthMode enum

FULL
values

Array with values in the same order as they appear in the spreadsheet

['2015/05/04 15:00', 'amin@example.com', 'Bob', '27', 'Bill',
'28', 'Susan', '25']
range

A Range object, representing the cell or range of cells that were edited

Range
namedValues

An object containing the question names and values from the form submission

{
  'First Name': ['Jane'],
  'Timestamp': ['6/7/2015 20:54:13'],
  'Last Name': ['Doe']
}

Google Docs events

Triggers allow Google Docs to respond when a user opens a document.

Open

(simple and installable)
authMode

A value from the ScriptApp.AuthMode enum

LIMITED
source

A Document object, representing the Google Docs file to which the script is bound

Document
user

A User object, representing the owner of the document (only available in simple triggers, and only if the current user is allowed to know the owner's email address, depending on a complex set of security restrictions)

amin@example.com

Google Forms events

The Google Forms-specific triggers let scripts respond when a user edits a form or submits a response.

Open

* (simple and installable)
authMode

A value from the ScriptApp.AuthMode enum

LIMITED
source

A Form object, representing the Google Forms file to which the script is bound

Form
user

A User object, representing the owner of the form (only available in simple triggers, and only if the current user is allowed to know the owner's email address, depending on a complex set of security restrictions)

amin@example.com

* This event does not occur when a user opens a form to respond, but rather when an editor opens the form to modify it.

Form submit

(installable)
authMode

A value from the ScriptApp.AuthMode enum

FULL
response

A FormResponse object, representing the user's response to the form as a whole

FormResponse
source

A Form object, representing the Google Forms file to which the script is bound

Form

Add-on events

The onInstall() trigger runs automatically when a user installs an add-on.

Install

(simple)
authMode

A value from the ScriptApp.AuthMode enum

FULL

Time-driven events

Time-driven triggers (also called clock triggers) let scripts execute at a particular time or on a recurring interval.

Time-driven (installable)
authMode

A value from the ScriptApp.AuthMode enum

FULL
year

The year

2015
month

Between 1 and 12

12
day-of-month

Between 1 and 31.

Because this property name contains dashes it must be accessed via e['day-of-month'] rather than dot notation.

31
day-of-week

Between 1 (Monday) and 7 (Sunday).

Because this property name contains dashes it must be accessed via e['day-of-week'] rather than dot notation.

7
week-of-year

Between 1 and 52.

Because this property name contains dashes it must be accessed via e['week-of-year'] rather than dot notation.

52
hour

Between 0 and 23

23
minute

Between 0 and 59

59
second

Between 0 and 59

59
timezone

The timezone

UTC

Send feedback about...

Apps Script
Apps Script