Apache Fineract entity-datatable checks

What Apache Fineract entity-datatable checks block before activation

A lender may need to stop a client, loan or savings account from becoming active until KYC or credit fields have been recorded. Apache Fineract entity-datatable checks enforce that requirement by linking a data table to an entity and a lifecycle action, so the platform refuses the action while the required data is missing. Teams reach for them when onboarding controls must be enforced in the system rather than left to individual staff, when a loan product needs credit inputs such as declared income or collateral details before approval, or when auditors expect evidence that a control operated on every record. Confirm the entity types, actions and product scoping your Fineract version supports in the Apache Fineract platform documentation.

Entity-datatable checks do not replace the approval workflow. A check confirms that data exists, not that it is accurate, complete or acceptable under your credit policy. A reviewer still has to verify identity documents, assess the credit file and decide whether to approve. Nor does the check amount to compliance. It is one control within a wider programme, and an independent assessor decides whether the design and operation meet a given framework. DeployOpen prepares the configuration, control descriptions and test evidence that an assessment will draw on, but it does not issue audit reports, attestations or certifications.

Before go-live, decide which fields are mandatory for each action, which products need product-specific checks, and who owns changes to the data table. Then test the negative cases: attempt to activate a client, a loan and a savings account with the data missing, and confirm that the platform blocks each one with a clear error. Also confirm that a complete record passes. Keep the test scripts and outputs as evidence. Ask your implementation partner or the vendor to confirm how the checks behave for batch actions and imported records, because those paths may not follow the same flow as interactive activation.

How the datatable attaches to client, loan and savings actions

A data table in Apache Fineract is registered against an entity type, such as client, loan or savings account, and the registration decides where the extra fields can appear in the product. Each registered table is a set of columns defined by the implementer, and each row written to it is tied to one specific record through that record's identifier. A KYC table on the client entity therefore holds one row per client, while a credit table on the loan entity holds rows for the loan being assessed. Before configuration starts, design the table around the decisions it must support: which fields the front end collects, which values must be present at activation, and which fields the credit team will later query. Fields that are optional for onboarding but required for credit approval should be separated into a different table, so that a mandatory check on one action does not block another.

The mandatory flag is the control that changes an outcome. When a table is marked as required for a given action, Fineract refuses the activation request until a row exists for the record being activated. The check belongs to the action, not to the table, so the same table can be required when a client is activated and optional when a loan is approved. Confirm in the platform documentation and in the release you run which actions each entity type supports for datatable checks, since support differs between client, loan and savings flows and may change between releases. Also confirm the exact response the API returns when a check fails, including the status code and error structure, because your integration, front end and operator runbook will all depend on that message being stable.

Testing this behavior is part of the design, not an afterthought. For each required action, plan at least one attempt without the data that must fail and one attempt with complete data that must succeed, run against a non-production tenant. Record the response payloads so that the team building the front end knows what to display. Decide early who owns the list of required fields, because a change to a mandatory field on a live product affects records already in progress. The full scope of onboarding fields, identifiers and approval steps is covered in the sibling pages, so this check should be planned together with them rather than set up separately.

Which entity and action to gate with entity-datatable checks

This table compares three places to attach an entity-datatable check in Fineract: client activation, loan approval or disbursement, and savings account activation. Read each row against the data you must hold before money moves, who owns those fields, and what breaks if the check is set too broadly. The main takeaway is to gate the narrowest action that still guarantees the control you need.

Option	Best suited data and owner	Main risk if too broad	Verify in the running release
Client activation	Identity and KYC fields such as ID type, address proof and source of funds. Owned by the onboarding or compliance team.	Staff cannot create pending clients for field collection, and onboarding stalls where documents arrive later.	Confirm that the check blocks activate and not client creation, and test a rejected activation with the data table empty.
Loan approval or disbursement	Credit inputs such as income, existing debt and collateral details. Owned by credit risk, with loan officers entering values.	Applications cannot be saved for review, and officers may enter placeholder values just to pass the gate.	Confirm whether the check fires on approve, disburse or both, and that it applies only to the product IDs you scoped.
Savings account activation	Deposit declarations such as beneficial ownership, purpose of account and tax residency. Owned by the deposits product team.	Low-risk deposit accounts are blocked by fields meant only for high-value or business accounts.	Confirm product scoping on savings products and that a closed or reactivated account keeps the same rule.
Scope by product or office	Fields that differ across loan or savings products. Owned by the product owner who maintains the data table definitions.	A single table attached to every product forces irrelevant fields on users and creates support tickets.	Check how the table is linked to each product and test one product from each family in the release you run.
Data table ownership and change control	Table definitions and code values. Owned by the platform team, with compliance sign-off on field changes.	A renamed or added mandatory field can freeze activations for clients already in the pipeline.	Test adding a required field against pending records and document how existing clients are handled.
Audit evidence of the gate	Test results showing the activation fails without data and succeeds with it. Owned by QA and the compliance lead.	Assessors see the rule configured but find no proof it runs, so the control is weak on paper.	Keep dated test runs per release and per product, and retain the API responses showing the rejected calls.

