Skip to content

Instantly share code, notes, and snippets.

@7ossam7atem1

7ossam7atem1/gsoc-2025-work-product.md

Last active August 31, 2025 11:26
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save 7ossam7atem1/75f84de1cad86e5e7e45f7ded911b7a9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save 7ossam7atem1/75f84de1cad86e5e7e45f7ded911b7a9 to your computer and use it in GitHub Desktop.
Download ZIP
GSoC 2025- Integrate Mifos X With Workflow Engine/Process Automation Tool- Work Product
Raw
gsoc-2025-work-product.md
image

Integrate Mifos X with Workflow Engine/Process Automation Tool

Mifos X implementation lacks a sophisticated workflow management system that seamlessly integrates both internal processes and interactions with external systems. An integration with a workflow engine such as Flowable makes life easier, meaning that non-tech folks can finally join the party dragging and dropping steps like they’re playing a game of Tetris. This reduces errors, speeds up process management, and fills the gap between Mifos X's core banking capabilities and advanced workflow automation.

Project Overview

Mifos users need greater flexibility and control over creating loan and customer onboarding workflows that integrate both internal processes and external systems.

This project focuses on building an external integration with a workflow engine (such as Flowable or jBPM) using the Mifos X REST API as the bridge. The auto-generated client library from the back end ensures a reliable contract between the workflow engine and the core banking system.

By leveraging this integration, the core banking system and its REST API serve as the central connector, enabling a UI-driven workflow engine where non-technical users can design and customize workflows. Through a drag-and-drop interface, users can easily define the various steps of a process, allowing for tailored and efficient loan management and customer onboarding.

Proposed Solution

Mifos X currently provides only basic workflow management capabilities, which fall short of modern standards. Our goal is not just to integrate Flowable and stop there, but to build a solution that is flexible and extensible, enabling easy migration to other workflow engines in the future.

We are starting with Flowable because it is highly regarded in the open-source community for its robustness and flexibility. Its support for BPMN 2.0 makes it ideal for modeling and executing complex business processes while providing clear, visualized workflows that are easily understood by non-technical users. Flowable’s active community also ensures continuous improvement, long-term sustainability, and strong support.

Moreover, Flowable’s seamless integration with Java and REST APIs makes it a perfect fit for Mifos X, allowing us to automate critical workflows such as payments, KYC, and AML/TF efficiently.

At the same time, we are keeping the design engine-agnostic, ensuring that the system can later integrate with other workflow solutions such as Temporal, Orkes, or AWS SWF. This approach prevents vendor lock-in and ensures the long-term adaptability of the platform.

Solution Details:

  • Introducing a WorkflowEngine layer, acting as an abstraction interface where different workflow engines can be integrated easily. Think of it as a generic adapter, keeping Mifos X core clean and adaptable by allowing various engines to plug in like different attachments for a tool.
  • Within this layer, we are employing Factory Pattern to dynamically select appropriate engine based on configurations, making it straightforward to switch from Flowable to Temporal or another engine by just updating the configuration file.
  • By starting with flowable, this layer ensures that Mifos X is set up to be compatible with various workflow engines in the future, enhancing the power and adaptability for all users not just the tech savvy ones.
  • We will be able to streamline processes like payments, KYC, AML/TF, improving efficiency and compliance in financials.

Progress Report

Pre-coding Phase

  • Before the coding period, I worked on setting up the project structure and familiarizing myself with Mifos and the Fineract Client that I was going to use.

Core Feature Implementation

