SYSPRO to Sage X3 Migration: A Technical Guide

SYSPRO to Sage X3 Migration: A Technical Guide

Migrating from SYSPRO to Sage X3 is a structural data translation problem. SYSPRO 8 stores data in Microsoft SQL Server, with module-prefixed tables (ArCustomer, InvMaster, SorMaster) in one database per company (help.syspro.com). Sage X3 organises customers and suppliers as roles of a business partner, and splits products across several tables (BPARTNER, BPCUSTOMER, ITMMASTER, ITMFACILIT, SORDER) (online-help.sagex3.com). There is no vendor-provided migration path between the two. Sage's product migration paths into X3 cover Sage 500 and Sage 300 (sageu.com). Every SYSPRO record must be extracted, transformed, and loaded through X3's import templates or web services.

If you want the scope, approach and price for your own data, start with our SYSPRO to Sage X3 migration page. This guide covers the technical detail.

Why Companies Move from SYSPRO to Sage X3

Two patterns drive this migration:

1. The licensing reset. SYSPRO is moving to a named-user subscription only, and publishes no subscription price (syspro.com). Companies that do not want to subscribe must move before their expiry date, and X3 is one of the ERPs they evaluate.
2. Multi-legislation needs. In Sage X3 each company carries a legislation code, which "determines certain rules and parameters necessary to fulfill country-specific legal requirements" (online-help.sagex3.com). Organisations running entities in several countries look for this.

Understanding the Sage X3 Folder, Company, and Site Hierarchy

SYSPRO migrators often misread Sage X3's organisational structure because it has no direct equivalent in SYSPRO. This conceptual gap causes design errors early in a migration project.

In Sage X3:

• A folder holds the data. Tables are created "in the folder's database" when their activity code and module are active for that folder (online-help.sagex3.com).
• A company is a legal entity. Its legislation code sets country-specific rules, for example FRA for French legislation (online-help.sagex3.com).
• A site (FCY) is where work happens. "All operating actions are performed within a site," and "a site must exist within a company" (online-help.sagex3.com).

SYSPRO equivalent mapping:

When moving from SYSPRO's one-database-per-company model to X3, you must add the correct X3 company and site codes to every record during transformation.

Core Architectural Differences

The X3 product and sales order tables above are the tables Sage lists for its full sales order import template (online-help.sagex3.com). GACCENTRY and GACCOUNT appear in Sage's sales and purchase invoice help (online-help.sagex3.com, online-help.sagex3.com).

The business partner layer is where most SYSPRO-to-X3 migrations first stumble. In SYSPRO, a customer is a row in ArCustomer and a supplier is a row in ApSupplier. In X3, Sage says "a customer can also be a supplier", and in that case "there is a single business partner record" that holds the shared identity, addresses, bank accounts and contacts (online-help.sagex3.com). The X3 Customers function maintains the Customers table together with its business partner, addresses, contacts and bank details (online-help.sagex3.com). Before loading, decide which SYSPRO customers and suppliers are the same company, so they become one business partner rather than two.

GL fiscal period handling is a second structural mismatch. In X3 a journal entry date "must belong to a fiscal year or period that is open for all the ledger types" (online-help.sagex3.com). Periods are managed per company and fiscal year. The fiscal year must be open before its periods can be opened, and periods are opened or closed in order without skipping one (online-help.sagex3.com). Set up and open every historical period you will load into before the GL load starts.

How to Get Data Out of SYSPRO

A one-off, read-only SQL extract is the most complete extraction method for on-premise deployments. SYSPRO 8 stores all data in Microsoft SQL Server, with each company's data in its own database plus a system-wide database (help.syspro.com). SYSPRO's database guide says "Each SYSPRO 8 company database contains approximately 1000 tables" (same source). SQL reaches every one of them, including the plus tables for custom form data. Our SYSPRO SQL table map lists the verified table names.

SYSPRO's own best-practice guide warns that "Connecting to the SYSPRO databases directly using SQL drivers is not advised" (help.syspro.com). That warning targets live integrations. For a migration extract, use a read-only login, ideally against a restored copy of the database, and never write back.

-- Read the customer master and its custom form data.
-- Inspect both tables, then join on the customer key.
SELECT * FROM ArCustomer;
SELECT * FROM [ArCustomer+];

Business Activity Queries (BAQs) "are SQL views that are created in the relevant company databases". "Any SQL user with db_datareader permissions can retrieve data using the views" (help.syspro.com).

e.net business objects such as ARSQRY (Customer Query), INVQRY (Inventory Query), and SORQRY (Sales Order Query) return XML for one record or a filtered set (help.syspro.com). They suit integration and validation, not bulk extraction. SYSPRO notes that archived sales orders cannot be queried with SORQRY (help.syspro.com). If SYSPRO's archive process has already moved historical orders to XML files, an extract built on SORQRY will silently miss them.

