View source for Phloc Skill Guide Comfac ERPN Loc

= Phloc Skill Guide — Building & Deploying Frappe/ERPNext Customizations =

A hands-on reference for creating custom reports, client scripts, Charts of Accounts templates, and other ERPNext customizations — then packaging them into the phlocalization Frappe app and deploying to a Frappe Cloud $25/month instance.

== Table of Contents ==

# [[#1. Local Development Environment Setup|Local Development Environment Setup]]
# [[#2. Adding Custom Reports|Adding Custom Reports]]
# [[#3. Adding Client Scripts|Adding Client Scripts]]
# [[#4. Adding Custom Fields to Existing DocTypes|Adding Custom Fields to Existing DocTypes]]
# [[#5. Adding Chart of Accounts Templates|Adding Chart of Accounts Templates]]
# [[#6. Adding Custom DocTypes|Adding Custom DocTypes]]
# [[#7. Adding Print Formats|Adding Print Formats]]
# [[#8. Adding Property Setters|Adding Property Setters]]
# [[#9. Adding Server-Side Hooks|Adding Server-Side Hooks]]
# [[#10. Testing|Testing]]
# [[#11. Frappe Cloud Deployment ($25/instance)|Frappe Cloud Deployment]]
# [[#12. Bench Command Reference|Bench Command Reference]]
# [[#13. Survival Checklist|Survival Checklist]]

== 1. Local Development Environment Setup ==

=== Prerequisites ===

* Python >= 3.10
* Node.js 18+
* MariaDB 10.6+ or PostgreSQL 14+
* Redis
* wkhtmltopdf

=== Initialize a Bench ===

<pre>
# Install bench CLI
pip install frappe-bench

# Create a new bench (pulls Frappe v15)
bench init --frappe-branch version-15 frappe-bench
cd frappe-bench

# Create a site
bench new-site phloc.localhost --mariadb-root-password &lt;password&gt; --admin-password admin

# Install ERPNext
bench get-app --branch version-15 erpnext
bench --site phloc.localhost install-app erpnext

# Install phlocalization
bench get-app https://github.com/xunema/phlocalization
bench --site phloc.localhost install-app bureau_of_internal_revenue

# Apply fixtures and migrations
bench --site phloc.localhost migrate

# Start dev server
bench start
</pre>

Access at <code>http://phloc.localhost:8000</code>

=== Enable Developer Mode ===

(required for creating DocTypes/reports via UI)

<pre>
bench --site phloc.localhost set-config developer_mode 1
bench --site phloc.localhost clear-cache
</pre>

== 2. Adding Custom Reports ==

Custom reports are the primary deliverable in phlocalization. The app uses '''Script Reports''' that extend ERPNext's financial statements.

=== File Structure (one directory per report) ===

All files must share the same snake_case name:

<pre>
bureau_of_internal_revenue/
  bureau_of_internal_revenue/
    report/
      your_report_name/
        __init__.py                    # Empty, required
        your_report_name.json          # Report metadata (DocType record)
        your_report_name.py            # Server-side logic
        your_report_name.js            # Client-side filters & formatting
        your_report_name.html          # HTML template (optional)
        test_your_report_name.py       # Tests
</pre>

=== Step-by-Step: Create a New Report ===

==== A. Create the report JSON definition ====

<pre>{
  "add_total_row": 0,
  "columns": [],
  "creation": "2026-03-09 00:00:00.000000",
  "disabled": 0,
  "docstatus": 0,
  "doctype": "Report",
  "filters": [],
  "idx": 0,
  "is_standard": "Yes",
  "letterhead": null,
  "modified": "2026-03-09 00:00:00.000000",
  "modified_by": "Administrator",
  "module": "Bureau of Internal Revenue",
  "name": "Your Report Name",
  "owner": "Administrator",
  "prepared_report": 0,
  "ref_doctype": "GL Entry",
  "report_name": "Your Report Name",
  "report_type": "Script Report",
  "roles": [
    {"role": "Accounts User"},
    {"role": "Accounts Manager"},
    {"role": "Auditor"}
  ],
  "timeout": 0
}</pre>

'''Critical fields:'''
* <code>report_type</code>: <code>"Script Report"</code> — runs your Python
* <code>ref_doctype</code>: <code>"GL Entry"</code> for financial reports (determines base permissions)
* <code>module</code>: Must match your module name exactly
* <code>is_standard</code>: <code>"Yes"</code> — marks it as part of the app (not user-created)

