RMAX Custom — User Guide

How to Create a Branch

1. Search for Branch and click + Add Branch.
2. Enter the Branch name (e.g. "Azzizziyah", "Warehouse Jeddah", "HQ Awtad"). This becomes the record ID.
3. Set Doc Prefix — the short alphanumeric prefix used in this branch's document numbers. The prefix MUST end with a hyphen. Examples: WJ-, AZZ-, HO-, CL1-.
4. Set Branch Name (Arabic) — used inside per-branch bilingual letterheads.
5. (Optional) Set Letter Head if you want to override the auto-generated RMAX - <Branch> letterhead with a different one.
6. Click Save.

How to Create a Branch Configuration

1. Go to the search bar and type Branch Configuration, then click + Add Branch Configuration.
2. Select the Branch (e.g. "Jeddah").
3. Select the Company this branch belongs to (e.g. "Clearlight New Co."). This is required.
4. In the Modes of Payment table, add the Cash and Bank Modes of Payment that branch users may collect against (e.g. Cash, Mada, Bank Transfer - HSBC). Only MoPs with type Cash or Bank appear in the picker. BNPL providers (Tabby/Tamara) are NOT added here — they are common to every branch.
5. In the Warehouse table, add the warehouses for this branch. They will be filtered to show only warehouses from the selected company. The first warehouse becomes the user's default.
6. In the Cost Center table, add cost centers. They are also filtered by company. The first cost center becomes the default.
7. In the User table, add all users who work in this branch (e.g. shameel@rmax.com, naseef@rmaxled.com).
8. Click Save.

What Happens Automatically

Template Pattern

How Letterhead Resolution Works

1. If the document has an explicit Letter Head field set, that one is used.
2. Otherwise, the system looks up RMAX - <Branch> matching the doc's branch (e.g. RMAX - Azzizziyah).
3. Falls back to the RMAX - Clear Light master letterhead if neither of the above exists.

Editing a Branch Letterhead

1. Search Letter Head → open RMAX - <Branch>.
2. Set Source to HTML (not Image).
3. Edit the HTML body. Standard placeholders like {{ company.company_name }}, {{ company.tax_id }}, {{ co_address.address_line1 }} are supported via Jinja.
4. Save.

Automatic Role Assignment

Permission Matrix

Three User Roles

Setup Steps

1. Go to Inter Company Branch list and click + Add.
2. Enter a Branch Name (e.g. "Jeddah Branch").
3. In the Company Cost Centers table, add a row for each company involved:
   • Select the Company (the buying company)
   • Select the Cost Center for that company
   • Select the Warehouse for that company
4. Save.

Auto-Created Purchase Invoice Details

Stock Transfer Workflow

Step-by-Step

1. Open a New Sales Invoice. The Company, Warehouse, and Cost Center will auto-fill from your branch defaults.
2. Set Payment Mode to Cash.
3. Select or create a Customer. (You can use the "Create New Customer" button to quickly add one.)
4. Add items to the Items table. Use Enter to move between columns and rows.
   The system will check stock automatically and warn you if quantity exceeds available stock.
5. Click Save. A Payment Popup will appear.
6. In the popup, allocate payment amounts across different payment modes (Cash, Card, etc.):
   • Click a payment mode button to fill the full amount to that mode
   • Or click the input field to auto-fill the remaining balance
   • You can split payments across multiple modes
7. Click Save & Submit to submit the invoice and create Payment Entries automatically.

Step-by-Step

1. Create a New Sales Invoice as usual.
2. Set Payment Mode to Credit.
3. Notice that the Customer dropdown is now filtered to show only customers with a credit limit.
4. Select a customer and add items.
5. Click Save. A confirmation dialog will ask: "Do you want to Submit this Sales Invoice now?"
   • Click Yes to submit immediately
   • Click No to save as draft

Full BNPL payment (100% Tabby or Tamara)