SYSPRO OData Service is read-only. SYSPRO's 2021 R2 help says it is limited to 5,000 rows "under the Microsoft best practice guidelines for performance and fair use", with $top and $skip paging (help.syspro.com). It "is the only mechanism available when applications need access to SYSPRO data in the Syspro Cloud ERP environment" (help.syspro.com). For example, a 500,000-row SorDetail table takes 100 paginated calls.

For migration, a read-only SQL extract is the preferred path. Where SQL is not possible, including Syspro Cloud ERP, use paginated OData reads.

How to Load Data into Sage X3

Load through X3's application layer, not by writing to its database. Sage's import/export module "uses the notion of objects to update the database" (online-help.sagex3.com), so X3's own controls run on every record. X3 offers two loading surfaces.

Import/export templates (GESAOE, run through the Imports function GIMPOBJ) are the main bulk loading mechanism. A template reads a flat file with fixed-length fields, a flat file with separators, or an XML file (online-help.sagex3.com). The Imports function shows an import log with the results. It can also move lines in an incorrect format to a temporary storage area. Sage says: "This enables rejected data to be corrected and reimported if necessary" (online-help.sagex3.com).

The template's field separator is configurable (online-help.sagex3.com). Pick one that never appears in your data, such as a pipe (|), because address data is full of commas. Load order matters: business partners and products must exist before orders and invoices.

Web services. X3 web services use the api1 protocol over HTTP, with GET for queries and details, POST to create, PUT to update and DELETE to delete. The platform also supports SOAP web services (online-help.sagex3.com). A request URL names the server and service, then api1, the application and contract (x3/$$prod/ for X3 data), the folder endpoint, and the entity. Sage's example creates a customer with a POST to .../x3/$$prod/DEMO.BPCUSTOMER?representation=BPCUSTOMER.$edit. Sage also notes that "sdata must no longer be used in webservice mode" (online-help.sagex3.com).

Query results come back 20 items per page by default, with $links for the next and previous page (online-help.sagex3.com). Responses to a POST carry $diagnoses entries with a $severity and a $message (online-help.sagex3.com). Log those per record so failed rows can be fixed and replayed.

// Pseudo-code for a Sage X3 web service load
async function loadCustomerToSage(customer) {
    const payload = {
        "BPCNUM": customer.code,
        "BPCNAM": customer.name,
        "CUR": customer.currency
    };
 
    const response = await axios.post(
        'https://x3-server:8124/api1/x3/$$prod/FOLDER.BPCUSTOMER?representation=BPCUSTOMER.$edit',
        payload,
        { headers: { 'Authorization': authHeader } }
    );
    // Record every $diagnoses entry with its $severity and $message
    logDiagnoses(customer.code, response.data);
    return response.data;
}

Data Model and Object Mapping

Mapping SYSPRO's tables to Sage X3's objects is the most critical phase. Parent records must exist before the records that reference them. The load order column below reflects those dependency chains.

SYSPRO to Sage X3 Entity Map

Customer Fields in Sage X3

SYSPRO column names vary by release, so read them from your own database. On the X3 side, the Customers function uses these fields (online-help.sagex3.com):

Tax Code and UOM Mapping

Tax codes are a high-failure-rate field. In X3, a tax rule "represents the tax territoriality principle, in other words, the calculation rules" for a business partner, and it is set on the customer with the VACBPR field (online-help.sagex3.com). There is no automated crosswalk from SYSPRO's tax codes. Each SYSPRO tax code must be matched by hand to an X3 tax rule and tax code. After loading invoices, compare line counts and tax totals with the source, not just header counts.

Unit of measure (UOM) codes in X3 "serve to qualify all 'Quantity' fields in the software and are used by all the modules" (online-help.sagex3.com). They sit in TABUNIT. Years of manual entry can leave variants such as EA, EACH and Each in SYSPRO. Before loading products, normalise all UOM values and confirm each one exists in X3.

How Do SYSPRO Custom Fields Map to Sage X3?

SYSPRO stores custom form data in plus tables, for example [ArCustomer+] for customer custom fields (help.syspro.com). In Sage X3, "for custom or specific fields, the field name must start with X_, Y_, or Z_". Tables tied to activity codes that start with X, Y or Z "are considered specific or custom and are not affected by version changes" (online-help.sagex3.com). Before migration, each SYSPRO custom field must be created in the X3 data dictionary, added to the relevant screen, and included in the import template. There is no automated mapping. The effort grows with every plus-table field you keep. Our guide to migrating SYSPRO custom form fields and plus tables covers the SYSPRO side in depth.

BOM and Routing Migration

Bill of materials and routing migration is one of the hardest areas in a SYSPRO-to-X3 migration.

