Legacy integration guide
How do you connect a custom application to a legacy system?
Define one useful business slice, keep the legacy system authoritative where appropriate, and place a controlled translation boundary between its interfaces and the new application's data, workflow and customer experience.
The direct approach
Map what the new application must read and write, which system owns each record and how fresh the information must be. Create an adapter that translates application-oriented operations into the legacy system's supported API, service, file or database interface. Add timeouts, idempotency, reconciliation and observable failure states at that boundary.
Deliver one end-to-end workflow while old and new components coexist. Avoid exposing the legacy interface directly to browsers, customers or every new service.
01
Define one complete integration slice
Start with a workflow such as retrieving order history, submitting a service request or checking account status. Record:
- the user and measurable outcome;
- source records, identifiers and rules;
- required reads, writes and approvals;
- freshness and response expectations;
- expected volume and peak behaviour;
- failure, correction and support ownership; and
- the evidence needed before expanding scope.
02
Protect the new application with a translation boundary
Microsoft describes an anti-corruption layer as a facade or adapter between subsystems with different semantics. It lets the new application use its own model while translation stays in one maintainable place.
Contract
Business language
Expose actions such as retrieve account or submit request, not vendor table operations.
Translation
Map meaning
Convert identifiers, statuses, dates, units, codes and errors deliberately.
Policy
Keep rules owned
Do not move source business rules into the adapter without explicit ownership.
Operations
Trace the journey
Use correlation identifiers and structured outcomes across every component.
03
Choose the narrowest supportable legacy interface
| Interface | Use when | Main constraint |
|---|---|---|
| Supported API or service | Required operations exist and vendor support is clear | Limits, latency, versioning and availability |
| Event or queue | Changes or accepted work can move asynchronously | Duplicates, ordering, replay and monitoring |
| Controlled file exchange | Batch import or export is the stable interface | Freshness, validation and partial failure |
| Read-only database access | Ownership permits it and no safer read path exists | Schema coupling and reporting load |
| Vendor extension | The platform offers a supported customisation boundary | Upgrade and platform dependency |
| Browser automation | No interface exists and the workflow justifies a managed last resort | Fragility, security and manual recovery |
04
Keep data and workflow ownership explicit
- Name the source of truth for every entity and status.
- Map legacy identifiers to stable application identifiers.
- Copy only data needed for a clear read, search or resilience benefit.
- Define refresh, correction, retention and deletion for every copy.
- Send writes through supported business operations.
- Separate delivery acknowledgement from business completion.
- Reconcile the final legacy state before declaring success.
Read the guide to modernising a business system without replacing it for the wider coexistence decision.
05
Assume the dependency will be slow, unavailable or inconsistent
| Failure | Required response |
|---|---|
| Timeout | Stop waiting within a defined budget and show an honest state |
| Duplicate request | Recognise the business request and avoid repeating the outcome |
| Rejected write | Preserve reason and route the exception to an owner |
| Schema change | Detect through contract tests before customer impact |
| Partial batch | Record accepted and rejected items and reconcile totals |
| Extended outage | Protect accepted work, communicate status and control replay |
06
Keep application and integration trust separate
- authenticate customers to the new application, not the legacy database;
- authorise every record and action before calling the adapter;
- use least-privilege integration identities and protected secrets;
- validate input and return only approved fields;
- separate customer, support and integration permissions;
- audit sensitive actions and privileged access; and
- test altered identifiers across caches, exports and background work.
07
Roll out with evidence and a fallback path
- Baseline the current workflow and support burden.
- Prototype the riskiest read, write and identity mapping.
- Build adapter tests with representative source behaviour.
- Pilot one user group while the old process remains recoverable.
- Monitor completion, errors, reconciliation and support effort.
- Document ownership and operating procedures.
- Expand only after the integration behaves under real failure.
Sources
Primary references
Questions
Frequently asked questions
Can a custom application connect to a legacy system?
Yes, when the legacy system has a supportable way to read data or submit work. Put its API, file, database or automation interface behind an adapter so the new application does not depend directly on legacy semantics.
What if the legacy system has no API?
Assess supported file exchange, read-only database access, vendor extensions, scheduled exports or carefully governed automation. Choose the narrowest interface that meets the business need and can be monitored and supported.
Should the custom application write to the legacy database?
Avoid direct writes unless the system owner explicitly supports them. They can bypass validation and business rules. Prefer a supported operation, integration service, command queue or controlled import process.
What is an anti-corruption layer?
It is an adapter or facade that translates between the new application's business model and the legacy system's data model, protocol and error behaviour. It contains legacy-specific details instead of spreading them through the new codebase.
How do you test a legacy integration?
Use representative records, roles, volumes and failures. Test duplicates, timeouts, partial batches, changed schemas, missing mappings, rejected writes and reconciliation against the source of record.
Plan the legacy connection
Bring the workflow, source interfaces and operational constraints.
LCR can help identify the safest connection, prototype the highest-risk assumption and plan a measurable first release.