1. Create a New Sales Invoice as usual. Set Payment Mode = Cash (the existing RMAX category, kept separate from BNPL).
2. Add the customer and the items. Apply any line discount or invoice discount first; the uplift always operates on the post-discount rate.
3. In the POS-style Enter Payment Amounts popup, set the full invoice total against Tabby (or Tamara). Cash row should be 0.00.
4. The line rates jump up by ÷ 0.92 in real time. The BNPL Portion Ratio shows 100%.
5. Click Save & Submit.

Split payment (cash + BNPL)

Example: SAR 1,000 invoice paid SAR 400 cash + SAR 600 Tabby.

1. Add Cash row = SAR 400. Add Tabby row = SAR 600.
2. BNPL Portion Ratio = 60%. Effective uplift factor = 1 + (0.60 × 0.086957) = 1.05217.
3. Each line rate is uplifted by 5.217% — the cash portion is not uplifted, only the Tabby-funded share. The customer-facing invoice shows a single uplifted total.

Step-by-Step

1. Open a new Journal Entry. Set Voucher Type = Bank Entry (or Journal Entry) and pick the Company.
2. Click the Load BNPL Settlement button in the toolbar.
3. In the dialog, pick the Mode of Payment (Tabby or Tamara). The dialog shows the resolved Clearing Account, Currency, and live GL Balance for context.
4. Pick the Bank Account that received the provider's payout.
5. Click Load Heads. The system clears any existing accounts table and inserts three rows: Dr Bank, Dr BNPL Fee Expense, Cr Clearing.
6. Type the actual amounts from the Tabby / Tamara settlement statement: bank credit (net), fee (commission), clearing credit (gross = bank + fee). The Difference column should be zero.
7. Optionally attach the provider's settlement statement PDF / CSV under Attachments.
8. Click Save, review for any orange warnings, then Submit.

BNPL Surcharge Collected

Lists submitted BNPL invoices with the SAR uplift attributed per Mode of Payment (Tabby / Tamara), based on the POS payment snapshot stamped at sale time. Use it to reconcile the surcharge collected against the provider's commission deductions on settlement statements — the two should match closely.

Filters: Company (required), From Date, To Date, Mode of Payment.

Columns: Sales Invoice, Posting Date, Customer, Mode of Payment, BNPL Uplift Attributed, Original Items Total.

Approval Workflow

Every No VAT Sale moves through a four-state workflow before it submits:

Step-by-Step (Creator)

1. Open No VAT Sale → + New.
2. Pick Branch. The Warehouse dropdown is now restricted to that branch’s configured warehouses.
3. Pick Warehouse, customer name, mode of payment.
4. Add item rows. Selling rate auto-fetches from No VAT Price price list, valuation rate from the Bin.
5. Pick Approved By. Required.
6. Save the draft.
7. Click Approval → Send for Approval. Status flips to Pending Approval and the approver gets notified.

Step-by-Step (Approver)

1. Open the ToDo or click the email link.
2. Review items, totals, and warehouse.
3. Click Approval → Approve & Submit. Optional remarks dialog. Doc is submitted; JE + SE post.
4. Or click Approval → Reject. Mandatory reason. Doc stays Draft, creator can edit + resend.

Step-by-Step

1. On a new Sales Invoice, click the + Create New Customer button above the Customer field.
2. Fill in the dialog:
   • Customer Name (required)
   • Mobile No (required)
   • Email ID (optional)
   • VAT Registration Number (optional, exactly 15 digits)
3. If VAT number is entered, address fields become mandatory:
   • Address Line 1, Building Number, Area/District, City, Country, Postal Code
4. Click Create Customer.
5. The new customer is automatically set on the Sales Invoice.

How It Works

1. On a Sales Invoice (or Quotation), click on an item row in the Items table.
2. A stock panel appears below the items table showing stock quantities across all warehouses.
3. The currently selected warehouse is highlighted.
4. Click on any warehouse row to set that warehouse on the item.
5. Click Show All to see all warehouses (default shows top 5).

Step-by-Step