SYSPRO side: routing steps are held in BomOperations and work centres in BomWorkCentre (help.syspro.com). Engineering change controlled bills may already have been archived to XML (archive type BO).

Sage X3 side: a work center is "a production resource that is to be used for an operation in a routing" (online-help.sagex3.com). A routing defines "the sequence of shop floor processes that are needed to produce, or process a particular product" (online-help.sagex3.com).

Key transformation requirements:

• Create SYSPRO work centres as X3 work centers before any routing references them.
• Keep the link between each component line and the operation it is issued to.
• Convert scrap, effective dates and alternate structures field by field, and agree each conversion rule with the production team before loading.

Load work centers before routings, routings before BOMs, and BOMs before production orders or WIP records.

Migration Approaches

CSV/Template-Based Migration

Extract from SYSPRO with read-only SQL, transform in Python or ETL tooling, load through X3 import templates. Best for: one-time bulk loading of master data. Complexity: Medium. Risks: separator handling, field-length mismatches, and load-order violations.

API-Based Migration

Extract from SYSPRO via SQL or OData, transform in flight, load through X3 web services. Best for: delta loads or cases needing per-record validation feedback. Complexity: High. Risks: per-record calls are slower than bulk templates, so test throughput on your own X3 server. Retry failed calls with backoff. Do not resend a rejected record until its $diagnoses are fixed.

Custom ETL Pipeline

Purpose-built scripts (Python, Node.js) or tools like Azure Data Factory handle extraction, transformation, and loading through a mix of templates and web services. Best for: complex migrations with heavy custom fields, multi-company rollups, or large manufacturing datasets. Complexity: High.

Managed Migration Service

Hand the data migration to a specialist. The implementation partner handles ERP configuration, and the migration partner handles the data move. Best for: teams without dedicated migration engineers, or those facing the SYSPRO licence deadline.

Step-by-Step Migration Process

1. Audit SYSPRO Data

Query each source table for row counts, null rates, and custom field usage. Identify archived data in XML files (sales orders, jobs, ECC bills of materials). Check plus tables for custom form data. Find which records are active across ArCustomer, ApSupplier, and InvMaster. Audit UOM codes for inconsistencies. List every tax code in use on customers and order lines.

2. Define Scope

Decide which entities migrate (master data, open transactions, historical transactions) and how far back. Use the move to drop outdated stock codes and inactive customers. Define which historical fiscal periods must be open in X3 to receive GL transactions. See What Data Should You Actually Migrate to Your New ERP? for scoping guidance. For job history, see SYSPRO WIP and job history: migrate or archive?

3. Prepare the Sage X3 Target

Create custom X_, Y_ or Z_ fields, and configure payment terms, tax rules, and the chart of accounts. Set up and open the fiscal years and periods that will receive GL transactions. Build or modify import templates for each object. Make sure all reference data (currencies, UOMs, customer categories, tax rules, work centers) exists before loading transactional data.

4. Extract from SYSPRO

Run read-only SQL queries against the company database, ideally a restored copy. Export plus table data with bracket-escaped names ([ArCustomer+]). Export currencies and exchange rates from TblCurrency and TblCurrDatedRates (help.syspro.com). Extract routing data from BomOperations and work centres from BomWorkCentre. For archived records in scope, extract from the XML archive files before going further.

5. Transform and Map

Map SYSPRO data to X3 fields. Turn ArCustomer and ApSupplier rows into business partners, merging companies that are both. Split InvMaster data across ITMMASTER, ITMSALES and ITMFACILIT. Convert UOM codes, tax mappings, and payment terms. Add X3 company and site codes to every record. For web services, build the JSON payload. For templates, format the delimited file with your chosen separator.

6. Load in Dependency Order

Follow the load sequence strictly: setup data (currencies, UOMs, tax rules) → fiscal periods → GL accounts → work centers → business partners → products and sites → routings and BOMs → inventory balances → open orders → open invoices → journal entries. Run sample migrations on a subset of every entity before loading production volumes. ClonePartner runs unlimited sample migrations before the full run.

7. Validate

Run record-count parity checks, field-level validation on a sample, GL trial balance reconciliation, and referential integrity checks. See the validation section below.

8. Delta Sync and Cutover

Go live on a Monday, never on a Friday. Run the bulk load in the days before go-live while SYSPRO stays live. Freeze SYSPRO before Monday's working day starts. Run a final delta covering changed records only, which takes about 30 minutes. Confirm record-count parity and GL balance reconciliation, then go live on X3.

Edge Cases That Break Migrations

Multi-address customers. X3 holds addresses in BPADDRESS, linked to the business partner (online-help.sagex3.com). Each SYSPRO ship-to or remit-to address must become its own X3 address record.

Archived sales orders. SORQRY cannot query archived sales orders in SYSPRO (help.syspro.com). If you need historical orders, extract them from the sales order archive files (archive type SO) before migration.

