Why moving from Fineract CN to Fineract 1.x is a re-platforming project
If your team runs or is evaluating Apache Fineract CN, the decision to make is where you go next, and the answer is Apache Fineract 1.x, the line the project maintains. The move is not an upgrade. CN is a separate microservices codebase, so the work is a data and integration rebuild: you extract data from CN, load it into a 1.x deployment, re-create the configuration it depends on, and re-implement every connection to the systems around it. Plan it as a re-platforming project with its own scope, cutover and sign-off.
The Fineract website states that Fineract CN, the microservices rewrite, was deprecated in May 2023 and archived in late 2023 without an official release. That means no maintained release line, no upstream fixes for security issues you find in your deployment, and no path that Apache Fineract publishes for moving CN data. Any security or compliance review of a CN estate should record that gap as a risk in its own right, independent of how well the platform currently runs.
The effort depends on three things you can measure now: the volume of client, account and ledger data in CN, the number and complexity of integrations that read or write to it, and how long you intend to run CN and 1.x side by side before cutover. Ask a partner to size each one from your own inventory before agreeing a scope or timeline. Confirm with your own team which CN services and interfaces are in use, because an accurate inventory is what makes a fixed-scope quote possible.
Which CN data and integration concepts map cleanly to 1.x
This table compares the main Fineract CN concepts with their Apache Fineract 1.x equivalents and marks each mapping as direct, needing transformation, or needing confirmation. The CN data model is not documented in the sources available to us, so every CN-side assumption must be checked against your own CN export and schema before you rely on it. Use the notes column to plan which items need a transformation step and which need a test.
| Concept | Fineract 1.x equivalent | Mapping type and migration note |
|---|---|---|
| Clients and KYC documents | Client records with KYC documents and client lifecycle in the 1.x REST API | Needs transformation: confirm each CN identity field maps to a 1.x client field and how documents are stored and referenced |
| Products (loan and savings) | Configurable loan and savings products with interest, fee and business rule settings | Needs confirmation: recreate products from the CN configuration, then check every rule against the 1.x product documentation |
| Ledgers and chart of accounts | Real-time integrated accounting with a general ledger and product-to-account mappings | Needs transformation: rebuild the chart of accounts and mappings in 1.x, then reconcile opening balances by account |
| Offices and staff | Office hierarchy and staff records used by clients, loans and accounting | Needs transformation: load the office tree first, since clients and accounts reference it |
| Savings portfolios | Savings accounts with balances, transactions and interest posting | Needs confirmation: decide whether to load outstanding balances or replay history, and verify how 1.x posts opening balances |
| Loan portfolios | Loan accounts with schedules, repayments and interest recalculation | Needs confirmation: schedule and recalculation behavior can change on import, so reconcile principal and interest per loan |
| Business events | External events such as ClientCreated, published to ActiveMQ or JMS brokers and Apache Kafka, disabled by default | Needs transformation: CN event consumers must be rebuilt against 1.x event names, payloads and broker settings |
| Authentication and tenancy | OAuth2 or HTTP basic authentication, with the Fineract-Platform-TenantId header for multi-tenant requests | Needs transformation: replace CN identity setup with 1.x auth, and change the default development credentials before go-live |
Documented import and API paths into Fineract 1.x
Fineract 1.x offers a few documented ways to load data, and each suits different records. The cards below cover the Excel bulk import, scripted API loads, the business events feed, tenant setup, and the open question of what Fineract CN can export.
Excel bulk import for core records
Fineract's Excel bulk import loads offices, staff, clients, groups, products, accounts, repayments and opening journal entries from templates, with no custom code. It is usually the first path to test for a CN migration. The load order matters: offices and staff must exist before clients, and products must exist before accounts. Confirm which sheets your target version's templates cover before you map CN fields to them.
Scripted loads through the REST API
Records the templates cannot carry, or loads that must be rerun, call for scripts against the REST API. Batch requests group several calls so that a client and its accounts can be loaded as one unit. Pair scripts with idempotency keys so a rerun does not duplicate records. This path needs developers who can read the API documentation closely, so confirm who will write and maintain the scripts before planning begins.
Business events feed for downstream sync
Fineract can publish external business events, such as ClientCreated, to ActiveMQ, other JMS brokers or Apache Kafka. The feed is disabled by default, so someone must switch it on deliberately for the environment. During parallel running, it can keep CN-era downstream systems such as a data warehouse or CRM in step with new Fineract records. Confirm event names and payloads in your version before building any consumer.
Tenant setup before any load
Fineract is multi-tenant. Each API request carries a Fineract-Platform-TenantId header, and tenant connections come from a tenants database. Create the target tenant and verify its database connection before any load starts. Keep test and production tenants separate so that a migration script cannot write to the wrong one, and decide how the header is set in each script and environment.
Confirming what CN can export
What Fineract CN can export, in which format, and whether its data model carries over cleanly must be confirmed in your own environment before the plan is final. Ask the CN operator or your previous vendor for every export path, then test each one against a sample dataset. Any record without a working export path needs a transform step that maps CN data to 1.x clients, products and ledgers, with its own tests.
The migration sequence from inventory to decommissioning CN
The sequence moves a Fineract CN deployment onto a maintained Fineract 1.x platform in controlled stages, with each phase closed by a written output and a named sign-off. Nothing is switched off until the new platform has matched the old one in counts, balances and ledger totals.
Inventory CN services, data and integrations
Start by listing every CN service in use, the data each one holds, and every system that reads from or writes to it, including reports, identity sources, payment files and notification paths. The business owner of each portfolio and the head of operations confirm the list, and the technical lead signs the inventory. Done means each data domain has a named owner, a source system, and a stated target in Fineract 1.x or an explicit decision to leave it out. Integrations that no one can name are a risk to raise now, not after cutover.
Stand up the target 1.x environment
Build the Fineract 1.x environment in infrastructure you control, using PostgreSQL as the database, a tenants configuration for each institution, and TLS on every external endpoint. Replace the default mifos credentials before any data is loaded, and confirm the release you deploy against the Fineract website and the project's release notes. The platform engineering lead and the security lead sign the environment, which is complete when access controls, backups and the tenant setup have been tested and documented.
Design the mapping and run a pilot load
Map each CN entity to its Fineract 1.x equivalent for clients, products, savings and loan accounts, offices, and the chart of accounts that feeds the general ledger. Document every transformation, default value and dropped field, then load a small, representative subset into a non-production tenant. The product owner and finance lead approve the mapping, and the pilot is closed when a sample of records can be traced from the CN source to the Fineract result with no unexplained differences.
Repeat trial loads until results are stable
Run full trial loads against fresh copies of the CN data, each time from the same scripted process, and log every rejected record and its cause. Continue until a complete load produces the same results on consecutive runs and the rejects are either corrected at source or accepted with a recorded reason. The migration lead owns the load log, and the data owner signs off each trial. The output is a repeatable runbook that the cutover team can execute without improvising.
Run a parallel period with reconciliation
Operate CN and Fineract 1.x side by side on the same business activity for an agreed period, and reconcile client counts, account balances, loan principal and interest, and ledger totals between them. Each difference is either explained and accepted or treated as a defect in the mapping or the load. The finance controller and operations lead sign the reconciliation pack, which is complete when every reconciled area shows no unexplained variance.
Cut over to Fineract 1.x
Freeze CN writes, run the final incremental load, reconcile the cutover figures against the frozen CN snapshot, and redirect integrations and users to Fineract 1.x. Keep a documented rollback decision point until the first business day closes cleanly on the new platform. The accountable executive and the operations lead sign the go-live decision, and the cutover is closed when reconciliation is clean, integrations have passed their checks, and staff can perform their daily tasks.
Decommission CN and archive its records
Once the agreed stabilization period has passed without a rollback decision, retire the CN services, revoke their credentials, and remove network paths to them. Retain read-only archives of CN data and configuration as your records policy requires, and confirm that the archive can be restored and read. The information security lead and the compliance owner sign the decommissioning record, which lists each service removed, each credential revoked and where each archive is held.
What drives the effort and cost of the CN to 1.x move
This table lists the factors that change the size of a Fineract CN to 1.x move and marks whether each one is paid once or keeps costing money. Read it as a checklist for scoping: each driver shows what to ask a partner or internal team to price. The main takeaway is that data volume, integration count and parallel run length usually matter more than the number of screens to rebuild.
| Driver | Why it changes effort or cost | One-time or recurring | What to ask for in a quote |
|---|---|---|---|
| Number of clients and accounts | Migration tooling, reconciliation and batch run tests scale with record counts. The README notes the Close of Business job can run for hours on deployments with millions of accounts. | One-time (load, test), recurring (batch capacity) | Record counts per entity, expected test load, and whether remote partitioning for COB is in scope |
| Product and ledger complexity | Each CN product, interest rule and ledger account must be mapped to a 1.x equivalent, and mismatches cause balance differences. | One-time | Product inventory, mapping workbook, and who signs off each mapped product and GL account |
| Number of CN integrations to rebuild | CN had its own service boundaries, so each consuming system must be re-wired to Fineract 1.x REST APIs and events. | One-time build, recurring support | Integration inventory with direction, frequency and owner for each interface |
| Event-based sync requirements | Business events such as ClientCreated are disabled by default and must be enabled, routed to ActiveMQ or Kafka, and tested for ordering and replay. | One-time build, recurring broker operations | Which events consumers need, broker choice, and retention and replay expectations |
| Number of tenants and offices | Each tenant has its own database connection and configuration, and each office carries its own accounting and reporting setup. | One-time per tenant and office | Tenant list, office hierarchy, and whether tenants share a configuration baseline |
| Data quality in CN | Duplicate clients, incomplete KYC records and unreconciled balances add cleansing and exception handling before any load. | One-time | Data profiling results, cleansing rules, and the owner who resolves exceptions |
| Length of the parallel run | Running CN and 1.x side by side doubles reconciliation and operator work for every day of overlap. | Recurring for the overlap period | Overlap length, daily reconciliation scope, and staffing for both systems |
| Security and access setup | Authentication, HTTPS and default credentials must be replaced in each environment before production use. | One-time, then recurring patching | Identity integration plan, certificate handling, and the patch cadence for quarterly 1.x releases |
Questions teams ask before moving from Fineract CN to 1.x
Can our team move from Fineract CN to 1.x without outside help?
Some teams can, provided they already run Java services, PostgreSQL and Kubernetes or an equivalent container platform, and have someone who knows their loan and ledger configuration in detail. The harder part is rarely the software install. It is rebuilding the product catalog, the chart of accounts mapping and every integration that CN used to feed, then proving the result with reconciliation. Ask your own engineers to list the CN services and integrations in use, then compare that list against the skills in the team. Gaps in either area are the usual reason to bring in a partner, and a written scope makes the gap visible before work starts.
What does the move ask from our staff?
The move needs finance and operations staff who can define products, interest rules, fees and accounting mappings in business terms, and engineers who can run the build, deployment and integration work. Business owners must sign off on how each CN product maps to a 1.x product, because the platforms model some behavior differently. Engineers need to be comfortable with the Fineract REST API, PostgreSQL, container deployment and authentication setup. Expect testers from operations to validate balances and schedules. Confirm named people and their available hours during scoping, because the schedule depends more on their availability than on the technology.
How is the cost of this move structured, and what drives it?
Cost falls into one-time work and recurring running costs. One-time work covers discovery of the CN estate, design of the target configuration, data mapping and migration tooling, integration rebuilds, testing, hardening and cutover. Recurring costs cover hosting, database operations, patching, monitoring and support. The main cost drivers are the number of products and ledgers to map, the number and complexity of integrations, data volume, the number of environments, and how much reconciliation evidence the business requires. Ask any provider for a quote built from a written scope that lists each of these items, and ask which items are fixed and which are priced per unit of work. No public figure is given here, so compare quotes on the same scope.
How long does the move take, and what changes the timeline?
Duration depends on scope rather than on a fixed template. A move with a small number of products, one ledger structure and a few integrations takes far less time than one covering many branches, several loan types, custom CN services and a long parallel run. The biggest schedule risks are unresolved product mapping decisions, late integration partner availability, and reconciliation failures that send teams back to earlier stages. Ask for a phased plan with explicit decision gates, and confirm which dependencies sit with your organization, such as access to test systems, vendor contacts and sign-off authority. Treat any duration without a stated scope as an estimate to challenge.
Can we move our CN data into 1.x without transforming it?
Usually not. CN and 1.x use different data models, identifiers and configuration, so data needs mapping and transformation before it can load. Fineract 1.x provides its own import mechanisms, and the mapping work decides which of them fits. Confirm with the vendor documentation and your own test loads which CN entities map directly, which need reshaping and which must be rebuilt as configuration instead of data. Balances, schedules and accounting entries need the most care, because a direct copy can lose history or recalculate values. Plan a dry run on a copy of production data and reconcile counts and balances before any cutover decision.
Can we upgrade a 1.x deployment later without starting over?
Yes, 1.x is the maintained line, and the project creates official releases quarterly at the end of each quarter, following the Apache Software Foundation release policy. End-of-life releases are archived. That means the upgrade path is a recurring operational task, not a one-time event. Ask how your design will handle schema migrations, since Liquibase migrations run only on write instances, and plan for a test environment that mirrors production. Check the current release on the project website and the release notes for each version you consider, and budget staff time for regular upgrades in your operating model.
What production hardening is needed before go-live?
Hardening is a set of controls, not a single setting. The project documentation strongly encourages HTTPS only, and the default development login must be replaced before any real use. Other work includes choosing an authentication model such as OAuth2 or basic authentication with strong credential management, restricting network access, separating read, write and batch instances, configuring backups and tested restores, enabling audit logging, and setting up monitoring for the Close of Business job. Each control should appear in your written scope with an owner and a test. Ask your provider how they will verify each control and which evidence they will hand over, and check results with your own security team.
What usually goes wrong when leaving CN for 1.x
Most failed CN to 1.x moves do not fail at the final cutover. They fail earlier, in mapping decisions nobody wrote down, integrations that were never re-tested, and environments that carried development settings into production. Each risk below has a prevention step you can put into the plan before the build starts.
Unmapped CN concepts found late
Fineract CN was a different microservices design, so some of its concepts have no one-to-one home in Fineract 1.x. Teams often discover this during trial loads, when a field or status has no target. Inventory every CN entity, field and status against a 1.x target before you write any load script, and record each decision as either mapped, transformed or dropped.
Integrations assumed to work after re-pointing
Pointing an existing system at a new Fineract API does not make it work. Request shapes, identifiers, authentication and event timing can differ, and a downstream ledger feed or reporting job may fail silently. List each integration that touched CN, then test it against 1.x with production-like payloads and confirm the owner who signs off on each one.
Default development credentials left active
The Fineract README ships a default development login, and it must be changed for any real deployment. Migration environments often keep it because loads run under a service account set up for testing. Rotate the default login, create named service accounts with the smallest roles needed for loading, and remove them before go-live.
Batch and COB runtime surprises
The Close of Business job can run for several hours on deployments with millions of accounts. A CN-sized portfolio loaded into 1.x may produce a first COB that is far longer than anyone planned for. Run COB on a full-volume copy of the data, measure duration, and decide whether remote partitioning is needed before the cutover date is fixed.
Business date mismatches during loading
Loans, schedules and accruals depend on the business date in effect when each transaction is posted. If historical loads run against the wrong date, interest and due dates shift, and the errors compound across every account. Set the business date deliberately for each load batch, record it in the migration log, and check a sample of schedules against the source system after each batch.
Reconciliation gaps found only in parallel run
Counts and totals can match on the day of load and still diverge once both systems process real activity. Differences often come from rounding, fee handling or postings that CN recorded differently. Define reconciliation measures before loading, including client and account counts, principal and interest per loan, and ledger trial balances, and run them daily through the parallel period.
Re-implementing integrations on Fineract 1.x
Every integration that consumed Fineract CN has to be rebuilt against the Fineract 1.x surface, because the CN microservice interfaces do not carry over. Start by listing every system that called or received data from CN: the front end, payment and notification services, reporting feeds, document stores and any batch jobs. For each consumer, record the data it reads or writes, how often it runs, and what it expects back. Then map each one to a specific 1.x REST endpoint, or to a business event if the consumer reacts to changes rather than polling. Where no direct equivalent exists, treat that gap as a design decision with an owner, not a detail for the build team to settle later.
Authentication and transport are simpler to plan than the endpoint mapping but are easy to get wrong. Fineract 1.x supports OAuth2 and HTTP basic authentication, and the project strongly encourages HTTPS only, with SSL settings supplied through environment variables such as FINERACT_SERVER_SSL_ENABLED. Confirm which scheme each consumer will use, who issues its credentials, and how tenant context is passed through the Fineract-Platform-TenantId header on every call. The README's default development login must be replaced before any consumer is pointed at a real environment, and each integration should use its own service account so access can be revoked without breaking the others.
Event publishing is the piece most likely to be assumed rather than configured. Fineract can publish business events such as ClientCreated to ActiveMQ, other JMS brokers or Apache Kafka, but this is disabled by default, so a consumer that expects events will receive nothing until someone enables the feature and points it at a broker. Switch it on deliberately, in a non-production tenant first, and confirm the event names and payloads with a test consumer before any downstream system depends on them. Then test each mapped integration against a copy of your own migrated data, not sample records, because the failures that matter tend to appear only with real client, product and ledger configuration.
How DeployOpen scopes and delivers a Fineract CN to 1.x migration
A Fineract CN to 1.x move touches environment, data, integrations and cutover at once, so the work is scoped in writing before any build starts. The cards below follow that order, from the fixed-scope agreement through to ongoing support after go-live.
Written, fixed-scope agreement
Before work starts, DeployOpen agrees scope, deliverables and timelines in writing, with each Fineract CN service, data domain and integration listed as in or out of scope. The scope document is the basis for the quote, so a quote follows from it rather than from a list of modules. Ask for the scope to name the CN services being retired, the 1.x modules you intend to use and the environments included.
1.x environment in your infrastructure
DeployOpen plans and implements the Apache Fineract 1.x environment inside your own cloud accounts, data centers or air-gapped network. The design covers PostgreSQL, the read, write and batch instance layout, tenant configuration and TLS. Confirm early which hosting and database standards your security team requires, because they shape the build.
Data mapping and load
DeployOpen maps CN client, product and ledger data to 1.x equivalents and documents every field that has no direct match. The mapping is then loaded and checked against the source system. Expect the mapping document to be the most useful artifact in the project, because it records every decision a reviewer or auditor will ask about.
Integration rebuild
Integrations built against CN APIs and events are re-implemented against Fineract 1.x REST APIs and its external event publishing, which is disabled by default and must be enabled and configured. Each interface gets an owner, a test plan and a retirement date for the old connection. Ask which downstream systems depend on CN and which of them can change.
Parallel run and cutover
DeployOpen supports a parallel run in which both platforms process the same activity, then plans cutover with a rollback decision point. The aim is to prove balances, ledgers and client counts match before the old platform is switched off. Agree the reconciliation criteria in the scope so go or no-go decisions rest on evidence.
Compliance evidence and retainers
DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications, which independent auditors and certification bodies provide. After go-live, retainers cover ongoing support, upgrades and testing on your 1.x environment. Quotes are built from the written scope, and DeployOpen publishes no price list.