Scoping entity-datatable checks by product, office or entity type

A check that applies to every client is the simplest rule to reason about. Every client creation or activation path asks for the same data table, so the control is easy to explain to auditors and easy to test. The trade-off is that the rule also applies to clients who will never borrow or save with a product that needs the data, which can slow onboarding for low-risk segments and push staff to enter placeholder values just to pass the check.

Clearest audit story: one rule, one data table, one place to show an examiner.
Highest friction: clients for whom the data is irrelevant still need it before activation.
Placeholder risk: if the data is not truly collected for everyone, staff may enter dummy values, which weakens the control.
Testing burden: test each client entry point (API, any front end and any batch or import path) to confirm none bypasses the rule.
Change impact: altering the mandatory fields later affects all existing onboarding flows at once.

Before you rely on a client-wide check, confirm in the documentation for your release how the data table is linked to clients and which actions the check actually gates.

Setting up mandatory entity-datatable checks in Fineract

This sequence turns a KYC and credit field list agreed with compliance into a Fineract configuration that blocks client activation or loan and savings actions until the required data is recorded. Each step ends with a check, so the team can show that the rule is in place, scoped correctly and consistent across environments.

Agree the field list with compliance
Compliance, credit and the implementation lead agree which KYC and credit fields must exist before each action, using the organization's onboarding policy as the source. For each field, record the name, data type, allowed values, the entity it belongs to (client, loan or savings account), and the action that must be blocked without it. Keep fields that are optional for the policy out of the list so the rule stays narrow. The step is done when the signed-off list is stored with the configuration backlog and every field has a named owner for future changes.
Create and register the datatable in a test tenant
An administrator creates the data table in a non-production Fineract tenant through the platform's data table administration, defining each column with the type agreed in the field list. Where a value is a fixed choice, such as a document type, the team uses code values rather than free text so later reporting stays consistent. The table is then registered against the target entity. Confirm the registration by reading the table back through the API and checking that every column name and type matches the approved list.
Attach the datatable to the chosen entity and action
The team links the registered data table to the entity and action that must be gated, for example client activation or loan approval, using the mandatory check settings that Fineract provides for data tables. The attachment should be made to the smallest set of actions the policy requires. Record the exact entity and action pairs in the change log. The check is complete when the data table attachment is visible in the configuration read-out and matches the approved pairs.
Configure product and office scope
Where the policy applies to some products or branches only, the team narrows the check to those products or offices so that unrelated business is not blocked. Scope decisions are made by the product owner and the branch lead, and each one is written down with its reason. Confirm the scope by listing the products and offices it covers and comparing that list with the decision record. Scope settings that do not match the decision record are the most common cause of unexpected rejections, so this check should be repeated after every product change.
Test that activations fail without the data
A tester creates a test client without the mandatory fields and attempts activation and the gated loan or savings action. Fineract should refuse the request. The tester captures the API response, confirms that the error identifies the missing data table and that the client or account state did not change, and stores the request and response with the test record. This negative test proves the control works before any real data is entered, and it should be repeated whenever the field list or scope changes.
Test that activations succeed with the data
The same tester completes the mandatory data table for the test client and repeats the activation and gated action. The request should succeed, and the stored values should be readable through the data table endpoint for that client. The tester also checks that a product or office outside the defined scope is not blocked. The step is done when the positive and negative results are recorded side by side, so a reviewer can see both outcomes in one place.
Confirm consistent configuration across environments
The data table definition, entity attachments and scope settings are exported from the test tenant and applied to staging and production through the team's normal change process, not recreated by hand. After each promotion, the team reruns the negative and positive tests in that environment and compares the configuration read-out with the approved record. Confirm with the vendor or your own environment team how the chosen Fineract version handles configuration export and import, since this varies by release. The step closes when all environments show the same configuration and the test evidence is filed with the change record.

Security and data protection for KYC fields in datatables

A datatable check is only as trustworthy as the controls around it. Whoever can change the table, the way the data travels to Fineract, and the records of who changed what all determine whether a KYC requirement holds in production. The cards below cover the controls to design and verify before the first activation gate goes live.

Restrict who can change datatables

