FINERACT-1783: Customizeable LoanRepaymentScheduleTransactionProcessor
This commit is contained in:
Aleksandar Vidakovic
committed by
Aleksandar Vidakovic
Aleksandar Vidakovic
parent
f2756b25bb
commit
fc895fce05
@@ -1,91 +1,5 @@
|
||||
= Modules
|
||||
|
||||
NOTE: Currently modules are a proof of concept feature in Fineract.
|
||||
We are currently working towards a fully modular codebase and will publish more here when we are ready.
|
||||
|
||||
== Custom modules
|
||||
|
||||
Creating customizations for Fineract services is easy. The method described here will work both with our future module guidelines (aka "clean room" modules) and with the intermediary solution we will put in place to avoid major refactorings.
|
||||
|
||||
The folder structure for modules is based on a convention that ensures that your extensions don't clash with Fineract's internals. This is to make sure that your downstream forks of Fineract are easy to sync. In the past we had all kinds of strategies to add custom code - including editing existing sources in `fineract-provider`. This is not recommended.
|
||||
|
||||
IMPORTANT: At the moment the only service(s) we prepared to be overridden/replaced are `org.apache.fineract.portfolio.note.service.NoteReadPlatformService` and `org.apache.fineract.portfolio.note.service.NoteWritePlatformService`. Please reach out on the developer mailing list if you need other services.
|
||||
|
||||
The recommended folder structure is very simple. If you follow this recommendation you'll get some additional benefits, e. g. you don't even have to edit `settings.gradle` to include your new custom modules. Your modules will also be automatically included in a custom Fineract Docker image build that you can use for your production deployments.
|
||||
|
||||
Let's assume your company/org is called "ACME Inc." and you are trying to (fully/partially) replace an existing Fineract service, let's say those in `org.apache.fineract.portfolio.note`. The recommended folder structure would then look something like this:
|
||||
|
||||
[plantuml, format=svg]
|
||||
----
|
||||
include::{diagramsdir}/custom-folder-structure.puml[]
|
||||
----
|
||||
|
||||
As soon as we can publish Fineract module JARs to Maven Central you'll have more freedom to setup your projects (including to setup separate Git repos). But for now please follow these instructions:
|
||||
|
||||
1. Create a folder under `custom` and name it according to your company/organisation (e. g. `acme` if your company is `ACME Inc.`); this way your custom modules can't clash even with other companies' modules
|
||||
2. Under your company folder create a folder for the `category` or `domain` your module is targeting; e. g. "loan", "client", "account" etc.
|
||||
3. Finally, setup `library` folders for the actual modules you want to create; usually that will be to replace/extend some existing service, so there could be a `service` folder, maybe even a `core` folder, e. g. if you want to add additional DTOs etc.; we have also an example for COB business steps
|
||||
4. Per `category`/`domain` you should have a `starter` library; means: a Spring Boot auto-configuration setup that makes including your module in Fineract easier ("hands-free"); the necessary parts for a auto-configuration library are a Spring Java configuration class (annotated with `@Configuration`) and a text file at `META-INF/spring.factories` in your starter resource folder:
|
||||
+
|
||||
[source,properties]
|
||||
----
|
||||
include::{rootdir}/custom/acme/note/starter/src/main/resources/META-INF/spring.factories[]
|
||||
----
|
||||
+
|
||||
Please make sure that your module libraries have proper `build.gradle` files:
|
||||
+
|
||||
[source,groovy]
|
||||
----
|
||||
include::{rootdir}/custom/acme/note/service/build.gradle[lines=19..]
|
||||
----
|
||||
+
|
||||
NOTE: You don't need to edit `settings.gradle` to add your modules/libraries. If you follow above convention they'll get included automatically.
|
||||
+
|
||||
5. The dependency.gradle file could look something like this:
|
||||
[source,groovy]
|
||||
----
|
||||
include::{rootdir}/custom/acme/note/service/dependencies.gradle[lines=19..]
|
||||
----
|
||||
|
||||
NOTE: We've included by default some basic and useful dependencies for all custom modules, like Slf4j, Lombok, the usual testing frameworks (JUnit, Cucumber, Mockito etc.)
|
||||
|
||||
IMPORTANT: Do not include your custom module in `fineract-provider`'s dependency.gradle file. This creates a circular dependency and will fail your build.
|
||||
|
||||
=== Database Migrations
|
||||
|
||||
If database migrations are needed as part of your customizations then you can add your own migration scripts. This is again based on conventions:
|
||||
|
||||
1. Create folders `db/custom-changelog` in one of your `resources` folders; we recommend using the resources folder in your starter library, but actually any of your custom libs will do.
|
||||
2. Under `db/custom-changelog` create an XML changelog file, e. g. `changelog-acme-note.xml`; you are free to choose a name for this file, but we recommend being consistent to avoid classpath conflicts.
|
||||
3. Under `db/custom-changelog` create a folder `parts` for your specific changelogs
|
||||
|
||||
[plantuml, format=svg]
|
||||
----
|
||||
include::{diagramsdir}/custom-db-migration-folder-structure.puml[]
|
||||
----
|
||||
|
||||
And here an example migration script:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
include::{rootdir}/custom/acme/note/starter/src/main/resources/db/custom-changelog/0001_acme_note_initial.xml[lines=22..]
|
||||
----
|
||||
|
||||
IMPORTANT: By default custom database migration changelogs are executed in context `tenant_db`. That makes sure your changes will be applied to the tenant database (read: main database and not the tenant store database). In theory you could also target the tenant configuration database, but it's not recommended to do that.
|
||||
|
||||
=== Deployment
|
||||
|
||||
Custom modules (better: the JAR files) only need to be dropped in Fineract's `libs` folder if you run Fineract from the Spring Boot JAR file. Dynamic loading of external JARs is provided since Fineract version 1.5.0. For your convenience we've created a separate Docker image module that automatically includes your custom modules (see `custom/docker`). You can build this Docker image with
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
./gradlew :custom:docker:jibDockerBuild
|
||||
----
|
||||
|
||||
The Docker image with included custom modules is called `fineract-custom`.
|
||||
|
||||
NOTE: We'll provide soon a way to customize the Docker image parameters (image name, JVM implementation, JVM args, ports etc.).
|
||||
|
||||
|
||||
=== Outlook
|
||||
|
||||
If this *proof of concept* is accepted we could prepare Fineract's services to be replaceable. This approach works already very well even if we don't have proper JAR libraries published on Maven Central. It's an important goal to separate customized code from Fineract's internals to have soon real modules.
|
||||
NOTE: Even if we are not quite there yet with full modularity you can already create your own custom modules to extend Fineract. Please see chapter <<_custom_modules>>.
|
||||
Reference in New Issue
Block a user