### SWDA / TPGateway Hub

Package soq-sg-tpgateway · permissions 90100–90104 (90105–90109 reserved) · Implementation guide: [SWDA TPGateway Sync Module](../engineering/modules/tpgateway/MODULE.md)

#### SWDA / TPGateway Hub

##### What this screen is

Reports live classes to SWDA (formerly SSG) through the TPGateway API: the course run and its sessions, learner enrolments and cancellations, attendance and Pass assessments. Admin → Education → SWDA TPGateway. Only live classes are synced; self-paced courses are not.

##### What you see

- **Sync hub** (`/admin/tpgateway`): counts per status (pending, needs data, synced, failed, skipped), records overdue or due within 5 days, filters by status, action and class, and per record the learner, SWDA deadline, SWDA reference and what is missing.
  - **Humanized Error Messages (Sprint 4):** Rather than raw HTTP 400 JSON payloads, the system translates SSG error responses into actionable plain-text guidance identifying the specific affected trainee (e.g., *"Invalid identification format for trainee Rachel Lee"* via `humanizedError()`).
  - **Interactive Record Actions:** Per-record **Retry** (resets status to `pending` to retry sync) and **Skip** (marks record as `skipped` to bypass unresolvable or exempt learner records without halting the batch queue). Global controls: **Sync now**, **Retry all failed**, and **Dry-run**.
- **Course run links** (`/admin/tpgateway/course-links`): one link per live class with its course reference number (CRN), mode of training, venue overrides, trainer and the SWDA run ID once published. **Push run update** re-sends a published run after you change the class or its sessions.
- **Settings & certificate** (`/admin/tpgateway/settings`): on/off, mode, UEN, training partner code, Corppass ID, course admin email, encryption key, default venue, deadlines, and the client certificate.
  - **Secret Masking & View Security (Sprint 4):** Sensitive credentials (encryption key, private key) are concealed using `maskSecret()` (e.g. `sec_••••••••1100`) and strictly withheld from view datasets, preventing accidental leakage in screen shares or logs.

##### Field / control guide

- **Send to SWDA automatically (every 5 minutes):** master switch, off by default. While off nothing is sent, but links can be prepared and the queue fills. 
- **Mode:** Mock (fake references, no call to SWDA; refused on production), UAT (SSG sandbox) or Production. UAT and Production need the UEN, TP code, encryption key and certificate. 
- **Encryption key:** the AES-256 key from the SSG Developer Portal for the chosen environment. Protected by secret masking (`maskSecret()`); never exposed in plaintext after saving. Leave blank later to keep it. 
- **Default venue:** used for every run unless the link overrides it. Floor, unit, postal code and room are required except for asynchronous eLearning and on-the-job training. 
- **Deadlines:** 14 days after the course start for enrolments and 14 days after the course end for attendance and assessments (SSG's rules); used for the overdue badges. 
- **Generate certificate / Download certificate (.pem):** creates our client certificate; upload the `.pem` on the SSG Developer Portal. The private key never leaves the server. 
- **Settings bag:** `soq_sg_tpgateway_settings`. The encryption key, private key and trainer ID numbers are encrypted with `APP_KEY`. 

##### How to complete the task

1. Run `php artisan migrate` and `php artisan soq:seed-tpgateway`; make sure the server cron runs `php artisan schedule:run` every minute. 
2. In Settings, enter the UEN and save, then **Generate certificate**, download it and upload it to the UAT app on the SSG Developer Portal. 
3. Enter the TP code, Corppass ID, course admin email, default venue and the UAT encryption key; choose UAT, switch sync on and save. 
4. In Course run links, link a live class to its CRN and fill in the trainer. 
5. In the Sync hub, open **Dry-run** on the course run to check the payload, then press **Sync now**. 
6. Fix the records marked "Needs data" (they are re-checked on every run) and watch the deadline column. 

**Notes / pitfalls:** A learner's enrolment is sent only when they have linked Singpass (the NRIC/FIN comes from Singpass), have a Singapore mobile number and a date of birth in their profile (or diploma application); otherwise the record waits as "Needs data". Attendance needs the Corppass ID setting. Editing a class after its run is published is not sent until you press **Push run update**. A published link cannot be deleted. Generating a new certificate breaks the connection until the new one is uploaded to SSG. Grants and SkillsFuture Credit amounts are not part of the enrolment yet.