Complete the steps described in the rest of this page, and in about ten minutes
you'll have created a Google Forms add-on that uses triggers to send an email
when a user responds to the form. To see what the add-on looks like when it's
finished, just install
Form Notifications
from the Google Forms Add-ons store.
Set it up
- Create a
new Google
Form.
If you are presented with a welcome screen, give the form a title and choose
a theme.
- From within your new form, click the More
more_vert menu and select Script editor....
If you are presented with a welcome screen, click Blank Project.
- Create a new HTML file by selecting the menu item File > New > HTML file.
Name this file
sidebar (Apps Script adds the .html extension
automatically).
- Repeat the previous step to create one more HTML file named
about.html.
- Replace the content of those files with the following content, respectively:
code.gs
/**
* @OnlyCurrentDoc
*
* The above comment directs Apps Script to limit the scope of file
* access for this add-on. It specifies that this add-on will only
* attempt to read or modify the files in which the add-on is used,
* and not all of the user's files. The authorization request message
* presented to users will reflect this limited scope.
*/
/**
* A global constant String holding the title of the add-on. This is
* used to identify the add-on in the notification emails.
*/
const ADDON_TITLE = 'Form Notifications';
/**
* A global constant 'notice' text to include with each email
* notification.
*/
const NOTICE = 'Form Notifications was created as an sample add-on, and is' +
' meant for' +
'demonstration purposes only. It should not be used for complex or important' +
'workflows. The number of notifications this add-on produces are limited by the' +
'owner\'s available email quota; it will not send email notifications if the' +
'owner\'s daily email quota has been exceeded. Collaborators using this add-on on' +
'the same form will be able to adjust the notification settings, but will not be' +
'able to disable the notification triggers set by other collaborators.';
/**
* Adds a custom menu to the active form to show the add-on sidebar.
*
* @param {object} e The event parameter for a simple onOpen trigger. To
* determine which authorization mode (ScriptApp.AuthMode) the trigger is
* running in, inspect e.authMode.
*/
function onOpen(e) {
try {
FormApp.getUi()
.createAddonMenu()
.addItem('Configure notifications', 'showSidebar')
.addItem('About', 'showAbout')
.addToUi();
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Runs when the add-on is installed.
*
* @param {object} e The event parameter for a simple onInstall trigger. To
* determine which authorization mode (ScriptApp.AuthMode) the trigger is
* running in, inspect e.authMode. (In practice, onInstall triggers always
* run in AuthMode.FULL, but onOpen triggers may be AuthMode.LIMITED or
* AuthMode.NONE).
*/
function onInstall(e) {
onOpen(e);
}
/**
* Opens a sidebar in the form containing the add-on's user interface for
* configuring the notifications this add-on will produce.
*/
function showSidebar() {
try {
const ui = HtmlService.createHtmlOutputFromFile('sidebar')
.setTitle('Form Notifications');
FormApp.getUi().showSidebar(ui);
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Opens a purely-informational dialog in the form explaining details about
* this add-on.
*/
function showAbout() {
try {
const ui = HtmlService.createHtmlOutputFromFile('about')
.setWidth(420)
.setHeight(270);
FormApp.getUi().showModalDialog(ui, 'About Form Notifications');
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Save sidebar settings to this form's Properties, and update the onFormSubmit
* trigger as needed.
*
* @param {Object} settings An Object containing key-value
* pairs to store.
*/
function saveSettings(settings) {
try {
PropertiesService.getDocumentProperties().setProperties(settings);
adjustFormSubmitTrigger();
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Queries the User Properties and adds additional data required to populate
* the sidebar UI elements.
*
* @return {Object} A collection of Property values and
* related data used to fill the configuration sidebar.
*/
function getSettings() {
try {
const settings = PropertiesService.getDocumentProperties().getProperties();
// Use a default email if the creator email hasn't been provided yet.
if (!settings.creatorEmail) {
settings.creatorEmail = Session.getEffectiveUser().getEmail();
}
// Get text field items in the form and compile a list
// of their titles and IDs.
const form = FormApp.getActiveForm();
const textItems = form.getItems(FormApp.ItemType.TEXT);
settings.textItems = [];
for (let i = 0; i < textItems.length; i++) {
settings.textItems.push({
title: textItems[i].getTitle(),
id: textItems[i].getId()
});
}
return settings;
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Adjust the onFormSubmit trigger based on user's requests.
*/
function adjustFormSubmitTrigger() {
try {
const form = FormApp.getActiveForm();
const triggers = ScriptApp.getUserTriggers(form);
const settings = PropertiesService.getDocumentProperties();
const triggerNeeded =
settings.getProperty('creatorNotify') === 'true' ||
settings.getProperty('respondentNotify') === 'true';
// Create a new trigger if required; delete existing trigger
// if it is not needed.
let existingTrigger = null;
for (let i = 0; i < triggers.length; i++) {
if (triggers[i].getEventType() === ScriptApp.EventType.ON_FORM_SUBMIT) {
existingTrigger = triggers[i];
break;
}
}
if (triggerNeeded && !existingTrigger) {
const trigger = ScriptApp.newTrigger('respondToFormSubmit')
.forForm(form)
.onFormSubmit()
.create();
} else if (!triggerNeeded && existingTrigger) {
ScriptApp.deleteTrigger(existingTrigger);
}
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Responds to a form submission event if an onFormSubmit trigger has been
* enabled.
*
* @param {Object} e The event parameter created by a form
* submission; see
* https://developers.google.com/apps-script/understanding_events
*/
function respondToFormSubmit(e) {
try {
const settings = PropertiesService.getDocumentProperties();
const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
// Check if the actions of the trigger require authorizations that have not
// been supplied yet -- if so, warn the active user via email (if possible).
// This check is required when using triggers with add-ons to maintain
// functional triggers.
if (authInfo.getAuthorizationStatus() ===
ScriptApp.AuthorizationStatus.REQUIRED) {
// Re-authorization is required. In this case, the user needs to be alerted
// that they need to reauthorize; the normal trigger action is not
// conducted, since authorization needs to be provided first. Send at
// most one 'Authorization Required' email a day, to avoid spamming users
// of the add-on.
sendReauthorizationRequest();
} else {
// All required authorizations have been granted, so continue to respond to
// the trigger event.
// Check if the form creator needs to be notified; if so, construct and
// send the notification.
if (settings.getProperty('creatorNotify') === 'true') {
sendCreatorNotification();
}
// Check if the form respondent needs to be notified; if so, construct and
// send the notification. Be sure to respect the remaining email quota.
if (settings.getProperty('respondentNotify') === 'true' &&
MailApp.getRemainingDailyQuota() > 0) {
sendRespondentNotification(e.response);
}
}
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Called when the user needs to reauthorize. Sends the user of the
* add-on an email explaining the need to reauthorize and provides
* a link for the user to do so. Capped to send at most one email
* a day to prevent spamming the users of the add-on.
*/
function sendReauthorizationRequest() {
try {
const settings = PropertiesService.getDocumentProperties();
const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
const lastAuthEmailDate = settings.getProperty('lastAuthEmailDate');
const today = new Date().toDateString();
if (lastAuthEmailDate !== today) {
if (MailApp.getRemainingDailyQuota() > 0) {
const template =
HtmlService.createTemplateFromFile('authorizationEmail');
template.url = authInfo.getAuthorizationUrl();
template.notice = NOTICE;
const message = template.evaluate();
MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
'Authorization Required',
message.getContent(), {
name: ADDON_TITLE,
htmlBody: message.getContent()
});
}
settings.setProperty('lastAuthEmailDate', today);
}
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Sends out creator notification email(s) if the current number
* of form responses is an even multiple of the response step
* setting.
*/
function sendCreatorNotification() {
try {
const form = FormApp.getActiveForm();
const settings = PropertiesService.getDocumentProperties();
let responseStep = settings.getProperty('responseStep');
responseStep = responseStep ? parseInt(responseStep) : 10;
// If the total number of form responses is an even multiple of the
// response step setting, send a notification email(s) to the form
// creator(s). For example, if the response step is 10, notifications
// will be sent when there are 10, 20, 30, etc. total form responses
// received.
if (form.getResponses().length % responseStep === 0) {
const addresses = settings.getProperty('creatorEmail').split(',');
if (MailApp.getRemainingDailyQuota() > addresses.length) {
const template =
HtmlService.createTemplateFromFile('creatorNotification');
template.summary = form.getSummaryUrl();
template.responses = form.getResponses().length;
template.title = form.getTitle();
template.responseStep = responseStep;
template.formUrl = form.getEditUrl();
template.notice = NOTICE;
const message = template.evaluate();
MailApp.sendEmail(settings.getProperty('creatorEmail'),
form.getTitle() + ': Form submissions detected',
message.getContent(), {
name: ADDON_TITLE,
htmlBody: message.getContent()
});
}
}
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
/**
* Sends out respondent notification emails.
*
* @param {FormResponse} response FormResponse object of the event
* that triggered this notification
*/
function sendRespondentNotification(response) {
try {
const form = FormApp.getActiveForm();
const settings = PropertiesService.getDocumentProperties();
const emailId = settings.getProperty('respondentEmailItemId');
const emailItem = form.getItemById(parseInt(emailId));
const respondentEmail = response.getResponseForItem(emailItem)
.getResponse();
if (respondentEmail) {
const template =
HtmlService.createTemplateFromFile('respondentNotification');
template.paragraphs = settings.getProperty('responseText').split('\n');
template.notice = NOTICE;
const message = template.evaluate();
MailApp.sendEmail(respondentEmail,
settings.getProperty('responseSubject'),
message.getContent(), {
name: form.getTitle(),
htmlBody: message.getContent()
});
}
} catch (e) {
// TODO (Developer) - Handle exception
Logger.log('Failed with error: %s', e.error);
}
}
- Create three more HTML files:
authorizationEmail.html
, creatorNotification.html, and
respondentNotification.html. Replace the content of those files with
the following content, respectively:
respondentNotification.html
- Select the menu item File > Save all. Name your new script
"Form Notifications Quickstart" and click OK. (The script's name is shown
to end users in several places, including the authorization dialog.)
When you have completed this process, you will have a project with 1 script file
and 5 HTML files.
Try it out
- Switch back to your form. Using the Add item select box, add a text
question to your form. Under Question Title, enter 'Email Address' and
click Done. You can create other form items if you like.
- After a few seconds, a Form Notifications Quickstart sub-menu will appear
under the Add-ons extension
menu. (If you chose a different name for your script,
that name appears instead.) Click Add-ons > Form Notifications
Quickstart, and in the resulting dialog click Configure notifications.
- A dialog box requesting script authorization appears. Click Continue.
- The add-on sidebar then appears. To test it, click the Notify me check
box and enter your email address. Also set the Send notifications after
box to '1'. Click Save.
- Click Preview so that you can submit a response. From here, enter
some information into the form elements and click Submit. If you have
done everything correctly, the add-on emails you a short notification
saying someone has responded to your form. Had you not changed the
Send notifications after every box, the add-on would have waited until
the form had 10 submissions (the default) before emailing you a notice.
- To test the respondent notifications, go back to the sidebar and click the
Notify respondents checkbox. The first select box lists the question
titles for each text question in your form. Choose the question you labeled
'Email Address'. If the 'Email Address' option does not appear, make sure
you've added a text item to your form named 'Email Address' (as stated in
Step 1), and reopen the sidebar by clicking Add-ons > Form Notifications
Quickstart, and in the resulting dialog clicking
Configure notifications.
- Change the text in the Notification email body text area to say what you
what to tell the respondents to your form.
- Go back to the form, fill out another submission and click Submit.
If you have done everything correctly, two emails should be sent this
time—one to the form creator and one to the form respondent. The form
creator email address is the one you entered into the sidebar directly; the
form respondent email address is what the respondent supplied in the 'Email
Address' question.
Publish
Since this is an example add-on, our tutorial ends here. If you were developing
a real add-on, the last step would be to
publish it for other people
to find and install.
Learn more
To continue learning about how to extend Google Docs with Apps Script, take a
look at the following resources:
