Technical migration guide
C/AL to AL Customisation Conversion Checklist
Use this C/AL to AL conversion checklist to inventory NAV modifications, refactor extensions, preserve data, test business logic, and prepare for Business Central.
What to take from this guide
- Txt2Al output is a conversion starting point, not a production-ready extension.
- Decide retain, replace, redesign, or retire before spending effort translating legacy code.
- Treat code, schema, custom data, integrations, permissions, tests, and operations as one controlled product change.
- Acceptance requires repeatable builds, representative data upgrades, business reconciliation, and an ownership handover.
Define done
Conversion is more than producing AL files
Microsoft's Txt2Al tooling can create AL source files from suitable C/AL text exports, but generated source is a starting point. A migration-ready extension must represent approved business outcomes, compile against the exact target, preserve required data, follow extension boundaries, pass analysis and tests, and remain operable through future updates.
Mechanical conversion
Transforms eligible C/AL source into initial AL syntax. It helps expose work but does not decide whether the customisation is still needed or whether its design is suitable for Business Central online.
Functional redesign
Reframes modifications as standard configuration, supported apps, extension objects, event subscribers, APIs, or other maintainable patterns while preserving approved controls and outcomes.
Data continuity
Maintains required custom fields and tables through compatible schema changes, table ownership, upgrade code, transformation, validation, and reconciliation.
Production readiness
Adds permissions, tests, telemetry, documentation, packaging, deployment, upgrade, support, and rollback evidence for the selected online or on-premises target.
Checklist 1
Build an evidence-based customisation inventory
Exporting every modified object without context produces a conversion backlog, not a plan. Compare the application with the correct standard baseline and attach business, data, integration, and ownership evidence to each difference.
| Inventory area | Capture | Why it changes the conversion |
|---|---|---|
| Application baseline | NAV version, build, cumulative update, localisation, standard comparison source, object ranges, and licence or source access. | Wrong baselines create false deltas and can lead to an unsupported intermediate or target combination. |
| Modified objects | Tables, pages, reports, codeunits, XMLports, queries, menusuites, forms or dataports in older releases, and object relationships. | Object types convert differently; some legacy concepts require replacement rather than direct translation. |
| Business purpose | Named owner, current use, process step, control, frequency, users, pain points, and acceptance criteria. | This is the evidence for retaining, replacing, redesigning, or retiring the modification. |
| Custom data | Fields, tables, keys, relations, option values, dimensions, record counts, retention, sensitivity, and reconciliation totals. | Schema identity and ownership decisions determine whether data can be synchronised and upgraded safely. |
| External dependencies | .NET interoperability, Automation or COM, control add-ins, file paths, printers, devices, DLLs, services, and credentials. | Platform-bound dependencies can require redesign for newer runtimes or Business Central online. |
| Integrations | SOAP or OData services, APIs, files, EDI, ecommerce, banking, warehouse devices, schedulers, queues, and error handling. | Contracts, authentication, timing, retry, monitoring, and ownership often matter more than the translated calling code. |
| Outputs and local needs | Reports, Word or RDLC layouts, labels, documents, GST-sensitive behaviour, payment outputs, translations, and Australian add-ons. | A clean compile does not prove local finance, document, or operational outcomes remain correct. |
| Quality evidence | Existing test codeunits, manual scripts, known defects, performance baselines, support history, and production telemetry where available. | The current behaviour must be observable before equivalent or intentionally changed behaviour can be accepted. |
Checklist 2
Make a decision for every modification
Conversion scope should be driven by current business need. Record the decision, owner, target design, data treatment, test evidence, and acceptance criteria for each custom outcome.
Retain
Keep the outcome because it remains necessary and no suitable standard capability or supported app meets the requirement. Rebuild it as an appropriately bounded AL extension.
- Document why the outcome is essential.
- Choose extension objects and events before coding.
- Define ownership, tests, telemetry, and update policy.
Replace
Use standard Business Central or a supported third-party app when it satisfies the approved outcome and commercial, data, security, and support requirements.
- Prove fit with representative scenarios.
- Map data and integration consequences.
- Confirm app licensing, dependencies, and vendor lifecycle.
Redesign
Preserve the outcome but change the implementation—for example, move base-code modifications to event subscribers, replace a local file dependency, or expose a supported API.
- Separate the requirement from the legacy technique.
- Document transaction, error, and security behaviour.
- Test equivalence and intentional differences.
Retire
Remove unused, duplicated, workaround, or obsolete logic. Decide what happens to its data, reports, permissions, scheduled tasks, integrations, documentation, and support procedures.
- Use evidence rather than assumption about usage.
- Obtain business and data-owner approval.
- Retain any required historical access or audit trail.
Checklist 3
Run the conversion as a controlled engineering workflow
The exact commands and intermediate releases depend on the source and target. These gates keep the work traceable and prevent a generated codebase from being mistaken for a completed extension.
| Gate | Required work | Evidence of completion |
|---|---|---|
| 1. Freeze and reproduce | Create verified backups and exports, record versions and tools, retain the standard comparison baseline, and prove the source environment can be restored. | Versioned source artefacts, checksums or release tags, backup-restore evidence, and a repeatable environment record. |
| 2. Prepare version 14 source | Follow Microsoft's application upgrade and conversion prerequisites, resolve unsupported source constructs, and export objects in the required new text format. | Clean, repeatable exports and a documented exception list tied to source objects. |
| 3. Convert with Txt2Al | Use the version 14 tool and appropriate parameters for the source, including required .NET declaration or legacy translation handling where applicable. | Generated AL, conversion logs, warnings, tool version, command record, and traceability back to source objects. |
| 4. Establish app structure | Define app identity, target platform and application versions, object identifiers, dependencies, namespaces or affixes where applicable, and extension boundaries. | Approved app manifests and dependency map that compile against symbols from the exact target. |
| 5. Refactor the design | Replace base modifications with extension objects, events, interfaces, APIs, supported apps, or standard configuration; remove obsolete and duplicate code. | Design mapping from every retained business outcome to maintainable AL objects and dependencies. |
| 6. Protect data | Plan table and field ownership, compatible schema synchronisation, option or enum mapping, upgrade code, transformations, defaults, and rollback. | Successful upgrade of representative data with reconciled counts, values, balances, and custom records. |
| 7. Replace platform dependencies | Redesign incompatible .NET, Automation, file-system, client, device, authentication, or integration dependencies for the chosen deployment target. | End-to-end tests in a target-like environment, including failure, retry, security, and monitoring behaviour. |
| 8. Complete the product | Add permission sets, translations, report layouts, installation and upgrade code, telemetry, configuration, support diagnostics, and documentation. | A deployable package with controlled configuration, least-privilege access, operations guidance, and release notes. |
| 9. Analyse, test, and package | Compile cleanly, run the relevant Microsoft analyzers, execute automated and manual tests, review warnings, and create a repeatable build artefact. | Recorded analyzer policy, test results, approved exceptions, signed acceptance evidence, and reproducible package output. |
| 10. Rehearse upgrade and cutover | Install and upgrade in sequence with representative data and apps, measure timings, test rollback and uninstallation assumptions, and rehearse support handover. | A passed rehearsal against cutover, reconciliation, performance, recovery, and operational-readiness criteria. |
Checklist 4
Review the hotspots that compilation does not settle
Compiler errors are visible; behavioural and data errors are often harder to detect. Give these areas explicit design and test ownership.
Posting and transaction boundaries
Check event placement, commit behaviour, locking, number series, dimensions, rounding, approvals, and errors in finance, inventory, warehouse, sales, purchasing, manufacturing, and service flows used by the business.
Tables, fields, and upgrade code
Avoid unplanned breaking schema changes. Confirm field identity, keys, option-to-enum mappings, data classification, table relations, defaults, ownership transfer, and upgrade sequencing with real data volumes.
Events and extension boundaries
Choose published events that align with the intended transaction and use the Event Recorder where helpful. Do not reproduce base-code modifications through brittle event chains without clear contracts and tests.
Reports, documents, and printers
Validate datasets, layouts, barcodes, labels, email delivery, archives, local printers, document numbering, GST presentation, and the exact devices and services used in operations.
External integrations
Reconfirm endpoints, API versions, authentication, secrets, certificates, throttling, idempotency, retries, sequencing, monitoring, privacy, and recovery—not only payload field mappings.
Permissions and scheduled work
Map legacy roles to least-privilege permission sets and test job queues, background sessions, approvals, service accounts, company access, and failure alerts in the target environment.
Checklist 5
Use layered tests and business reconciliation
Microsoft supports AL test codeunits and sandbox testing. Combine automated checks with representative end-to-end business scenarios and reconciliation; do not run a large conversion project by relying on ad hoc user testing at the end.
| Test layer | What it should prove | Typical evidence |
|---|---|---|
| Build and static analysis | The extension compiles for the exact target and meets the agreed CodeCop, PerTenantExtensionCop, AppSourceCop, or UICop policy as applicable. | Repeatable build logs, analyzer results, and reviewed suppressions or ruleset exceptions. |
| Automated business logic | Core calculations, posting rules, validation, error paths, upgrade code, permissions, and regressions behave as designed. | AL test codeunit results tied to requirements and defects. |
| Integration and contract | Realistic endpoints, authentication, payloads, volume, timing, retry, idempotency, and monitoring work across system boundaries. | Contract results, trace identifiers, failure simulations, reconciliation, and operational alerts. |
| Migration and schema | Apps install and upgrade in the intended sequence and all required legacy data remains accurate and usable. | Record counts, control totals, field samples, subledger-to-ledger reconciliation, and upgrade telemetry. |
| User acceptance | Named users can complete approved end-to-end processes, controls, documents, reports, and exception handling. | Executed scripts, evidence, defect outcomes, and authorised sign-off against acceptance criteria. |
| Performance and operations | Critical workloads, scheduled processing, support diagnostics, deployment, rollback, update, and recovery are acceptable. | Target-like measurements, runbooks, alerts, recovery tests, and ownership confirmation. |
Checklist 6
Do not accept the extension without an upgrade and support handover
The converted code becomes a maintained product. Acceptance should establish who can build, deploy, troubleshoot, update, and transfer it after the migration team leaves.
- Source repository, complete history, release tags, branching policy, and access are transferred
- Build dependencies, target symbols, compiler and analyzer versions, rulesets, and pipeline are documented
- App identities, object ranges, namespaces or affixes, dependencies, secrets, certificates, and environments have owners
- Installation, upgrade, uninstallation, backup, rollback, and data-recovery constraints are explicit
- Permission sets, setup, feature flags, job queues, integration endpoints, and monitoring are documented
- Automated test code, UAT scripts, test data assumptions, results, and known limitations are retained
- Telemetry, support diagnostics, alert routes, service levels, and escalation contacts are operational
- Third-party licences, app versions, vendor commitments, and renewal responsibilities are recorded
- Known defects, technical debt, accepted risks, deprecations, and target-release follow-up have owners and dates
- Customer administrator access, source rights, documentation rights, and transition assistance match the signed agreement
Practical answers
Frequently asked questions
Does Txt2Al fully convert a C/AL solution?
No. Microsoft's tooling converts eligible C/AL text into initial AL files. The output still needs app structure, dependency resolution, refactoring, schema and data-upgrade design, permissions, analysis, testing, packaging, and validation against the target Business Central release.
Which Txt2Al version should be used?
Microsoft documents Txt2Al as part of Business Central version 14, the last release with C/AL. Follow the current Microsoft conversion and upgrade instructions for the exact source and target rather than using an arbitrary tool version or command copied from another project.
Should every C/AL modification become an AL extension?
Not automatically. Compare each modification with standard Business Central and supported apps, verify present business use, and decide to retain, replace, redesign, or retire it. Required custom outcomes should be implemented through maintainable extension-based patterns.
Can custom NAV data be lost during conversion?
Yes, if custom fields or tables, schema identity, table ownership, option values, dependencies, or upgrade code are mishandled. Profile and back up the source, design data upgrades, rehearse with representative copies, and reconcile every required data category before cutover.
What should an Australian C/AL conversion test?
In addition to global application behaviour, test the organisation's actual GST-sensitive transactions, finance controls, payment and banking processes, document layouts, reporting, local apps, warehouse or distribution workflows, integrations, and audit or retention requirements. Qualified finance and tax advisers should approve relevant outcomes.
Primary references
Official Microsoft guidance
Microsoft changes product pricing, licensing, tooling, and supported upgrade routes over time. Use these source pages to validate the current position for your target release.
Plan from evidence
Qualify the customisation footprint before estimating conversion
LeXurey's readiness check captures the first non-sensitive details about the NAV environment and migration priorities. A C/AL conversion estimate still requires source and object access, technical comparison, data profiling, and an agreed Statement of Work.