jorgecuadros-platform/docs/RENEWAL_NOTICES.md

Insurance Renewal Notices ("Atlas" reports)

Staff refer to this report in the UI as "the Atlas report", but Atlas isn't a report — it's a carrier: ATLAS, S.A. is one of the insurance companies (COMP column) SEGUROS brokers policies for, alongside QUALITAS, S.A. and others. The legacy frontend (SEGUROS 16.mdb) never parameterized carrier or coverage tier in its renewal-notice report — it cloned the entire report + query chain once per carrier per coverage variant instead. This doc explains that clone pattern and the underlying workflow so the new platform can replace ~40 cloned Access objects with one parameterized feature.

Why this needed extra tooling

objects.json/LEGACY_DATABASES_OBJECTS.md (see migration/catalog_objects.py) only capture report names — DAO's catalog interface doesn't expose a report's RecordSource or control layout, only the full Access object model does, and that model refused to load here ("The Visual Basic for Applications project in the database is corrupt", a common failure mode for old .mdb files opened in a newer Access build).

The workaround: Application.SaveAsText(acReport, name, path) exports a report's complete design as plain text without touching the VBA project. The raw (binary-blob-stripped) exports for the ATLAS renewal reports are committed in migration/legacy_report_defs/:

• AMPL_R_RENEW_X_MES_NEW_ATLAS_13.txt — Auto/Amplia (full coverage)
• AMPL_RENEW_X_MES_NEW_ATLAS_2013.txt — Auto/Amplia, alternate batch
• RC_RENEW_X_MES_NEW_ATLAS_13.txt — Auto/RC (liability only)
• RCR_RENEW_X_MES_NEWATLAS_2013.txt — Auto/RC, renewal-of-renewal variant
• LIC_RENEW_X_VENCE_ATLAS_2013.txt — Driver's-license insurance

(PrtDevMode/PrtMip/OleData/GUID binary properties — printer settings and object GUIDs, no business meaning — were stripped so the files are readable text instead of multi-hundred-KB hex dumps.)

The report chain

Each report is bound to a query that layers 2–3 other queries, filtered to one carrier, with two typed parameters staff fill in every run:

Report: AMPL R RENEW X MES NEW ATLAS 13
  RecordSource -> Query: AMPL R RENEW CALC ATLAS 13
    FROM [AMPL R CALC VIG], [AMPL R MENS]     (in-force calc view + installment schedule)
    WHERE COMP = "ATLAS, S.A."
      AND DatePart("m",[HASTA]) = [TECLEE MES DE VENCIMIENTO (1 A 12)]   -- typed param
      AND DatePart("yyyy",[HASTA]) = [TECLEE AÑO DE VENCIMIENTO (1999)]  -- typed param

Report: LIC RENEW X VENCE ATLAS 2013
  RecordSource -> Query of the SAME NAME (query and report share a name)
    FROM [LIC MENS], LIC INNER JOIN DATGRAL ... INNER JOIN [VIGENT CASA] ...
    WHERE DatePart("m",[hasta]) = [TECLEE MES DE VENCIMIENTO 1 A 12]
      AND DatePart("yyyy",[hasta]) = [TECLE AÑO VENCIMIENTO (1999)]
      AND LIC.COMP = "ATLAS, S.A."

Staff pick a line of business, type the expiry month + year, and the report prints one notice per matching policy for that carrier that month. On screen the report is captioned "AVISO DE RENOVACION" (auto lines) or "R E N E W A L N O T I C E" (license-insurance line). Every page prints the notice twice (identical top-half/bottom-half sections) — one copy to mail, one for the office file.

The multi-notice (reminder) workflow

Renewal reminders escalate through three generations, each its own report clone, with a matching CONTROL ... companion report (a send/checklist log):

Generation	Report suffix	Control/log report
1st notice	RENEW / (bare)	CONTROL <LOB> RENEW X MES
2nd notice	RENEW2	CONTROL <LOB> RENEW2 X MES (or X MES sibling)
3rd notice	RENEW3	CONTROL <LOB> RENEW3 X MES

This pattern repeats per line of business: AMPL/AMPL R (auto full coverage), RC/RC R (auto liability), LIC (driver's license), RCR, MF/MF2/MF3 (home/multi-risk), MCA2, ME, INCEN (fire) — none of it is visible from the table schema alone, only from the report/query names (see docs/LEGACY_DATABASES_OBJECTS.md, "What the Reports actually reveal").

What's hardcoded vs. what's real policy data

The extracted designs show the letter body mixes two very different kinds of content:

1. Per-policy data, pulled live from the query: customer id, policy number, vehicle (make/model/body/engine), expiry date.
2. Static label text baked into the report design, re-typed by hand every time a batch was cloned for a new rate or carrier — e.g. (from AMPL_R_RENEW_X_MES_NEW_ATLAS_13.txt):
   • "COLLISION DEDUCTIBLE $ 500.00 Dls. THEFT DEDUCTIBLE $ 1000.00 Dls. ..."
   • "New Renewal annual Premium $ 365.25 Dls."
   • "Total Annual Premium $ 405.25 Dls"
   • the whole CSL/medical-coverage recommendation and rental-car upsell paragraphs

None of those dollar figures are formulas — they're literal text, which is why there are so many near-duplicate reports: a new coverage tier or rate meant cloning the whole report and hand-editing the labels, rather than changing a parameter.

The underlying data these figures should come from already exists on the source tables and is preserved (unmapped-but-captured) in Policy.coveragesJson after migration — confirmed against docs/LEGACY_DATABASES.md's table appendix:

Legacy column	Sanitized coveragesJson key	Meaning
COBERTURA	cobertura	Coverage days/territory tier (30/40/50/365)
CSL LIMITE	csl_limite	Combined single limit (liability)
GASTOS MEDICO	gastos_medico	Medical coverage amount
SERVICIO ADICIONAL	servicio_adicional (LICENCIAS: servicio_adiconal, a source typo)	Add-on service flag
PROPIEDADES	propiedades	Property-damage coverage amount
PERSONAS	personas	Per-person liability amount

(Policy.netPremium/total/currency are already first-class columns — see packages/database/prisma/schema.prisma.)

Migration implication: a rebuilt renewal notice should render these from data (one parameterized template), not from report design text. See RenewalNotice in schema.prisma and the aviso-renovacion entry in apps/api/src/reports/reports.registry.ts for the first cut at this.

Built 2026-08-01/02. The three generations above are now RenewalNotice.generation 1/2/3, mailed by apps/api/src/renewals/ on an operator-editable cadence (default 06:00 daily) and driven from the Pólizas tab of /notificaciones. The CONTROL … X MES companion reports have no equivalent and need none: every attempt — sent, failed, or skipped for a missing address — lands in email_notification_log. See MASS_EMAIL_NOTIFICATIONS.md and INSURANCE_FEATURES_SPEC.md §1. This document stays a record of the legacy report chain, not of what shipped.

Caveats

• Only the ATLAS variants were extracted verbatim; the QUALITAS and "generic" (no-carrier-suffix) clones weren't pulled but are presumed structurally identical modulo the COMP filter and hardcoded figures.
• coveragesJson key names above are derived from migration/extract.py's sanitize_column_name (lowercase, non-alphanumeric → _) applied to the source column names in docs/LEGACY_DATABASES.md, not verified against a live migrated database (no staged output was present in this environment). Confirm against real data before wiring a template to these keys.