Event Objects
Page Summary
Apps Script can run a function automatically using simple or installable triggers when a specific event occurs.
When a trigger fires, an event object (
e) containing contextual information is passed to the function as an argument.This page details the fields within the event object for various trigger types across different Google services like Sheets, Docs, Slides, Forms, Calendar, and Workspace add-ons.
Events produced by installable triggers include a
triggerUidto identify the specific trigger.Calendar triggers indicate that a sync operation is needed, not which specific event changed.
Simple triggers andinstallable triggers let Apps Scriptrun a function automatically if a certain event occurs. When a trigger fires,Apps Script passes the function an event object as an argument, typically callede. The event object contains information about the context that caused thetrigger to fire. For example, the sample code below shows a simpleonEdit(e)trigger for a Google Sheets script that uses the event object to determine whichcell was edited.
functiononEdit(e){//Setacommentontheeditedcelltoindicatewhenitwaschanged.varrange=e.range;range.setNote('Last modified: '+newDate());}This page details the fields in the event object for different types oftriggers.
Events produced by installable triggers contain atriggerUid identifying the trigger that produced the event. This is helpful for scripts that have multiple installable triggers.Google Sheets events
The various Google Sheets-specific triggers let scripts respond to a user'sactions in a spreadsheet.
Open(simple andinstallable) | |
|---|---|
authMode | A value from the LIMITED |
source | A Spreadsheet |
triggerUid | ID of trigger that produced this event (installable triggers only). 4034124084959907503 |
user | A amin@example.com |
Change(installable) | |
|---|---|
authMode | A value from the FULL |
changeType | The type of change ( INSERT_ROW |
source | A Spreadsheet |
triggerUid | ID of trigger that produced this event. 4034124084959907503 |
user | A amin@example.com |
Edit(simple andinstallable) | |
|---|---|
authMode | A value from the LIMITED |
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 |
range | A Range |
source | A Spreadsheet |
triggerUid | ID of trigger that produced this event (installable triggers only). 4034124084959907503 |
user | A amin@example.com |
value | New cell value after the edit. Only available if the edited range is a single cell. 10 |
Form submit(installable) | |
|---|---|
Caution: Make sure you use this form submit trigger withSpreadsheetTriggerBuilder. | |
authMode | A value from the FULL |
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']} |
range | A Range |
triggerUid | ID of trigger that produced this event. 4034124084959907503 |
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'] |
Google Docs events
Triggers allow Google Docs to respond when a user opens a document.
Open(simple andinstallable) | |
|---|---|
authMode | A value from the LIMITED |
source | A Document |
triggerUid | ID of trigger that produced this event (installable triggers only). 4034124084959907503 |
user | A amin@example.com |
Google Slides events
Triggers allow Google Slides to respond when a user opens a presentation.
Open(simple) | |
|---|---|
authMode | A value from the LIMITED |
source | A Presentation |
user | A amin@example.com |
Google Forms events
The Google Forms-specific triggers let scripts respond when a user edits a formor submits a response.
Open* (simple andinstallable) | |
|---|---|
authMode | A value from the LIMITED |
source | A Form |
triggerUid | ID of trigger that produced this event (installable triggers only). 4034124084959907503 |
user | A amin@example.com |
* This event does not occur when a user opens a form to respond, but ratherwhen an editor opens the form to modify it.
Form submit(installable) | |
|---|---|
Caution: Make sure you use this form submit trigger withFormTriggerBuilder. | |
authMode | A value from the FULL |
response | A FormResponse |
source | A Form |
triggerUid | ID of trigger that produced this event. 4034124084959907503 |
Google Calendar events
Calendar triggers fire when a user's calendar events are updated (created,edited, or deleted).
These triggers do not tell you which event changed or how it changed.Instead, they indicate that your code needs to do an incremental sync operationto pick up recent changes to the calendar. For a full descriptionof this procedure, see theSynchronizing resources guide for theCalendar API.
To synchronize with Calendar in Apps Script, perform the following steps:
- Enable theCalendar advanced service forthe script project. The built-inCalendar service isn't sufficient forthis workflow.
- Determine what calendars should be synchronized. For each such calendar,perform aninitial syncoperation using the Calendar advanced service'sEvents.list() method.
- The result of the initial sync returns a
nextSyncTokenfor that calendar.Store this token for later use. - When the Apps Script
EventUpdatedtrigger fires indicating a calendarevent change, perform anincremental syncfor the affected calendar using the storednextSyncToken. This isessentially anotherEvents.list()request, but providing thenextSyncTokenlimits the response to onlyevents that have changed since the last sync. - Examine the response of the sync to learn what events were updated andhave your code respond appropriately. For example, you can log the change,update a spreadsheet, send email notices, or take other actions.
- Update the
nextSyncTokenyou stored for that calendar with the one returnedby the incremental sync request. This forces the next sync operation toonly return the most current changes.
410 error. When this happens, your code should conduct afull syncand replace all the stored synced data and tokens you have for that calendar.EventUpdated(installable) | |
|---|---|
authMode | A value from the FULL |
calendarId | The string ID of the calendar where the event update occurred. susan@example.com |
triggerUid | ID of trigger that produced this event. 4034124084959907503 |
Google Workspace add-on events
TheonInstall() trigger runsautomatically when a user installs anadd-on.
Install(simple) | |
|---|---|
authMode | A value from the FULL |
Google Chat app events
To learn about event objects in Google Chat, seeReceive and respond to interactions with your Google Chat app.
Time-driven events
Time-driven triggers(also called clock triggers) let scripts execute at a particular time or on arecurring interval.
| Time-driven (installable) | |
|---|---|
authMode | A value from the FULL |
day-of-month | Between Because this property name contains dashes it must be accessed via 31 |
day-of-week | Between Because this property name contains dashes it must be accessed via 7 |
hour | Between 23 |
minute | Between 59 |
month | Between 12 |
second | Between 59 |
timezone | The time zone. UTC |
triggerUid | ID of trigger that produced this event. 4034124084959907503 |
week-of-year | Between Because this property name contains dashes it must be accessed via 52 |
year | The year. 2015 |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-11 UTC.