Creating, editing or detaching a datatable is a configuration change to a control. Removing a mandatory field or detaching the table from an activation action silently weakens the KYC gate, so the permission to manage datatables should sit with a small group separate from the people who onboard clients. Check which Fineract roles include datatable administration in your deployment, and test that a standard onboarding user cannot modify a KYC table or its attachments.

Protect personal and identity data

KYC tables hold identity numbers, dates of birth, addresses and sometimes document references. Decide which fields are sensitive, limit which roles can read them, and confirm that API responses and reports return only what each consumer needs. Ask whether your database backups, replicas and logs encrypt these columns or the storage underneath them, and whether any test environment was filled with copies of production identity records.

Enforce HTTPS and strong authentication

Onboarding forms send identity data to Fineract over the API, so the transport must be protected. The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. The README's default development login must be replaced before any real deployment, and the chosen authentication method, OAuth2 or HTTP basic, should be verified end to end for every client that submits KYC data.

Keep an audit trail of configuration changes

A reviewer must be able to show when a datatable was created, which mandatory fields it carried on a given date, and who changed the product link. Confirm which configuration and data changes Fineract records with user and timestamp, which it does not, and where you will export that history. Store it outside the application database so that an administrator cannot edit the evidence of their own change.

Separate tenants in multi-tenant deployments

Fineract is multi-tenant. Requests carry a Fineract-Platform-TenantId header, and tenant database connections come from a tenants database. A KYC table defined in one tenant must never be readable or attachable from another, so test that a request for tenant A with credentials for tenant B fails, and that each tenant's datatables and client records stay isolated in reports and exports.

How to test that activations fail without the data

The control is only proven when a test shows that an activation is refused while a required entity-datatable row is missing. Start with negative tests: for each mandatory field in the data table, create a client, loan or savings account, leave that one field empty, and attempt the action that should be blocked, such as client activation or loan approval. Record the exact response and the resulting status, then repeat for every mandatory field in turn so that no field is assumed to be covered by another. Include the case where the data table row is absent altogether, because a blank row and a missing row can behave differently in your configuration and both paths need evidence.

Pair those with positive tests that supply complete data and confirm the action succeeds, and with scope tests that run the same action on a product or action type the check is not meant to cover. The scope tests show that the check does not block unrelated products, which is as important to the business as the block itself. Test data should be synthetic and kept in a non-production tenant that mirrors your production configuration. Confirm with your Fineract administrators how the data table is bound to each entity and product in your build, since the test matrix must match those bindings exactly.

Schedule regression tests after each Fineract upgrade, after any change to the data table or its product scope, and after changes to the authentication setup that affects who can perform activations. Fineract releases are published quarterly according to the project's release documentation, so plan the regression run into the upgrade window rather than treating it as optional. Store each run with the test IDs, the build or release version, the tester, the date and the outcome, so internal audit or an external assessor can trace each control to its evidence. DeployOpen prepares this test plan and evidence pack; independent auditors and certification bodies make any assessment of whether the control is adequate.

Limits to confirm before relying on datatable gating

Entity-datatable checks look like a single switch, but how far they hold depends on the running Fineract release and on how your team calls the API. Each card below names one boundary to test in your own environment, using the release notes for the version you deploy and scripted test cases that mirror your real onboarding and loan paths.

Entity types and actions enforced

Confirm which entity types and actions your running release actually checks against a mandatory data table. Support for a check on client activation does not imply the same check on loan approval, disbursement or savings activation. Build a matrix of entity, action and product, then try to complete each action without the data and record whether it fails as designed.

Bulk and batch request coverage

Determine whether the mandatory data check also applies when activations or loan actions arrive through batch requests. A gate that holds for single calls can be bypassed if the batch path skips the same validation. Send equivalent batch payloads with and without the required data and confirm that the outcome and error reporting match the single-call behavior.

Approval steps and pending statuses

Check when the data requirement is evaluated relative to approval and pending states. A record may be approved, or moved to active, before a data table row is present if the check runs only at one step. Walk each client and loan through pending, approved and active states with the table empty, and confirm where the block occurs and who can override it.

Effect on existing records

Establish whether adding a mandatory data table to a product or entity changes records that already exist. Some implementations will only enforce the check on new actions, leaving older clients or loans without the data. Ask how your team will identify and remediate legacy records, and test a reactivation or update on a record created before the rule existed.

Behavior across API clients and front end

Confirm that the check behaves the same for every client that calls Fineract, including the Mifos web application, your integration services and any scripts. Front ends may hide fields or validate locally, which does not protect the API. Test direct REST calls with the required data omitted and confirm the rejection is enforced server side for each client path you run.

Not a substitute for identity verification

