Why the Apache Fineract office hierarchy decides who sees what
The office hierarchy is the tree of offices in Apache Fineract, with head office at the root and regions and branches beneath it. It decides which staff members can see which clients, loans and savings accounts, and it is the unit that branch-level accounting and calendar settings attach to. For a lender with a head office, regional managers and several branches, the tree is a design decision that must be settled before go-live, because user permissions and branch books both depend on it.
A multi-office structure is needed when separate branches must see only their own portfolio, when branches close their books or observe their own holidays, or when regional managers need visibility across several branches at once. A single office is enough when one team works from one location and every user needs the same view of the book. Either way, confirm in the documentation for your target release how a parent office's users see child offices and whether closures and holidays can be set per office. Record the answer for each role before any configuration starts.
Plan the tree with migration in mind. Office records are referenced by clients, loans, savings accounts, staff and journal entries, so a restructure after data has loaded means reconciling history across every record that points to an office. Map the intended tree to staff roles, branch calendars and accounting closures in one workbook, then check the Apache Fineract platform documentation for how the release you deploy handles office changes.
How the office tree scopes users, clients and reports
Administrators create the office tree and assign users to offices, so their configuration sets the boundaries that every other role inherits. Each office record points to a parent, and the structure you create determines which offices sit beneath head office, which regions group branches, and where a user's access begins and ends. Record the intended tree and the user-to-office mapping in writing before anyone creates offices in a test tenant.
- Creation order: Build head office first, then regions, then branches. Confirm whether the parent is set at creation or changed later through an update.
- User assignment: Each user belongs to an office. Confirm which roles can see records in child offices and which are limited to their own office.
- Permission testing: Log in as one user per branch and check the client list, loan list and reports against the expected scope.
- Change control: Moving or renaming an office can change what existing users, clients and reports show. Require sign-off before reorganizing the tree in production.
Confirm in the current Apache Fineract platform documentation whether office scope is enforced through roles, through data scoping, or through both for the release you run.
Branch managers work inside one office for daily operations, but they still depend on the tree above them. Their client lists, loan queues, collection work and cash activity usually show only the records tied to their branch, and their operational calendar, such as branch holidays and accounting closures, is set at the office level. Understanding these boundaries prevents staff from searching for clients who sit in a neighboring branch or assuming a closure applies to the whole network.
- Client and loan lists: Expect lists to reflect the assigned office. Confirm how a manager finds a client transferred from another branch.
- Branch holidays: Holidays are set per office. Confirm how a branch holiday affects due dates and the batch run for that office.
- Accounting closures: Closures can be tied to an office. Confirm whether a branch can close its books while a parent or sibling office remains open.
- Transfers: Moving a client or account to another branch involves the receiving office and the accounting effects. Plan these with the transfer procedure, not as an informal request.
- Staff assignments: Loan officers and tellers are tied to offices. Confirm what happens to their portfolios and cash when they move.
Before rolling out a branch procedure, confirm in the current documentation which of these behaviors apply to your release and which need a configuration change.
Head office reporting teams need figures across regions and branches, and they need to know whether a parent-level report includes its children or only its own records. The answer determines whether a consolidated report is trustworthy without a manual merge. Reporting access is also a control question, because broad visibility across the tree is a privilege that should be granted deliberately and reviewed.
- Consolidation: Confirm whether parent-office reports aggregate child offices automatically, and whether totals match the sum of branch reports.
- Office filters: Check that reports can be filtered to one branch, one region or the whole network, and that the filter is applied consistently across client, loan and savings reports.
- Cross-branch access: Limit reporting roles to what each team needs. Test that a regional user cannot see another region's clients.
- Reconciliation: Reconcile consolidated totals against branch cash and ledger positions at each closure. Record any office that closed late or reopened after the report was run.
- Historical views: Office changes alter how past records group. Decide whether reports should reflect the tree at the reporting date or the current tree.
When designing these reports, confirm the scoping behavior of each report type in the current documentation, and test it on a copy of the tree before relying on it for management or regulatory figures.
Office structure options and when each fits
This table compares flat, regional and deeper office hierarchies, plus one tenant per legal entity versus one office tree per tenant. Read each row as a decision lever: the option you choose changes who sees what, how closures roll up, and how much data must be reshaped before migration.
| Option | What it changes | Trade-off | What to confirm in your environment |
|---|---|---|---|
| Flat office tree (head office and branches only) | Few levels to maintain. User scoping is simple, since most staff see one branch or all branches. | Simple to administer, but regional managers cannot be given a clean read scope over a group of branches. | Whether any role needs a regional view, and how many branches the first go-live covers. |
| Regional tree (head office, regions, branches) | Regional managers can be scoped to their region. Branch closures and reports can be rolled up by region. | Adds a level that every user and report must be mapped against. Reorganizing regions later means moving offices. | Your region boundaries, who approves cross-region activity, and whether regional reporting matches the org chart. |
| Deeper tree (additional levels such as area or cluster) | Finer scoping and roll-ups for large networks. More levels to validate in closures and reports. | Greater flexibility for large networks, but more configuration, more test cases, and more places where a mistake in parent assignment spreads. | Whether your reporting needs a level Fineract cannot express through the office structure alone, and how often levels change. |
| One tenant per legal entity | Each legal entity keeps its own data, users, configuration and accounting. Cross-entity reporting needs an external step. | Strongest separation for regulators and audits, but each tenant carries its own setup, upgrades and operating effort. | Whether each legal entity needs its own general ledger and regulator reporting, and whether staff serve more than one entity. |
| One office tree per tenant | Several offices, regions and branches share one tenant and one set of products, users and accounts. | Fewer environments to run and easier group reporting, but scoping depends entirely on correct office assignment and role design. | Whether all offices operate under the same products, policies and ledger, and who can see data across offices. |
| Branch-level accounting closures and holidays | Closures and holidays are set per office, so a flat or regional choice changes how many offices must be maintained. | Per-branch closures give accurate books but multiply the closure steps to run and review. | Which offices close on which days, and who signs off each branch closure before the business day rolls. |
| Migration effort from existing branch data | Each office, region and parent link must be mapped to the target tree before any client or loan is loaded. | A deeper or multi-entity design needs more mapping rules and reconciliation checks per office. | Current branch codes, reporting hierarchy, and which legacy systems hold the source of truth for office ownership. |
Setting up the office tree in Fineract
This sequence builds the office tree from an agreed hierarchy, then tests that each office's users, holidays and closures behave as designed before any client or ledger data is loaded. The output is a verified tree with a signed baseline that finance and operations have approved.
Agree the hierarchy with finance and operations
Finance, operations and the Fineract administrator agree the tree before anything is created in the system. For each node, record the office name, a unique office code, the parent office, the opening date, the currency and the team that will hold its staff. Finance confirms which offices post to which ledger entities and who approves closures, and operations confirms which branches share a holiday calendar. The output is a signed tree document. Confirm in the documentation for your release which office fields are mandatory and which can be changed after go-live, since some attributes are difficult to change once transactions exist.
Create the head office and child offices
Create the head office first, then each region and branch under its parent, either through the admin screens or the offices API described in the documentation for your release. Enter office codes exactly as agreed, because integrations and reports commonly refer to offices by code. Verify by exporting the office list and comparing it line by line with the signed tree, checking every parent link. A wrong parent link changes which users and reports inherit that branch, so correct it now, before users are created. Keep the exported list as the baseline for later changes.
Assign staff and roles to offices
Create a staff record for each employee, link it to the office where they work, and then create user accounts linked to those staff records. Assign roles that match the permissions each person needs. Confirm in your version how role permissions combine with office scope, because a role can grant broad permissions while the office assignment limits which records appear. Verify by signing in as a test user from each branch and opening the client list, loan list and reports. Each user should see only their own branch's records. Record the result in the test log before moving on.
Configure branch holidays
Define holidays for each office or group of offices that share a calendar, using the holiday setup in Fineract. With operations, decide which dates are national holidays, which are branch-specific closures, and whether repayment due dates that fall on a holiday move to the next working day. Confirm how holiday handling interacts with your loan product settings in the version you run. Verify by creating a test loan with a repayment date on a configured holiday and checking that the schedule follows the rule chosen for that office. Repeat for an office with a different calendar to confirm the holiday applies only where intended.
Set up branch-level accounting closures
Configure accounting closures per office so finance controls the period each branch can post into. Agree each office's closing date with finance and record who may create or change a closure. Verify by posting a test journal entry dated inside a closed period for one office and confirming it is rejected, then posting the same entry to an open office and confirming it succeeds. Check how a closure on a branch affects entries posted to its parent region, and record the expected result with finance. Confirm in your version whether closures can be set on parent offices and whether they cascade to child offices.
Test scope across the full tree
Run one scope test per office level before any client or ledger data is loaded. Use a test user at the head office, at a region and at a branch, and confirm what each can see and post. Include a user at a parent office to check whether it inherits child records, as your design requires. Verify with a written matrix listing user, office, expected visibility and actual result, where every row passes or a tree change is logged and retested. Keep the matrix with the signed hierarchy so the same test can be repeated after any reorganization or migration load.
Security and access risks in a multi-branch Fineract setup
An office tree only protects branch data if the people, roles and deployment settings around it are controlled. The cards below cover the access mistakes that most often expose one branch's data to another, and the controls that catch them before go-live and during operation.
Users assigned to the wrong office
A user's office assignment determines which clients, loans and savings accounts appear in their searches and reports. A teller created under the wrong branch can see and act on another branch's portfolio without any error being raised. Before go-live, reconcile every user's office against the staffing roster, and test with one user per branch that a search returns only that branch's clients. Re-run the check after every reorganization, since transfers of staff and clients change who should see what.
Over-broad roles at head office
Head office staff often need consolidated reporting and occasional corrections, which tempts administrators to grant broad permissions that also allow posting, closures and user management across every branch. Define separate roles for branch operations, regional oversight and head office administration, and keep the administrator role small. Ask the implementation team to show, for each role, which permissions it holds and which offices it can act in, and confirm this against your own segregation-of-duties rules.
Test environments under default credentials
Fineract's README ships a default development login, and a test or pre-production instance copied from a default setup can keep it. Test data copied from production into a less protected environment exposes real client records to anyone with that login. Confirm that every environment has its default login changed, that test data is masked or synthetic, and that the same role model is used in test so that access tests are meaningful.
Default login change before any real use
The default development login must be replaced before any real deployment, including staging environments that hold realistic data. Replace it with named accounts tied to individual staff, and disable or remove the default account rather than leaving it dormant. Verify the change by attempting a login with the old credentials on each environment and confirming it fails.
HTTPS-only access to the API
Branch staff reach Fineract through a front end over the network, and any plain HTTP path would send credentials and client records in clear text. The project documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Confirm that plain HTTP is refused at every entry point, including internal load balancers and any gateway in front of the API, and that certificates are renewed on a schedule.
Audit of office and user changes
Changes to the office tree, user office assignments and role permissions alter who can see branch data, so they need the same traceability as transactions. Record who made each change, when, and what it replaced, and review these events at a fixed cadence. Ask the implementation team where Fineract's audit records are held, how long they are kept in your environment, and how you will export them for your internal audit or external assessor.
Planning the hierarchy before migration to Fineract
Fix the office tree before any client, loan or savings data is loaded. Clients, staff, loan officers and accounts all reference an office, so a tree that changes after migration means re-pointing records that were already validated, reconciled and possibly already in use. Treat the hierarchy as a reference dataset with an owner, a sign-off and a change log, and load it first in the target environment so that every later import file can be checked against it. Confirm which Fineract release and database you will run before you finalize the tree, since the import tooling and API behavior you test against should match the version you go live on.
Settle several questions with the business before anyone builds the import files. Agree a unique, stable branch code for every office, because codes are what your migration mappings and reconciliation reports will key on, and reuse of a retired code creates confusion in historical data. Ask for any planned branch openings, closures, mergers or regional reshuffles over the next several years, so the tree reflects the structure you will run rather than the one you have today. For each historical branch, decide whether it maps to a live office, is folded into another office, or is kept only as a legacy reference outside Fineract. Record each mapping in a table that finance, operations and risk all sign.
Keep the hierarchy decision separate from the question of where existing clients sit. Moving clients, their loans and savings between offices later uses the propose and accept transfer flow, with its own loan officer, group and accounting checks, so the migration does not need to place every client perfectly on day one. Confirm with the business which clients are migrated into their current branch and which are reassigned afterward, and document that choice. Also confirm with your implementation team whether the import mechanism you use can place records against the office codes you define, so the plan starts from what the import actually supports.
Limits to confirm in your environment
The office hierarchy shapes reporting, closures and holidays, so several behaviors depend on how Fineract runs in your deployment. Confirm each limit with the platform documentation and a test environment before you commit the branch model to a migration plan.
Maximum practical office depth
Confirm how many levels of parent and child offices your reporting and user scoping can handle before queries, dashboards or permission checks slow down. Build a test tree that matches your real regional structure, including head office, regions and branches, and time the reports your operations teams run daily. Record the depth at which you would need to flatten the tree.
Holidays and the close of business job
Confirm how a holiday defined for one office affects the Close of Business Day job, which runs across the whole deployment. Test a branch-level holiday on a day when other branches are open, and check whether accruals, due dates and repayment schedules shift as you expect. Note that the job can run for several hours on large deployments, so schedule holiday tests with that duration in mind.
Branch closures and multi-currency accounting
Confirm what happens to ledger balances, journal entries and currency conversions when a branch is closed or its accounting is closed for a period. Check whether closing one office's books blocks postings from other offices that share the same currency or GL accounts. Ask your accounting team to reconcile a test closure against the expected trial balance before any cutover.
Which reports respect office scope
Confirm for each standard report and custom report whether it filters by the user's office or returns data for the whole tenant. Test with a user limited to one branch and compare results with a user at head office. Treat any report that ignores scope as a data exposure risk until the vendor documentation or your own test proves otherwise.
Tenant and environment settings
Confirm which office settings are per tenant and which can differ between environments, since a hierarchy built in a test tenant may not carry over unchanged. Check the tenant identifier handling in your API calls and confirm that office IDs are preserved or remapped during migration. Document the exact configuration version you tested so the results can be repeated after an upgrade.
Questions teams ask before building the office hierarchy
What drives the cost of designing a Fineract office tree?
The main driver is how many decisions the tree forces: how many levels the organization needs, which offices own which products and accounting, and how user access is scoped by branch. Costs are mostly labor, split between the design workshops with your finance and operations leads and the configuration work that follows. Fixed-scope engagements are priced from a written scope, so ask for the number of branches, the number of levels, whether regional users need scoped access, and whether migration data must be mapped to the new offices. Design and configuration are usually one-time costs, while changes to the tree after go-live recur as reorganizations occur and need their own change control.
How long does office hierarchy configuration usually take?
Duration depends mainly on branch count, the depth of the hierarchy, and whether historical data must be loaded against the offices. A single-office pilot is quick to configure; a network with regional layers, branch-level closures and a migration mapping takes longer because each office needs validated holidays, accounting settings and user scopes. DeployOpen does not publish durations, so ask for a timeline in the written scope that lists the branch count, the migration volumes and the test cycles. Confirm with your own team how many business days per week finance can review test results, since that often sets the pace more than configuration does.
What does the work need from our finance and operations staff?
Finance and operations staff need to provide decisions and sign-offs, not just data. They should confirm the legal and reporting structure of the organization, which offices hold cash or post to the general ledger, how month-end and year-end closures happen at branch level, and which public holidays apply to each location. Operations should supply the list of branches, their opening and closing dates, the staff who manage each one, and the reporting lines that determine who sees what. Ask for a named decision owner for each area so that reviews do not stall while questions wait in a queue.
Can our internal team build the office hierarchy without a partner?
Yes, a capable internal team can build the office tree, but it needs Fineract experience in the team and enough time to test the scope rules properly. The hard parts are rarely the API calls themselves. They are the accounting and access decisions that are difficult to reverse once transactions exist, and the verification of user scopes across roles. Teams that build in-house should plan for a written test plan, a staging environment matching production configuration, and a review by finance before go-live. A partner is most useful when the internal team lacks that Fineract depth or when the timeline is fixed and cannot absorb rework.
Which mistakes are expensive to fix after the hierarchy goes live?
The most expensive mistakes are structural ones made before transactions post. Changing an office's place in the tree after clients, loans and journal entries exist affects reporting, user access and accounting views, and it must be reconciled rather than simply edited. Other costly errors include unclear branch-level closure rules, holidays entered for the wrong office, and user roles that see more branches than intended. Ask for a review of the hierarchy in a staging environment with sample transactions before go-live, and confirm with your auditors what evidence they will want about the office structure and access scopes.
How do we confirm that branch users only see their own data?
Confirm it by testing it, using accounts from each role and each branch, and recording the results. Fineract's documentation describes how users are associated with offices, but your own test cases should verify what each role can read, create and approve across the tree, including regional managers and head-office users. Run the tests against the security configuration that will be used in production, including the authentication method and tenant settings, because a development login or relaxed profile can hide scope problems. Keep the test results as evidence for internal reviews and external assessments. DeployOpen prepares systems and evidence for compliance assessments, but auditors issue the opinions.
What should we ask for in a quote for this work?
Ask for a written scope that lists the deliverables, the assumptions and the exclusions. The key items are the number of offices and levels in the tree, the accounting closure and holiday rules to configure, the user roles and scopes to test, the migration mappings to office codes, and the test and sign-off cycles with your staff. Ask how change requests are handled after the scope is agreed, what is one-time and what is covered by a retainer for ongoing support, and which of your internal roles the plan depends on. A quote that cannot name these items is hard to compare with another one.
Should we plan the office hierarchy before data migration starts?
Yes. The office tree is a dependency for migrated clients, loans, savings and accounting balances, so it should be fixed in the design before any import mapping is written. Changing the tree during migration forces remapping of records and retesting of balances, which is slower and riskier than settling the structure first. Agree the office codes, the parent-child relationships and the branch closure dates with finance before the migration plan is finalized. Note that the Fineract documentation and the README describe a production deployment as complex and time-consuming, so treat the hierarchy as one early milestone in the broader plan.
How DeployOpen scopes and delivers the office hierarchy
DeployOpen fixes the office design in writing before any configuration starts. The written scope lists the head office, each region and each branch as it will exist in Fineract, the parent of every office, the staff who will sit in each one, and which users should see which branches. It also records the branch-level accounting closures and holiday calendars each office needs, so the design is agreed in one document rather than assembled during the build. Because most engagements are fixed-scope, the deliverables and the points at which the client signs off are agreed before work begins, and any change to the tree after that is handled through the written change process.
Configuration is delivered inside your own infrastructure, in your cloud accounts, data centers or air-gapped network, against the Fineract instance you run. The office tree is entered and checked in a non-production tenant first, then promoted with the same steps used for the rest of the platform. DeployOpen documents the resulting tree, the role and office assignments behind each user's visible scope, and the closure and holiday settings per branch. That documentation is what your operations, risk and audit teams will read later, so it is written to be checked against the live system rather than kept as a diagram.
Your teams keep the structure after go-live, and branch changes are normal: openings, mergers, staff moves and new regional managers. DeployOpen offers retainer support for these changes, where the office tree, scoping rules and documentation are updated under the same controls used for the original build. Ask any partner, including DeployOpen, to state in the quote who performs each change, how the documentation is revised, and how a change is tested before it reaches the production tenant. No timeline or outcome is promised here, since these depend on the agreed scope and your own environment.
