Spreadsheet Update¶
Spreadsheet_update.js implements schema migration for audit spreadsheets. spreadsheetUpdateData is the ordered manifest of every version from 3.0.1 to 3.0.10, each with a version number, a human-readable release note, and a required_confirmation flag. The migration bodies live in src/v3Legacy/v3/updates/<num>.js and are located by naming convention: updateSpreadsheetToVersion_<num> plus an optional updateSpreadsheetCompleted_<num> callback.
Behavior¶
- On open, updates that need no confirmation are applied silently (
spreadsheetUpdateNotRequireConfirmation, called fromonOpenSheetCallback). - Updates that require confirmation are surfaced in the "check updates" sidebar screen. While any confirmation-required update is pending, the whole add-on menu is replaced by a single "Updates pending" item and onEdit automation is disabled.
- The sidebar can also scan the user's Drive and update many audits in bulk, walking each one up version by version.
- If an update fails, the developer list is emailed with the spreadsheet id, failed version, and stack trace, and the migration stops so no later update runs against a half-migrated sheet.
Functions¶
| Function | Description | Facing |
|---|---|---|
spreadsheetUpdateNotRequireConfirmation(ssId) |
Runs on spreadsheet open. Bails out if any confirmation-required update is pending; otherwise silently applies the leading no-confirmation updates. | Trigger (on open) |
getScreenDataForCheckUpdates(ssId) |
Bootstrap payload for the check-updates sidebar screen: spreadsheet info plus pending confirmation-required updates. | User-facing (sidebar) |
checkUpdatesGetAudits(currentOrMultiple, multipleScope) |
Returns the list of audits to update: just this spreadsheet, or 'v3' / 'pre_v3' / 'all' audits found in Drive. Filters out audits already at the highest version and annotates each with its detected version. |
User-facing (sidebar) |
upOneVersionAuditById(ssId, title, processPropertyKeyName) |
Applies exactly one pending version step to the given audit, pushing progress messages to the sidebar. The sidebar calls it repeatedly to walk an audit up to the latest version. | User-facing (sidebar) |
markAsNotAudit(ssId) |
Tags a Drive file with the not_issue_list property so it is excluded from future bulk-update scans. Lets users dismiss false positives. |
User-facing (sidebar) |
getSpreadsheetVersion(ssId) |
Resolves the stored version, trying: the version key on the Configuration sheet, cell B1 of the legacy Settings sheet, then the legacy Drive file property. Returns 0 for pre-v3 spreadsheets. |
Shared |
saveSpreadsheetVersion(ssId, versionNum) |
Writes the new version back using the same three-tier fallback. | Shared |
availableUpdatesRequiredConfirmation(ssId) / availableUpdatesNotRequiredConfirmation(ssId) |
The leading run of pending updates that do (or do not) require confirmation. | Shared |
getAvailableUpdates(ssId) |
All manifest entries newer than the current version, sorted ascending. | Shared |
getLowestUpdateNumber() / getHighestUpdateNumber() |
Bounds of the manifest; the highest number decides whether an audit is up to date. | Shared |
doUpdateSpreadsheet(ssId, updatesList) |
Applies each update in sequence; on failure emails the developers and rethrows. | Shared |
doUpdateSpreadsheetSpecificUpdate_(ssId, update) |
Applies one update: resolves the function by name, throws if missing or erroring, flushes writes, saves the new version, runs the optional completed-callback. | Internal |
getUpdateFunctionName(versionNum) / getUpdateCompletedFunctionName(versionNum) |
Naming-convention helpers. | Internal |