Lot and serial history. SYSPRO's lot Purge and Archive program copies "lot transactions and inspection records to an archive file", and "the header record is never deleted from the lot master table; only the lot transactions are deleted and archived" (help.syspro.com). A query of LotDetail can return plausible row counts while the movement history sits in the archive. If lot traceability continuity is required in X3, audit the archive before extraction, not after. See SYSPRO lot and serial traceability migration for the full approach.

GL fiscal period mismatch. X3 rejects journal entries dated in a period that is not open for all ledger types (online-help.sagex3.com). Open all required historical periods in X3 before the GL load, even if you close them again right after migration.

Work in progress (WIP). SYSPRO tracks jobs in WipMaster, WipJobAllMat, and WipJobAllLab (help.syspro.com). Moving open WIP to Sage X3 means recreating production orders, which often needs manual reconciliation. There is no clean automated path for in-flight work orders. Flush the shop floor before cutover, or plan for manual entry of open WIP in X3.

Multi-company databases. SYSPRO uses a separate database for each company. In Sage X3, companies and their sites live in the same folder. Add the correct company and site codes to every record during transformation.

Import template separator collisions. X3 splits fields on the separator set in the template. Address data containing that character will corrupt field alignment. Use a separator that never appears in your data, and strip or replace newline characters embedded in address or notes fields during transformation.

Tax code mismatches on invoice lines. Check every invoice's line count and tax total against the source after loading, not just the invoice header count.

Validation and Testing

Never treat a successful web service response or a completed template import as proof of data integrity.

• Record-count parity across every entity between SYSPRO source tables and X3 target tables. Include line counts: compare SORDERQ lines with SorDetail lines, not just SORDER headers with SorMaster.
• Field-level validation on a sample of records, comparing source values with loaded values. Prioritise high-failure fields: tax codes, UOM codes, payment terms, and custom fields.
• GL trial balance reconciliation. Closing balances in SYSPRO must match opening balances in X3 at account level, not just in total.
• Invoice line count validation. Every invoice's line count in X3 must match the source.
• Referential integrity checks. Every sales order references a valid customer, every invoice a valid product, and every lot record a valid item.
• BOM structure validation. Component counts per BOM must match the source. Spot-check converted scrap values.
• UAT with business users. Operations, finance, and warehouse teams confirm their workflows run on the migrated data.
• Rollback plan. Keep SYSPRO data available, in SYSPRO while your licence lasts or in an archive after it, until validation is signed off by business owners.

For a structured approach, see The Ultimate ERP Data Migration Checklist and How to Build a Data Migration Playbook.

Data Migration vs. ERP Implementation: Two Separate Clocks

These are two different workstreams. The data migration (extracting from SYSPRO, transforming, loading into X3, and validating) takes days. Most data migrations complete within 1 to 5 business days, depending on data volume, complexity, and API rate limits. Small datasets under 10,000 records can finish in under 24 hours.

The ERP implementation (configuring Sage X3 modules, setting up workflows, training users, running UAT and going live) takes months. The customer's implementation partner or Sage runs it. ClonePartner does not implement ERPs.

The SYSPRO deadline sits on a third timeline. If your licence expires before X3 is ready, extract and archive your SYSPRO data before your expiry date (31 October 2026 outside the US, 31 December 2026 in the US), then load it into X3 when the implementation is ready.

When to Use a Managed Migration Service

Build in-house when your team knows both SYSPRO's SQL schema and Sage X3's import templates well, the scope is limited to master data with few custom fields, and engineering capacity is not tied up in the implementation.

Use a managed service when:

• Custom field density is high. SYSPRO plus tables with dozens of fields need matching X3 custom fields and template changes, and the work grows with each field.
• Manufacturing data is in scope. BOMs, routings, WIP jobs, and lot and serial traceability chains involve multi-table joins on both sides, strict load order, and archive traps.
• The SYSPRO licensing deadline is the forcing function. Engineering time spent on a one-time data migration is time not spent on X3 configuration and user training.
• Historical data volume is large. Archived subsets need careful reconstruction, fiscal period management, and batch loading with retry logic.
• Tax code mapping is complex. Organisations with several tax jurisdictions should have migration engineers check the tax rule crosswalk before loading invoices.

ClonePartner is vendor-neutral and does not resell either SYSPRO or Sage X3. We handle the data layer (extraction, transformation, loading, and validation) with record-count parity, field-level checks, and reconciliation reports.

• Fixed pricing: one fixed price per project, starting at $500 (clonepartner.com). No hourly billing and no per-record metering.
• Speed: most data migrations complete within 1–5 business days, depending on data volume, complexity, and API rate limits.
• Security: SOC 2 Type II and ISO 27001. Staging data is purged within 30 days of project close.

See the SYSPRO to Sage X3 migration page for scope and pricing.