access_log.md

Frappe Core Doctype: Access Log

The Access Log Doctype is a system utility in Frappe used to record and track user access to various documents, reports, and pages within the system. It helps administrators monitor user activity, especially concerning data exports and views of sensitive information.

Core Purpose

• To log instances where users view or export data.
• To provide an audit trail for data access and system usage.
• To help in troubleshooting or security analysis by showing who accessed what and when.

Key Files Defining Access Log

• access_log.json: Defines the schema (fields, properties, permissions) of the Access Log Doctype.
• access_log.py: Contains the server-side Python controller logic, primarily for creating log entries and managing old logs.
• access_log.js: Handles client-side JavaScript for interactions on the Access Log form, such as navigating to the logged document or report.
• access_log_list.js: (Standard list view JS, not analyzed in detail here but would customize the list appearance/behavior).

access_log.json - Schema Definition

The JSON file defines the structure and metadata for Access Log entries.

• Naming:
  • autoname: "hash"
  • naming_rule: "Random"
  • This means each log entry is assigned a unique, randomly generated hash as its name, ensuring unique identifiers.
• Key Fields:
  • user (Link to User): The user who performed the action.
  • timestamp (Datetime): The date and time of the access.
  • export_from (Data): The Doctype or context from which an export was initiated (e.g., "Sales Invoice", "Report").
  • reference_document (Data): The specific document name or identifier that was accessed or is related to the log entry.
  • method (Data): The specific method or action that was logged (e.g., "export_csv", "printview", "get_list").
  • file_type (Data): If a file was exported/downloaded, this field stores its type (e.g., "CSV", "PDF").
  • report_name (Data): If a report was accessed, its name is stored here.
  • filters (Code): If a report was accessed with specific filters, those filters (usually as a JSON string) are logged.
  • columns (HTML Editor): For exports, this might store the list of columns/fields that were exported.
  • page (HTML Editor): If a raw HTML page view was logged, its content might be stored or referenced.
  • show_document (Button): A button on the form to navigate to the reference_document.
  • show_report (Button): A button on the form to navigate to the report_name with its filters.
• Permissions:
  • By default, only users with the "System Manager" role have read, delete, export, etc., permissions. This restricts access to potentially sensitive log data.
• Other Properties:
  • track_seen: 1 (Enabled) - Views of the Access Log documents themselves are tracked.
  • Most fields are read_only because log entries are system-generated and not meant for manual editing.

access_log.py - Server-Side Logic

The Python controller handles the creation and maintenance of log entries.

• AccessLog(Document) Class: The standard controller class.
• clear_old_logs(days=30) (Static Method):
  • Provides a mechanism to periodically clean up old access logs.
  • By default, it deletes logs older than 30 days. This is crucial for database performance and storage management.
  • This method can be called via a scheduled job (e.g., daily or weekly).
• make_access_log(...) (Whitelisted Function):
  • This is the core function used throughout the Frappe framework to record an access event.
  • It's called when a user exports data, views a print format, accesses certain reports, etc.
  • Parameters: doctype, document, method, file_type, report_name, filters, page, columns.
  • It constructs a new "Access Log" document with these details and the current frappe.session.user.
  • It uses db_insert() for immediate saving or deferred_insert() if the system is in a read-only database state.
  • Includes a retry mechanism for DuplicateEntryError, though this is less likely with a "hash" autoname.
  • Ensures frappe.db.commit() is called for logs generated during GET requests (like print views) to persist the log entry immediately.

access_log.js - Client-Side Logic

The JavaScript file enhances the user experience when viewing an Access Log entry.

• frappe.ui.form.on("Access Log", { ... });: Standard form event binding.
• show_document: function (frm):
  • Triggered when the "Show Document" button (defined in access_log.json) is clicked.
  • Uses frappe.set_route to navigate the user directly to the form view of the document specified in frm.doc.export_from (as Doctype) and frm.doc.reference_document (as document name).
• show_report: function (frm):
  • Triggered when the "Show Report" button is clicked.
  • If frm.doc.report_name includes a /, it's treated as a direct route to a page-based report.
  • Otherwise, it's assumed to be a standard query report. It parses frm.doc.filters (if they exist) and navigates to the report view using frappe.set_route("query-report", frm.doc.report_name, filters).

How It's Used (Examples)

• When a user exports a list of "Sales Invoices" to CSV, an Access Log entry is created:
  • user: The user who exported.
  • export_from: "Sales Invoice" (or the report name if exported from a report).
  • reference_document: Might be empty or refer to a specific report if applicable.
  • file_type: "CSV".
  • method: "export_csv".
• When a user views a print format of a "Purchase Order PO-001":
  • user: The user.
  • export_from: "Purchase Order".
  • reference_document: "PO-001".
  • method: "printview".

Administration and Maintenance

• Viewing Logs: System Managers can view Access Logs from the list view, filter by user, document, date, etc.
• Cleanup: The clear_old_logs function should be scheduled (e.g., via "Scheduled Job Type") to run regularly to prevent the tabAccess Log table from growing indefinitely.

This Doctype is crucial for system auditing and understanding data access patterns within a Frappe application.