Saudi Odoo migration rehearsal workbook: from extract to signed acceptance

Set up the workbook and its decision rules

Create tabs for source systems, migration objects, field mappings, external IDs, extract runs, import runs, reconciliation, defects, rehearsal comparisons and cutover approval. Give each object and run a stable ID so that a mapping change can be traced to its test and business acceptance.

For every object, record the business purpose, source owner, target owner, extraction method, cleansing owner, mapping reviewer, dependency position, create/update rule, expected count, reconciliation method and final approver. State what is explicitly out of scope and how authorised users will access any retained archive.

A migration is accepted only when technical repeatability and business correctness are both evidenced. An import log without errors does not establish that a VAT number, Arabic name, account, stock value or open invoice is correct.

Define each migration object by business purpose

Separate companies, accounting settings, accounts, journals, taxes, customers, suppliers, products, units, branches or analytic dimensions, open invoices and bills, payments, opening entries, bank statements, stock, historical documents and attachments. Each has different dependencies and acceptance tests.

For Zoho Books, QuickBooks and spreadsheet sources, record the exact organisation, edition or file and the available export or authorised API path. Inspect actual rows before choosing a mapping. Do not infer the presence or meaning of custom fields, classes, locations, taxes or inventory from the product name alone.

Decide whether the target needs a transactional record, opening position, reference only or archive link. The decision explains why the object is needed, who uses it after cutover and how it will be reconciled. This avoids both unnecessary historical volume and the loss of operationally necessary detail.

Control extraction and source-data cleansing

Use versioned, read-only source extracts with a named extraction time and parameters. Save expected row counts, source totals and file hashes or equivalent controlled identifiers where your process supports them. Restrict access to financial, employee and personal data to the approved migration group.

Cleansing rules cover duplicate parties, missing legal names, invalid VAT identifiers, incomplete Arabic names or addresses, obsolete items, inconsistent units, inactive accounts, broken dates and orphan references. The business data owner approves the corrected value; the import developer does not invent it.

Keep the original source value, corrected value, reason, owner and approval in the cleansing log. Repeating an extract should not silently undo an approved correction or apply a different manual edit. Where the source can be corrected directly, record whether the new extract supersedes the earlier cleansing action.

Map fields and durable external IDs

The mapping sheet names the source object and field, source example, transformation rule, target model and field, required status, default rule, reviewer and test scenario. Include Arabic display names and descriptions, legal identifiers, addresses, currency, accounts, tax codes, units, branches and custom dimensions.

Assign a stable, namespaced external ID to each imported record. Derive it from a durable source identifier under a documented rule, not from spreadsheet row position. Define whether reruns create, update, skip or require manual review, and how dependent records resolve the same external ID.

Test changes to a source value and to a target mapping between runs. The intended record should update without creating a duplicate, and dependent documents should retain the correct party, item, account and tax relationship. AI-assisted mapping or anomaly detection can support review, but named people approve every material rule and exception.

Publish the dependency sequence before loading documents

The dependency register shows which objects must be accepted before the next load begins. Accounting foundations and companies come before their journals and taxes; parties and products come before documents; accounts, taxes and dimensions must be ready before opening entries; warehouses and items must be stable before stock positions.

Include users, roles and technical configuration where they affect ownership or access. Bank statements, inventory, historical documents and attachments receive their own sequence and prerequisites. A failed prerequisite stops the dependent wave unless the runbook records a reviewed alternative.

Each import wave records its start and completion, operator, source version, mapping version, target environment, expected and actual counts, errors, warnings and approval. The sequence is part of the rehearsal evidence, not an informal note held by one developer.

Reconcile opening balances, history and the ZATCA boundary

Reviewed 5 November 2026. Finance agrees the cutover date, trial balance, receivables, payables, tax-control accounts, bank balances, currency positions and inventory valuation. Reconcile at the agreed detail level, including party and currency for open documents and warehouse and item for stock.

Historical transactions and attachments are scoped separately from open documents and opening positions. Importing historical invoices does not make them new Phase 2 submissions by default. The runbook separates historical references from new production documents and controls numbering, original-invoice references and duplicate prevention.

The Odoo 19 Saudi localisation documents Phase 1 QR and Phase 2 integration modules, while ZATCA's roll-out phases and the taxpayer's notification control the applicable wave context. New Odoo invoices are tested in their intended environment and journal, with Arabic output, XML, credit and debit notes and final status reviewed separately from migrated history.

Make every import run repeatable and reviewable

The run record includes the operator, target environment, exact extract and mapping versions, start and end steps, expected and actual counts, created and updated records, rejected rows, warnings and exceptions. Logs are retained in a controlled location with sensitive values protected.