==== B. Create the Python report (<code>your_report_name.py</code>) ====

<pre>import frappe
from frappe import _
from frappe.utils import flt

from erpnext.accounts.report.financial_statements import (
    get_columns,
    get_data,
    get_period_list,
)


def execute(filters=None):
    """Main entry point. Frappe calls this automatically."""
    period_list = get_period_list(
        filters.from_fiscal_year,
        filters.to_fiscal_year,
        filters.period_start_date,
        filters.period_end_date,
        filters.filter_based_on,
        filters.periodicity,
        company=filters.company,
    )

    # Fetch account data from ERPNext
    asset = get_data(
        filters.company,
        "Asset",
        "Debit",
        period_list,
        only_current_fiscal_year=False,
        filters=filters,
        accumulated_values=filters.accumulated_values,
    )

    columns = get_columns(
        filters.periodicity, period_list, filters.accumulated_values, filters.company
    )

    data = []
    data.extend(asset or [])

    # Return tuple: (columns, data, message, chart, report_summary)
    return columns, data, None, None, None</pre>

'''Return value is always a tuple:''' <code>(columns, data, message, chart, report_summary)</code>

==== C. Create the JavaScript file (<code>your_report_name.js</code>) ====

<pre>frappe.query_reports["Your Report Name"] = $.extend(
    {},
    erpnext.financial_statements,
    {
        // Override the formatter to customize display
        formatter(value, row, column, data, df) {
            const formatted = erpnext.financial_statements.formatter
                ? erpnext.financial_statements.formatter(value, row, column, data, df)
                : value;

            // Hide numeric values for top-level group rows
            if (data && data.indent === 0 && typeof value === "number") {
                return "";
            }
            return formatted;
        },
    }
);

// Add ERPNext dimension filters (Cost Center, Project, etc.)
erpnext.utils.add_dimensions("Your Report Name", 10);

// Add custom filters
frappe.query_reports["Your Report Name"]["filters"].push({
    fieldname: "accumulated_values",
    label: __("Accumulated Values"),
    fieldtype: "Check",
    default: 1,
});

frappe.query_reports["Your Report Name"]["filters"].push({
    fieldname: "level",
    label: __("Show Levels Upto"),
    fieldtype: "Select",
    options: ["1", "2", "3", "4", "All"],
    default: "All",
});</pre>

'''Patterns:'''
* <code>$.extend({}, erpnext.financial_statements, {...})</code> — inherit standard financial statement behavior
* Push additional filters after the extend
* Filter object: <code>{fieldname, label, fieldtype, default, options?, reqd?}</code>
* To remove inherited filters: <code>.filter(f =&gt; !["cost_center"].includes(f.fieldname))</code>

==== D. Create the HTML template (<code>your_report_name.html</code>) ====

For financial reports, reuse ERPNext's template:

<pre>{% include "accounts/report/financial_statements.html" %}</pre>

Or write custom Jinja HTML for non-financial reports.

==== E. Register the report ====

No hooks.py change needed. Frappe auto-discovers reports by the JSON file in the module's <code>report/</code> directory. Just run:

<pre>
bench --site phloc.localhost migrate
bench --site phloc.localhost clear-cache
</pre>

The report appears under: '''Accounting &gt; Reports &gt; Your Report Name'''

== 3. Adding Client Scripts ==

Client scripts inject JavaScript into existing DocType forms. This is how phlocalization adds the Schedule field toggle to the Account form.

=== File Location ===

<pre>
bureau_of_internal_revenue/
  public/
    js/
      your_doctype.js
</pre>

=== Register in hooks.py ===

<pre>doctype_js = {
    "Account": "public/js/account.js",
    "Sales Invoice": "public/js/sales_invoice.js",   # add more as needed
}</pre>

=== Client Script Pattern ===

<pre>frappe.ui.form.on("Sales Invoice", {
    // Runs on form load/refresh
    refresh(frm) {
        frm.trigger("setup_custom_fields");
    },

    // Runs when a specific field changes
    customer(frm) {
        if (frm.doc.customer) {
            frappe.call({
                method: "frappe.client.get_value",
                args: {
                    doctype: "Customer",
                    filters: { name: frm.doc.customer },
                    fieldname: "tax_id"
                },
                callback(r) {
                    if (r.message) {
                        frm.set_value("custom_tax_id", r.message.tax_id);
                    }
                }
            });
        }
    },

    // Custom event (triggered by frm.trigger)
    setup_custom_fields(frm) {
        frm.toggle_display("custom_tax_id", !!frm.doc.customer);
    }
});</pre>

