View source for Repo comfac-hrms CommonEdits

= Repo:comfac-hrms/CommonEdits — Common Edit Scenarios =

This page contains practical recipes for common customization tasks.

== Scenario 1: Adding a New Field to a Form ==

=== Goal ===
Add "Emergency Contact Phone" field to the Employee form.

=== Files to Touch ===
# <code>hrms/setup.py</code> OR Frappe Desk UI
# (Optional) <code>hrms/overrides/employee_master.py</code> for validation

=== Method A: Via Frappe Desk (Quickest) ===

# Log in as Administrator
# Go to '''Employee''' list
# Click '''Menu''' → '''Customize'''
# In "Customize Form", scroll to bottom
# Click '''Add Row''':
#* Label: Emergency Contact Phone
#* Fieldtype: Data
#* Options: Phone
#* Insert After: emergency_contact_name
# Click '''Update'''

=== Method B: Via Code (Reproducible) ===

Create <code>hrms/setup.py</code> if not exists:

<syntaxhighlight lang="python">
import frappe

def setup_custom_fields():
    custom_fields = {
        "Employee": [
            {
                "fieldname": "custom_emergency_phone",
                "label": "Emergency Contact Phone",
                "fieldtype": "Data",
                "options": "Phone",
                "insert_after": "emergency_contact_name",
                "translatable": 0
            }
        ]
    }
    
    for doctype, fields in custom_fields.items():
        for field in fields:
            if not frappe.db.exists("Custom Field", f"{doctype}-{field['fieldname']}"):
                frappe.get_doc({
                    "doctype": "Custom Field",
                    "dt": doctype,
                    **field
                }).insert()
    frappe.db.commit()
</syntaxhighlight>

Add to <code>hooks.py</code>:

<syntaxhighlight lang="python">
after_install = "hrms.setup.setup_custom_fields"
</syntaxhighlight>

=== How to Verify ===
# Go to Employee form
# Check if new field appears after "Emergency Contact Name"
# Create test employee, fill in emergency phone
# Verify it saves and appears in list view if configured

---

== Scenario 2: Changing Validation Logic ==

=== Goal ===
Require manager approval for leave applications longer than 7 days.

=== Files to Touch ===
# <code>hrms/hr/doctype/leave_application/leave_application.py</code>

=== What to Change ===

Find the <code>validate()</code> method or add to it:

<syntaxhighlight lang="python">
def validate(self):
    # ... existing validation code ...
    
    # Custom validation
    if self.total_leave_days > 7 and not self.leave_approver:
        frappe.throw(_(
            "Leave applications longer than 7 days require a leave approver."
        ))
</syntaxhighlight>

=== How to Verify ===
# Create leave application for 10 days
# Try to submit without selecting approver
# Should get error message
# Select approver, submit should work

---

== Scenario 3: Adding a New Report ==

=== Goal ===
Create a report showing employees with negative leave balances.

=== Files to Touch ===
# <code>hrms/hr/report/negative_leave_balance/</code> (new directory)
# <code>hrms/hr/report/negative_leave_balance/negative_leave_balance.json</code>
# <code>hrms/hr/report/negative_leave_balance/negative_leave_balance.py</code>

=== What to Create ===

'''negative_leave_balance.json:'''

<syntaxhighlight lang="json">
{
 "add_total_row": 0,
 "columns": [],
 "creation": "2024-01-01 00:00:00.000000",
 "disable_prepared_report": 0,
 "disabled": 0,
 "docstatus": 0,
 "doctype": "Report",
 "filters": [],
 "idx": 0,
 "is_standard": "Yes",
 "modified": "2024-01-01 00:00:00.000000",
 "modified_by": "Administrator",
 "module": "HR",
 "name": "Negative Leave Balance",
 "owner": "Administrator",
 "prepared_report": 0,
 "ref_doctype": "Leave Ledger Entry",
 "report_name": "Negative Leave Balance",
 "report_type": "Script Report",
 "roles": [
  {"role": "HR Manager"},
  {"role": "HR User"}
 ]
}
</syntaxhighlight>

'''negative_leave_balance.py:'''

<syntaxhighlight lang="python">
import frappe
from frappe import _