Week 1

  • Initialized the project skeleton and added the Fineract Java client library as the foundation. Implemented the WorkflowEngine interface to define workflow operations and introduced the WorkflowEngineFactory to enable dynamic engine selection. Built the first engine integration with the FlowableWorkflowEngine and added configuration properties to support flexibility and easy switching. The database was switched from H2 in-memory to MySQL for greater consistency. In addition, created the FineractAuthService for handling authentication with the Fineract system and the FineractClientService for client onboarding, including creating and activating clients. Finally, refined the overall project structure for better organization(#PR1).

Week 2

  • Migrated the Fineract client integration from the older Java Fineract client to the new Kotlin Multiplatform (KMP) client to improve cross-platform compatibility and long-term maintainability. Refactored both the FineractClientService and FineractAuthService to use the KMP client APIs, updating all service methods along with their request and response handling. Input validation and error handling were enhanced across all client-related service methods to ensure more robust and predictable behavior. In addition, the test suite was updated and expanded to cover all service methods, including validation and error scenarios, to guarantee higher reliability and code quality(#PR3).

  • Refactored the FineractAuthService to return an Observable<AuthenticationResponse> using RxJava instead of CompletableFuture for handling authentication. All logic and error handling were updated to maintain functional equivalence with the previous implementation. The FineractAuthServiceTest was also refactored to use RxJava’s blockingFirst() and TestObserver for assertions and error validation, ensuring consistent and reliable test coverage(#PR4).

Week 3

  • Updated the FineractClientService methods to accept their respective DTOs instead of raw maps, eliminating the risk of runtime errors from incorrect map keys or value types and ensuring strong type safety. All outgoing data to APIs is now wrapped in DTOs, with internal conversion to maps handled through dedicated .toMap() methods. The FineractClientServiceTest was refactored to use DTOs instead of maps, with test matchers and error message assertions updated to match the new DTO-based signatures and service logic. Most cases were thoroughly tested and covered to ensure reliability and correctness(#PR11).

  • Added the AsciiDoc Maven plugin (asciidoctor-maven-plugin:2.2.1) to the pom.xml and configured it with docs/asciidoc/ as the source directory and docs/generated/ as the output directory. Set up the HTML5 backend with enhanced features for generating documentation. Also introduced a docs/README.md file as a comprehensive guide for writing and maintaining project documentation(PR#13).

Week 4

  • Completed the ClientApi coverage in Fineract-KMP by implementing full and basic client creation, retrieval, update, activation, closure, and deletion (pending only). Added support for client status management, including reject, withdraw, reactivate, undo reject, and undo withdraw. Implemented functionality to assign and unassign staff to clients, update the default savings account, and handle client transfers with operations such as propose, withdraw, reject, accept, and propose-and-accept. Also enabled performing all client operations using external IDs(PR#16).

Week 5

  • This pull request establishes the foundational architecture for the Mifos Workflow service by integrating the Flowable BPMN workflow engine with proper initialization, error handling, and Spring DataSource support, along with a WorkflowEngineFactory for engine management. It introduces a robust authentication layer through FineractAuthService, ensuring all workflow operations are secured, and sets up core BPMN process definitions for client onboarding, transfers, and offboarding with placeholder delegates for future implementations. A centralized GlobalExceptionHandler has been implemented in compliance with RFC 7807 to deliver consistent, structured error responses for validation, business, and runtime errors. The configuration has been enhanced via WorkflowConfig, FineractApiConfig, and application properties to support workflow, authentication, and database settings. The WorkflowService provides high-level workflow operations abstracting engine and authentication details, while basic tests confirm engine and authentication integration(PR#24).

Week 6

  • Introduced robust error handling with new FineractApiException and WorkflowException, ensuring all errors follow the RFC-7807 details format. Added ineractErrorHandler and WorkflowErrorHandler utilities for consistent error extraction, logging, and mapping across the service. Implemented BPMN 2.0 delegates for client onboarding steps including creation, staff assignment, activation, and rejection, with built-in validation and error handling. Expanded core workflow models to track process status, completion, and active process instances, and introduced workflow engine statistics along with process control request models. Refactored Fineract client and authentication services to adopt the new error handling utilities for uniform processing. Enhanced FlowableWorkflowEngine and FlowableMapper for better process management and extensibility, and updated WorkflowService to align with the new engine and mapping logic. Added ClientOnboardingController and AuthenticationController to expose workflow and authentication endpoints, and introduced AuthenticationStatusDTO for standardized authentication responses(PR#25).

  • Updated all tests to expect FineractApiException instead of raw IllegalStateException or RuntimeException, aligning them with the service’s new error-wrapping logic. Each test now validates error messages against those produced by FineractErrorHandler (e.g., “Failed to retrieve closure reasons for resource ClientClosureReason”), ensuring consistency across client and authentication tests. This resolves previous failures caused by the shift to wrapped exceptions and strengthens the test suite with more robust, future-proof error handling(PR#27).

  • Added Docker support with a multi-stage Dockerfile using Maven 3.9.6 and OpenJDK 21 to produce a lean, optimized image. Introduced a full docker-compose.yml setup orchestrating MySQL 8.0 alongside the Spring Boot app, and added a .dockerignore file to exclude unnecessary files for faster builds. Also configured Spring Boot Actuator in application.properties to enable application monitoring and management(PR#28).

Week 7

  • Introduced ClientTransferController to manage the client transfer workflow, with delegates for proposing, accepting, and rejecting transfers, all backed by robust error handling and Fineract integration. Updated DTOs to align with Fineract API requirements by removing unsupported fields and enforcing proper dateFormat and locale. Enhanced the BPMN process to leverage Spring beans and correctly manage assignee variables, while improving error handling and workflow variable management across the transfer lifecycle(PR#33].

  • Added ClientOffboardingController to handle the client offboarding workflow, with delegates for closing accounts, retrieving closure reasons, and verifying client accounts, all integrated with Fineract and backed by robust error handling. Updated DTOs to comply with both Fineract API and workflow requirements, and enhanced the BPMN process to leverage Spring beans with correctly managed assignee variables(PR#36).

Week 8,9

  • Added a comprehensive unit test suite for the Mifos Workflow service, covering controllers, exception handling, workflow engine, and utilities. Controller tests include authentication (AuthenticationControllerTest), client onboarding (ClientOnboardingControllerTest with LocalDate handling), client offboarding (ClientOffboardingControllerTest with exception scenarios), and client transfer (ClientTransferControllerTest with date validation). Enhanced error handling coverage with GlobalExceptionHandlerTest, FineractErrorHandlerTest for HTTP exception scenarios and error body extraction, and reflection-based testing for MethodArgumentNotValidException. Strengthened workflow engine reliability with FlowableWorkflowEngineTest (API mocking), WorkflowEngineFactoryTest (reflection-based init testing), and WorkflowEngineTest to validate the interface contract, including mocked ProcessEngine services and query chains. Also added WorkflowErrorHandlerTest for exception pattern matching, covering both Supplier and Runnable overloads, while verifying error code mappings and exception creation(PR#37).

  • Delivered a complete documentation suite for the Mifos Workflow service. Added an index.adoc home page with project overview, architecture, and a quick start guide; a full api-reference.adoc with REST API documentation and examples; workflow-processes.adoc for detailed BPMN workflow descriptions; deployment-guide.adoc for setup, deployment, and operations; and configuration-reference.adoc as a comprehensive configuration guide. Enhanced the docs with rich visuals, including an architecture diagram, BPMN process diagrams for client onboarding, offboarding, and transfer workflows, Fineract API integration diagrams, and an error handling flow for troubleshooting. All documentation is structured in AsciiDoc with Maven integration via the asciidoctor-maven-plugin, image handling through maven-resources-plugin, and a professional navigation system with cross-document linking(PR#38).

Week 10

  • Introduced LoanOriginationController to manage Mifos X loan origination workflows, with delegates for submitting, approving, and rejecting loan applications, all integrated with Fineract and backed by robust error handling. Added DTOs aligned with Fineract API requirements and updated the BPMN process to leverage these delegates, verified through Flowable Modeler testing. Strengthened the workflow with full error handling and variable management across the loan origination lifecycle(PR#40).

Week 11

  • Added LoanDisbursementController to handle Mifos X loan disbursement workflows, with Flowable delegates for processing disbursement requests and verifying loan status, fully integrated with Fineract and supported by robust error handling. Introduced DTOs aligned with Fineract API requirements and updated the BPMN process to use these delegates, validated through Flowable Modeler testing. Enhanced the workflow with comprehensive error handling and variable management throughout the disbursement lifecycle(PR#41).

  • Introduced LoanCancellationController to manage Mifos X loan cancellation workflows, with Flowable delegates to handle cancellation operations and DTOs aligned with Fineract API requirements. Designed and tested a BPMN 2.0 process model that leverages these delegates, verified through Flowable Modeler for correctness and reliability(PR#44).

  • Introduced a standardized API response wrapper with fields for success, message, optional data, and an ISO timestamp, along with static factory methods for simplified response creation. Updated controller endpoints to return ResponseEntity<ApiResponse<Void>> instead of ResponseEntity<Void>, and aligned all corresponding tests to match. Also fixed the loan disbursement delegate to correctly use the approved amount rather than the transaction amount during the manager review task in the disbursement workflow(PR#45).

Week 12

  • Added a comprehensive unit test suite for all implemented Mifos workflows, covering controllers, services, delegates, utilities, and exceptions. Controller tests validate endpoints across loan, client, and authentication workflows, while service tests mock Fineract API integrations. BPMN delegates are thoroughly tested for execution flow, error handling, and variable management, including staff assignment, client creation, activation, rejection, transfer, closure, account verification, and loan workflows (creation, approval, rejection, disbursement, and status verification). Specific tests such as LoanApprovalDelegateTest (date formatting and note handling), LoanDisbursementDelegateTest (retry logic and error handling), and LoanStatusVerificationDelegateTest (comprehensive loan data validation) ensure robustness of key processes. Utility classes and custom exception handling are also tested to guarantee consistent behavior across the workflow engine(PR#46).

  • Fixed loan cancellation and disbursement tests to align with workflow behavior. Extended WorkflowException to include loan-specific exceptions for more accurate error handling. Cleaned up the ApiResponse wrapper by removing duplicated code and adding Lombok’s @Getter annotation for simplicity and maintainability(PR#47).

  • Documented all remaining functionalities, including loan workflows, and added BPMN 2.0 process model diagrams to the AsciiDoc suite. Updated the README file to reflect the latest features and documentation resources(PR#48).

Future Improvements

  • Implement more additional workflows from Mifos X APIs provided by Fineract-KMP client.
  • Adding retry mechanisms For advanced ainancial workflows.
  • Integrating the module with other Modules when finished like Loan Risk Assessment and Credit Bureau.
  • Integrating the Module with a Web-based tooling for BPMN, DMN and Forms Like BPMN.io.

What I Learned

  • Enhanced my knowledge of Java and Spring Boot.
  • Learned how to work effectively as part of a team.
  • Gained experience in using source control systems (Git, GitHub, and Docker).
  • Understood and dealt with technical debt in practice.
  • Improved my time management skills.
  • Strengthened my communication skills.
  • Deepened my understanding of the microfinance domain.

Acknowledgment

I am deeply grateful to my mentors Ed Cable, Yash Sancheti, and Victor Romero for their invaluable support and guidance throughout this project. They continuously reviewed my work, helped me navigate key technical decisions, and pointed me toward the right concepts and resources whenever I needed help. Their support was both technical and personal, and I truly appreciate the time and effort they dedicated to mentoring me.

I also want to thank the GSoC organizers and admins for their constant support in making this program a smooth and rewarding experience.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment