Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

What This Module Is (Big Picture)

The bulk import module allows administrators to import large datasets into the system using spreadsheet files.
Instead of creating records manually through the UI, institutions can upload Excel templates containing many records at once.
This module processes those spreadsheets and automatically creates or updates records.
Common bulk import operations include:
  • creating many clients
  • creating loan accounts
  • uploading office data
  • importing savings accounts
  • importing accounting entries

Layman Example

Suppose a bank needs to create 5,000 new clients.
Instead of entering each client manually, the bank prepares an Excel file.
Example spreadsheet:
The administrator uploads this file.
The system reads the spreadsheet and creates all client records automatically.
The fineract-bulk-import module handles this process.

Where the Code Lives

Key Package

org.apache.fineract.infrastructure.bulkimport
Responsibilities include:
  • parsing spreadsheet files
  • validating imported data
  • processing batch records
  • creating system entities

Core Domain Entity:

ImportDocument.java

Path
fineract-bulk-import/src/main/java/org/apache/fineract/infrastructure/bulkimport/domain/ImportDocument.java
This entity represents a bulk import job.

Key fields on

ImportDocument

Spreadsheet Templates

Bulk imports use predefined templates.
Example templates include:
These templates define required columns and data format.

Example Excel Template

Client Import Template
The system reads these rows and creates client records.

Example Spreadsheet Processing Code

java
QUBITS OF DPK
1public void processBulkImport(List<Map<String, String>> rows) {
2
3    for (Map<String, String> row : rows) {
4
5        String clientName = row.get("Client Name");
6        String phone = row.get("Phone");
7
8        createClient(clientName, phone);
9    }
10}
This method processes each row in the spreadsheet and creates records.

Import Validation

Before importing records, the system validates:
  • required columns
  • data formats
  • duplicate records
  • missing values
Invalid rows may be rejected while valid rows are processed.

API Layer

Main controller
BulkImportApiResource
Example endpoints
plain text
QUBITS OF DPK
1GET  /v1/imports/templates
2POST /v1/imports/upload
3GET  /v1/imports/{importId}
These APIs allow administrators to:
  • download import templates
  • upload spreadsheet files
  • monitor import job status

Read Services

Read services retrieve import job information.
Examples include:
  • retrieving import status
  • retrieving import logs
  • retrieving import results
These help administrators monitor import operations.

Write Services

Write services manage bulk import jobs.
Responsibilities include:
  • uploading import files
  • parsing spreadsheet data
  • validating records
  • processing batch creation

Repository Layer

Exceptions

These ensure only valid import files are processed.

How It All Connects (Full Flow)

Example: Uploading client import file
java
QUBITS OF DPK
1Admin UI
2    │ Upload Excel file
3    ▼
4BulkImportApiResource
5    ▼
6BulkImportService
7    │ Parse spreadsheet
8    │ Validate rows
9    ▼
10Entity Services
11    │ Create clients
12    ▼
13Database
14    ▼
15Import job marked complete

Why This Module Matters

Bulk import helps institutions:
  • migrate data into the system
  • onboard thousands of clients quickly
  • perform mass operations efficiently
This is essential for large financial institutions or data migrations.

One-Sentence Summary

fineract-bulk-import enables importing large datasets into the system using spreadsheet templates and automated batch processing.