Skip to content

deleted_document.md

Latest commit

 

History

History
89 lines (72 loc) · 7.35 KB

deleted_document.md

File metadata and controls

89 lines (72 loc) · 7.35 KB

Frappe Core Doctype: Deleted Document

The Deleted Document Doctype in Frappe serves as a temporary holding place or a "recycle bin" for documents that have been deleted from the system. When a user deletes a document, a record is created in "Deleted Document" storing a snapshot of the original document's data. This allows for auditing of deletions and provides a mechanism for restoring accidentally deleted documents.

Core Purpose

  • To keep a record of all documents deleted from the system.
  • To store the data of the deleted document at the time of deletion.
  • To allow System Managers to review deleted documents.
  • To provide a facility to restore deleted documents.
  • To help in maintaining an audit trail of document lifecycles, including deletions.

Key Files Defining Deleted Document

  • deleted_document.json: Defines the schema (fields, properties, permissions) of the Deleted Document Doctype.
  • deleted_document.py: Contains the server-side Python controller logic, primarily for the restoration process and for clearing old deleted document records.
  • deleted_document.js: Handles client-side JavaScript for the Deleted Document form, providing "Restore" or "Open" buttons.
  • deleted_document_list.js: Customizes the list view for Deleted Documents.
  • test_deleted_document.py: Contains unit tests for the restoration logic.

deleted_document.json - Schema Definition

This JSON file outlines the structure for each Deleted Document record.

  • Key Fields:
    • deleted_name (Data, In List View, Read Only): The original name (ID) of the document that was deleted. This is also the title_field for this Doctype.
    • deleted_doctype (Data, In List View, Read Only): The Doctype of the document that was deleted (e.g., "Sales Order", "Item").
    • data (Code, Read Only): This is a crucial field that stores a JSON string representation of the entire deleted document's data at the moment it was deleted.
    • restored (Check, Default: 0, In List View, Read Only): A flag (0 or 1) indicating whether this deleted document has subsequently been restored.
    • new_name (Read Only): If the document was restored, this field will store the name (ID) of the newly created (restored) document. This is important because the original name might be unavailable or the document might be restored with a modified name.
  • in_create: 1: This property ensures that users cannot manually create "Deleted Document" records through the standard UI. These records are generated exclusively by the system when a document is deleted.
  • Permissions:
    • Only users with the "System Manager" role have permissions to read these records, delete them (which means permanently removing the deleted document's record from this log), and export them.
    • There are no create or write permissions for any role, as these records are system-managed and generally immutable after creation (except for the restored and new_name fields updated by the system upon restoration).
  • Other Properties:
    • row_format: "Compressed" - For a more compact list view of deleted documents.
    • track_changes: 1 - Changes to the Deleted Document records themselves (e.g., when restored status changes) are versioned.
  • Module: "Core"

deleted_document.py - Server-Side Logic

The Python controller handles the restoration of documents and the cleanup of old deleted records.

  • DeletedDocument(Document) Class:
    • no_feed_on_delete = True: Prevents the system from creating an Activity Log entry when a "Deleted Document" record itself is permanently purged.
    • clear_old_logs(days=180) (Static Method):
      • Provides a utility to permanently delete "Deleted Document" records that are older than a specified number of days (defaulting to 180 days).
      • This is important for database maintenance to prevent the tabDeleted Document table from growing indefinitely. This can be scheduled as a regular background job.
  • restore(name, alert=True) (Whitelisted Function):
    • The core function responsible for restoring a document.
    • name: The name of the "Deleted Document" record to be restored.
    • It checks if the document has already been marked as restored.
    • Deserializes the JSON data stored in the data field back into a Frappe document object.
    • Attempts to insert() the document.
      • Handles Workflow/Status Issues: If an error like frappe.DocstatusTransitionError occurs (e.g., trying to insert a document that was previously Submitted or Cancelled), it resets the docstatus to 0 (Draft) and clears any workflow state field before re-attempting the insertion. This ensures documents are restored in a modifiable state.
    • Adds a comment to the newly restored document indicating its origin.
    • Updates the original "Deleted Document" record by setting restored = 1 and populating new_name with the ID of the restored document.
  • bulk_restore(docnames) (Whitelisted Function):
    • Allows System Managers to restore multiple deleted documents in a single operation from the list view.
    • It iterates through the provided list of "Deleted Document" names, calls the restore() function for each, and provides progress updates.
    • It categorizes the results into restored, already restored (invalid), and failed attempts.

deleted_document.js - Client-Side Logic

This script provides the user interface elements on the "Deleted Document" form.

  • frappe.ui.form.on("Deleted Document", { ... });:
    • refresh: function (frm):
      • If frm.doc.restored is true (the document has been restored):
        • It adds an "Open" button. Clicking this button navigates the user to the form view of the restored document (using frm.doc.deleted_doctype and frm.doc.new_name).
      • If frm.doc.restored is false (the document has not been restored):
        • It adds a "Restore" button. Clicking this button calls the server-side restore method.
        • On successful restoration, the form is reloaded (frm.reload_doc()) to reflect the updated status (e.g., the "Restore" button changes to "Open").

How It's Used

  1. When a user with appropriate permissions deletes a document (e.g., a "Task", "Sales Invoice") in Frappe:
    • The system automatically creates a new record in the "Deleted Document" Doctype.
    • This record stores the original Doctype, original name, and a JSON snapshot of the deleted document's data.
  2. A System Manager can later navigate to the "Deleted Document" list view to see all such records.
  3. They can open a specific "Deleted Document" record.
    • The data field will show the JSON content of the original document.
    • If not yet restored, a "Restore" button will be visible.
  4. Clicking "Restore":
    • The system attempts to re-create the document from the stored JSON data.
    • If successful, the "Deleted Document" record is updated (restored = 1, new_name is set), and the button on the form changes to "Open".
  5. The "Deleted Document" records themselves can be periodically purged using the clear_old_logs function (typically via a scheduled job) to manage database size.

This Doctype acts as an important safety net, allowing recovery from accidental deletions and providing an audit trail of what was deleted.