Migration Checklist: Moving to Dolibarr

Phase 0

Decide & Plan

Lock the decisions before any byte moves.

• List every object in scope by Dolibarr module. Map source objects to Dolibarr modules you intend to enable: Third Parties, Products/Services, Stocks, Customer Invoices (Facture), Supplier Invoices (FactureFournisseur), Proposals (Propal), Orders, Projects, Accounting, Users, Bank, ECM. Mark each as in-scope or out-of-scope.

  Risk if skipped: Undocumented scope produces mid-cutover surprises when a source object has no enabled destination module to receive it.

• Decide the Dolibarr deployment model. Pick one: self-hosted on your own LAMP/LEMP stack (DoliWamp, DoliDeb, DoliRpm, Docker image, or zip), shared web hosting, or DoliCloud. The choice fixes PHP version, MySQL/MariaDB or PostgreSQL backend, and what php.ini limits you can change.

  Risk if skipped: Shared hosting with locked php.ini caps your upload_max_filesize and memory_limit and silently blocks large CSV imports later.

• Decide whether to run a single-entity or multi-entity install. Enable the Multi-company module only if you must isolate legal entities in one install. Multi-entity changes table behavior and the upgrade path.

  Risk if skipped: Switching from single to multi-entity after data is loaded requires manual re-keying of entity columns across llx_ tables.

• Define the historical-data scope. Decide how many fiscal years of invoices, supplier invoices, payments, stock movements, and journal entries are in scope. Decide whether closed periods come over as posted documents, as opening balances only, or as an external archive.

  Risk if skipped: Importing 7+ years of closed-period invoices into a fresh install bloats llx_facture and the bound journal, slowing month-end forever after.

• Identify GDPR and accounting-retention obligations. Document EU GDPR data-subject rights (access, rectification, erasure, portability) and the legal retention window for invoices and accounting records in each operating country. Confirm where the Dolibarr database and document storage will physically sit.

  Risk if skipped: Hosting a self-hosted instance outside the EU without documented safeguards triggers GDPR cross-border transfer obligations after go-live.

• Name a single accountable migration owner and a finance approver. The owner runs the punch list. The finance approver signs the opening trial balance and the post-load reconciliation in writing.
• Write the success criteria. Define what must be true to declare the migration complete: e.g. opening trial balance ties to source by zero, every open AR/AP invoice exists in Dolibarr with matching balance, stock-on-hand per warehouse matches source.

  Risk if skipped: Without written success criteria, the migration drifts into a multi-month tail of one-off fixes.

• Set the cutover window and the source-system freeze. Pick a date that aligns with a fiscal period boundary. Communicate the freeze to all source-system users at least two weeks ahead.

  Risk if skipped: Cutting over mid-period forces a manual delta reconciliation of partial-month transactions.

• List out-of-scope items explicitly. Examples: legacy custom reports, paper-only attachments, archived users with no future role, departments closing within the year. Publish the list so it cannot be re-litigated later.

Phase 1

Pre-Migration Prep

Make the destination ready and the source clean.

Phase 2

Source Export

Pull everything you might need in a form you can transform.

• Export third parties (customers, suppliers, prospects) to CSV. Include name, supplement name, address lines, ZIP, city, country code, phone, fax, email, VAT number, customer/prospect/supplier flag, legal form code, payment terms, and every custom field. UTF-8 encoding.

  Risk if skipped: ANSI/Windows-1252 source files corrupt non-ASCII names (é, ñ, ö) on import and require a re-export.

• Export contacts and their links to third parties. Contacts are a separate object in Dolibarr (Socpeople). Export with a foreign key column pointing back to the third-party external ID.
• Export products and services with all attributes. Ref, label, description, type (product vs. service), price, VAT rate, weight, dimensions, default warehouse, default unit of measure, supplier ref(s), accounting codes (sell, buy), barcode, and every extra field.
• Export product lots / serial numbers and their batch metadata. Lot number, product ref, manufacturing date, sell-by date, eat-by date. Skipping this loses traceability for any regulated product.

  Risk if skipped: Re-creating lots manually after invoices reference them produces orphan rows in llx_product_lot.