After a failure, document the cause, affected object and dependent waves, correction, rerun rule and reviewer. A rerun uses the same external-ID and dependency logic so that it repairs the intended records without duplicating accepted data. Manual database changes are avoided unless explicitly controlled, documented and reviewed.

Assisted transformation never becomes unattended acceptance. Reviewers inspect source meaning, mapping decisions, exceptions and final financial and operational results. If a tool generates code or values, its output enters the same version control, test and approval process as any other migration component.

Use reconciliation packs that business owners can sign

The finance pack compares source and target trial balances, receivables, payables, tax accounts, bank balances and currency positions. It also samples documents line by line for party, account, tax, quantity, amount, due date and reference. Each difference has a category, explanation, owner, correction and reviewer.

The operations pack compares stock quantities and valuation, open purchase or sales work, units, warehouses and other scoped operational states. Users execute representative downstream transactions to prove that migrated records can be used, not merely viewed.

The Arabic data pack checks names, addresses, item descriptions and future invoice output. It links to Arabic rendering and XML acceptance where those records are used in new ZATCA scenarios. Sign-off names the finance, operations and data reviewers; technical completion alone does not close the pack.

Run the first rehearsal to expose and classify defects

Use a production-shaped copy where appropriate, with the intended modules, configuration, roles and migration tooling. Load versioned extracts in the published dependency order and execute the actual cutover runbook, including access checks and downstream smoke tests.

Record elapsed steps and waiting points for planning without turning one observed run into a fixed commitment for every future run. Classify defects as source data, mapping, dependency, configuration, permission, performance, integration, reconciliation or acceptance issues. Assign each an owner and required retest.

The first rehearsal ends with a corrected runbook, updated mappings and a clear list of unresolved decisions. It is not presented as final acceptance merely because the last import eventually completed.

Run the second rehearsal to prove correction and repeatability

Start with fresh approved extracts and the corrected mapping and runbook. The intended operators, rather than only the original developer, execute the sequence. Compare run IDs, counts, updates, errors, reconciliation differences and required manual interventions with the first rehearsal.

Prove that corrected mappings behave as expected, external IDs prevent duplicates and previously accepted objects remain correct. Review any new difference introduced by the correction. Where a production-shaped copy is not appropriate, document the alternative environment, its limitations and the compensating evidence.

Two rehearsals are planned where appropriate; they are not a ritual that replaces judgement. Material scope or source changes can require another targeted run. Final approval depends on the agreed evidence and open-risk decision rather than the number of rehearsals alone.

Rehearse transition, fallback and first-production scenarios

The cutover plan covers source freeze or change control, final extract timing, last reconciled balances, user access, journal onboarding, provider readiness, final imports, reconciliation and operational smoke tests. It names who declares each gate complete and who has authority to stop the release.

Transition scenarios include a late source change, rejected import, unresolved balance, unavailable bank or payment provider, failed ZATCA test, missing credential owner and delayed user acceptance. For each, the team agrees whether to correct and continue, isolate an object, use a documented fallback or stop.

The first production scenarios use the same reconciliation and invoice-acceptance structure as the rehearsals. New standard and simplified invoices and adjustments are monitored separately from migrated history, with final status and Arabic output checked by responsible reviewers.

Connect migration acceptance to training and hypercare

Role-based training uses the migrated records that users will actually see. Finance reviews balances and adjustments, operations process open work and stock, and administrators learn external-ID, import, credential and support boundaries. Arabic and English SOPs describe the same owners and controls.

Hypercare tracks unresolved migration differences, duplicate suspects, source-to-target questions, integration health and repeated manual work. Issues link back to object and run IDs so that a recurring problem can be traced to its mapping or source decision.

Exit requires agreed reconciliation, no unowned critical migration exception, stable support ownership and an accepted handover. The handover contains source and mapping versions, external-ID rules, import and reconciliation logs, archive access, known limitations and residual actions with owners.

Use official product references and educational delivery sessions

Use the Odoo 19 Saudi fiscal localisation for current product setup and ZATCA's specification hub for technical requirements. Use Odoo 19 bank synchronisation documentation to frame account-specific feed tests rather than assuming coverage.

Public OXP2026 sessions on rehearsals, enablement and adoption, dependency ordering, external IDs and import review and discovery and responsibilities are educational delivery material only. They are not Saudi regulatory guidance, Oakland references, customer stories or endorsements.

Odoo 20 demonstrations are separate educational context and do not establish Odoo 19 migration or reporting capability. The organisation's approved mappings, repeatable runs, reconciliation and business sign-off remain the decisive migration evidence.