1. Open a New Material Request. The type defaults to Material Transfer.
2. The Target Warehouse (Set Warehouse) auto-fills from your default warehouse permission.
3. Select the Source Warehouse (Set From Warehouse). It is filtered to exclude the target warehouse.
4. Add items and quantities. Schedule Date is auto-set to today.
5. Save and Submit.

Step-by-Step (Requester)

1. Open a New Stock Transfer.
2. The Source Warehouse auto-fills from your default warehouse.
3. Select the Target Warehouse (filtered to exclude source, ignores user permissions so you can send to any warehouse).
4. Add items: select Item Code, set Quantity, and choose UOM (filtered to the item's available UOMs).
5. Save to create as Draft.
6. Click Submit to send for approval (state changes to Pending).

Step-by-Step (Approver)

1. Open the Stock Transfer in Pending state.
2. Review the items and quantities.
3. Click Approve to approve — a Stock Entry (Material Transfer) is automatically created and submitted.
4. Or click Reject to reject the transfer.

Step-by-Step

1. Open the existing Purchase Receipt you want to replace.
2. Click Create → Final GRN.
3. A new Purchase Receipt opens with all data copied:
   • Header fields (supplier, company, currency, etc.)
   • All item rows with quantities, rates, and warehouses
   • Tax rows
   • Posting time is set to 10 minutes before the original
4. Make your corrections (edit quantities, items, etc.).
5. Click Submit.
6. The original Purchase Receipt is automatically cancelled (if submitted) or deleted (if draft).

Step-by-Step

1. Go to the Purchase Receipt list.
2. Select multiple Purchase Receipts using the checkboxes (they must be from the same supplier).
3. Click Actions → Create Single Purchase Invoice.
4. Confirm the action. A single Purchase Invoice is created with all items from all selected receipts.
5. A success message with a link to the new Purchase Invoice appears.

Step-by-Step

1. Open a submitted Quotation.
2. Click Create → Sales Invoice.
3. A new Sales Invoice opens with all items and details mapped from the Quotation.
4. Review, adjust if needed, and Save/Submit.

Step-by-Step

1. Open a Landed Cost Voucher and add the Purchase Receipt(s).
2. Set Distribute Charges Based On to Distribute Manually.
3. Check the Distribute by CBM checkbox (appears after selecting Distribute Manually).
4. In the items table, enter the CBM value for each item.
5. Add the tax/charge row in the Taxes and Charges table.
6. The Applicable Charges column auto-fills proportionally based on each item's CBM ratio.
7. Save and Submit.

Pick a template on the PR

1. Open any Purchase Receipt and expand the LCV Charges Checklist section.
2. Select LCV Charge Template — the default Standard Import KSA ships with 11 charges.
3. Save the PR. The checklist populates with each charge + the correct expense account for the PR's company.
4. A coloured indicator appears at the top of the form showing the status:
   • Not Started — no charge booked yet (grey).
   • Pending — mandatory charges missing (red).
   • Partial — mandatory charges done, optional still pending (orange).
   • Complete — every charge booked (green).

Create the LCV from the template

1. From the PR, click LCV Checklist → Create LCV from Template.
2. A Draft Landed Cost Voucher opens pre-populated with only the pending charges (already-booked rows are skipped).
3. If every pending charge is CBM-based, the LCV is pre-set to Distribute Manually + Distribute by CBM.
4. Enter the actual shipment amounts for each row and submit.
5. Back on the PR, the indicator flips to Complete and each checklist row shows the LCV reference + amount.

Standard Import KSA — shipped charges

Every Company gets these 11 expense accounts (under Indirect Expenses → Landed Cost Charges) and one template row each:

Duplicate the template if you need a variant (e.g. Air-only, road freight) — copy Standard Import KSA, rename, tweak rows. The app will never overwrite a template that isn't the shipped default.

Example — one shipment, three items

If Freight = 2,500 SAR (after exchange), Port = 800 SAR, Mawani = 300 SAR (total 3,600 SAR), the app distributes each charge by the CBM share:

• LED Panel absorbs 1,800 SAR (50%)
• Spot Light absorbs 1,080 SAR (30%)
• UFO 300W absorbs 720 SAR (20%)

Stock valuations (Stock In Hand Dr) increase by those amounts; each expense account (Freight, Port, Mawani) is credited with its own GL entry.

VAT Rules (Customer)

Phone Number Rules

Customer Type

Customer Type options include: Company, Individual, Partnership, Branch.

Duplicate VAT — Sales Manager Override

Genuine cases exist where two Customer records share one VAT number (e.g. subsidiaries under one parent legal entity, the same VAT-registered chain invoicing under two storefronts). Without an override the system rejects the second Customer with:

VAT Registration Number already used by Customer: CUST-0042. A Sales Manager can tick 'Allow Duplicate VAT' to override.

Roles allowed to unlock: Sales Manager, Sales Master Manager, System Manager.

1. Open the new Customer (the one you are trying to save).
2. Tick Allow Duplicate VAT (Manager Override).
3. Fill Duplicate VAT Reason — mandatory. Example: "Branch of CUST-0042, same legal entity, separate storefront".
4. Save. The duplicate check is skipped for this Customer only.

What is pre-filled on a new SI

Branch User lock

For plain Branch Users the Update Stock field is read-only. This prevents accidental credits that skip stock movement. A description appears under the field: “Locked for Branch Users. Contact a Sales Manager to change.”

Users who hold any of these additional roles can still untick the field when needed: Sales Manager, Sales Master Manager, Stock Manager, System Manager, Administrator.

Why this matters

When Update Stock is ticked, submitting the Sales Invoice reduces stock in the selected warehouse immediately — no separate Delivery Note needed. Useful for counter / cash sales.

When it is unticked, stock stays put and you are expected to create a Delivery Note to dispatch goods later (credit-sale flow).

What gets created

• Employee Grades: Sponsorship, Non-Sponsorship.
• Salary Components: Basic, Housing Allowance, Transportation Allowance, Food Allowance, Other Allowance, GOSI Employee.
• Salary Structure: RMAX Sponsorship KSA - <CompanyAbbr> per Company, in Draft. Split shown below.
• No default structure for Non-Sponsorship — attach a custom one per employee if needed.

Sponsorship structure — sample payout on base 10,000 SAR

Enter a monthly base figure on the Salary Structure Assignment for an employee and the components compute automatically. GOSI Employee (deduction) is not pre-filled — add it per employee nationality (Saudi / GCC / expat rules differ).

What to do on day one

1. Open HR → Employee Grade — confirm Sponsorship / Non-Sponsorship exist.
2. Open Salary Structure → RMAX Sponsorship KSA - <CompanyAbbr> (Draft). Review earnings, add deductions if required (GOSI, advances, etc.), then Submit.
3. For each expat employee, create a Salary Structure Assignment picking the shipped structure + entering their monthly base.
4. Non-Sponsorship employees: create a matching Salary Structure (free form) and assign it separately.

Setup (one-time)

1. Open Inter Company Branch master → create one row per (Selling Company, Buying Company) pair. Set the cost center + warehouse the buying side will use when its PI is auto-created.
2. Ensure the Inter Company Price price list exists (auto-created by after_migrate) and item rates are loaded for inter-company prices.
3. Mark the customer record as Internal Customer + set Represents Company on the customer for the buying side.

Daily Flow

1. Branch creates Delivery Note(s) as usual. For inter-company DNs, tick Is Inter-Company and set Inter-Company Branch on the DN. Submit (stock leaves the selling company’s warehouse).
2. Accounts opens the Delivery Note list. Select 2+ submitted inter-company DNs that share the same Customer, Represents Company, Currency, and Inter-Company Branch.
3. Click the list action Create Inter-Company SI.
4. System builds one Draft Sales Invoice on the selling side:
   • Taxes inherited from the first selected DN.
   • Cost Center + Source Warehouse pulled from Inter Company Branch for the selling Company.
   • Update Stock = OFF (DNs already moved stock; this SI is purely the inter-company invoice).
   • Each row mirrors the underlying DN row at the inter-company Price List rate.
5. Each source DN gets stamped: Inter-Company SI = the new SI, Inter-Company Status = Consolidated. They are now locked from being batched again.
6. Review the Draft SI → Submit. On submit:
   • System auto-creates the matching Purchase Invoice on the buying Company.
   • Buying side’s PI uses the cost center + warehouse from Inter Company Branch.
   • If the SI is a return, the system links to the original PI and sets Is Return on the PI side too.

Validation Rules

• Selected DNs must be submitted (docstatus=1).
• Each must have Is Inter-Company ticked.
• All must share the same Customer, Represents Company, Currency, and Inter-Company Branch.
• None already linked to a non-cancelled SI via Inter-Company SI.
• Inter Company Branch master must have a row for the selling Company with valid Cost Center + Warehouse for the buying side.

Any violation aborts the batch with a clear message.

Roles & DocTypes

Step 1 — Branch User: Damage Slip

1. Open Damage Slip → New.
2. Pick Branch Warehouse (the branch warehouse where the damaged stock currently sits).
3. Pick Damage Warehouse (filtered to Damage Jeddah - CNC or Damage Riyadh - CNC).
4. Add item rows (item code + qty).
5. Save + Submit. Status flips to Pending.

Step 2 — Damage User: Damage Transfer (inspection)

1. Open Damage Transfer → New.
2. Pick the Damage Warehouse.
3. Click Get Pending Slips — pulls in submitted Damage Slips for that warehouse.
4. For each item row: attach at least one image (proof of damage) and pick the Supplier Code (Clear Desk / Clear Light / RMAX / Clear Desk USD).
5. Save + Submit. The system auto-creates a Stock Entry (Material Transfer) moving items from the branch warehouse → Damage warehouse.
6. Linked Damage Slips switch from Pending to Transferred.

Step 3 — Admin: Write Off

1. Open the submitted Damage Transfer.
2. Click Write Off (top-right action button).
3. System creates a Stock Entry (Material Issue): Dr Damage / Loss Account, Cr Stock In Hand. Quantity leaves the Damage warehouse permanently.
4. Damage Transfer status → Written Off.

Selling Damaged Stock as Scrap

If damaged items still have salvage value (e.g. metal scrap, returnable shells), see the Scrap Sale section. Sell from the Damage warehouse (where items sit after Damage Transfer) instead of writing them off — preserves the recoverable value as scrap revenue.

Install on Android (APK)

1. Download the latest APK from GitHub Releases → v1.0.19.
2. On the device: Settings → Security → Install from unknown sources (enable).
3. Open the downloaded rmax-wh-v1.0.19.apk and tap Install.
4. App name: RMAX WH. Points to rmaxerp.enfonoerp.com.

Each update is a new APK download. Check Releases page for the latest version.

Install on iOS / Any Browser (PWA)

1. Open Safari on the iPhone (must be Safari for Add to Home Screen).
2. Go to: https://rmaxerp.enfonoerp.com/damage-pwa
3. Tap the Share icon → Add to Home Screen.
4. The PWA appears as an app icon on the home screen.

Login

• Use your ERP username and PIN (set under your User profile in the ERP).
• The app works online only — an active internet connection is required.

One-Time Setup

1. Foundation accounts (Inter-Branch Receivable — Asset, group, under Current Assets — and Inter-Branch Payable — Liability, group, under Current Liabilities) are created automatically per root Company by after_migrate.
2. Per-counterparty leaf accounts (Due from <Branch>, Due to <Branch>) are created lazily the first time they’re needed, plus immediately when a new Branch is added.
3. Open Company → pick the Company → set Inter-Branch Cut-Over Date. Auto-injector is now ON for entries on/after this date.
4. For multi-branch (3+) Journal Entries, set Inter-Branch Bridge Branch on the Company. Every other branch in the JE pairs against the bridge.

Scenario A — HO pays rent for Branch Riyadh

1. Open Accounting → Journal Entry → New.
2. Pick Posting Date and Company.
3. Add line 1: Rent Expense, Debit 1,000, Branch = Riyadh.
4. Add line 2: HO Bank Account, Credit 1,000, Branch = HO.
5. Save.

The system auto-adds:

Submit the JE. Each branch’s books balance independently; consolidated still nets to zero.

Scenario B — Cash transfer HO → Branch

Same flow as A: enter Riyadh Bank Dr 5000, HO Bank Cr 5000. System adds the Due-from/Due-to legs.

Scenario C — Stock transfer between branches (automatic)

Two routes, identical accounting:

• Stock Transfer workflow (preferred for branch users): Material Request → Stock Transfer → Approval. On approval, the system creates the Stock Entry as usual. If source warehouse and target warehouse belong to different branches, a companion Journal Entry records the inter-branch obligation at valuation cost. Source DocType = Stock Transfer.
• Direct Stock Entry (Material Transfer): Stock Manager opens Stock Entry directly. On submit the system resolves each warehouse → Branch via Branch Configuration. Same-branch warehouse pair (e.g. WH-HO-1 ↔ WH-HO-2 both under HO) — no companion JE. Cross-branch — system re-tags the SE’s own GL legs by branch and creates the companion JE. Source DocType = Stock Entry.

Cancelling the source document (Stock Transfer or Stock Entry) auto-cancels the companion JE.

Multi-Branch (3+) JEs — Bridge Mode

If a single JE involves 3 or more branches, the system needs an explicit pivot to know how to pair Due-from/Due-to legs. Set Inter-Branch Bridge Branch on the Company (typically HO) and ensure the bridge is one of the branches in the JE. Every non-bridge branch is then paired against the bridge.

Without a bridge configured, the system rejects 3+ branch JEs with a clear error so you don’t accidentally post unbalanced per-branch books.

Reconciliation Report

Open Reports → Inter-Branch Reconciliation. Matrix view: rows = from branch, columns = to branch, cells = net Due balance for the period. Health check: every (A→B + B→A) pair must sum to zero — non-zero rows flag missing reversals or unmatched legs.

Roles: Accounts Manager, Accounts User, Auditor, System Manager.

How It Works

Filtered DocTypes

Sales Invoice List — Extra Filters

The Sales Invoice list view includes additional standard filters in the header:

App Structure

rmax_custom/
├── hooks.py                          # App config: JS includes, doc_events, fixtures, permissions
├── setup.py                          # after_migrate: Branch User role + DocType permissions
├── inter_company.py                  # Auto PI creation on SI submit
├── landed_cost.py                    # LCV distribution helper
├── branch_defaults.py                # Cost center override for branch users
├── branch_filters.py                 # permission_query_conditions for list filtering
├── overrides/
│   └── landed_cost_voucher.py        # LCV class override (CBM distribution)
├── api/
│   ├── customer.py                   # Quick customer creation + VAT validation
│   ├── sales_invoice_payment.py      # POS payment popup backend
│   ├── warehouse_stock.py            # Stock balance across warehouses
│   ├── material_request.py           # MR creation API
│   ├── purchase_invoice.py           # Bulk PI from multiple PRs
│   └── item.py                       # Party Specific Item creation
├── public/js/
│   ├── enter_navigation_global.js    # Global Enter key → Tab behavior
│   ├── warehouse_stock_popup.js      # Stock panel below items grid
│   ├── sales_invoice_pos_total_popup.js  # POS payment dialog
│   ├── sales_invoice_popup.js        # SI form enhancements
│   ├── create_customer.js            # Quick customer dialog on SI
│   ├── create_multiple_supplier.js   # Bulk supplier linking on Item
│   ├── materiel_request.js           # MR warehouse defaults
│   ├── vat_validation.js             # Customer VAT + phone rules
│   ├── contact_validation.js         # Contact phone validation
│   ├── item_branch_user.js           # Hide cost fields for Branch User
│   ├── purchase receipt.js           # Final GRN flow
│   ├── purchase_receipt_list.js      # Bulk PI from list
│   ├── material_request_list.js      # Urgent indicator
│   ├── sales_invoice_list.js         # Extra list filters
│   └── landed_cost_voucher.js        # CBM distribution client
├── rmax_custom/
│   ├── doctype/
│   │   ├── branch_configuration/     # Branch → Company/WH/CC/Users mapping
│   │   ├── inter_company_branch/     # Inter-company CC/WH config
│   │   ├── stock_transfer/           # Custom transfer with approval workflow
│   │   └── (child tables)            # Config User/WH/CC, ST Item, IC Branch CC
│   └── custom_scripts/quotation/     # Create SI from Quotation button
└── fixtures/
    ├── workflow.json                  # Stock Transfer workflow (4 states)
    ├── role.json                      # Branch User role definition
    ├── custom_field.json              # Custom fields (payment mode, CBM, VAT, urgent)
    └── property_setter.json           # Field tweaks (MR defaults, SI filters, customer type)

Data Flow Diagrams

Sales Invoice (Cash) Flow

User creates SI (Cash mode)
  → Items added (stock check + warehouse popup)
  → Click Submit → Payment Popup appears
  → Allocate amounts across payment modes
  → "Save & Submit"
      → before_validate: cost center override (branch_defaults.py)
      → SI saved + submitted
      → Payment Entries auto-created (one per mode)
      → on_submit: if inter-company → auto-create draft PI (inter_company.py)

Branch Configuration Flow

Admin saves Branch Configuration
  → validate(): check WH/CC belong to Company
  → before_save(): delete permissions for removed users
  → on_update() → create_permissions():
      → User Permission: Company (is_default=1)
      → User Permission: Branch
      → User Permission: Warehouse (first=default)
      → User Permission: Cost Center (first=default)
      → User Permission: Company default CC (is_default=0, access only)
      → Assign "Branch User" role to user

Stock Transfer Approval Flow

User creates Stock Transfer
  → Draft → Send For Approval → Pending
  → Target branch user opens it
  → validate(): check user in target branch's Branch Configuration
  → Approve → on_submit() → create Stock Entry (Material Transfer)
  → OR Reject → stays as draft

app_include_js (loaded on every desk page)

doc_events (server-side hooks)

permission_query_conditions (list filtering)

override_doctype_class

after_migrate

Customer APIs

Payment APIs

Stock & Item APIs

Layer 1: User Permissions (from Branch Configuration)

When a Branch Configuration is saved, these User Permissions are created per user:

Layer 2: DocType Permissions (from setup.py after_migrate)

Custom DocPerm records control which DocTypes the Branch User can read/write/create/submit. These are created programmatically on every bench migrate.

Layer 3: permission_query_conditions (from branch_filters.py)

SQL WHERE clauses injected into list queries to filter documents by branch warehouses. Only affects Branch User role; Admin/Stock Manager bypass.

Logic for SI/PI/DN/PR:

WHERE (
  set_warehouse IN (user's branch warehouses)
  OR name IN (SELECT parent FROM items WHERE warehouse IN (user's WHs))
  OR owner = current_user
)

Layer 4: Cost Center Override (from branch_defaults.py)

Server-side before_validate hook that replaces cost centers the user doesn't have access to. Catches cases where a tax template or item default injects a cost center the branch user can't access.

Layer 5: Client-side Restrictions (from item_branch_user.js)

Hides cost/valuation fields on Item form for Branch Users. Checks frappe.user_roles and only applies if user has Branch User but NOT Stock Manager or System Manager.

Custom Fields

Workflows

Key: Approval is branch-based — only users from the target warehouse's Branch Configuration can approve/reject. Validated in stock_transfer.py → validate().

Dependencies