Target release	15.12
Epic	Customer Self Service Portal
Document status	DRAFT
Document owner	Adi Raju
Designer	Adi Raju
Developers	Adi Raju
QA	SSN

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 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. This can be done in two ways: A) use Spring's RestTemplate and act like a client, or B) inject needed resources in the code. Option B is chosen to help reuse user activity logging and tracking.

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

Scope of this feature is to provide only platform capability and doesn't include any UI.

Separate URL endpoints for customer self service

All the APIs resources for customer self service would start with /mifosng-provider/api/v1/self.

Having separate root context for this API comes with lot of complications. It would require changes at tomcat deployment level.

Identifying self service user

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 for 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 API with URL containing /self/ 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 for URLs with /self/ and one for existing APIs. These extensions would additionally check the is_self_service_user attribute and enforce proper authorisation.

Self Service User Role permissions

Existing Role permission APIs would be used. Due to differentiation of self service and back office user authorisation as explained above, a self service user will not have access to any APIs other than those exposed for self service channel.

New APIs for self service users

To start with, all the APIs exposed would support only GET methods. And data scope would be limited to clients association mapping to the user.

Usecase	API
Authentication Basic HTTP	/mifosng-provider/api/v1/self/authentication?username={username}&password={password}
Authentication Oauth2	/mifosng-provider/api/self/oauth/token?username={username}&password={password}&client_id={clientId}&grant_type={grant_type}&client_secret={client_secret}
	/mifosng-provider/api/self/oauth/token?refresh_token={refresh_token}&client_id={clientId}&grant_type={grant_type}&client_secret={client_secret}
	/mifosng-provider/api/v1/self/userdetails?access_token={access_token}
List Clients	/mifosng-provider/api/v1/self/clients
Retrieve a Client	/mifosng-provider/api/v1/self/clients/{clientId}
Retrieve client accounts overview	/mifosng-provider/api/v1/self/clients/{clientId}/accounts
Get client image	/mifosng-provider/api/v1/self/clients/{clientId}/images
List client charges	/mifosng-provider/api/v1/self/clients/{clientId}/charges
Retrieve a client charge	/mifosng-provider/api/v1/self/clients/{clientId}/charges/{clientChargeId}
List client transactions	/mifosng-provider/api/v1/self/clients/{clientId}/transactions
Retrieve a client transaction	/mifosng-provider/api/v1/self/clients/{clientId}/transaction/{transactionId}
Retrieve a Savings Account	/mifosng-provider/api/v1/self/savingsaccounts/{accountId}
List Savings account transactions	/mifosng-provider/api/v1/self/savingsaccounts/{accountId}/transactions
Retrieve a savings account transaction	/mifosng-provider/api/v1/self/savingsaccounts/{accountId}/transactions/{transactionId}
List Savings account charges	/mifosng-provider/api/v1/self/savingsaccounts/{accountId}/charges
Retrieve a savings account charge	/mifosng-provider/api/v1/self/savingsaccounts/{accountId}/charges/{savingsAccountChargeId}
Retrieve a Loan	/mifosng-provider/api/v1/self/loans/{loanId}
List loan account transactions	/mifosng-provider/api/v1/self/loans/{loanId}/transactions
Retrieve loan account transaction	/mifosng-provider/api/v1/self/loans/{loanId}/transactions/{transactionId}
List loan account charges	/mifosng-provider/api/v1/self/loans/{loanId}/charges
Retrieve a loan account charge	/mifosng-selfservice/api/v1/loans/{loanId}/charges/{chargeId}

Data scoping self service API

A new service would be written to validate the request parameters against the Data scope for the given user. Parameters for each API would be validated for client id, loan id, account id, additional parameter requests etc. On invalid requests appropriate AuthenticationException would be thrown.

Role permissions verification would be taken care by the existing service implementations.

Notes

On this feature deployment, all the existing users will be marked as non-self service user.

Questions

Below is a list of questions to be addressed as a result of this requirements document:

Question	Outcome

Out of Scope

Transfers within/outside client accounts are not considered yet.

Browser not supported