erpnext/transaction-deletion-import-logic-summary.md

Transaction Deletion CSV Import Logic - Updated Behavior

Auto-Detection of Company Field

When importing a CSV without a company_field column or with empty values, the system uses smart auto-detection:

Priority Order:

1. "company" field (most common convention)

   • Check if a field named company exists that links to Company DocType
   • ✅ Use "company" if found

2. First Company link field (custom fields)

   • If no "company" field, get all fields linking to Company DocType
   • ✅ Use the first one (sorted by field index)

3. No company field (DocTypes without company filtering)

   • If no Company link fields exist at all
   • ✅ Leave company_field as None/empty
   • ✅ Delete ALL records (no company filtering)

Import CSV Format

Minimal Format (Auto-Detection)

doctype_name,child_doctypes
Sales Order,Sales Order Item
Note,
Task,

Result:

• Sales Order: Auto-detects "company" field → Filters by company
• Note: No company field → Deletes all Note records
• Task: Has "company" field → Filters by company

Explicit Format (Recommended)

doctype_name,company_field,child_doctypes
Sales Order,company,Sales Order Item
Sales Contract,primary_company,Sales Contract Item
Sales Contract,billing_company,Sales Contract Item
Note,,

Result:

• Sales Order: Uses "company" field explicitly
• Sales Contract (row 1): Uses "primary_company" field
• Sales Contract (row 2): Uses "billing_company" field (separate row!)
• Note: No company field, deletes all records

Multiple Company Fields Example

doctype_name,company_field,child_doctypes
Customer Invoice,head_office,Customer Invoice Item
Customer Invoice,billing_company,Customer Invoice Item

Deletion Process:

1. Row 1 deletes: WHERE head_office = 'ABC Company'
2. Row 2 deletes: WHERE billing_company = 'ABC Company'
3. Documents with both fields = ABC get deleted in first pass
4. Documents with only billing_company = ABC get deleted in second pass

Validation Rules

✅ Accepted Cases

1. DocType with "company" field - Auto-detected
2. DocType with custom Company link field - Auto-detected (first field used)
3. DocType with multiple Company fields - Auto-detected (first field used), but user can add multiple rows
4. DocType with NO Company fields - Accepted! Deletes ALL records
5. Explicit company_field provided - Validated and used

❌ Rejected Cases

1. Protected DocTypes - User, Role, DocType, etc.
2. Child tables - Auto-deleted with parent
3. Virtual DocTypes - No database table
4. Invalid company_field - Field doesn't exist or isn't a Company link
5. DocType doesn't exist - Not found in system

Code Flow

# 1. Read company_field from CSV (may be empty)
company_field = row.get("company_field", "").strip()

# 2. Auto-detect if not provided
if not company_field:
    # Try "company" first
    if exists("company" field linking to Company):
        company_field = "company"
    else:
        # Check for other Company link fields
        company_fields = get_all_company_link_fields()
        if company_fields:
            company_field = company_fields[0]  # Use first
        # else: company_field stays empty

# 3. Validate if company_field was provided/detected
if company_field:
    if not is_valid_company_link_field(company_field):
        skip_with_error()

# 4. Count documents
if company_field:
    count = count(WHERE company_field = self.company)
else:
    count = count(all records)

# 5. Store in To Delete list
append({
    "doctype_name": doctype_name,
    "company_field": company_field or None,  # Store None if empty
    "document_count": count
})

Examples

Example 1: Standard DocType with "company" Field

CSV:

doctype_name,company_field,child_doctypes
Sales Order,,

Auto-Detection:

• Finds "company" field linking to Company
• Sets company_field = "company"
• Counts: WHERE company = 'Test Company'
• Result: Deletes only Test Company's Sales Orders

Example 2: Custom Company Field

CSV:

doctype_name,company_field,child_doctypes
Project Contract,,

Auto-Detection:

• No "company" field found
• Finds "contracting_company" field linking to Company
• Sets company_field = "contracting_company"
• Counts: WHERE contracting_company = 'Test Company'
• Result: Deletes only Test Company's Project Contracts

Example 3: No Company Field (Global DocType)

CSV:

doctype_name,company_field,child_doctypes
Note,,
Global Settings,,

Auto-Detection:

• No Company link fields found
• Sets company_field = None
• Counts: All records
• Result: Deletes ALL Note and Global Settings records

Example 4: Multiple Company Fields (Explicit)

CSV:

doctype_name,company_field,child_doctypes
Sales Contract,primary_company,Sales Contract Item
Sales Contract,billing_company,Sales Contract Item

No Auto-Detection:

• Row 1: Uses "primary_company" explicitly
• Row 2: Uses "billing_company" explicitly
• Both rows validated as valid Company link fields
• Result: Two separate deletion passes

Example 5: Mixed Approaches

CSV:

doctype_name,company_field,child_doctypes
Sales Order,,Sales Order Item
Sales Contract,billing_company,Sales Contract Item
Note,,

Result:

• Row 1: Auto-detects "company" field
• Row 2: Uses "billing_company" explicitly
• Row 3: No company field (deletes all)

User Benefits

✅ Flexible: Supports auto-detection and explicit specification ✅ Safe: Validates all fields before processing ✅ Clear: Empty company_field means "delete all" ✅ Powerful: Can target specific company fields in multi-company setups ✅ Backward Compatible: Old CSVs (without company_field column) still work

Migration from Old Format

Old CSV (without company_field):

doctype_name,child_doctypes
Sales Order,Sales Order Item

New System Behavior:

• Auto-detects "company" field
• Works identically to before
• ✅ Backward compatible

New CSV (with company_field):

doctype_name,company_field,child_doctypes
Sales Order,company,Sales Order Item

Benefits:

• Explicit and clear
• Supports multiple rows per DocType
• Can specify custom company fields

---

Generated for Transaction Deletion Record enhancement