Google recently announced the general availability of the new Google Forms API. For developers familiar with Google Apps Script for some time it has been possible to create, access, and modify Google Forms through the Forms Service. In this post I will highlight why Google Apps Script developers might want to use the new Forms API and some resources I’ve found useful for working with the new API in Apps Script projects. As part of this I’d like to share my experience of using the Forms API within a Google Forms Add-on and some factors to consider if you are particularly interested in watching for Google Form edits.
TL;DR The Google Forms REST API provides an alternative method for managing forms and responses. For Apps Script developers it is likely you’ll want to stick with using the Forms Service. The Forms REST API creates an option to receive notifications for responses and edits to a form’s content and settings. It is easy to create and renew Google Form watches within a Google Forms Add-on. To revert to an earlier version of a form you need to store your own copy of the instance of Form object as this is accessible via either the Forms or Google Drive APIs.
Getting started with the Forms API in Google Apps Script
For existing Google Apps Script developers the official Forms API documentation provides some great guidance to help you get started. A recommended starting point is the page on Compare REST API with Forms Service, which highlights the key differences and opportunities between the REST API and Forms Service.
Generally there is good parity between the Forms API and Forms Service in terms of creating and modifying forms, with the exception of setting correct answers for question types that are not multiple choice. There may be scenarios where batch updating or getting the entire form object using the REST API is the preferred option.
There are currently no plans to make the Forms REST API available as an Apps Script ‘Advance Service’, but developers can still use the Forms REST API using UrlFetchApp and the documentation provides guidance on setting up an Apps Script project for this purpose.
The documentation also includes instructions on setting a sample web app which lets you explore the Forms REST API. I found doing this incredibly useful for trying out the various service endpoints.
Tip: even if you don’t want to use the sample web app the source is on GitHub and includes Apps Script code for all the Forms API endpoints. I’ve been using these in my own projects to speed up development.
Watching Google Forms for edits and responses with Cloud Pub/Sub
In this Totally Unscripted episode we were fortunate to have Christian Schalk come on and talk about the Forms API while it was in beta. One of the areas we discussed was the ability to set up push notifications from forms. As part of this you can watch for form submission, which is also possible using the Google Apps Script Forms Service. The Forms REST API does however also open up the opportunity to watch for edits and setting changes in a form, which is not possible in the Forms Service.
Getting started with forms.watches and Cloud Pub/Sub
The documentation includes a guide to Set up and receive push notifications, which gives a great conceptual overview of what is required and how to set up/handle push notifications. My additional notes on the setup process are:
- Using the Apps Script/Forms API web app example referenced above made it very easy to create, delete and renew a test watch
- For testing I used same GCP project as the web app to Set up a Cloud Pub/Sub topic
As I was unfamiliar with Cloud Pub/Sub this was an area I had to spend a bit more time getting my head around. If you are coming from an Apps Script developer background my notes on each of the steps in the current ‘Set up a Cloud Pub/Sub topic’ are below in emphasis:
To set up a Cloud Pub/Sub topic, do the following:
- Complete the Cloud Pub/Sub Prerequisites. – recommend you review pricing first (step 3)! I found using the Google Cloud Product calculator easier to get an estimate. For testing if you do not enable topic message retention monthly cost should be $0.00. Also if you are using an existing GCP project you can skip this step
- Set up a Cloud Pub/Sub client. – for testing I also skipped this step and instead used a Google Sheet with a publish web app as a test endpoint to collect Pub/Sub push notifications (I wouldn’t recommend this for production, but worked well for getting started). If you copy this Google Sheet and open the script editor there are instructions for setting up.
- Review the Cloud Pub/Sub pricing, and enable billing for your Developer Console project.
- Create a Cloud Pub/Sub topic one of three ways:
- using the Developer Console (easiest) – for testing I recommend this option
- using the command line tool (for simple programmatic use) or
- using the Cloud Pub/Sub API.
- Create a Subscription in Cloud Pub/Sub to tell Cloud Pub/Sub how to deliver your notifications. – if you are using the copied Google Sheet/web app in step 2 make sure this is a push notification using the published web app url as the endpoint (it is not currently possible to enable authentication for an Apps Script endpoint published as a web app as the doPost headers are not readable)
- Finally, before creating watches that target your topic, you need to grant permission to the Forms notifications service account ([email protected]) to publish to your topic.
Tip: If you are interested in additional guidance on setting up push notifications, perhaps with the view of putting something into production I recommend reading Google Forms Push Notifications with Node.js by Rubén Restrepo
Once you’ve gone through the step above you will have a topicName you can add to the your Forms API sample Apps Script web app (if adding a topicName don’t forget to Manage Deployment in the Script Editor and make an edit to push a new published version).
A quick recap of what we’ve done so far:
- Copied the Forms API sample Apps Script web app
- Created and associated it with a GCP project with the Forms API enabled
- Created and notification logging Google Sheet deployed as a web app
- Added a Cloud Pub/Sub topic and push subscription using the logging Google Sheet web app url as a push notification endpoint
- Updated the Forms API sample Apps Script web app to include the
topicNamefrom the associated GCP Cloud Pub/Sub
Creating and renewing forms.watches in a Google Forms Add-on
There are a couple of scenarios where you might want to set up event handlers for Google Forms using the Forms REST API. For form responses you may want to bypass Apps Script and use Cloud Pub/Sub to get and process responses using your own infrastructure. In the case of a form edit based behaviour your only option is to use the Forms REST API.
There is no reason you have to use Google Apps Script for creating and renewing watching, but if you are looking to develop something as a Google Forms Add-on, using Apps Script is currently your only option. Hopefully from the official documentation you’ve also already picked up that when a forms watch is created it only lasts 7 days before it is deleted, unless it is renewed.
To handle forms.watches creation and renewal I’ve published a Google Forms Add-on forms.watches Handler Example on GitHub. In this example, the addFormWatch() function creates a watch and stores the watch id in Properties Service and also adds a time based trigger to renew the watch based on the returned expiry date. The renewWatchHandler() renews the watch via the Forms API also creating a new time based trigger to renew again when the watch expires.
Unless there is a script error the watch will be continually renewed. To break out of this loop there is a deleteFormWatch() which calls the Forms API to list any watches created by the user for a Google Form ID, before deleting these and any time-based triggers used for watch renewal.
Important: “Notifications do not contain detailed form or response data. After each notification is received, a separate API call is required to fetch fresh data.”
Google Forms API – Notification responses
As noted in the documentation creating forms.watches only let you know there has been a Google Form response or edit which means if you are developing a Google Forms Add-on you will need to factor in additional infrastructure to handle fetching/processing the new data.
Notes on Google Forms revision history
As part of Google Docs, Sheets and Slides the user interface includes access to the file’s version history (File > Version history > See version history). Google Forms doesn’t have this feature and given the new Google Forms REST API creates a way to get notifications when a Form has been changed I was interested to see if this functionality could easily be replicated.
In theory the answer is ‘yes’ but as far as I can see it would require getting, storing and handling the Form response object after each edit. This is actually a bit of an anomaly in my opinion for Google Workspace editors as previous versions of a Doc, Sheet or Slide can be exported using Google Drive API Revisions (for more explanation on this here is a very useful Stack Overflow post on how to revert back a Google Doc to a previous revision using Google Apps Script).
Whilst the Google Drive API Revisions resource doesn’t include export links for Google Forms it does include information about the last modifying user so you can see who made the edit, just not what they changed.
Note: The revisionId returned by forms.get is different to the ID of the revision used in drive.revisions.get
Summary
Hopefully this has been a helpful summary of what is possible using the Google Forms REST API. For Google Apps Script developers it creates some additional ways to manage Google Forms which are useful to keep in mind particularly if you encounter limits with the Forms Service. I found there is quite a bit to get your head around particularly if you are new to Cloud Pub/Sub notifications. If there are any hints, tips I’ve missed or if you have any questions feel free to get in touch, either through this site or on Twitter/LinkedIn.
