GSoC 2018 Proposal

Project: Fineract SMS/Email Notification Microservice.

Applicant: Ebenezer Kwesi Akyen Graham

Abstract

This project is a new feature request for the Apache Fineract CN. The SMS/Email Notifications service would be a microservice developed on Apache Fineract CN to enable MFI members to get notified on events occurring on their accounts.

...

This problem has led to the need for a microservice such as this one to be developed to  enable MFI staff members to select notifications which need to be sent or the member chooses choose specific events during account creation.

Project Goals

1. Develop a SMS/Email notification mircroservice

2. Incorporate the microservice into a demo-server

3. Incorporate the Notification user interface into the fims-web-app

1. Interface Includes an interface for microservice configuration

2. Interface Includes an interface to select frequency for members

3. Interface Includes an interface to subscribe members to specific events

Proposed Solution

When an event occurs, the system knows the subscribers to notify and now the notification itself has to be generated. An event listener listening to the rest API controller event, will then create an instance of the corresponding mircroservice interact with it .hence creating a notification

NB: each mircroservice will have a corresponding listener listening to it event emitters. For instance, AccountingListener, OrganisationListener etc

...

The messages are now formatted using a template associated to a topican event.

The prepared messages will be passed to the application containing email gateway such as google’s SMTP server or Twilio SMS to be transmitted. I propose that the system allows multiple configurations to accommodate cases where the application supports multiple organisations who use different services.

Subsystems Breakdown

EventListener

An event listener will listen for EventEmitters generated. For instance for a new client creation the NotificationEventListener will capture the event emittered and generate the notification content

• NotificationEventListener

• Has microservice instance

• Has a JmsListener to listen to emitted event

• Has an SMSGateway/EmailGateway Object

• Creates a NotificationMapper

• Creates a recipient and their notification

• Localize the message using subscriber preference

• Sends the email or SMS

Domain

This package will define the class for the entities in the problem domain.

• Notification

• States the Recipient

• states the action

• states the content

• NotificationMapper

• Takes topic mapping and map notifications to subscribers

• NotificationMapperRepository

• Accumulate NotificationMappings

Configuration

This will be used to configure the behaviour of the system. This will be used to help scale the transmission of notifications in a day where more notifications are going out. (for instance an organisation with multiple gateways can scale in high)

Also, in a case where the Application support multiple MFI each MFI can get their own notification

• NotificationConfiguration

• Has SMSConfiguration

• Has EmailConfiguration

• SMSConfiguration

• Defines accountSID

• Defines auth Id

• EmailConfiguration

• Defines and sets mail service host

• Defines and sets mail service ports

• Defines and sets authentication credentials

SMSService

Use the Twilio SMS service and google SMTP Server

• Has Senders number

• Has reciepent number

• Retrieves organisation’s sms API configuration

• Message content

EmailService

• recipient addresses

• Sender’s address

• Authenticate email gateway

• Mail content

...

This component will use the template component to form the message format. The template will abstract the various message formats. I believe using Apache Velocity to prepare default themes and allow the user to generate custom templates woube be a good consideration. Also, given that Fineract CN and Velocity [ http://velocity.apache.org/  ] share the same license it will be easier to use them

Template

• SMS templates

• Email Templates

Event Listeners

This tentative document identifies and shortlists events which will be considered for the notification service. Under each microservice, is a list of events and each event will have a corresponding email and SMS message. Likewise, each event will have a default message and recipient associated with it.

Default Message: This is the default message which will be sent when that event occurs if no customized template has defined.

Default Recipient(s): This is the default recipient(s) who will receive the notification when the event occurs.

PS: The message samples listed are for demo purposes.

Identity Service: IdentityEventListener.java

Event: onCreateUser

Default Message: 

Dear {{Name}},

This is to notify you that you account has been created.

Below are your MFI account  details.

{{login address}}

{{password}}

Yours Sincerely

{{MFI}} team.

Default Recipient(s): Customer

Event: onChangeUserRole

Event: onChangeUserPassword

Event:  onAuthentication

Office Service: OfficeEventListener.java

Event: onCreateEmployee

Default Message: 

Dear {{Name}},

This is to notify you that you account has been created.

Below are your MFI account details.

{{login address}}

{{password}}

Use this link to login to your account.

{{endpoint}}

Yours Sincerely

{{MFI}} team.

Default Recipient(s): Staff member

Event: onUpdateEmployee

Event: onDeleteEmployee

Event: onSetContactDetail

Event: onDeleteContactDetail

Event: onCreateOffice

Event: onDeleteOffice

Event: onUpdateOffice

Customer Service:

Event: customerCreatedEvent()

Default Message: 

Dear {{Customer Name}},

Your account with {{MFI}}  has been successfully created at {{Office}}.

Thanks

Default Recipient(s): Customer

Event: customerUpdatedEvents

Event: customerActivatedEvent

Event: customerLockedEvent()

Event: customerUnlockedEvent()

Event: customerClosedEvent()

Event: customerReopenedEvent()

Event: addressChangedEvent()

Event: contactDetailsChangedEvent

[Suggestion]

Please share your opinion on whether a listener should be defined  IdentificationCard and protrait related events. For instance identificationCardScanDeleteEvent or portraitPutEvent and portraitDeleteEvent

Accounting Service:

Event: onCreateAccount

Event: onChangeAccount

Event: onCloseAccount

Event: onLockAccount

Event: onUnlockAccount

Event: onReopenAccount

Event: onDeleteAccount

Portfolio Service:

Event: onDeny

Event: onApprove

Event: onDisburse

Event: onAcceptPayment

Event: onCheckLate

Event: onMarkLate

Event: onMarkInArrears

Event: onWriteOff

Event: onClose

Event: onRecover

Event: onCreateProduct

Event: onChangeProduct

Event: onDeleteProduct

Event: onEnableProduct

Event: onGroupCreated

Event: onGroupActivated

Event: onGroupUpdated

Deposit Service:

onAccrual

onDividendDistribution

Teller Service:

Event: onCreate

Event: onChange

Event: onOpen

Event: onClose

Event: onAuthenticate

Event: onPause

Event: confirmTransaction

Event: onDeleteTeller

Event: onSaveDenomination

Cheque Service:

Event: onIssueCheques

Event: onChequeTransaction

Event: onChequeApproved

Event: onChequeCanceled

Payroll Service:

Event: onPostCollection

Reporting Service:

No listener will be implemented for the reporting microservice on less stated otherwise.

Web Interface

• An interface to configure SMS and email frequency

• An interface to configure organisation(s) SMS API

• An interface to configure organisation(s) Email Gateway

Database Structure

Entity 1: Subscriber

• Id

• communication_preference

• language_preference

• high_priorities

• medium_priorities

• low priorities

Entity 2: SMSConfigurations

• Id

• organisation

• auth_token

• accountid

• option

Entity 3: EmailConfigurations

• Id

• organisation

• auth_token

• auth_secret

• port

• host

• option