Troyon Data — User Guide

This is a day-to-day guide for people who actually operate the system — data-entry staff and whoever triages a failed scrape — not another architecture doc (see Overview, TroyenAPI Reference, TroyenDataHelpers Reference for those).

Logging into TroyenDataWeb (the admin portal)

• Go to /Login. There is no password field — login is email + a 6-digit TOTP code from an authenticator app.
• Flow: enter your email → the system confirms it's a known, active, TOTP-configured account → enter the current code from your authenticator app → you're in (a jwt cookie is issued).
• You cannot self-register. A SuperAdmin creates your account via an invite link (UserManagementController.CreateInvite). Opening that link walks you through scanning a QR code to link your authenticator app; you're logged in automatically once your first code is confirmed.
• Roles: SuperAdmin, DevLead, SupportLead, Developer, Support. Only a SuperAdmin can create invites, deactivate/reactivate users, change roles, or reset someone's TOTP (issues a fresh setup link).
• Auto-logout after 60 minutes of inactivity (you'll get a warning at 55 minutes) — save your work if you step away.

Finding your way around the portal

Nav item	Where it goes	What it's for
Dashboard	Dashboard/IndexV2	Landing page after login.
Races → Pre Race	PreRace/Index	Review upcoming races/meetings before they run.
Races → Results	Result/Index	Manual result entry (has a result-entry modal).
Horses	HorsesList/Index, HorseDetails/Index	Browse/edit horse master data.
Master Data → Courses / Country / Exchange Rates	Courses/Index, Country/Index, Country/ImportExchangeRates	Reference data used across meetings/races.
Logs → Unmapped Meetings	MissingMeetings/Index	Meetings without a matched rsMeetingId — needs manual mapping.
Logs → Missing Silks	MissingSilks/Index	Runners with no silk image — feeds into the Silk Generator.
Logs → Mismatch Races	UnvalidatedRaces/Index	Races flagged as inconsistent (isValidated == false).
Logs → Audits / Requests / System Logs	Audits/Index, Requests/Index, SystemLogs/Index	Troubleshooting trails. A "Recent Error Logs" modal in the nav bar has a Resolve/Resolve-All workflow gated by a hardcoded developer PIN (1333).
Comments → EQ / RP / RN	EqComments/Index, RpComments/Index, RnComments/Index	Manage race write-ups/comments by source.
Silk Generator	/SilkV2	Generate jockey/horse silk images (pairs with Missing Silks above).
Instruction → Scrapers	Instruction/Scrapers	The in-app version of this guide's "when a scraper fails" section below — always check there too, it may be more current.
System (config/dev)	LLM Prompts, Config, Client Config, API Key Management, Customer Data Templates, Transformation Rules	Config-level pages, more relevant to dev/ops than day-to-day data entry.
Profile menu (top right)	My Profile, My Activity, My Team (team leads only), User Management (SuperAdmins only), Sign Out	Account management.

There's also a "Delete Meetings" option added to TD Admin recently (per changelogs/CHANGELOG.troyon-data-web.md v3.4.0) — its exact placement in the nav wasn't confirmed in this pass, so if you don't see it, check under Pre Race or Master Data, or ask a dev-lead.

When a scraper fails: the backup chain

The portal's Instruction → Scrapers → Backup tab defines a fixed fallback order — this is the single most important workflow for a data-entry person to know. Run each tool only if the one before it failed:

1. Punter Main Scraper (primary) — the automated pipeline; always tried first.
2. Punter Web Scraper (1st backup) — standalone tool, VPN required for the whole run.
   • Download PunterWebScraper.zip from Google Drive (shared by your team lead), extract it fully (don't run from inside the zip), allow it through Windows SmartScreen ("More info → Run anyway", once per PC).
   • Run PunterWebScraper.exe — it prompts for Date (yyyy-MM-dd, defaults to today), Discipline, and optional Country. A browser window opens itself — leave it alone until you see "Press any key to close this window…".
   • Output/logs land next to the exe; send the logs folder to your team lead if it fails.
3. Neds Scraper (2nd backup) — this one is manual and runs through Rundeck, not a local exe:
   • Open the Meeting API endpoint shown in the in-app guide, copy the Country/Course/Date/Discipline values for the meeting you need.
   • Open the linked Rundeck job (rundeckthor.troyendata.com), paste those values in, click Run Job Now, and wait.
   • Verify: meeting scraped → saved to DB → DataDump/RaceCard JSON generated → uploaded to S3 (checklist is in the in-app guide).
4. RS DataDump Scraper (final fallback) — no VPN needed (opposite of #2).
   • Same Google-Drive/extract-zip/SmartScreen flow as #2.
   • Run it via run.bat, not rsdump.exe directly — double-clicking the exe will just flash and close instantly.
   • Prompts for Venue (track name or code, required), Date (defaults to today), Discipline (1–4 menu, 1 = thoroughbred).

To update any of these standalone tools: delete the old extracted folder and re-extract a fresh zip from Google Drive — don't try to patch in place.

Known gaps in this guide

• PunterScraperLauncher (the WPF GUI wrapper around the primary scraper) has no end-user install/usage doc anywhere in the repo — only a developer rebuild guide (PunterScraper/STANDALONE-APP.md). If you use this tool day-to-day, its fields map to --race-type/--start-date/--end-date/--country/--course/--ignoreCahce on the underlying scraper, but there's no walkthrough of the GUI itself to point to.
• The RsDataDump tool's source (and its bundled run.bat) wasn't found under any obviously-named folder in this checkout — it may live in a separate repo, or its wrapper is generated only at publish time.