ERPNext Africa · migration playbook
Sage X3 → ERPNext Migration Playbook
Migrating mid-to-large manufacturers and distributors off Sage X3 (Sage Enterprise Management) onto ERPNext — and the ways X3 differs from a simpler source like SysPro.
◆ Originated under imbilawork for the ERPNext Africa venture · June 2026 · reusable IP, to be handed to ERPNext Africa
How Sage X3 differs from SysPro (read this first)X3 is a heavier, multi-legislation ERP. Four things shape the whole migration:
- Unified Business Partner (
BPARTNER/BPCUSTOMER/BPSUPPLIER) — one partner can be customer and supplier; ERPNext splits these into separate Customer + Supplier records. - Multi-ledger / multi-legislation accounting — X3 keeps several ledgers (actual, IFRS/local, analytical) per company; ERPNext has one statutory ledger + Accounting Dimensions. You must choose the source-of-truth ledger.
- Folders (dossiers) — X3 runs a parent reference folder + child folders (legislations/test/prod). Confirm which folder is the source.
- Database can be Oracle or SQL Server — extraction tooling depends on which (SysPro is always SQL Server).
The five-stage method below mirrors the SysPro playbook — the principles (reconcile to the cent, phased over big-bang, opening balances + current-year only, dependency-ordered load, explicit SA localisation) are identical. This page focuses on the X3-specific mechanics.
01 · Discovery & Assessment
- Folders & legislations — list the X3 folders, which legislations/companies are live, and which folder is the migration source.
- Ledgers in use — actual / IFRS / local / analytical; decide which ledger maps to ERPNext's statutory ledger and how analytical dimensions carry over.
- Modules in use — Finance (GL/AP/AR/Fixed Assets), Sales, Purchasing, Inventory (multi-site), Manufacturing (BOM/routing/work orders), Projects, plus any X3 vertical add-ons.
- Customisations — X3 4GL (L4G) specifics, custom screens/entry points, Sage X3 workflow, Crystal/SAP BI reports. As with any ERP, these don't port 1:1 — re-implement or retire.
- Integrations — EDI, bank, CRM, BI/data-warehouse, e-commerce.
- DB platform — Oracle or SQL Server (drives extraction).
- Localisation — SA VAT (VAT201), multi-currency, multi-company.
Reconciliation contract (same rule as always)Trial balance @ cutover (per chosen ledger), AR & AP aging, stock qty + valuation per site, open SO/PO/WO, bank balances — must match to the cent before go-live, signed off by the client finance lead.
02 · Module & Data Mapping (Sage X3 → ERPNext)
Key X3 tables (verify per version/folder)
| X3 table | Holds | → ERPNext |
|---|---|---|
GACCENTRY / GACCENTRYD | GL journal entries (header/detail) | Journal Entry / GL (opening + current-year) |
GACCOUNT + account structure | Chart of accounts (by ledger) | Account (tree) — flatten chosen ledger |
CACCE / analytical dims | Analytical accounting | Cost Center / Accounting Dimensions |
BPARTNER / BPCUSTOMER / BPSUPPLIER | Unified business partner; customer & supplier roles | Split into Customer + Supplier (same BP can become both) |
ITMMASTER / ITMFACILIT | Item master / item-site settings | Item / Item Defaults per Warehouse |
ITMMVT / STOJOU / STOCK | Stock movements / journal / on-hand | Opening Stock Reconciliation (qty + valuation per site) |
SORDER/SORDERP/SORDERQ | Sales order header/line/qty | Sales Order (open only) |
SDELIVERYD · SINVOICE | Deliveries · sales invoices | Delivery Note · Sales Invoice (open items) |
PORDER · PINVOICE | Purchase orders · invoices | Purchase Order · Purchase Invoice (open) |
BOM/BOMD · ROUTING | Bills of material · routings | BOM · Operation + Workstation + Routing |
MFGHEAD / MFGITMTRK | Work orders / tracking | Work Order + Job Card (open jobs only) |
The two X3-specific transforms that bite1 · Business-Partner split — dedupe BPs and fan them out into Customer and/or Supplier; preserve the BP code as a cross-reference. 2 · Ledger collapse — pick one ledger as the GL source of truth; carry analytical accounting as ERPNext Cost Centers / Accounting Dimensions, not as parallel ledgers.
03 · Data Migration — Extract, Transform, Load
Extraction paths (X3-specific)
- Direct SQL against the X3 database (Oracle or SQL Server) — best fidelity; needs DBA access and knowledge of the table set + the active folder's schema.
- X3 import/export templates — X3's native template-based export to flat files (good for masters; respects X3's own validation).
- X3 web services / REST — where direct DB access is restricted.
Then the same pattern as SysPro: extract → stage to clean CSV → load (Data Import for masters; scripted, reconciled ETL for transactions & opening balances). See the SysPro data-migration section for the tooling detail.
Load sequence (dependency order)
- Company (per legal entity) + fiscal years + currencies
- Chart of Accounts (chosen ledger → tree) + Cost Centers / Accounting Dimensions
- Tax templates (+
csf_zaVAT) - Groups & dimensions — Customer/Supplier/Item Groups, UOMs, Warehouses (sites), Price Lists
- Master data — Customers & Suppliers (from the BP split), Items, Item Prices, BOMs, Routings
- Opening stock — Stock Reconciliation per item per site
- Opening financial balances — opening JE (chosen ledger), open AR/AP
- Open transactions — open SOs, POs, Work Orders
- Current-year detail (only if in-system history is needed)
Opening-balances golden ruleBalances as of the cutover date, then current-year detail only — archive the rest. Reconcile each step against X3 before moving on. Idempotent loads; ≥2 full dry-runs before go-live.
04 · Cutover & Go-Live
Identical discipline to the SysPro playbook:
- Timing — month-end / low-activity; freeze the source folder during final extract+load.
- Parallel run — ~2 weeks dual entry, reconcile weekly.
- Reconciliation gate (go/no-go) — trial balance (chosen ledger), AR/AP aging, stock qty+valuation, open SO/PO/WO, bank — all tie, finance-lead signed off.
- X3 → read-only post-cutover; defined rollback + owner before go-live; 2–4 weeks hypercare with daily mini-reconciliation.
05 · Risks & Gotchas (X3-specific)
- Multi-ledger confusion — migrating the wrong ledger, or trying to keep all ledgers, breaks the GL. Decide and document the source ledger early.
- Business-Partner model — a BP that is both customer and supplier must become two ERPNext records, linked back to the BP code; missing this corrupts AR/AP.
- Analytical accounting — X3's analytical dimensions don't map to a second ledger in ERPNext; use Accounting Dimensions / Cost Centers, agreed with finance.
- Folders — pulling from the wrong folder (test vs prod, or the reference folder) yields wrong data. Confirm the source folder.
- Oracle vs SQL Server — extraction scripts and types differ; confirm the DB platform up front.
- Heavy customisation & 4GL — X3 implementations are often deeply customised; budget for re-implementing logic as ERPNext customisations, not porting it.
- Scale — X3 clients are typically larger than SysPro ones; data volumes push you toward scripted ETL over the Data Import tool, and lengthen the timeline.
- SA localisation — VAT201 via
csf_za; multi-currency rounding verified on a sample.
The meta-riskSame as ever: if you can't reconcile to the cent, you don't go live.
Sources
Sage X3 architecture & data model: Sage — X3 Architecture · X3 online help — ITMMASTER · DataSelf — X3 pre-mapped tables · X3 architecture schema · RKL — X3 modules
X3 migration: Greytrix · CertiPro · Platform3 roadmap · Frappe forum — Sage→ERPNext
Shared migration method: see the SysPro → ERPNext playbook (sources cited there for ERPNext data import, opening balances & cutover best practice).