• Export current stock levels per product per warehouse. These become the opening stock movement transactions in Phase 5, not direct UPDATEs to llx_product_stock.

  Risk if skipped: Directly writing stock totals bypasses the movement audit trail and breaks future reorder reports.

• Export customer invoices (Facture) with all header and line fields. Invoice ref, date, due date, third-party external ID, currency, multicurrency rate, total HT, total VAT, total TTC, status, paid status. Export lines separately with FK to header ref.
• Export supplier invoices (FactureFournisseur) with header and lines. Mirror the customer-invoice export structure for AP. Include supplier ref number (their invoice number, not yours).
• Export proposals and customer orders with lines. Only if in scope. Status mapping in Phase 3 will translate source pipeline states to Dolibarr status codes.
• Export payments and bank reconciliation history. Payment date, amount, payment mode (check, transfer, card, cash), bank account, and the invoice(s) the payment is allocated against.

  Risk if skipped: Loading invoices without payments leaves every closed invoice showing 'unpaid' and breaks the AR aging.

• Export the general ledger trial balance as of the cutover date. Per-account debit and credit totals for the closing of the period before cutover. This becomes the opening-balance journal entry in Phase 3.
• Export historical journal entries if posted history is in scope. Account code, debit, credit, date, journal code, narration, third-party reference. Group rows by journal entry number.
• Export user list with roles, groups, and reporting structure. Login, email, first name, last name, group memberships, active flag. Strip passwords; Dolibarr will issue new ones at first login.
• Export agenda events, notes, and per-record comments. Dolibarr stores agenda events (llx_actioncomm) and per-object notes (note_private, note_public). Export with the parent object's external ID so they can be re-linked.

  Risk if skipped: Notes loaded without a parent FK end up as orphan rows visible only by direct SQL query.

• Export attachments and document binaries with their parent references. Pull the binary files plus a manifest CSV mapping each file to source object type + source ID. Preserve original filenames and MIME types.
• Screenshot and document source automations, reports, and dashboards. These are rebuilt manually in Dolibarr's report module and via custom triggers. Capture the specification now so Phase 7 has a target.
• Record the exact timestamp of every export. Per-file timestamp + per-object source count. The cutover delta will be measured against this.

Phase 3

Transform & Map

Reshape source exports into Dolibarr-ready files.

Phase 4

Sandbox Test Migration

Surface every problem in the sandbox.

• Load a 5% representative sample of each object into the sandbox. Use Tools → New Import for CSV/Excel uploads. Step 1 pick the predefined dataset, Step 2 upload the file, Step 3 map columns, Step 4 simulate, Step 5 run real import.
• Run the import simulator before every real load. Dolibarr's import wizard exposes a simulation step that flags row-by-row errors without writing. Treat any simulation error as a hard stop.

  Risk if skipped: Skipping the simulator means errors only surface after partial writes, leaving the table in a mixed state.

• Validate field-by-field on 5–10 random sandbox records per object. Pick records at random per object, open the card in Dolibarr, and compare every visible field plus the extra-fields tab against the source export.
• Test special-character handling on a non-ASCII third party. Verify names with é, ö, ñ, Arabic, or CJK characters survive round-trip from CSV through import to UI render.

  Risk if skipped: Encoding bugs surface as garbled names on customer-visible PDFs after go-live.

• Test long-string handling at the column-length boundary. Confirm descriptions and notes at or slightly over the destination column length truncate or reject as the mapping spreadsheet predicted.
• Test parent-child link integrity. Load a sample third party, then its contacts, then an invoice with lines. Confirm each child appears in the parent's tab in the Dolibarr UI.
• Test the opening-balance journal entry in sandbox. Post the full opening journal, then run the trial balance report. Debits and credits must equal and tie to the source trial balance to the cent.

  Risk if skipped: An out-of-balance opening journal blocks subsequent posted invoices from reconciling cleanly.

• Test stock-movement seeding against current-stock targets. Run the opening stock movements, then check the stock-by-warehouse report against the source. Confirm fractional quantities (e.g. 1.36 kg) survive the dot-decimal transform.

  Risk if skipped: Comma-decimal sneaks back in and Dolibarr stores 1 instead of 1.36, dropping inventory accuracy.