def execute(filters=None):
    columns = [
        {"label": _("Employee"), "fieldname": "employee", "fieldtype": "Link", "options": "Employee", "width": 150},
        {"label": _("Employee Name"), "fieldname": "employee_name", "fieldtype": "Data", "width": 200},
        {"label": _("Leave Type"), "fieldname": "leave_type", "fieldtype": "Link", "options": "Leave Type", "width": 150},
        {"label": _("Balance"), "fieldname": "balance", "fieldtype": "Float", "width": 120},
    ]
    
    data = frappe.db.sql("""
        SELECT 
            employee,
            (SELECT employee_name FROM tabEmployee e WHERE e.name = lle.employee) as employee_name,
            leave_type,
            SUM(leaves) as balance
        FROM `tabLeave Ledger Entry` lle
        GROUP BY employee, leave_type
        HAVING balance < 0
        ORDER BY balance ASC
    """, as_dict=True)
    
    return columns, data
</syntaxhighlight>

=== How to Verify ===
# Run <code>bench migrate</code>
# Go to HR module → Reports
# Look for "Negative Leave Balance"
# Run report, verify data

---

== Scenario 4: Modifying a Print Format ==

=== Goal ===
Add company logo to Salary Slip print format.

=== Files to Touch ===
# Frappe Desk UI (Print Format Builder)

=== What to Change ===

# Go to '''Payroll''' → '''Salary Slip'''
# Open any salary slip
# Click '''Print''' → '''Customize'''
# In Print Format Builder:
#* Drag "Image" field to header
#* Set image source to <code>{{ frappe.db.get_value("Company", doc.company, "company_logo") }}</code>
#* Adjust size and position
# Save as new print format or update standard

=== Alternative: Raw HTML ===

Edit print format HTML:

<syntaxhighlight lang="html">
<div class="print-format">
    <div class="row">
        <div class="col-xs-6">
            <img src="{{ frappe.db.get_value('Company', doc.company, 'company_logo') }}" style="max-height: 60px;">
        </div>
        <div class="col-xs-6 text-right">
            <h2>Salary Slip</h2>
            <p>{{ doc.name }}</p>
        </div>
    </div>
    <!-- ... rest of format ... -->
</div>
</syntaxhighlight>

=== How to Verify ===
# Open any salary slip
# Click Print
# Verify logo appears in preview
# Check PDF export

---

== Scenario 5: Adding a New DocType ==

=== Goal ===
Create "Employee Training Record" DocType to track completed trainings.

=== Files to Touch ===
# <code>hrms/hr/doctype/employee_training_record/</code> (new directory)
# <code>hrms/hr/doctype/employee_training_record/employee_training_record.json</code>
# <code>hrms/hr/doctype/employee_training_record/employee_training_record.py</code>

=== What to Create ===

'''Option A: Via Frappe Desk (Recommended)'''

# Go to '''DocType List''' (search in awesome bar)
# Click '''New'''
# Fill:
#* Name: Employee Training Record
#* Module: HR
#* Fields:
#** Employee (Link → Employee)
#** Training Name (Data)
#** Training Date (Date)
#** Trainer (Data)
#** Certificate (Attach)
#** Status (Select: Completed/In Progress/Planned)
# Save, then <code>bench export-fixtures</code> OR manually create files

'''Option B: Manual JSON'''

Create <code>employee_training_record.json</code>:

<syntaxhighlight lang="json">
{
 "actions": [],
 "autoname": "format:TRN-{YYYY}-{#####}",
 "creation": "2024-01-01 00:00:00.000000",
 "doctype": "DocType",
 "engine": "InnoDB",
 "fields": [
  {
   "fieldname": "employee",
   "fieldtype": "Link",
   "label": "Employee",
   "options": "Employee",
   "reqd": 1
  },
  {
   "fieldname": "training_name",
   "fieldtype": "Data",
   "label": "Training Name",
   "reqd": 1
  },
  {
   "fieldname": "training_date",
   "fieldtype": "Date",
   "label": "Training Date"
  },
  {
   "fieldname": "trainer",
   "fieldtype": "Data",
   "label": "Trainer"
  },
  {
   "fieldname": "certificate",
   "fieldtype": "Attach",
   "label": "Certificate"
  },
  {
   "fieldname": "status",
   "fieldtype": "Select",
   "label": "Status",
   "options": "Planned\nIn Progress\nCompleted"
  }
 ],
 "index_web_pages_for_search": 1,
 "links": [],
 "modified": "2024-01-01 00:00:00.000000",
 "module": "HR",
 "name": "Employee Training Record",
 "naming_rule": "Expression",
 "owner": "Administrator",
 "permissions": [
  {
   "create": 1,
   "delete": 1,
   "email": 1,
   "export": 1,
   "print": 1,
   "read": 1,
   "report": 1,
   "role": "HR Manager",
   "share": 1,
   "write": 1
  },
  {
   "create": 1,
   "delete": 0,
   "email": 1,
   "export": 1,
   "print": 1,
   "read": 1,
   "report": 1,
   "role": "HR User",
   "share": 1,
   "write": 1
  }
 ],
 "sort_field": "modified",
 "sort_order": "DESC",
 "states": [],
 "track_changes": 1
}
</syntaxhighlight>