'''Key frm methods:'''
* <code>frm.toggle_display(fieldname, show)</code> — show/hide field
* <code>frm.set_value(fieldname, value)</code> — set value
* <code>frm.trigger(event_name)</code> — fire custom event
* <code>frm.doc.fieldname</code> — read current document values
* <code>frm.add_custom_button(label, callback, group)</code> — add toolbar button
* <code>frm.set_query(fieldname, filters)</code> — set link field filters

=== Apply changes ===

<pre>
bench build --app bureau_of_internal_revenue
bench --site phloc.localhost clear-cache
</pre>

== 4. Adding Custom Fields to Existing DocTypes ==

Two approaches, both valid. The phlocalization app currently uses '''fixtures'''; the recommended upgrade-safe pattern is '''programmatic creation'''.

=== Approach A: Fixtures (current phlocalization pattern) ===

'''1. Create the field via Frappe UI''' (with developer mode on):
* Go to Customize Form &gt; select DocType &gt; add field &gt; save

'''2. Register in hooks.py:'''
<pre>fixtures = [
    {
        "doctype": "Custom Field",
        "filters": [
            ["Custom Field", "module", "=", "Bureau of Internal Revenue"]
        ]
    }
]</pre>

'''3. Export:'''
<pre>
bench --site phloc.localhost export-fixtures --app bureau_of_internal_revenue
</pre>

This writes <code>fixtures/custom_field.json</code>. The JSON contains the full field definition including <code>dt</code> (target DocType), <code>fieldname</code>, <code>fieldtype</code>, <code>label</code>, <code>insert_after</code>, <code>options</code>, etc.

'''4. Fields are re-imported on every <code>bench migrate</code>.'''

=== Approach B: Programmatic (recommended for production) ===

This is the pattern used by India Compliance, HRMS, and other official Frappe apps. It survives bench updates more reliably.

'''1. Add hooks:'''
<pre>after_install = "bureau_of_internal_revenue.setup.after_install"
after_migrate = "bureau_of_internal_revenue.setup.after_migrate"</pre>

'''2. Create <code>bureau_of_internal_revenue/setup.py</code>:'''
<pre>from frappe.custom.doctype.custom_field.custom_field import create_custom_fields


def after_install():
    create_custom_fields(get_custom_fields())


def after_migrate():
    create_custom_fields(get_custom_fields())


def get_custom_fields():
    return {
        "Account": [
            {
                "fieldname": "schedule",
                "fieldtype": "Select",
                "label": "Schedule",
                "insert_after": "parent_account",
                "options": "\n".join([""] + [f"SCHED {i}" for i in range(1, 24)]),
                "translatable": 1,
            }
        ],
        "Sales Invoice": [
            {
                "fieldname": "bir_tax_category",
                "fieldtype": "Link",
                "label": "BIR Tax Category",
                "options": "Tax Category",
                "insert_after": "taxes_and_charges",
            }
        ],
    }</pre>

'''Why <code>after_migrate</code> matters:''' It runs on every <code>bench migrate</code> (which happens on every <code>bench update</code>), re-asserting your fields even if something reset them.

== 5. Adding Chart of Accounts Templates ==

ERPNext allows custom Chart of Accounts (COA) templates. For BIR compliance, you need a Philippine COA with schedule assignments.

=== COA Template File Location ===

Place your template inside the app:

<pre>
bureau_of_internal_revenue/
  bureau_of_internal_revenue/
    chart_of_accounts/
      __init__.py
      verified/
        __init__.py
        philippines_bir_standard.py
</pre>

=== Register via hooks.py ===

<pre>regional_overrides = {
    "Philippines": {
        "erpnext.accounts.doctype.chart_of_accounts.chart_of_accounts.get_charts_for_country":
            "bureau_of_internal_revenue.bureau_of_internal_revenue.chart_of_accounts.get_charts_for_country"
    }
}</pre>

=== COA Template Format (Python dict) ===

<pre># philippines_bir_standard.py

