History and snapshot design for GTM reporting

A recommendation that gets overwritten each time a model runs cannot explain why the final decision changed. Decide what history the business needs before choosing storage.

Choose the history shape

Need	Pattern	Example
Last change only	Field history	Owner changed from SDR to AE
Every decision run	Event or child record	Recommendation version and evidence
Point-in-time population	Scheduled snapshot	Pipeline state each Monday
Full audit trail	Append-only event log	Approval, override, and applied change

One pattern can serve more than one need. Do not make a snapshot carry per-record explanation if an event record is the useful unit.

Recommendation and final decision

Store at least:

• recommendation outcome and version;
• evidence and confidence band;
• final outcome, if someone changed it;
• reason code and actor;
• timestamps for recommendation and final decision; and
• the workflow run that consumed the result.

Keep old versions. A new recommendation should create a new event, not erase the old one.

Snapshot discipline

Name the snapshot clock, population filter, timezone, and source report. Record whether a failed run produced no snapshot or a marked incomplete snapshot. A missing snapshot is different from a zero population.

Salesforce reporting snapshots can save report results into a target object on a schedule, according to the official Salesforce documentation. Other platforms offer different historical features. Verify the current product behavior and retain the same business contract if the storage changes.

Choose the smallest history that answers the question

Use field history for who changed a specific value and when, an event model for business transitions and repeated workflow runs, and snapshots for the state of a population at a regular point in time. Do not snapshot every field by default. Define the question, required grain, retention period, and late-arriving behavior first.

Include stable subject and run IDs, event or snapshot time, source observation time, definition version, and the values needed to reproduce the measure. Decide whether corrections amend an earlier fact or create a new correction event. Preserve ingestion failures separately from a legitimate empty population.

Validate historical reporting

Rebuild one past result from the stored history and compare it with a known report or operating record. Test reopened records, owner changes, deleted records, late events, and definition changes. Monitor expected versus actual snapshot counts and the age of the latest successful capture. History that silently stops is worse than no history because it still looks authoritative.

Related: Reporting-ready workflow design, Evidence requirements and confidence, and Error, exception, and override reporting.