Send to A11ytrain¶

🚂 Send to A11ytrain (src/sendToA11ytrain/) is a sidebar workflow that validates an audit spreadsheet and pushes its contents to A11yTrain, Equal Entry's web app where ACRs are generated.

Workflow¶

Open. The menu item calls showSidebar(), which renders Sidebar.html in the Sheets sidebar titled "Equal Entry - ACR".
Validate. The user clicks Validate. The sidebar calls processInput(data) via google.script.run.
Server-side validation. processInput → updateList() → validateAudit(), which resets the per-spreadsheet error and warning logs, loads the Issue Titles - v3 catalog and the Platform/Browser by Scope technology table, then parses Configuration (getAuditConfig), Scenarios (getScenarios), and Results (getResults), and cross-checks with invalidAudit.
Results shown. The sidebar renders red error chips and yellow warning chips per sheet. Clicking a chip calls jumpTo(sheet, cellA1) to navigate straight to the offending cell. Rows with warnings on the Results sheet will not be sent to A11ytrain.
Choose options. With zero errors, a second form appears: Before Remediation / After Remediation radio buttons, plus advanced settings for "Do not mark as a test audit" (checked by default) and "Send to staging".
Send. After a confirmation prompt, the sidebar calls finalize_api(result).
Submission. finalize_api builds the payload (prepareApiData), checks whether an audit with the same project name already exists, prompts before overwriting an existing before/after issue list, blocks "after remediation" submissions when the Updated Delivery Date is missing, then POSTs to the staging or production A11yTrain REST API.
Confirmation. A modal dialog shows a link to the created issue list in the chosen environment.

What is sent¶

The JSON payload contains the sheet URL, an audit object (project name, company, product, summary, product description, parsed SO code, scope, WCAG level, VPAT short name, delivery dates), a scenarios map from the Scenarios tab, an issues array (one object per warning-free Results row, with resolved third-party company/product), and the flags fake, before_remediation, and after_remediation.

A separate legacy path (finalize) instead appends a summary row to a shared "Audits" tracking spreadsheet (tab <Year> Audits).

interface.js¶

Function	Description	Facing
`showSidebar()`	Renders the sidebar. Entry point wired to the add-on menu item.	User-facing (menu)
`processInput(input)`	The sidebar's RPC target. Re-validates the audit and returns `{isSuccess, el, finalize, link, staging, fake, beforeRemediation}` so the client can show errors or proceed to submission.	User-facing (sidebar)
`updateList(id?)`	Runs `validateAudit` and converts the errors and warnings into the HTML fragment of clickable per-sheet cards.	Internal

Util.js¶

Module-level shared state: errors, warnings (spreadsheet id → sheet → cell → messages), scenarioList, issueTitles, externalTech, links, and tableCoord (column-number-to-letter lookup).

Function	Description	Facing
`jumpTo(sheetName, position, id?)`	Activates the given cell so the user is scrolled to it. Invoked from the sidebar chips.	User-facing (sidebar)
`getDataFrom(audit, sheet)`	Full data range of a tab as a 2D array; `[]` if the tab is missing.	Internal
`getTechnologies(audit)`	Reads `Platform/Browser by Scope` cell by cell as rich text (capturing hyperlink URLs) into `externalTech`.	Internal
`fetchIssueTitles(id?)`	Parses `Issue Titles - v3` into `{successCriterion: {standard, level, titles[]}}` for validating the Issue and Success Criteria columns.	Internal
`createErrorsLog(audit)`	Initializes or resets the error and warning buckets for Configuration, Scenarios, and Results.	Internal
`buildRow(headers, objArray)`	Builds a tracker spreadsheet row from headers and source objects, appending today's date as "Last Update".	Internal
`buildRemediateRow(results)`	The post-remediation severity counts row.	Internal
`addLink(audit, auditList, config)`	Turns the Audit Name cell in the tracker into a hyperlink back to the audit spreadsheet.	Internal
`generateSheetLink(year)`	Direct URL to the `<Year> Audits` tab in the shared tracker, creating the tab if absent.	Internal
`modifyKey(obj, oldKey, newKey)`	Renames an object key in place.	Internal
`closeSidebar()`	Closes the sidebar (used after fatal validation errors during submission).	Internal

Validation modules¶

Function	File	Description
`getAuditConfig(audit)`	`getConfig.js`	Reads the Configuration tab as key/value pairs. Requires EE Project Name, Company Name, Audit Scope, and a Deliver Date; warns on a missing Updated Delivery Date. Parses the project-name convention (`SO###`, at least four `-` separated segments, a `Q1-Q4 YYYY` quarter) into `config.SO` and `config.Year`.
`getScenarios(audit)`	`getScenarios.js`	Reads the Scenarios tab, validates that each scenario header matches `S<n>: <name>`, counts scenarios and steps, and warns when a scenario has fewer than 8 steps. Populates `scenarioList` for Results validation.
`getResults(audit)`	`getResults.js`	Reads the Results tab, checks that 17 mandatory columns are present, and validates each row's EE Status, Unique Title, Scenario/URL, Repro Steps, Success Criteria, and Issue against the scenario list and issue-title catalog. Mostly empty rows are skipped; rows with any warning are excluded from the returned issue set. Returns `{Count, Issues}`.
`invalidAudit(audit, config, scenarios, issues)`	`Validations.js`	Cross-checks that the issue count does not exceed step count x scenario count, logs all accumulated errors and warnings, and returns true if any blocking errors exist.
`alreadyFinalized(config)`	`Validations.js`	Checks the shared tracker tab for a row already containing this audit's name.

Finalize.js and FinalizeApi.js¶

Function	Description	Facing
`validateAudit(id?)`	The validation orchestrator (see workflow above). Returns `[config, scenarios, issues, isInvalid]`.	Internal
`finalize(id?)`	Legacy "finalize to spreadsheet" path: validates, then appends a summary row to the `<Year> Audits` tracker tab. If already finalized, prompts "Add after remediation?" and writes the remediation counts next to the existing row.	User-facing (prompts)
`finalize_api(data)`	The API submission entry point (see workflow above).	User-facing (sidebar)
`prepareApiData(audit)`	Assembles the full JSON payload for A11yTrain.	Internal
`sendDataToAPIStaging(...)` / `sendDataToAPIProduction(...)`	POST the payload to the staging or production endpoint and store the resulting issue-list URL.	Internal

Known issues worth fixing

The A11yTrain API token is hard-coded in FinalizeApi.js source (staging and production). It should move to Script Properties like the OpenAI key.
buildRemediateRow repeats Major where Fixed appears to be intended, given the header order in Finalize.js.
In getResults, the Total count is summed over the wrong object, and headersToCheck is an accidental implicit global.
invalidAudit replaces the Results error bucket with a plain array, which breaks the cell-chip rendering for that case.