chart_data = {
    "name": "Philippines - BIR Standard",
    "country_code": "ph",
    "tree": {
        "Assets": {
            "account_type": "",
            "is_group": 1,
            "root_type": "Asset",
            "Current Assets": {
                "is_group": 1,
                "account_type": "",
                "Cash and Cash Equivalents": {
                    "is_group": 1,
                    "account_type": "",
                    "Cash on Hand": {
                        "account_type": "Cash",
                    },
                    "Cash in Bank": {
                        "account_type": "Bank",
                    },
                },
                "Trade and Other Receivables": {
                    "is_group": 1,
                    "Accounts Receivable": {
                        "account_type": "Receivable",
                    },
                },
            },
        },
        "Liabilities": {
            "is_group": 1,
            "root_type": "Liability",
            "Current Liabilities": {
                "is_group": 1,
                "Accounts Payable": {
                    "account_type": "Payable",
                },
                "BIR Withholding Tax Payable": {
                    "account_type": "Tax",
                },
            },
        },
        "Equity": {
            "is_group": 1,
            "root_type": "Equity",
            "Share Capital": {},
            "Retained Earnings": {
                "account_type": "Equity",
            },
        },
        "Income": {
            "is_group": 1,
            "root_type": "Income",
            "Sales Revenue": {
                "account_type": "Income Account",
            },
        },
        "Expenses": {
            "is_group": 1,
            "root_type": "Expense",
            "Cost of Goods Sold": {
                "account_type": "Cost of Goods Sold",
            },
            "Operating Expenses": {
                "is_group": 1,
                "Salaries and Wages": {
                    "account_type": "Expense Account",
                },
            },
        },
    },
}</pre>

=== Alternative: JSON-based COA ===

Place a JSON file at:
<pre>
bureau_of_internal_revenue/
  bureau_of_internal_revenue/
    chart_of_accounts/
      verified/
        ph_bir_standard.json
</pre>

Same tree structure as above but in JSON format. Frappe discovers it automatically if the <code>get_charts_for_country</code> function is set up to scan this directory.

== 6. Adding Custom DocTypes ==

For app-specific data models (e.g., "BIR Tax Schedule", "E-Invoice Log").

=== Create via Bench (Developer Mode) ===

<pre>
# In the Frappe UI: DocType List &gt; + New DocType
# OR via code:
bench --site phloc.localhost new-doctype "BIR Tax Schedule" \
    --module "Bureau of Internal Revenue"
</pre>

=== File structure created automatically ===

<pre>
bureau_of_internal_revenue/
  bureau_of_internal_revenue/
    doctype/
      bir_tax_schedule/
        __init__.py
        bir_tax_schedule.json       # Schema definition
        bir_tax_schedule.py         # Controller (server logic)
        bir_tax_schedule.js         # Form script (client logic)
        test_bir_tax_schedule.py    # Tests
</pre>

=== Controller pattern ===

<pre># bir_tax_schedule.py
import frappe
from frappe.model.document import Document


class BIRTaxSchedule(Document):
    def validate(self):
        """Runs before save."""
        if not self.schedule_code:
            frappe.throw("Schedule code is required")

    def on_submit(self):
        """Runs when document is submitted."""
        pass

    def on_cancel(self):
        """Runs when document is cancelled."""
        pass</pre>

=== No hooks.py change needed ===

Frappe auto-discovers DocTypes from the module's <code>doctype/</code> directory during <code>bench migrate</code>.

== 7. Adding Print Formats ==

=== Standard Jinja Print Format (in-app, upgrade-safe) ===

<pre>
bureau_of_internal_revenue/
  bureau_of_internal_revenue/
    print_format/
      bir_sales_invoice/
        bir_sales_invoice.json
        bir_sales_invoice.html
</pre>

'''bir_sales_invoice.json:'''
<pre>{
  "doctype": "Print Format",
  "name": "BIR Sales Invoice",
  "doc_type": "Sales Invoice",
  "module": "Bureau of Internal Revenue",
  "standard": "Yes",
  "print_format_type": "Jinja",
  "raw_printing": 0,
  "disabled": 0
}</pre>