• Test the attachment binary upload path. Upload a small set of files to the documents directory under documents/<module>/<ref>/ and confirm they appear in the object's Documents tab.

  Risk if skipped: Wrong subdirectory paths leave binaries on disk but invisible in the UI.

• Run a full-volume rehearsal where the sandbox allows it. Time each load step. Extrapolate against production volume to confirm the cutover window is realistic and the PHP memory_limit is sized correctly.

  Risk if skipped: An untimed cutover is a guess; a 90-minute estimated load that runs 6 hours blows the freeze window.

• Hand the sandbox to a finance user for spot-checks. Have them open ten random invoices, run a small AR aging, and pull one customer's full transaction history. Their gut says more than the row counts.
• Take a second filesystem + DB backup of the sandbox after a clean test load. Keep this as the gold reference for diffing against production after Phase 5.
• Get written sign-off from the migration owner and finance approver before proceeding. No production cutover starts without both signatures.

  Risk if skipped: Skipping sign-off lets unresolved sandbox issues recur in production where they cost more to fix.

Phase 5

Production Cutover

Execute the load in a tightly sequenced window.

• Confirm the source system is in read-only or fully frozen state. Verify no writes have happened in the last hour. Take a screenshot of the freeze banner shown to source users.

  Risk if skipped: A late source write creates an invoice that exists in the source but not in the destination after cutover.

• Take the final source export — the delta from the Phase 2 baseline. Re-export every object using the same scripts as Phase 2 to capture changes between baseline and freeze.
• Take a fresh mysqldump (or pg_dump) of the empty production Dolibarr. This is the absolute rollback point if the cutover has to abort.
• Confirm scheduled jobs and integrations remain paused. Re-check after the dump. Background jobs firing during import cause cascading side-effects.

  Risk if skipped: An active job that triggers on invoice creation fires on every imported row and sends thousands of emails.

• Load in dependency order — users first. Users, then dictionaries (any custom rows), then warehouses, then third parties, then contacts, then products, then product lots, then opening stock movements.

  Risk if skipped: Loading invoices before third parties produces orphan invoices that cannot be edited until the third party arrives.

• Post the opening-balance journal entry, then load posted prior-year journals if in scope. Verify the post-journal trial balance equals the source trial balance to the cent before any documents are loaded.
• Load open AR invoices and AP invoices. Use the Import tool's update-if-exists mode keyed on ref/ref_ext so a re-run does not duplicate.

  Risk if skipped: Insert-only mode on a re-run creates duplicate invoices that double the AR balance.

• Load customer payments and their allocations against invoices. Payments first into llx_paiement, then the allocation rows. Confirm each invoice's remaining-amount updates as expected.
• Load proposals, customer orders, and supplier orders if in scope. Status codes per the dictionary mapping from Phase 3.
• Upload attachment binaries into documents/<module>/<ref>/ paths. Script the binary copy. The Dolibarr ECM module will index them and they will appear in each object's Documents tab.
• Load agenda events, notes, and per-object comments last. These reference every other object and must come after their parents exist.
• Capture row counts and import job IDs at every step. Diff against the source delta counts immediately. If a step shows a count mismatch, stop and diagnose before loading the next dependency level.

  Risk if skipped: Pushing through a count mismatch buries the bug under three more loads.

• Re-enable integrations and scheduled jobs only after all loads complete. Re-enable in the reverse order of disabling. Smoke-test each as it comes back on.

Phase 6

Validate

Prove the migration before users get in.

• Compare per-object row counts: source delta vs. Dolibarr llx_ tables. Run SQL counts directly on llx_societe, llx_socpeople, llx_product, llx_facture, llx_facturedet, llx_facture_fourn, llx_paiement, llx_stock_mouvement, llx_bookkeeping. Investigate any non-zero delta.

  Risk if skipped: A silent five-row drop in invoice lines distorts revenue for the period until someone notices in the close.

• Run the Dolibarr trial balance report and tie to source. Accounting → Reports → Trial balance, dated as of the cutover day. The delta against the source's closing trial balance should be zero.

  Risk if skipped: A non-zero delta in the trial balance is a hard blocker for the first close on Dolibarr.

