Skip to main content

GForms Proof of Concept

This guide covers the GForms Proof of Concept: manually installing the Apps Script sidebar into a real Google Form and validating it end to end. For the automated test suite (Vitest, Tiers 1–4) see GForms Add-on Tests.

The add-on is installed as a form-bound script — the simplest setup for testing. All source files live in AddOns/GForms/.

Prerequisites​

  1. A reachable ROPA deployment. Apps Script's UrlFetchApp runs on Google's servers, so it cannot reach localhost:3000. Use the production app (https://rat.gd) or a Vercel preview URL.

  2. Your Google account must exist in Clerk. The sidebar sends Session.getActiveUser().getEmail() to /api/gforms/activities, which looks that email up in Clerk. Test with a Google account whose email is a Clerk user belonging to at least one organization. Otherwise every call returns 401 No Clerk user found for this email.

  3. A logging spreadsheet you own. constants.gs ships with a hardcoded LoggingFileId. If your account cannot open that sheet, every Generate fails at updateLogging (Logging.gs calls SpreadsheetApp.openById). Create a blank Google Sheet, take its ID from the URL (docs.google.com/spreadsheets/d/<ID>/edit), and use that. The script creates the year-named tab and headers automatically.

Setup​

1. Create the test form and open its script editor​

  • Create a Google Form at forms.google.com.
  • In the form editor: ⋮ (More) → Apps Script. This opens a script project bound to that form.

2. Copy the code in​

  • Replace the default Code.gs content with AddOns/GForms/constants.gs.
  • Add three more script files (+ → Script) named ShowSidebar, ProcessForm, and Logging, and paste in the corresponding .gs contents.
  • Add an HTML file (+ → HTML) named exactly Sidebar and paste Sidebar.html.

3. Set the manifest​

  • Project Settings (gear) → check "Show appsscript.json manifest file".
  • Replace appsscript.json with the checked-in AddOns/GForms/appsscript.json.
  • If testing against a preview deployment instead of rat.gd, change urlFetchWhitelist to that domain. The whitelist is a prefix match — a mismatch makes every API call fail.

4. Edit the constants​

var Constants = {
  ROPA_API_BASE: "https://rat.gd",   // or your preview URL, no trailing slash
  DefaultLocale: "en",
  LoggingFileId: "<your-sheet-id>",  // the sheet from prerequisite 3
};

5. Authorize on first run​

Save all files, select the showSidebar function in the editor toolbar, and click Run once. Google walks you through the OAuth consent (the six scopes from the manifest). An unverified personal script shows the "Google hasn't verified this app" screen — click Advanced → Go to … (unsafe). This is normal for a bound test script.

Test Plan​

Reload the form editor tab, then click the puzzle-piece (add-ons) icon → your script's menu → "Obre". The sidebar opens, fetches your org's activities, and switches to the org's default locale automatically.

#ScenarioExpected result
1anonymous = yes, indirect = no"No clause needed" message; nothing added to the form
2anonymous = no, no special categoriesOnly the required Art. 13 info checkbox is added (with the activity's public URL)
3anonymous = no, several special categories checkedTwo checkbox items: consent list (optional) + Art. 13 info clause (required)
4Run Generate again with different answersPrevious GDPR items are deleted (tracked by ID in document properties) before the new ones are inserted — regardless of language
5Change the language dropdownSidebar labels and generated clause text switch locale (labels come from GET /api/gforms/locales/:locale)
6Account belonging to multiple orgsOrg picker appears first; activities load after selecting an org

Each successful run also:

  • appends a row to the logging sheet (Logging.gs), and
  • emails the executing user a summary ("GForms: Resultat de l'execució").

Troubleshooting​

  • Sidebar doesn't open — showSidebar catches errors and logs them. In the script editor open Executions (left sidebar) to see the failure. Most common causes: 401 (email not in Clerk), urlFetchWhitelist / ROPA_API_BASE mismatch, or the deployment being unreachable.
  • Sanity-check the API without Apps Script — before debugging the sidebar:
    • https://rat.gd/api/gforms/locales/en in a browser should return the gforms message JSON (no auth required).
    • https://rat.gd/{locale}/gforms with your Clerk login exercises the same activities/clause endpoints with none of the Apps Script moving parts.
  • Generate fails after the questionnaire — almost always the logging sheet: verify LoggingFileId points to a sheet your account can edit.
  • Testing unreleased API changes — the form-bound script calls whatever ROPA_API_BASE points to. Local working-tree changes are not exercised until deployed; point ROPA_API_BASE at a preview deployment (and update urlFetchWhitelist) to test them.