Create <code>employee_training_record.py</code>:

<syntaxhighlight lang="python">
import frappe
from frappe.model.document import Document

class EmployeeTrainingRecord(Document):
    def validate(self):
        # Custom validation
        if self.status == "Completed" and not self.certificate:
            frappe.msgprint(_("Warning: No certificate attached for completed training."))
</syntaxhighlight>

=== How to Verify ===
# Run <code>bench migrate</code>
# Go to HR module
# Search for "Employee Training Record"
# Create test record
# Verify validations work

---

== Scenario 6: Changing a Workflow ==

=== Goal ===
Add "Pending HR Review" step to Leave Application workflow.

=== Files to Touch ===
# Frappe Desk → Workflow List

=== What to Change ===

# Go to '''Workflow''' list
# Open '''Leave Application'''
# Add new state:
#* State: Pending HR Review
#* Update Field: Status
#* Update Value: Pending HR Review
# Add new transitions:
#* From: Open → To: Pending HR Review, Action: Send to HR, Condition: doc.total_leave_days > 5
#* From: Pending HR Review → To: Approved, Action: HR Approve
#* From: Pending HR Review → To: Rejected, Action: HR Reject
# Save

=== How to Verify ===
# Create leave application > 5 days
# Submit, should go to "Pending HR Review"
# Verify HR Manager can approve/reject
# Check that shorter leaves skip this step

---

== Scenario 7: Adding a Server Script ==

=== Goal ===
Auto-calculate leave balance when leave application is created.

=== Files to Touch ===
# <code>hrms/hr/doctype/leave_application/leave_application.py</code>

=== What to Change ===

Add to <code>LeaveApplication</code> class:

<syntaxhighlight lang="python">
def before_insert(self):
    """Auto-calculate leave balance before saving"""
    if self.employee and self.leave_type:
        balance = get_leave_balance(self.employee, self.leave_type, self.from_date)
        self.leave_balance = balance

def get_leave_balance(employee, leave_type, date):
    """Helper function to calculate balance"""
    result = frappe.db.sql("""
        SELECT SUM(leaves) as balance 
        FROM `tabLeave Ledger Entry`
        WHERE employee = %s AND leave_type = %s AND transaction_date <= %s
    """, (employee, leave_type, date), as_dict=True)
    
    return result[0].balance or 0
</syntaxhighlight>

=== How to Verify ===
# Create new leave application
# Select employee and leave type
# Leave Balance field should auto-populate

---

== Scenario 8: Connecting to Another App ==

=== Goal ===
Link Employee to comfac-webshop Customer account.

=== Files to Touch ===
# Custom field in Employee (via desk or code)
# (Optional) <code>hrms/overrides/employee_master.py</code>

=== What to Change ===

Add custom field to Employee:
* Fieldname: <code>webshop_customer</code>
* Label: Webshop Customer Account
* Fieldtype: Link
* Options: Customer (from ERPNext)

Add to <code>hrms/overrides/employee_master.py</code>:

<syntaxhighlight lang="python">
def after_insert(self):
    """Create webshop customer for new employees"""
    if not self.webshop_customer:
        customer = frappe.get_doc({
            "doctype": "Customer",
            "customer_name": self.employee_name,
            "customer_type": "Individual",
            "customer_group": "Employee",
            "territory": "Philippines"
        })
        customer.insert(ignore_permissions=True)
        
        # Link back to employee
        self.db_set("webshop_customer", customer.name)
</syntaxhighlight>

Add to <code>hooks.py</code>:

<syntaxhighlight lang="python">
doc_events = {
    "Employee": {
        "after_insert": "hrms.overrides.employee_master.after_insert"
    }
}
</syntaxhighlight>

=== How to Verify ===
# Create new employee
# Check if Customer is auto-created
# Verify link appears in Employee form
# Check customer appears in ERPNext Sales module

== Related Pages ==

* [[Repo_comfac-hrms_Overview]] — Project overview
* [[Repo_comfac-hrms_DirectoryMap]] — Directory structure
* [[Repo_comfac-hrms_EntryPoints]] — How app starts, config files
* [[Repo_comfac-hrms_DataModel]] — DocTypes and data structures
* [[Repo_comfac-hrms_ExtensionPoints]] — Hooks and customization

[[Category:Repository Analysis]]