'''bir_sales_invoice.html:'''
<pre>&lt;div class="page-break"&gt;
    &lt;h2&gt;{{ doc.company }}&lt;/h2&gt;
    &lt;p&gt;TIN: {{ doc.tax_id }}&lt;/p&gt;
    &lt;table&gt;
        &lt;tr&gt;
            &lt;th&gt;Item&lt;/th&gt;&lt;th&gt;Qty&lt;/th&gt;&lt;th&gt;Rate&lt;/th&gt;&lt;th&gt;Amount&lt;/th&gt;
        &lt;/tr&gt;
        {% for item in doc.items %}
        &lt;tr&gt;
            &lt;td&gt;{{ item.item_name }}&lt;/td&gt;
            &lt;td&gt;{{ item.qty }}&lt;/td&gt;
            &lt;td&gt;{{ frappe.format_value(item.rate, {"fieldtype": "Currency"}) }}&lt;/td&gt;
            &lt;td&gt;{{ frappe.format_value(item.amount, {"fieldtype": "Currency"}) }}&lt;/td&gt;
        &lt;/tr&gt;
        {% endfor %}
    &lt;/table&gt;
    &lt;p&gt;&lt;strong&gt;Grand Total: {{ frappe.format_value(doc.grand_total, {"fieldtype": "Currency"}) }}&lt;/strong&gt;&lt;/p&gt;
&lt;/div&gt;</pre>

=== Export via fixtures (alternative) ===

<pre># hooks.py
fixtures = [
    # ... existing fixtures ...
    {
        "doctype": "Print Format",
        "filters": [["Print Format", "module", "=", "Bureau of Internal Revenue"]]
    }
]</pre>

== 8. Adding Property Setters ==

Property Setters modify properties of existing DocType fields (e.g., making a field mandatory, changing its default, hiding it) without modifying the DocType source.

=== Programmatic approach (in setup.py) ===

<pre>import frappe


def after_migrate():
    create_custom_fields(get_custom_fields())
    create_property_setters()


def create_property_setters():
    property_setters = [
        {
            "doctype": "Sales Invoice",
            "fieldname": "tax_id",
            "property": "reqd",
            "value": "1",
            "property_type": "Check",
        },
        {
            "doctype": "Sales Invoice",
            "fieldname": "tax_id",
            "property": "default",
            "value": "",
            "property_type": "Data",
        },
    ]
    for ps in property_setters:
        frappe.make_property_setter(ps, is_system_generated=False)</pre>

=== Fixture approach ===

<pre># hooks.py
fixtures = [
    {
        "doctype": "Property Setter",
        "filters": [["Property Setter", "module", "=", "Bureau of Internal Revenue"]]
    }
]</pre>

== 9. Adding Server-Side Hooks ==

=== Document Event Hooks ===

Trigger your code when documents are saved, submitted, or cancelled:

<pre># hooks.py
doc_events = {
    "Sales Invoice": {
        "validate": "bureau_of_internal_revenue.overrides.sales_invoice.validate",
        "on_submit": "bureau_of_internal_revenue.overrides.sales_invoice.on_submit",
    },
    "Purchase Invoice": {
        "validate": "bureau_of_internal_revenue.overrides.purchase_invoice.validate",
    },
}</pre>

<pre># bureau_of_internal_revenue/overrides/sales_invoice.py
import frappe


def validate(doc, method):
    """Called before every Sales Invoice save."""
    if doc.company_address:
        # Add BIR validation logic
        pass


def on_submit(doc, method):
    """Called when Sales Invoice is submitted."""
    pass</pre>

=== Whitelisted API Methods ===

Expose Python functions as REST API endpoints:

<pre># hooks.py (uncomment and modify)
override_whitelisted_methods = {
    "erpnext.accounts.utils.get_balance_on":
        "bureau_of_internal_revenue.overrides.accounts.get_balance_on"
}</pre>

Or create standalone API endpoints:

<pre># bureau_of_internal_revenue/api.py
import frappe


@frappe.whitelist()
def get_bir_schedule(account):
    """Callable via /api/method/bureau_of_internal_revenue.api.get_bir_schedule"""
    return frappe.db.get_value("Account", account, "schedule")</pre>

=== Scheduled Tasks ===

<pre># hooks.py
scheduler_events = {
    "daily": [
        "bureau_of_internal_revenue.tasks.daily_compliance_check"
    ],
    "monthly": [
        "bureau_of_internal_revenue.tasks.generate_monthly_bir_summary"
    ],
}</pre>

== 10. Testing ==

=== Test file pattern ===

