Skip to content

activity_log.md

Latest commit

 

History

History
107 lines (85 loc) · 7.66 KB

activity_log.md

File metadata and controls

107 lines (85 loc) · 7.66 KB

Frappe Core Doctype: Activity Log

The Activity Log Doctype in Frappe serves as a versatile record-keeping system for various user and system activities. It's designed to track "update feeds," providing a timeline of events, including user authentications, document interactions, and other notable system operations.

Core Purpose

  • To maintain a chronological record of system and user activities.
  • To track user login, logout, and impersonation events.
  • To link activities to specific documents or timelines within the application.
  • To provide a basis for user activity feeds and audit trails beyond just data access (which is covered by "Access Log").

Key Files Defining Activity Log

  • activity_log.json: Defines the schema (fields, properties, permissions).
  • activity_log.py: Contains the server-side Python controller logic for creating, validating, and managing log entries.
  • activity_log.js: Handles client-side JavaScript, primarily to make the form read-only.
  • feed.py: Contains helper functions to generate specific activity logs for authentication events (login/logout).
  • activity_log_list.js: (Standard list view JS, not analyzed in detail here but would customize the list appearance/behavior).

activity_log.json - Schema Definition

This JSON file outlines the structure and metadata for Activity Log entries.

  • Description: "Keep track of all update feeds."
  • document_type: "Setup"
  • Key Fields:
    • subject (Small Text, Required, In List View): The primary title or summary of the activity. This is also the title_field.
    • user (Link to User, Default: __user, Read Only): The user who performed or is associated with the activity.
    • full_name (Data, In List View): The full name of the associated user.
    • communication_date (Datetime, Default: "Now"): The timestamp of the activity.
    • ip_address (Data): The IP address of the user, typically logged for authentication events.
    • operation (Select): Specifies the type of operation, with predefined options like "Login", "Logout", "Impersonate". Can be extended for other custom operations.
    • status (Select, In List View): Indicates the outcome or state of the activity (e.g., "Success", "Failed", "Linked", "Closed").
    • content (Text Editor): Allows for a more detailed message or content related to the activity.
    • reference_doctype (Link to DocType) & reference_name (Dynamic Link to reference_doctype): Links the activity to a specific document in the system.
    • reference_owner (Read Only): Fetched from the owner of the reference_name document.
    • timeline_doctype (Link to DocType) & timeline_name (Dynamic Link to timeline_doctype): Used to associate the activity with a specific document's timeline.
    • link_doctype (Link to DocType, Read Only) & link_name (Dynamic Link to link_doctype, Read Only): Provides another generic way to link the activity to a document.
  • Permissions:
    • By default, "System Manager" role has read access. Other roles might be granted permissions as needed for specific activity types they should see.
  • Other Properties:
    • track_seen: 1 (Enabled) - Views of Activity Log documents themselves are tracked.
    • search_fields: "subject" - Allows searching based on the log's subject.
    • sort_field: "creation", sort_order: "DESC" - Logs are typically viewed in reverse chronological order.

activity_log.py - Server-Side Logic

The Python controller manages the lifecycle and utility functions for Activity Log entries.

  • ActivityLog(Document) Class:
    • before_insert(): Automatically populates full_name (from the user field) and sets the date (likely an internal field, as communication_date is in JSON) to the current time.
    • validate():
      • Calls set_status(): If the log is new and linked to a reference_doctype and reference_name, it sets the status to "Linked".
      • Calls set_timeline_doc(self): This utility function (from frappe.core.utils) likely processes timeline_doctype and timeline_name to correctly associate this log with a document's timeline view.
      • Calls set_ip_address(): If operation is "Login" or "Logout", it records the current request's IP address.
    • clear_old_logs(days=90) (Static Method): Provides a function to delete activity logs older than a specified number of days (defaulting to 90 days). This is important for database maintenance.
  • on_doctype_update() (Global Function):
    • Called during bench migrate.
    • Ensures that database indexes are created on (reference_doctype, reference_name) and (timeline_doctype, timeline_name) fields to optimize query performance when filtering or fetching logs related to specific documents.
  • add_authentication_log(subject, user, operation="Login", status="Success") (Global Function):
    • A dedicated helper to easily create Activity Log entries for authentication events.
    • It simplifies logging logins, logouts, or impersonations by pre-filling some fields and inserting the log, ignoring permissions for this system-level logging.

activity_log.js - Client-Side Logic

The client-side JavaScript for Activity Log is minimal.

  • frappe.ui.form.on("Activity Log", { ... });:
    • refresh: function (frm):
      • Calls frm.disable_form(). This ensures that the Activity Log form is always read-only when viewed by a user, as these logs are system-generated and not intended for manual editing.

feed.py - Authentication Feed Logic

This file provides functions that are typically hooked into Frappe's authentication system to generate specific Activity Log entries.

  • login_feed(login_manager):
    • Triggered upon successful user login (for non-Guest users).
    • Creates an Activity Log entry with a subject like "[Full Name] logged in" using add_authentication_log.
  • logout_feed(user, reason):
    • Triggered when a user logs out (for non-Guest users).
    • Creates an Activity Log entry with a subject like "[Full Name] logged out: [Reason]" and sets the operation to "Logout", also using add_authentication_log.

How It's Used (Examples)

  • User Login: When "john.doe@example.com" logs in successfully, an Activity Log is created:
    • user: "john.doe@example.com"
    • full_name: "John Doe"
    • subject: "John Doe logged in"
    • operation: "Login"
    • status: "Success"
    • ip_address: The user's IP address.
  • Document Comment: When a user comments on "Sales Order SO-001":
    • An Activity Log (or a similar feed-generating mechanism using Communication Doctype which then might create an Activity Log) could be created:
      • user: The commenting user.
      • subject: "User commented on Sales Order SO-001"
      • content: The comment text.
      • reference_doctype: "Sales Order"
      • reference_name: "SO-001"
      • status: "Linked" (or similar)
  • System Events: Can be used by developers to log custom system events or milestones.

Administration and Maintenance

  • Viewing Logs: System Managers (or other roles with permission) can view Activity Logs. These logs often form the basis of document timelines or user activity feeds.
  • Cleanup: The clear_old_logs function should be scheduled to run regularly (e.g., via "Scheduled Job Type") to manage database size, typically retaining logs for a period like 90 days.

The Activity Log Doctype provides a flexible way to track a wide array of interactions and events within Frappe, contributing to auditability and user-facing timelines.