# Sheets Import

Browser tool to import a Google Sheets programme workbook into cx v2 pack JSON files.
**https://contexts.live/org/{slug}/tools/cx-sheets-import.html**

---

## What it does

Reads a multi-tab Google Sheets workbook structured as a cx programme. Fetches the
programme metadata tab, follows the link to the programme tab, then fetches each unit
tab. Builds a cx v2 pack JSON for each unit plus one for the programme itself, and
downloads them all as a zip.

The sheet must be publicly shared (view access) — no authentication is used.

---

## Sheet structure

The workbook expects three kinds of tabs:

### Programme metadata tab
Vertical key/value layout — column A is the field name, column B is the value.

| A | B |
|---|---|
| id | BBCP |
| lines | https://docs.google.com/…?gid=131364363 |
| url | https://… |
| language | en |

The `lines` field must contain the URL of the programme tab (with gid).

### Programme tab
Horizontal layout with headers in row 1: `type`, `en`, `filename`, `url`, and optional
language columns.

Rows before the first `unit` row are treated as programme metadata. Each `unit` row
becomes a pack reference line in the programme pack, and the `url` column provides the
link to that unit's tab.

### Unit tabs
Horizontal layout with headers in row 1. The `type` column drives parsing:

- Rows before the first `text` row → unit metadata (field name from `type` column)
- From the first `text` row onwards → subtitle lines

---

## Column mapping

| Sheet column | Pack field | Notes |
|---|---|---|
| Bare language codes (`en`, `zh`, `ja`) | `st.text.{lang}` | |
| Colon-separated triples (`ad:text:en`) | `ad.text.en` | Dot-nested |
| `speaker` | `sp` | |
| `type` | `type` | Always present on lines |
| Everything else | plain field | Kept as-is |

Meta row values follow the same column mapping and are wrapped under the field name
from the `type` column.

---

## Usage

1. Open the sheet in Google Sheets and navigate to the programme metadata tab
2. Copy the URL from the browser address bar (must include `?gid=…`)
3. Paste into the Sheets Import tool and click **Fetch**
4. Review the programme metadata and unit list
5. Click **Import & Download ZIP** — fetches all unit tabs and downloads a zip

---

## Output

The zip contains one JSON file per unit plus one for the programme:

- `{programme_id}.json` — programme pack with pack reference lines
- `{unit_filename}.json` — one per unit tab

---

## Notes

- The tool runs entirely in the browser — nothing is uploaded to the server
- The sheet must be publicly shared (anyone with the link can view)
- The metadata tab URL must include a `gid=` parameter — navigate to that specific tab before copying the URL
- After import, load each pack into the editor to review and adjust before deploying