Activity history in a business app: what to record
Short answer: An activity history should record who did what, to which record, when, and what changed from and to, for every action that matters to the business, including actions taken by the system itself. Decide up front which records need history, how long it's kept, who can see it, and how it's protected from editing. Writing these decisions into the spec costs a few hours; adding history after launch means some months of changes are simply gone.
When a price changes on a quote, a customer's address is edited, or an order is cancelled, someone eventually asks "who did that, and when?" If the app can't answer, the conversation turns into guesswork. Activity history is easy to underspecify because nobody needs it until something goes wrong. Below is a blueprint you can drop into a requirements document, with a "decide this" table at the end.
What an entry should contain
OWASP's Logging Cheat Sheet says application logs must record "when, where, who and what" for each event. For business activity history, that becomes:
- When: a timestamp in a consistent time zone (store UTC, display local).
- Who: the user, or the system process, integration or scheduled job that acted.
- What action: created, updated, deleted, status changed, exported, approved.
- Which record: the type and ID (Quote 1042, Customer 318).
- What changed: the fields, with before and after values.
- Where from: the screen, API or import that triggered it, if useful.
- Why (optional): a reason field for sensitive changes such as discounts or cancellations.
The Django package django-simple-history is one example of how frameworks handle this: it stores a "change reason" in a history_change_reason field, according to its historical model docs. Other frameworks have comparable auditing packages.
User actions vs system actions
Plenty of changes don't come from a person clicking a button:
- An integration updating stock from the warehouse system
- A nightly job closing expired quotes
- A payment provider's webhook marking an invoice paid
- A bulk import
Each should appear in the history with a clear actor ("Stock sync", "Nightly expiry job"), not as a blank or as the admin who set it up. OWASP also advises not excluding events from "known" sources such as internal systems or monitoring, though you can flag them by type.
Watch out for bulk operations
Automatic history often relies on hooks that fire when a single record is saved. django-simple-history's common issues page notes that it saves history via a post-save signal, and that for bulk create, bulk update and queryset updates, signals aren't sent and history isn't saved automatically; the package provides utility functions to work around this. Whatever the framework, put "bulk changes and imports must be recorded" in the spec and test it.
Viewing history where people need it
A history table that only developers can query isn't much use. Specify:
- Per-record history: a "History" tab on each important record, newest first, showing who, when and what changed in plain language ("Price changed from €120 to €95").
- Global activity view: for admins, filterable by user, record type, action and date.
- Readable values: show names, not IDs ("Assigned to Aoife", not "user_id 14").
- Permissions: decide who sees what. Staff may see history on their own records; admins see everything.
What to leave out
OWASP lists data that should usually not be recorded directly in logs, but removed, masked, hashed or encrypted instead, including passwords, session identifiers, access tokens, payment card data, encryption keys, and sensitive personal data. In activity history terms:
- Don't store full card or bank details, even "before" values.
- Mask sensitive fields in before/after views ("changed", without the values).
- Exclude noisy technical fields (last-seen timestamps, cache counters). django-simple-history, for example, has an
excluded_fieldsoption for this.
Protection from tampering
History is only trustworthy if ordinary users can't edit it. OWASP says logging data must be protected from tampering, unauthorised access, modification and deletion, and recommends processes to detect if logging has stopped.
Practical requirements:
- History entries are append-only in the app: no edit or delete buttons.
- Database permissions prevent the app's normal user role from updating or deleting history rows, where feasible.
- Admin actions on history (exports, any purges) are themselves recorded.
- An alert or check fires if history entries stop being written.
Retention
OWASP says log data shouldn't be destroyed before the required retention period and shouldn't be kept beyond it. Decide how long each type of history is kept, for example longer for financial records than for edits to a contact's notes, and plan automatic deletion after that. Check the rules where you operate for any required periods.
Exports
Specify who can export history, in what format (CSV is usually enough), with which filters, and that exports are logged. Large exports should run in the background and email a link, rather than timing out.
Performance
History tables grow fast. Ask for:
- Indexes on record type, record ID, user and timestamp
- Pagination on history views
- Writing history in the same transaction as the change, so you never get a change without its entry
- A plan for archiving old entries if the table becomes very large
The "decide this" table
| Decision | Options | Example answer (hypothetical) |
|---|---|---|
| Which records have history? | All / selected | Quotes, orders, customers, prices, user accounts |
| Field-level before/after? | Yes / action only | Yes, except masked fields |
| System actors named? | Yes / no | Yes, each integration and job named |
| Reason required? | Never / for sensitive actions | Discounts over a set level, cancellations |
| Who can view? | By role | Staff: own records; managers: team; admins: all |
| Retention | Per record type | Longer for financial records; shorter for notes |
| Tamper protection | App-only / app + database | App + database permissions |
| Exports | Who, format, logged? | Admins, CSV, logged |
| Bulk changes | Recorded? | Yes, tested |
| Monitoring | Alert if logging stops? | Yes |
FAQ
Is activity history the same as undo?
No. History tells you what happened; restoring a previous state is a separate feature with its own design.
Can't we just use the server logs?
Server logs are for technical troubleshooting, often aren't kept long, and aren't readable per record by staff. Business history belongs in the app.
Will history slow the app down?
Writing one extra row per change is usually cheap. Slow history views come from missing indexes and unpaginated lists, which you can specify against.
Should logins be in the activity history?
Sign-ins, failed sign-ins and permission changes are worth recording, often in a separate security log alongside the business history.
Answers to "who changed this?" are easiest to build in from day one, so bring your app spec and we'll go through the history requirements together.