A populated data table proves that a field was captured, not that the information is true. Verification of identity documents is a separate process with its own evidence, reviewers and retention rules. Keep the two controls distinct in your procedures, and confirm with your compliance function and auditor how each is evidenced before relying on the datatable as a KYC control.

What buyers ask about cost, effort and testing entity-datatable checks

What drives the effort of an entity-datatable check in Fineract?

The effort depends on how many actions the check must guard and how many products it must scope to. A single data table attached to one client action is a small change, but a check that gates client activation, loan approval and savings activation across several products adds configuration, role decisions and test cases for each path. Other drivers are how many fields are mandatory, whether the data must be validated against an external source, and how much of the existing client data must be back-filled. Ask the partner to list each action, product and field in the written scope so the effort can be traced to specific items.

Can our own team configure a datatable check without outside help?

Often yes, if the team has someone who knows the Fineract REST API, the data table definitions and the product configuration, and who can test in a non-production environment. The work itself is configuration rather than custom code, but mistakes are easy to make: a check attached at the wrong scope can block good activations or let incomplete files through. Teams usually need outside help when the rules must be reviewed against a compliance requirement, when several products share the same gating logic, or when the checks must be proven with repeatable tests. Your own staff should own the rules and the evidence either way.

How long does an entity-datatable check engagement typically take?

No duration can be given here without the scope. The timeline follows from the number of actions gated, the number of products affected, the amount of test data needed and how many review cycles the compliance team requires. A narrow change to one client action can be scoped as a short piece of work, while a set of checks across loans, savings and client onboarding needs a longer plan with test cycles. Ask for a timeline tied to named deliverables, and confirm which dependencies, such as sign-off or a test tenant, can hold the schedule.

What does the client need to provide before the work starts?

Three things usually decide whether the work moves smoothly. The first is written compliance sign-off on the required fields, validation rules and the actions they gate, so the build does not stop for interpretation. The second is test data: representative client records, including incomplete ones, that show what should be blocked and what should pass. The third is a non-production Fineract tenant, configured close to production, where checks can be built and tested without touching live portfolios. Confirm who in your organization approves each item and how long that review takes.

How are entity-datatable checks maintained across Fineract upgrades?

Checks are configuration held in the platform, so they must be re-tested whenever Fineract is upgraded, because a new release can change how data tables, validation or API responses behave. Plan a regression test set that covers every gated action and every product, and run it on a non-production copy before each upgrade. Record the expected result for each test so a failure is easy to read. The cost of this work recurs with each upgrade cycle, so ask whether the quote includes a re-test pass and who owns the test set afterwards. Check the Fineract release notes for any changes that touch the affected areas.

What should a fixed-scope quote for these checks include?

A fixed-scope quote should list the exact actions to be gated, the products and client types in scope, each data table and field with its validation rule, and the environments where work happens. It should name the test cases that prove each check blocks activation without the required data, and state what evidence is handed over. It should also separate one-time build work from recurring items such as upgrade re-testing and support, identify what the client must supply, and state the assumptions behind the estimate. DeployOpen agrees scope, deliverables and timelines in writing before work starts, so ask for that document to be the basis of any comparison.

Do entity-datatable checks replace a compliance assessment?

No. The checks are a technical control that enforces data collection before an action proceeds, and they help prepare evidence for a compliance review. They do not decide whether your program meets a regulation or standard. An independent auditor or certification body makes that judgment, and DeployOpen does not issue audit reports or certifications. Ask your compliance lead to map each gated field to the requirement it supports, and confirm which parts of the evidence must come from your own processes rather than from Fineract configuration.

How DeployOpen scopes and delivers Fineract activation controls

DeployOpen plans, configures, tests and hands over entity-datatable checks that stop a Fineract client, loan or savings account from activating until its required KYC or credit data is recorded. Each step is agreed in writing and runs inside infrastructure your organization controls.

How we scope

We list each activation action that must be gated, such as client activation, loan approval or savings activation, in the written scope
We agree which data table fields are mandatory for each client type and product, with your compliance and credit owners
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts

How we build

We create the data tables and attach them to the client, loan or savings entities, then scope each attachment by product where needed
We configure the checks in your non-production Fineract environment and record the exact configuration for review
We write test cases that confirm activations fail without required data and succeed once the data is complete

How we hand over

We deliver the configuration record, test evidence and a list of the data fields that gate each activation step
We document how to add or change a mandatory field so your team can apply the change through a controlled process
We walk your operations and compliance staff through the controls so they know what evidence to retain

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover
We can rerun the activation tests after a Fineract upgrade or a change to a product or data table
Our work prepares controls and evidence for compliance assessments, while independent auditors issue any audit opinion

Requiring data before activation with Apache Fineract entity-datatable checks