How to use this core banking data migration checklist
This checklist is for a bank or lender that has chosen, or is evaluating, *Apache Fineract* and must load live client, loan and savings data without losing a single balance. The short answer is that a safe data migration into Fineract is planned as a sequence of gates: scope and source data first, then product mapping, trial loads, reconciliation, cutover and a tested rollback. Each gate produces evidence that the next one depends on, so no step should start until the one before it has a signed-off result. The sections that follow take the reader through those gates in order, from the questions to answer about the legacy core to the reports that prove the new books match the old ones.
Fineract is a headless application. It exposes REST APIs and does not ship its own user interface, so the migration will touch the API layer, the batch and read instance setup and whatever front end or integration the institution adds. It is also multi-tenant: requests carry a Fineract-Platform-TenantId header and tenant connections come from a tenants database, so the tenant structure must be decided before any data is loaded, because it is expensive to change afterward. The project's README warns that production deployment can be complex, costly and time-consuming, and that it does not provide a comprehensive production deployment guide. That means the migration plan has no ready-made template to inherit. The institution and its implementation partner must write the runbook, the acceptance criteria and the rollback plan themselves, and should confirm each assumption against the exact release they intend to run, Fineract documentation, rather than relying on general practice.
Functional requirements to define before loading data
This table lists the functional requirements to settle before any client, loan or savings record enters Fineract, with the reason each one matters and the artifact that proves it is done. Read each row as a gate: the migration team should not start full loads until the named artifact exists and has been reviewed by finance and operations owners. The main takeaway is that most migration failures trace back to unagreed mappings and balances, not to the loading tool itself.
| Requirement | Why it matters | How to verify |
|---|---|---|
| Client and KYC record scope | Decides which legacy customer, group and identity fields must map to Fineract client records and which are archived elsewhere. | Signed field-level scope sheet listing each legacy field, its target Fineract field or archive location, and the owner who approved it. |
| Loan and savings product mapping | Each legacy product must map to a Fineract product with matching rules, or balances will be reinterpreted when loaded. | Product mapping sheet reviewed by credit and deposit product owners, with every legacy product code assigned a target or an explicit retirement decision. |
| Schedule and interest rule conversion | Repayment schedules and interest calculations must reproduce the legacy results, or customers and regulators see different amounts. | Side-by-side schedule comparison for a sample of loans across each product, showing zero unexplained differences in the trial load report. |
| Accrued and unpaid amounts | Accrued interest, fees and overdue amounts often sit outside principal and are the first items to break at cutover. | Accrued and arrears report per account reconciled to the legacy system at the agreed cut-off date, signed by the finance owner. |
| Opening balances against the general ledger | Client-level balances must tie to control accounts in the general ledger, or the books will not balance after load. | Opening balance journal and trial balance comparison to the legacy ledger, with a signed balance confirmation from the controller. |
| Currency and rounding | Currency codes, decimal places and rounding rules differ between cores and can shift totals by small amounts across many accounts. | Documented currency table and rounding policy, plus a trial load report showing the rounding difference per product and total. |
| Tenant assignment | Fineract is multi-tenant, and each request carries a tenant identifier, so wrong tenant mapping can expose or misplace records. | Tenant assignment matrix tied to legal entities and partners, checked in a trial environment by confirming test requests resolve to the correct tenant. |
| Document links | KYC files, contracts and collateral documents must stay linked to the right client or loan after move, and retention rules still apply. | Document index mapping legacy file references to new records, with a sample retrieval test and a retention owner named for each document class. |
How source data and product mapping differ by origin
When an institution replaces its existing core, the source is usually a system that has run for years and holds the full portfolio. The extracts are large, often produced by the vendor's reporting tools or by database queries that the original implementation team wrote. Much of the product logic lives in configuration screens, end-of-day jobs and fee rules that nobody has written down in one place, so the team has to rebuild the rules from the running system rather than from a specification.
- Extract shape: Expect client, loan and savings account tables, schedule tables, transaction histories and GL balances as separate files, often with internal codes instead of readable names.
- Undocumented rules: Interest accrual conventions, day-count methods, penalty and fee triggers, and rounding behavior are frequently set by configuration flags that no current staff member owns.
- Product inventory: Map every active and dormant product code, including those with few accounts, because retired products still carry balances that must be migrated or closed.
- Mapping before load: Agree a target Fineract product for each source product, the accounting mapping for each product to GL accounts, and the status and lifecycle mapping for loans and savings.
- Historical depth: Decide which transaction history is loaded and which is summarized into opening balances, and confirm that the source system can produce it in a reconciled form.
Before any load, confirm with the outgoing vendor and the current operations team which end-of-day behaviors are configured rather than standard, and test each against a sample of accounts.
In a merger, the acquired institution's core may be a different product, configured by a different team, with its own customer identifiers and product catalog. Extracts can arrive in a form the receiving institution has never handled, and the acquired team may have left or may hold knowledge that is not in any system document. Two sets of rules often overlap, so the mapping must decide which institution's terms, fees and accounting treatment apply to each migrated account.
- Identifier conflicts: Client and account numbers can collide across the two institutions, so a stable mapping key and cross-reference table are needed before any client record is created.
- Product overlap: Similar products may differ in rate basis, grace periods or fee schedules, and the decision on whether to keep, merge or close each product needs approval from credit and product owners.
- Contract terms: Confirm whether existing contractual terms can be carried over, and where the acquirer must issue notices or obtain consent before changing terms.
- Accounting differences: The two general ledgers may use different charts of accounts and cut-off conventions, so opening balances must be reconciled to both sets of books.
- Data quality: Duplicate clients, missing KYC documents and inconsistent addresses are common and must be resolved or flagged before load.
Confirm with legal, credit and finance leads who sign off each product mapping, and whether any account requires customer communication before the cutover.
A new product, or a pilot run from spreadsheets or a partial system, usually starts with data that was never designed as a ledger. Balances may be tracked in workbooks, repayment schedules may be calculated by formula, and client records may sit in a CRM or a document store. The main risk is that the spreadsheet looks complete while the rules behind its formulas are undocumented, so the migration must reverse-engineer the calculations before any figure is trusted.
- Formula-based schedules: Recalculate every schedule from the stated terms and compare the results with the spreadsheet, rather than copying the displayed values.
- Informal rules: Rules for grace periods, early repayment and penalties often exist only in an operator's habit, so capture them in writing with the product owner.
- Missing accounting detail: Spreadsheets rarely hold a double-entry history, so opening balances must be set against the general ledger as of a defined date.
- Client data gaps: Identity verification, consent records and beneficial ownership information may be incomplete, and these gaps must be closed before the record is loaded.
- Single-owner files: Confirm which version of each workbook is authoritative and who can attest that it is complete.
Before loading, ask the product owner to sign a mapping that states how each spreadsheet column maps to a Fineract field and which calculations the platform will perform going forward.
Security requirements for migration data
Migration extracts contain the same customer identities, loan balances and account histories as production, often copied into staging and tooling that receive less hardening. The cards below cover the controls the FTC Safeguards Rule expects for covered institutions, and they apply to any staging environment that holds migrated data.
Encrypt extracts and staging
Every client, loan and savings extract should be encrypted in transit between the legacy core, transfer hosts and the Fineract staging database, and at rest in staging, scratch volumes and backups. Under 16 CFR 314.4, covered institutions must encrypt customer information in transit over external networks and at rest. Ask who holds the keys for staging, whether extracts are deleted after each trial load, and whether encryption covers temporary files written by ETL tools.
Require MFA for migration access
Anyone who can read staging, run the loader, or change migration tooling needs multi-factor authentication, including vendor engineers and contractors. 16 CFR 314.4 requires multi-factor authentication for any individual accessing any information system, so the requirement covers the staging database, the batch host and the CI pipeline that deploys loaders. Confirm that shared accounts are not used for loads and that privileged sessions are recorded.
Control changes to migration scripts
Mapping files, transformation scripts, product configuration and load parameters should go through the same change management as production code. The rule requires covered institutions to adopt change management procedures. In practice, each trial migration should run from a tagged version, every mapping change should have a named approver, and the exact version loaded at cutover should match the version the reconciliation team signed off.
Log every load and correction
Loads, reloads, manual balance corrections and account status changes should write to an audit trail that records the user, time, source file and affected records. 16 CFR 314.4 requires covered institutions to log the activity of authorized users. Ask whether logs from the Fineract database, the batch host and the transfer tooling are kept in a location migration staff cannot edit, and how long they are retained.
Test staging like production
Staging holds real customer records during trial migrations, so it belongs in the testing scope. The Safeguards Rule's penetration testing and vulnerability assessment provision, at 16 CFR 314.4(d)(2), applies to information systems in general, so staging environments should be covered unless the institution runs effective continuous monitoring. Ask the implementation partner to include staging in the test plan and to confirm how findings are tracked before cutover.
Remove data after trials
Trial migration copies should not outlive their purpose. Define where each extract lives, who may copy it, how long it is kept after each run, and how it is destroyed, including backups and snapshots of the staging database. Put the retention and destruction steps in the cutover plan so that the data set used for the final load is the only copy left once production is live.
How trial migrations build confidence before cutover
The sequence moves from a narrow, product-by-product proof to full trial loads and a rehearsed cutover, so each pass removes one class of defect before the next one starts. Sign-off is tied to evidence at every stage, not to the date on a plan.
Freeze the migration scope and mapping baseline
The client product owner, the finance controller and the migration lead agree which products, account types and balance categories move into Fineract, and record the product mapping as a versioned document. Any later change goes through a written change request. The step is done when the scope and mapping baseline is signed by the product owner and the finance controller, and every source field is either mapped, transformed or excluded with a reason.
Load a subset of products first
The migration team loads one or two representative products into a non-production tenant, typically a simple savings product and a single loan product with a standard repayment schedule. The goal is to surface structural errors in client records, account identifiers and schedule generation before volume hides them. The step closes when the subset loads without rejected records and the team can explain every warning in the load log.
Run full trial loads into a non-production tenant
The team runs a complete extract, transform and load against a separate non-production tenant that mirrors the production configuration, including products, accounting rules and opening-balance journals. Each run is logged with its input extract, row counts and rejects. The pass proves that the full data set loads within the window the team has planned for and that the tenant configuration matches the signed mapping baseline.
Compare balances and schedules against the source
Reconciliation analysts compare client counts, account balances, outstanding principal, accrued interest, fees and repayment schedules in Fineract against the source system and the general ledger opening balances. Differences are classified as mapping defects, rounding differences, source data quality issues or accepted exceptions. The step is done when every difference has a recorded owner and classification, and the finance controller signs the balance comparison.
Fix mapping defects and retest affected records
Developers correct the transformation logic or product configuration that caused each defect, and the team reruns only the affected subset before a full run. Every fix is recorded against the mapping baseline, with the reviewer who approved the change. The check that closes the step is a targeted rerun showing the defect is gone and no previously clean records have changed.
Repeat trial loads until results are stable
The full trial load repeats until two consecutive runs produce the same counts, balances and exception list, with only accepted exceptions remaining. Stability matters more than a single clean run, because it shows the migration does not depend on a manual step or on one-off data corrections. The sign-off comes from the migration lead, the finance controller and the operations owner, based on the run log and the reconciliation report.
Rehearse the cutover window and rollback
The team runs the full cutover runbook end to end on a production-like environment, including freezing source transactions, running the final extract, loading, executing reconciliation, opening the tenant to users and reversing the process. The rehearsal records the actual elapsed time of each step, which the client should check against the agreed cutover window. The step is complete when the rollback path has been exercised, the operations owner accepts the runbook, and the go or no-go decision criteria are written down.
Operational requirements and how to verify them
This table compares the operational items a Fineract migration depends on, what each one should look like before cutover, and the evidence a reviewer should ask to see. Read each row as a question to answer with a document or test result, not a statement to accept on trust. The main takeaway is that a migration is only as safe as the rehearsal, restore and rollback evidence behind it.
| Requirement | What to set up | How to verify |
|---|---|---|
| Environment parity between trial and production | Trial environments use the same Fineract version, database engine, tenant layout, product configuration and batch schedule as production | Compare configuration exports and version details from both environments, and confirm any difference is documented and accepted in writing |
| Instance layout | One write instance, one batch instance and read instances on database read replicas, set through environment variables for each instance type | Review deployment configuration for each instance and confirm only the write instance is set to run Liquibase migrations |
| Liquibase migration control | Schema migrations run only on write instances, or run separately using the liquibase-only Spring profile on Kubernetes | Walk through a migration log from a trial run showing which instance executed the schema changes and when |
| Database choice | PostgreSQL, the database the Fineract README recommends, with MariaDB and MySQL deprecated under FSIP-9 | Confirm the engine and version in each environment, and ask the implementation partner to explain how the team will handle any legacy database exports |
| Backup before each load | A full, tested backup of the target tenant database taken immediately before each trial and production load | Run a restore test into a separate environment and record the time taken and the row counts checked after restore |
| End-of-day batch scheduling around cutover | A batch calendar that blocks loads from overlapping end-of-day jobs, with an agreed freeze window for the cutover weekend | Review a batch timing log from trial runs and confirm the production window fits the measured duration with a documented buffer |
| Runbooks for rollback | Step-by-step rollback procedures with named owners, decision points and the exact point where the legacy system stays authoritative | Hold a runbook walkthrough with operations, the bank's finance team and the partner, and record gaps and owners for each step |
What reconciliation reports must prove at cutover
Reconciliation reports at cutover have one job: prove that Fineract holds the same customers, accounts, money and obligations as the source system, and that every gap is explained. The comparison should run at several levels. Count clients and active loan and savings accounts by product and status. Compare principal, accrued and paid interest, fees, penalties and outstanding balances per account. Compare each loan's repayment schedule, including installment dates, amounts and remaining periods, against the source. Finally, compare the opening general ledger balances that Fineract posts against the source trial balance for the same cutover date. Ask the implementation partner to show which Fineract reports or extracts produce each figure, and confirm that the source extracts are taken at the same cutoff timestamp.
Every difference, however small, needs a written disposition: corrected in the source, corrected in the migration mapping, accepted as a known rounding or product-rule variance with an approver, or deferred with a named owner and date. A report with unexplained residuals is not a sign-off. Agree the tolerance thresholds, the approvers (typically finance, operations and risk) and the sign-off sequence before the first trial migration, so that the reconciliation pack for each trial shows whether the gaps are shrinking. Ask who signs the final opening balance confirmation and whether the auditor will want to see the reconciliation pack as evidence.
Retention is the other half of the output. Keep the source extracts, the reconciliation workbooks, the disposition log and the migration scripts or configuration used for each run, together with the source system's final state, for as long as the institution's own policy and applicable rules require. Where a broker-dealer is involved, SEC Rule 17a-4(b) requires preservation of certain records, including bills receivable or payable and bank statements, for not less than three years, the first two in an easily accessible place. Not every institution is subject to that rule, so confirm with counsel or your compliance function which record types and retention periods apply to your entity, and make sure the decommissioning plan for the legacy core does not delete the only copy of data you must keep.
What buyers ask before hiring migration help
How much effort does a Fineract data migration take?
The effort depends mostly on how many loan and savings products the institution runs, how clean its source data is, how many systems the data comes from, and how deep the reconciliation must go. No public effort figure applies to every institution, so ask for an estimate built from your own inventory. Start by counting products, active accounts, source systems and the number of balance types that must tie back to the general ledger. Each of these adds mapping, transformation and checking work. Data quality is often the largest variable: missing KYC fields, duplicate clients, inconsistent currencies or unrecorded schedule changes all add cleanup cycles before any load can succeed. Ask the partner to show how it sized each of these drivers in the written scope.
Can our internal team run a Fineract migration alone?
A capable internal engineering team can build the loaders, but the migration also depends on banking judgment that engineers rarely hold alone. Fineract is headless and exposes REST APIs, so the technical load work is a matter of scripting against those APIs, setting up tenants and running repeatable trial loads. The harder parts are mapping legacy product rules to Fineract configuration, agreeing opening balances with finance, and proving every balance ties out. Teams without prior Fineract production experience should expect a learning curve. The Fineract README itself warns that production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. Many institutions therefore combine internal ownership with an outside implementation partner.
What do product owners, finance and data owners need to commit?
Three groups must commit time before the first trial load, and their sign-off is what makes the migration defensible.
- Product owners confirm how each legacy loan and savings product behaves, including fees, interest methods, grace periods and penalty rules, and approve the mapping to Fineract products.
- Finance approves the chart of accounts mapping and the opening balances booked against the general ledger, and signs off each reconciliation report.
- Data owners certify the source extracts, explain exceptions and decide how incomplete records are corrected or retired.
Agree named owners, decision deadlines and a sign-off record for each group in the project plan. Without these roles, trial loads tend to stall on questions no one is authorized to answer.
How long should trial loads and reconciliation be planned for?
Plan trial loads and reconciliation as repeated cycles, not a single event, and ask the partner for a duration based on your own data volumes and product count. No supplied source gives a standard number of trial runs or a reconciliation duration, so treat any figure you hear as unverified until it is tied to your environment. Each trial should load the full scope, reconcile client counts, account balances, schedules and general ledger totals, then log every exception. The number of cycles typically falls as data quality improves and owners resolve exceptions. Ask the partner to show how many trial cycles it assumes, what each cycle must prove and how long a full reconciliation run takes in your test environment.
What should a fixed-scope migration quote contain?
A fixed-scope quote should turn each migration question into a named deliverable with an owner and an acceptance test. DeployOpen works from written scope agreed before work starts, and it does not publish a price list, so the quote should follow from that document. Expect the quote to list the following:
- The data sets in scope, such as clients, loan and savings accounts, schedules, balances and documents, with counts per set.
- The product mapping, tenant setup and general ledger mapping, with the decisions each one requires.
- The number of trial migrations, the reconciliation reports produced and the acceptance criteria for each.
- The cutover runbook, rollback procedure and the client, staff and third-party responsibilities during cutover.
- Assumptions about source data quality, the exclusions and the change process for scope adjustments.
Ask for each assumption in writing so that later disputes trace back to agreed terms.
What happens if a cutover must be rolled back?
A rollback plan must be written, rehearsed and approved before cutover, and it must state who decides to roll back and by what deadline. The plan should define the point of no return, the state of the source core during the rollback window, how any transactions posted to Fineract after cutover are reversed or re-entered, and how the general ledger is restated. Trial migrations are the place to prove this, because the team can practice reverting a full load. Ask the partner how it preserves source extracts, timestamps the cutover and reconciles the source and target after a rollback. Any retention or record-keeping duties that apply to your institution should be confirmed with your compliance team before the plan is final.
Which data controls should an auditor expect to see?
Auditors typically look for a complete, traceable record of how every balance moved from the source system into Fineract. Keep the source extracts, transformation scripts, load logs and reconciliation reports under version control and access restriction, and make sure each trial and final load can be reproduced. Confirm with your auditor which evidence they expect, since DeployOpen prepares systems and evidence for assessments but does not issue audit reports or attestations. Relevant records may also fall under record-keeping rules in your jurisdiction, so check retention periods with counsel. Ask the implementation partner to describe its evidence pack for each cycle and how access to migration data is logged.
How does the migration relate to Fineract's release schedule?
Fineract releases are created quarterly, at the end of each quarter, so the target version can change during a long migration project. The README states that official releases follow the ASF release policy and that end-of-life releases are archived. Fix the target version at the start, record it in the scope, and decide in advance whether a newer quarterly release will be adopted before cutover or after it. Changing version mid-migration can alter how products or batch processes behave, so each change should trigger a repeat of the affected trial loads. Ask the partner how it tracks release notes and schedules regression testing for any upgrade decision.
Questions that separate implementation partners on data migration
Start with the question that filters out most candidates: how many Fineract data migrations has the partner completed in production, and for which institution types and volumes? Ask for the count, the Fineract version each migration ran on, and whether the partner loaded clients, loan and savings accounts, repayment schedules and balances, or only a subset. A partner who has only built demonstration tenants will describe the work in general terms. A partner with production migrations can name the awkward cases: accounts in arrears at cutover, loans with split or rescheduled schedules, and savings accounts with interest posted on a different cycle. Ask how they map source products to Fineract loan and savings products, who signs off each mapping, and how they handle a source product with no equivalent. On accounting, ask how opening balances are posted against the general ledger, which journal or entry type is used, and who approves the figures before go-live.
Next, ask how many trial loads the plan includes, what each trial is meant to prove, and what changes between them. Strong answers describe a sequence: an early load to expose mapping defects, a full-volume load to test timing and batch behavior, and a final dress rehearsal on the cutover runbook. Ask how reconciliation is evidenced. The partner should show how client counts, account counts, principal, interest and fee balances, and general ledger totals are compared between the source system and Fineract, and how exceptions are logged and cleared. Ask for a sample reconciliation report from a past engagement with client data removed, and for the cutover and rollback runbook itself. A description is not evidence. The runbook should name the steps, owners, go and no-go criteria, and the point after which rollback is no longer practical. Finally, ask how quarterly Fineract releases affect the migration tooling. Since the project publishes official releases each quarter, the partner should explain how scripts and mappings are re-tested against a new release and who owns that work during your project.
How DeployOpen scopes and delivers a core banking migration
The sequence turns a migration idea into a written, fixed-scope plan, a tested load path and an evidence pack that the institution's own auditors can review. DeployOpen deploys self-hosted open-source platforms inside the client's own infrastructure and does not publish a price list.
Review source systems and data inventory
DeployOpen reviews the source core or spreadsheets, the extract formats and the data owners with the institution's core banking, finance and risk teams. The output is a written inventory of client, loan, savings and GL data sets, with volumes, known data quality issues and the named owner of each. The step is done when the institution signs off the inventory as the basis for scope.
Agree the migration scope in writing
DeployOpen drafts a scope document covering product mapping, tenant setup, opening balance rules, trial loads, reconciliation reports, cutover and rollback, and the deliverables for each. The institution's project sponsor and compliance lead review and approve the document before any work starts. The step is done when the signed scope fixes what is in and out of the engagement.
Map products and configure tenants
The team maps each source product to a Fineract loan or savings product, documents the accounting rules and sets up the tenant structure in the target environment, which runs in the institution's own cloud account, data center or air-gapped network. Product mapping sheets and the tenant configuration are version controlled and reviewed by the finance owner. The step is done when every source product has an approved target product and a tested configuration.
Run trial migrations and fix defects
DeployOpen runs repeated trial loads of clients, accounts, schedules and balances into a non-production environment, logging every rejected record and its cause. Each run is compared with the previous one so defects and mapping gaps close in a controlled order. The step is done when a trial run completes with reviewed exceptions and the institution accepts the remaining open items in writing.
Prepare reconciliation and evidence pack
DeployOpen builds reconciliation reports that tie account counts, principal, interest and opening GL balances between the source and Fineract, and assembles the evidence for the institution's auditors, such as change records, load logs and sign-off trails. DeployOpen prepares this evidence but does not issue audit reports or attestations, which remain the role of independent auditors. The step is done when finance and audit reviewers confirm the reports are complete enough for their review.
Rehearse cutover and rollback
The team runs a full dress rehearsal of the production cutover, including freeze, final extract, load, reconciliation and the rollback path to the source system. Timings and decision points are recorded, and the institution confirms who authorizes each step. The step is done when the rehearsal produces a runbook the operations team has executed without open blockers.
Hand over and offer ongoing support
DeployOpen hands over runbooks, configuration records, reconciliation procedures and documentation to the institution's operations team, and confirms the post-cutover monitoring checks. Where the institution wants continued help with upgrades, testing or operations, DeployOpen offers retainers defined in a separate written agreement. The step is done when the operations team accepts handover and any retainer scope is agreed in writing.