<pre># test_your_report_name.py
import frappe
from frappe.tests.utils import FrappeTestCase
from unittest.mock import patch

from bureau_of_internal_revenue.bureau_of_internal_revenue.report.your_report_name.your_report_name import execute


class TestYourReportName(FrappeTestCase):

    def test_basic_execution(self):
        filters = frappe._dict(
            company="_Test Company",
            from_fiscal_year="2025",
            to_fiscal_year="2025",
            period_start_date="2025-01-01",
            period_end_date="2025-12-31",
            filter_based_on="Fiscal Year",
            periodicity="Yearly",
            accumulated_values=1,
        )
        columns, data, *_ = execute(filters)
        self.assertTrue(len(columns) &gt; 0)

    @patch("bureau_of_internal_revenue.bureau_of_internal_revenue.report.your_report_name.your_report_name.get_data")
    def test_with_mocked_data(self, mock_get_data):
        mock_get_data.return_value = [
            frappe._dict(account="Cash - TC", account_name="Cash", indent=1, total=500),
        ]
        filters = frappe._dict(company="_Test Company")
        columns, data, *_ = execute(filters)
        self.assertEqual(data[0].total, 500)</pre>

=== Run tests ===

<pre>
# All tests for the app
bench --site phloc.localhost run-tests --app bureau_of_internal_revenue

# Specific test file
bench --site phloc.localhost run-tests \
    --module bureau_of_internal_revenue.bureau_of_internal_revenue.report.balance_sheet_bir.test_balance_sheet_bir

# With verbose output
bench --site phloc.localhost run-tests --app bureau_of_internal_revenue -v
</pre>

== 11. Frappe Cloud Deployment ($25/instance) ==

=== Frappe Cloud Pricing (as of 2026) ===

{| class="wikitable"
! Plan !! Price !! What you get
|-
| '''$25/mo''' (Starter/Basic) || $25 USD/month || 1 site, shared bench, limited resources, custom apps supported
|-
| $50/mo (Standard) || $50 USD/month || More CPU/RAM, priority support
|-
| Dedicated || Custom || Dedicated server, full control
|}

The $25/mo plan is sufficient for testing and small deployments. It supports custom app installation.

=== Step-by-Step: Deploy to Frappe Cloud ===

==== 1. Prepare your repository ====

Ensure your repo has:
* <code>pyproject.toml</code> with <code>[tool.bench.frappe-dependencies]</code>
* <code>app_name</code> in <code>hooks.py</code> matches the top-level directory name
* <code>__init__.py</code> in the app root
* Repo is public on GitHub (or you grant Frappe Cloud access to private repo)

'''Fix the placeholder in pyproject.toml first:'''
<pre>[project]
name = "bureau_of_internal_revenue"
authors = [
    { name = "Ambibuzz Technologies LLP", email = "buzz.us@ambibuzz.com" }
]
description = "Philippine BIR Localization for ERPNext"
requires-python = ">=3.10"
readme = "README.md"
dynamic = ["version"]
dependencies = [
    "frappe~=15.95.0"
]

[tool.bench.frappe-dependencies]
frappe = "~=15.95.0"
erpnext = "~=15.0.0"</pre>

==== 2. Sign up and create a bench on Frappe Cloud ====

# Go to [frappecloud.com](https://frappecloud.com) and sign up
# '''Dashboard &gt; Benches &gt; New Bench'''
# Select Frappe version: '''Version 15'''
# Add apps:
#* '''ERPNext''' (from Frappe's official list)
#* '''Your custom app''': click "Add App" &gt; paste GitHub URL <code>https://github.com/xunema/phlocalization</code> &gt; select branch
# Choose region (nearest to Philippines: Singapore)
# Create the bench — Frappe Cloud builds it (takes 5-15 minutes)

==== 3. Create a site ====

# '''Dashboard &gt; Sites &gt; New Site'''
# Select your bench
# Choose the $25/mo plan
# Set subdomain: <code>phloc.frappe.cloud</code> (or custom domain)
# Select apps to install: '''ERPNext''' + '''Bureau of Internal Revenue'''
# Create site — Frappe Cloud provisions it and runs <code>bench migrate</code> (applies fixtures)

==== 4. Verify deployment ====