• Reconcile open AR total against source. Customer → Invoices → list filtered to unpaid. Sum total remaining-amount and compare to the source AR aging total.
• Reconcile open AP total against source. Same exercise for FactureFournisseur — unpaid filter, sum, compare.
• Reconcile stock-on-hand per product per warehouse. Stock → Reports → Stock per warehouse. Compare against the source stock report. Any product with a delta gets a stock-correction movement, not a direct UPDATE.

  Risk if skipped: Direct UPDATE to llx_product_stock to mask a delta hides the underlying transform bug and corrupts the audit trail.

• Spot-check 25–50 random records across customers, invoices, products, payments. Compare every visible field on the Dolibarr card against the source export. Document each pass/fail.
• Verify multicurrency invoices show the historical FX rate, not today's. Open three foreign-currency invoices from different prior periods and confirm multicurrency_rate and multicurrency_total_ttc match the source.
• Verify product lots are linked to the right products. Open a lot, check it shows under its parent product's Lots tab. Repeat for a sample of ten.
• Verify a sample of attachments opens correctly from the Documents tab. Click through to download. Confirm the binary is intact and the filename is preserved.
• Verify the audit-trail strategy from Phase 3 actually held. If you used the source_created_at extra field, confirm it is populated on a sample. If you used best-match owner, confirm fk_user_author matches the expected user.
• Run a GDPR export on a single contact to confirm portability still works. Pull a contact's complete record from the database. Confirm all linked data (orders, invoices, comments) is reachable.
• Confirm document storage location matches the data-residency commitment. Verify the documents directory lives on the storage volume in the region required by the Phase 0 compliance decision.
• Have 3–5 power users validate their core workflows end-to-end. Sales: create a proposal from a migrated customer. Accounting: receive a payment against a migrated invoice. Warehouse: log a stock movement on a migrated product.

  Risk if skipped: Workflow-level bugs only surface during real use; finding them after go-live is 10x more expensive.

• Document every UAT-surfaced data issue and assign an owner. Anything material gets fixed before users come in; anything cosmetic goes to a Phase 7 follow-up list.
• Get written sign-off from the migration sponsor before opening to users. No general access until the sponsor approves in writing.

Phase 7

Post-Migration Cleanup

Close out cleanly so the team can move on.

• Send the go-live announcement with login URL and support contact. Include first-login password-reset instructions and where to report data issues. Tag the first-responder rotation.
• Run role-segmented training sessions in the first week. Sales, accounting, warehouse, admin. Record and post the sessions to the internal knowledge base.
• Set the source system to read-only and announce the read-only date. Read-only first, not immediate decommission. Users need a reference window for the first close on Dolibarr.

  Risk if skipped: Decommissioning the source the same day as cutover removes the ability to diff against it when a reconciliation question arises.

• Rebuild reports and dashboards inside Dolibarr. Standard reports live under each module's Reports menu. Custom needs go through the Export module or custom SQL through a reporting layer.
• Rebuild automations using Dolibarr triggers and scheduled jobs. Triggers under Home → Setup → Modules trigger configurations. Scheduled jobs under Home → Admin tools → Scheduled jobs. These do not migrate from the source.
• Schedule daily database + documents backups. Use the Backup module under Home → System tools → Backup, plus filesystem-level snapshots of the documents directory and conf.php. Test a restore once.

  Risk if skipped: An untested backup is a hope, not a backup; the first restore attempt always finds the missing file.

• Configure data-retention purge jobs to honor the Phase 0 retention policy. Use scheduled jobs or the Purge module to delete or anonymize records past the retention window.
• Reassign ownership from the data-migration user to real users. If you used a single placeholder owner in Phase 3, bulk-update fk_user_author / fk_user_resp to the real owners now.
• Schedule the 30-day retrospective. Capture what went well, what didn't, and what the next major upgrade should do differently.
• Decide and document the source-system decommission date. Typically 90 days after cutover. Confirm the source retention obligation is independently satisfied by the archived exports.
• Archive the full set of source exports, mapping spreadsheets, and transform scripts. Long-term cold storage. Label by cutover date. These are the forensic record if a discrepancy surfaces months later.

  Risk if skipped: Without archived exports, a year-end audit question about a migrated transaction has no source of truth to reference.

• Close out the migration project formally with a final status report. Final task counts, residual issues with owners, lessons learned, and the link to the 30-day retrospective.