Overview
Currently, Mifos-X platform is bank staff facing. This feature extension enables end-user Customers to login to view/transact on the accounts and loans they hold. Data visible to Customers will be a sub-set of what Staff can see. Data like account notes and internal approval cycles would not be accessible for the Customers.
Business Requirements
Below requirements are derived from previous discussions and inputs from https://mifosforge.jira.com/wiki/pages/viewpage.action?pageId=72908832
System should be able to add/update/remove customers as portal users
Customers should be able to view details of the Approved Loan Accounts like Loan Details, Repayment Schedule, Charges etc
Customers should be able to view details of the Approved Savings Accounts like Account Summary, Transactions, Charges etc
Customers should be able to transfer funds between their own accounts (not immediate priority)
Customers should be able to transfer funds to others’ accounts (not immediate priority)
Story Breakdown
As an Administrator I should be able to create/update/reset password/deactivate customer login user and associate it to client id so that customer can login to the system and view/transact on their own accounts
As an Administrator I should be able to assign access permissions to the customer login user so that I can control what actions customer login user can perform on the system
As a customer I should be able to validate my username/password credentials with the system so that I can continue invoking APIs to view/transact on my accounts
As a customer I should be able to retrieve my personal details so that I can validate my personal data with the organization
As a customer I should be able to change my password credential so that I can keep my login access secure
As a customer I should be able to retrieve list of my savings accounts details so that I can be aware of my holdings
As a customer I should be able to retrieve transactions related to one of my savings accounts so that I am aware of details of my holdings
As a customer I should be able to retrieve charges related to one of my savings accounts so that I am aware of charges incurred on my transactions
As a customer I should be able to retrieve list of my loan account details so that I can be aware of my commitments/liabilities
As a customer I should be able to retrieve repayment schedule of one of my loan accounts so that I am aware of my commitments/liabilities
As a customer I should be able to retrieve transactions related to one of my loan accounts so that I am aware of details of my holdings
As a customer I should be able to retrieve charges related to one of my loan accounts so that I am aware of charges incurred on my transactions
Critical Design Decisions
Reuse of current services
Keeping ease of maintenance in mind, it is decided that this feature addition should reuse the existing services as much as possible. This will also help in extending new functionalities as well.
Separate endpoint APIs
As suggested by Markus, setting up a separate resource endpoints is the right thing to do for at least one reason. If a MFI wants to ever make a public available web client that allows a customer to deal with his account(s) it is insecure to expose the whole back-office API to the world. With a dedicated API only this endpoint needs to be exposed and it would not be possible to trial the whole system and hack it.
Reuse of existing user login and roles insfrastructure
Since we decided to reuse the existing services, it is imperative that we use the existing user login permission and roles infrastructure. This also helps in reuse of the user activity logging and tracking.
Proper data scoping for customer login
We should build a service that can validate the API requests against the valid data scope assigned to self service user. A self service login user, should be able to view/transact only their loans and savings accounts. Also it should prevent the user from reading certain confidential information like notes and internal approval cycle.
Design
New Screens
Scope of this feature is to provide only platform capability and doesn't include any UI.
Separate root URL for customer self service
New root resource url /mifosng-selfservice would be defined where all the self service APIs would be exposed.
The resources exposed as part of this root would be similar to /mifosng-provider root. For eg, API to get list of loans in self-service would be /mifosng-selfservice/api/v1/loans.
This would be achieved similar to the suggestion provided here http://stackoverflow.com/questions/10231854/multiple-jersey-applications-with-same-path-for-root-resource
Identifying self service user and role permissions
m_appusers table would be modified to add a column 'is_self_service_user to identify a self service API user.
Existing Create/update users APIs would be modified to read/write/update this additional field.
This API would be available only /mifosng-provider root, indicating this is in control of back office/administrative user.
Linking Self Service user to a Client
A new table m_selfserviceuser_client_mapping would be created where one-to-many mapping between app user and client would be provided.
Existing Create/update users APIs would be modified to capture this association in case of self service user.
This API would be available only /mifosng-provider root, indicating this is in control of back office/administrative user.
All the data scoping for self service user would be based on this client mapping.
In future, additional use cases like agent, staff with limited scope can be created with multiple client mapping in this table and they would get access to view/transact on only such clients.
Future extensions to map an user to a group/center/fund etc can also be achieved thru the same mapping table. For eg, periodic batch jobs to keep this mapping automatically updated can be implemented, so that a staff will automatically get visibility of a new client assigned under him, albeit with a little delay.
Differentiation of self service user and back office user Authorisation
A self service user should be able to use only self service APIs and back officer should not have access to self service APIs and vice versa.
Any APIs with root /mifosng-provider should be accessible only for m_appusers whose is_self_service_user attribute is false and Any APIs with root /mifosng-selfservice should be accessible only for m_appusers whose is_self_service_user attribute is true.
Two new AuthenticationProvider classes would be created extending existing default spring DaoAuthenticationProvider one each for /mifosng-provider and /mifosng-selfservice roots. These extensions would additionally check the is_self_service_user attribute and enforce proper authorisation.
New APIs for self service users
| Usecase | API | Notes |
|---|---|---|
| Authentication Basic HTTP | /mifosng-selfservice/api/v1/authentication?username={username}&password={password} | |
| Authentication Oauth2 | /mifosng-selfservice/api/oauth/token?username={username}&password={password}&client_id={clientId}&grant_type={grant_type}&client_secret={client_secret} | |
| /mifosng-selfservice/api/oauth/token?refresh_token={refresh_token}&client_id={clientId}&grant_type={grant_type}&client_secret={client_secret} | ||
| /mifosng-selfservice/api/v1/userdetails?access_token={access_token} | ||
| List Clients | /mifosng-selfservice/api/v1/clients | Return list of clients mapped to given self service app user |
| Retrieve a Client | /mifosng-selfservice/api/v1/clients/{clientId} | Only approved and active clients |
| Retrieve client accounts overview | /mifosng-selfservice/api/v1/clients/{clientId}/accounts | Only approved and active accounts |
| Get client image | /mifosng-selfservice/api/v1/clients/{clientId}/images | |
| List client charges | /mifosng-selfservice/api/v1/clients/{clientId}/charges | |
| Retrieve a client charge | /mifosng-selfservice/api/v1/clients/{clientId}/charges/{clientChargeId} | |
| List client transactions | /mifosng-selfservice/api/v1/clients/{clientId}/transactions | |
| Retrieve a client transaction | /mifosng-selfservice/api/v1/clients/{clientId}/transaction/{transactionId} | |
| Retrieve a Savings Account | /mifosng-selfservice/api/v1/savingsaccounts/{accountId} | Only approved and active account |
| List Savings account transactions | /mifosng-selfservice/api/v1/savingsaccounts/{accountId}/transactions | |
| Retrieve a savings account transaction | /mifosng-selfservice/api/v1/savingsaccounts/{accountId}/transactions/{transactionId} | |
| List Savings account charges | /mifosng-selfservice/savingsaccounts/{accountId}/charges | |
| Retrieve a savings account charge | /mifosng-selfservice/api/v1/savingsaccounts/{accountId}/charges/{savingsAccountChargeId} | |
| Retrieve a Loan | /mifosng-selfservice/api/v1/loans/{loanId} | Only approved and active account |
| List loan account transactions | /mifosng-selfservice/loans/{loanId}/transactions | |
| Retrieve loan account transaction | /mifosng-selfservice/api/v1/loans/{loanId}/transactions/{transactionId} | |
| List loan account charges | /mifosng-selfservice/api/v1/loans/{loanId}/charges | |
| Retrieve a loan account charge | /mifosng-selfservice/api/v1/loans/{loanId}/charges/{chargeId} |
User interaction and design
Exception Handling
Reporting
APIs
Notes
Questions
Below is a list of questions to be addressed as a result of this requirements document:
| Question | Outcome |
|---|---|