Audit Trail in Frappe Framework (v15): Complete Documentation

Audit Trail in Frappe Framework Version 15 provides a secure and immutable record of all document changes. It captures every update made to a DocType, along with timestamps, user information, and field-level modifications. This feature is critical for compliance, data integrity, and accountability within ERPNext and custom applications built on Frappe.

1. What Is Audit Trail in Frappe v15?

Audit Trail is a built-in mechanism in Frappe v15 that automatically records every change made to documents, including who made the change, when it was made, and what fields were modified. It ensures traceability and provides a detailed history of document revisions.

2. Why Audit Trail Matters

Audit Trail is essential for:

• Compliance (ISO, FDA, SOX, industry regulations)
• Ensuring accountability in multi-user environments
• Tracking unauthorized or accidental changes
• Maintaining historical versions of records
• Strengthening internal controls in ERP systems

Frappe v15 maintains these logs in a structured and secure format that cannot be tampered with through the UI.

3. How Audit Trail Works in Frappe v15

When a document is saved, the framework automatically:

1. Compares the current version of the document with the previous version
2. Detects changed fields
3. Creates a new version entry (Version DocType)
4. Logs:
   • Changed fields
   • Old and new values
   • Timestamp
   • User who triggered the change

This is handled internally by the frappe.model.document and frappe.versioning modules.

4. Where Audit Trail Logs Are Stored

Audit logs are stored in the built-in Version DocType.

Example Version Entry Structure:

Developers can fetch version logs programmatically:

versions = frappe.get_all(
"Version",
filters={"ref_doctype": "Sales Order", "ref_name": "SO-0005"},
fields=["name", "data", "owner", "creation"]
)

5. How to Enable Audit Trail in Frappe v15

Audit Trail is enabled using the “Track Changes” option inside a DocType.

Steps:

1. Open the DocType in Desk
2. Enable Track Changes
3. Save the DocType

Once enabled, all updates to documents of this type are versioned automatically.

6. Document Versioning Flow

When a document is modified:

1. Framework detects changed fields
2. Previous version is compared with new version
3. New Version entry is created
4. Change log is displayed in the document’s timeline

This ensures a complete historical view of the document lifecycle.

7. View Audit Trail from UI

Frappe Desk shows the version log in the Timeline panel of a document.

Users can view:

• Field changes
• Who updated the record
• Exact timestamps
• Old vs new values

This makes troubleshooting and compliance checks easier.

8. Important Audit Trail Features in Frappe v15

Field-level tracking

Only modified fields are logged.

Immutable logs

Entries cannot be edited or deleted through the user interface.

Version history display

Visible in Document Timeline.

Supports all DocTypes

Custom, standard, and child tables are supported.

JSON change storage

Efficient storage of field differences.

9. Example Audit Trail JSON Structure

A Version document contains a structured JSON diff:

{
"changed": [
{
"fieldname": "customer_name",
"old": "John Doe",
"new": "John D."
}
]
}

This makes the change log machine-readable and audit-ready.

10. Using Audit Trail Programmatically

Fetch versions for a document:

logs = frappe.get_all(
"Version",
filters={"ref_doctype": "ToDo", "ref_name": "TD-0001"},
fields=["*"]
)

Get detailed change diffs:

version = frappe.get_doc("Version", logs[0].name)
changes = version.get_data()

11. Best Practices for Audit Trail (Compliance Ready)

Enable Track Changes for all sensitive DocTypes

• Avoid storing sensitive credentials in text fields
• Use role permissions to control access to Version logs
• Never delete or truncate Version table
• Regularly export logs for compliance audits

12. Troubleshooting Audit Trail Issues

13. Industry Use Cases

ERPNext Accounting

Track edits to invoices, journal entries, and payments.

Manufacturing

Log changes in BOMs, Work Orders, or Quality Inspections.

HR & Payroll

Track modifications to Salary Structure, Employee records, and Attendance logs.

Healthcare

Regulatory audit readiness for patient and lab records.

14. Related Documentation (Cross-References)

• DocType Overview
• Users & Permissions
• Role-Based Access Control
• Frappe Security Features
• Versioning API (GitHub v15)

Conclusion

Audit Trail in Frappe v15 is a powerful and essential feature for maintaining data integrity, ensuring accountability, and meeting compliance requirements. With automatic versioning, immutable change logs, and easy access through both UI and API, it provides a reliable foundation for secure ERP applications.