# Log in at <code>https://phloc.frappe.cloud</code>
# Go to '''Search Bar &gt; Balance Sheet BIR''' — report should appear
# Go to '''Accounting &gt; Chart of Accounts''' — verify Schedule field on group accounts
# Go to '''Customize Form &gt; Account''' — verify Schedule custom field exists

==== 5. Update workflow ====

When you push changes to GitHub:

# '''Dashboard &gt; Benches &gt; your bench &gt; Updates'''
# Click '''"Deploy"''' or enable auto-deploy
# Frappe Cloud pulls latest code, runs <code>bench migrate</code>, restarts
# Your fixtures, reports, and hooks are re-applied automatically

=== Frappe Cloud CLI (alternative) ===

<pre>
# Install FC CLI
pip install press-cli

# Login
fc login

# List your benches
fc bench list

# Deploy (trigger update)
fc bench deploy &lt;bench-name&gt;
</pre>

== 12. Bench Command Reference ==

=== Daily Development Workflow ===

<pre>
# Start dev server (Frappe + Redis + workers)
bench start

# After editing Python files — apply DB changes
bench --site phloc.localhost migrate

# After editing JS/CSS files — rebuild assets
bench build --app bureau_of_internal_revenue

# Quick cache clear (when UI doesn't reflect changes)
bench --site phloc.localhost clear-cache

# Export fixtures after creating custom fields via UI
bench --site phloc.localhost export-fixtures --app bureau_of_internal_revenue
</pre>

=== Site Management ===

<pre>
# Create new site
bench new-site &lt;site-name&gt; --mariadb-root-password &lt;pw&gt; --admin-password &lt;pw&gt;

# Install app on site
bench --site &lt;site-name&gt; install-app bureau_of_internal_revenue

# Uninstall app
bench --site &lt;site-name&gt; uninstall-app bureau_of_internal_revenue

# Drop site entirely
bench drop-site &lt;site-name&gt; --force

# Backup
bench --site &lt;site-name&gt; backup --with-files

# Restore
bench --site &lt;site-name&gt; restore &lt;backup-file&gt;

# Open console (Python shell with frappe context)
bench --site &lt;site-name&gt; console

# Open mariadb shell
bench --site &lt;site-name&gt; mariadb
</pre>

=== App Management ===

<pre>
# Get app from GitHub
bench get-app &lt;url&gt; --branch &lt;branch&gt;

# Remove app from bench (not from site)
bench remove-app &lt;app-name&gt;

# Check installed apps on site
bench --site &lt;site-name&gt; list-apps

# Update all apps
bench update

# Update specific app only
bench update --apps bureau_of_internal_revenue
</pre>

=== Development Tools ===

<pre>
# Run tests
bench --site &lt;site-name&gt; run-tests --app bureau_of_internal_revenue

# Run tests verbose
bench --site &lt;site-name&gt; run-tests --app bureau_of_internal_revenue -v

# Export fixtures
bench --site &lt;site-name&gt; export-fixtures --app bureau_of_internal_revenue

# Build assets
bench build --app bureau_of_internal_revenue

# Clear cache
bench --site &lt;site-name&gt; clear-cache
</pre>

== 13. Survival Checklist — Will My Changes Survive <code>bench update</code>? ==

{| class="wikitable"
! Check !! Safe Pattern !! Unsafe Pattern
|-
| '''Custom fields on standard DocTypes''' || Fixtures or <code>create_custom_fields()</code> in setup.py || Manual changes in "Customize Form" without exporting
|-
| '''Client scripts''' || <code>doctype_js</code> in hooks.py + JS files in <code>public/js/</code> || "Custom Script" records in Frappe UI
|-
| '''Reports''' || Script Report JSON + .py/.js/.html files in app directory || "Query Report" or "Report Builder" saved in UI
|-
| '''Print formats''' || Standard print format JSON + HTML in app directory || Custom Print Format created via UI
|-
| '''DocType modifications''' || Custom Fields, Property Setters || Modifying standard DocType source code
|-
| '''Server logic''' || <code>doc_events</code>, <code>override_whitelisted_methods</code> in hooks.py || Editing ERPNext .py files directly
|}

'''Rule of thumb:''' If you created it through the Frappe UI and it's not exported to a file in your app directory, it will '''not''' survive a <code>bench update</code>.

[[Category:ERPNext]]
[[Category:Frappe]]
[[Category:Developer Guide]]
[[Category:Tutorial]]
[[Category:Comfac ERPN Loc]]