Uph

bench get-app https://github.com/Sendipad/uph

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Sendipad%2Fuph)](https://frappegems.com/gems/apps/Sendipad/uph)

--- ## 🖼️ Visual Insights

Advanced Tree Hierarchy providing consolidated financial visibility at every node.

### Party Workspace

Centralized Party Workspace for unified management and reporting.

### Data Quality & Governance ### Conflict Resolution ### Smart Linking

Fuzzy matching and Smart Linking interface to easily assign ERPNext parties to their Master Entity.

--- # Unified Party Hub (UPH) **Unified Party Hub (UPH)** is an enterprise-grade Master Data Management (MDM) extension for ERPNext. It centralizes siloed business roles (Customers, Suppliers, Employees) into a unified, tree-based hierarchy, providing consolidated financial visibility and rigorous data governance across complex business ecosystems. > **Target users:** ERPNext implementers who need a single, governed entity for parties that can act as customer, supplier, employee, etc. ## Overview Standard ERPNext implementations often face challenges when managing complex business entities: - **Fragmented Identity**: A single legal entity acting as both a Customer and a Supplier exists as two disconnected documents. - **Multi-Currency Logic**: Transacting with the same party in multiple currencies often requires creating duplicate party records (e.g., "Customer USD", "Customer EUR") to map to specific Receivable/Payable accounts. - **Siloed Reporting**: Financial reports (General Ledger, Aging) are segmented by the specific Party record, making it difficult to get a 360-degree view of the legal entity's total exposure. - **Data Redundancy**: Address and Contact data must be duplicated across multiple party roles. UPH solves these problems by introducing the **Party Master** - a central governance layer that sits above standard ERPNext Party types. --- ## v3 Update Notes (Merge Confirmation) ### ✅ Migration Patch Included The v3 merge includes a post-model migration patch: - `uph.patches.migrate_duplicate_exclusion_to_party_issue` This patch migrates legacy **Duplicate Exclusion** records into **Party Issue** records and maps legacy statuses (`Detected`, `Dismissed`, `Merged`) into the new issue workflow states (`Open`, `Ignored`, `Resolved`). ### New UX/UI Additions in v3 - **UPH Setup Wizard** (`uph-setup-wizard`) for first-run setup, language/template selection, numbering rules, and safe seeding options. - **Auto-redirect guard** for Administrator/System Manager to enforce setup completion before using core UPH forms/tree views. - **Data Quality Dashboard UX expansion** with dedicated tabs for Duplicate Issues, Unlinked Roles, Unlinked Vouchers, and Transaction Health. ### Key Feature Fixes/Enhancements in v3 - Unified governance model using **Party Issue** as the operational issue registry. - Duplicate scanning with normalized fuzzy matching and queue-based execution. - Unlinked role resolution with suggestion-based linking and create-from-role flow. - Transaction policy checks for draft aging, cancelled-unamended detection, and party-master mismatch analysis. --- ## Quick Start > **Prerequisites:** Frappe/ERPNext v15+ and a working bench site. ### Getting Started: Prevent Customer/Supplier Name Overwrites If you want to stop `customer_name` / `supplier_name` from changing after a rename, pick one: 1. Change ERPNext naming settings Set “Customer Naming By” to `Naming Series` in **Selling Settings**. Set “Supplier Naming By” to `Naming Series` in **Buying Settings**. This prevents `after_rename` from overwriting `customer_name` / `supplier_name`. 2. Code override (UPH) Implement a small hook to skip updating `customer_name` / `supplier_name` during rename events. If you want this pattern in-core, open an issue or PR and reference your expected behavior. ```bash # Install app bench get-app https://github.com/Sendipad/uph bench --site {your-site} install-app uph # Migrate to apply fixtures and setup bench --site {your-site} migrate ``` After install, open **Party Master Settings** and review: - Party type rules - Doctype mappings for transactional documents - Duplicate voucher prevention rules --- ## Core DocTypes UPH introduces the following DocTypes to manage party data: ### 1. Party Master ([`Party Master`](uph/party/doctype/party_master/party_master.json)) The central hub for all party entities. Key features: - **Tree-based Hierarchy**: Supports parent-child relationships for organizational structures - **Hierarchical Numbering**: Automatic numbering based on parent node - **Multi-Role Support**: Link Customers, Suppliers, Employees under one entity - **Legal Identity**: Tax ID, registration numbers, legal entity types - **Contacts & Addresses**: Centralized contact and address management - **Primary/Secondary Roles**: Define primary role and link secondary roles - **Internal Party**: Mark as internal party for inter-company transactions ### 2. Party Analytic Accounting ([`Party Analytic Accounting`](uph/party/doctype/party_analytic_accounting/party_analytic_accounting.json)) Enables Oracle TCA-like site accounting. Features: - **Accounting Non-Duplication**: Eliminates redundant accounts for branches - **Multiple Dimension Types**: Site, Business Unit, Branch, Territory, Cost Center, Factory/Plant - **Company-Specific Rules**: Configure rules per company - **Effective Dating**: Track validity periods for accounting dimensions - **Allow/Restrict Rules**: Control which parties can use specific dimensions ### 3. Party Master Parties ([`Party Master Parties`](uph/party/doctype/party_master_parties/party_master_parties.json)) Junction table linking Party Master to ERPNext parties: - **Dynamic Links**: Links to Customer, Supplier, Employee, Shareholder - **Currency Tracking**: Track currency per linked party - **Party Name**: Reference to the linked party name ### 4. Party Master Settings ([`Party Master Settings`](uph/party/doctype/party_master_settings/party_master_settings.json)) Central configuration for UPH: - **Party Type Rules**: Configure uniqueness rules per party type - **DocType Mapping**: Inject party_master field into transactional documents - **Field Synchronization**: Sync fields between Party Master and linked parties - **PAA Configuration**: Enable and configure Party Analytic Accounting - **Tree View Settings**: Auto-expand levels, hide balance - **Duplicate Voucher Check**: Prevent duplicate vouchers for same Party Master ### 5. Party Relationship ([`Party Relationship`](uph/party/doctype/party_relationship/party_relationship.json)) Define N-to-N relationships between parties: - **Relationship Types**: Parent/Subsidiary, Ownership, Management - **Ownership Percentages**: Track ownership stakes - **Validity Periods**: Define relationship effective dates - **Party Relationship Type**: Configure relationship type master data ### 6. Duplicate Exclusion ([`Duplicate Exclusion`](uph/party/doctype/duplicate_exclusion/duplicate_exclusion.json)) Rules for excluding duplicates: - **Exclusion Criteria**: Define rules to ignore certain duplicates - **Document Types**: Apply rules to specific doctypes ### 7. Party Issue ([`Party Issue`](uph/party/doctype/party_issue/party_issue.json)) Unified governance issue registry introduced in v3: - **Issue Types**: Duplicate, Unlinked, Health, Transaction Policy - **Workflow States**: Open, Under Review, Resolved, Ignored - **Operational Metadata**: score, source engine, references, JSON details - **Migration Target**: receives migrated records from legacy Duplicate Exclusion patch --- ## Key Workflows ### 1) Create a Party Master 1. Create a new **Party Master**. 2. Set **Party Type**, legal identity fields, and (optionally) hierarchy parent. 3. Link existing parties (Customer/Supplier/Employee) or create new ones. ### 2) Link Existing Parties Use **Party Master > Parties** to link existing parties to a single entity. The system enforces: - Role rules (primary/secondary). - Duplicate constraints from **Party Master Settings**. ### 3) Transactional Validation - Transactional documents mapped in **Party Master Settings** will validate or auto‑set `party_master`. - Party Analytic Accounting (PAA) valid