Self Service Portal (Client-Level APIs)

Owned by Vishwas Babu A J
Last updated: Aug 31, 2015 by Ed Cable

 Raw meeting notes which led to the creation of this wiki at https://docs.google.com/a/confluxtechnologies.com/document/d/1cLDTmCF0N8RwJBx2Uh6xUncHTcuYrY3LOWvzMMX0QUg/edit# .What started off as a discussion on Pay go sol module has now extended to a a variety of use cases (involving agent-partner networks, need to provide restricted & hierarchical data scope to such external partners, simplification of relationships between staff and users etc...)

Overview

An agent for the pay as you go Solar Module is modeled as an MFI staff with limited permissions, i.e he would only be allowed limited access to staff roles including the ability to create new Clients and opening Pay-go-sol (a savings/current account) accounts for the client.

Building out this functionality would require a minor enhancements to Staff API's wherein we would want to add the ability to tag a staff as a Agent for reporting purposes

Additionally, the Agent would have a savings account with the MFI which would be used for accepting payments from Customers. So the agent would accept physical cash from the customer and make a transfer of the equivalent amount from his current account to the customers current account.

For this bit of the agent functionality, we intend to add the ability of creating a "Client" account for a staff and build out and leverage a generic Client self service portal.

Client Self Service Portal

A Client account is created for every Agent. As a Client, the agent has the ability to

  • View their own loan or savings account details

  • Transfer funds within their own accounts

  • Transfer funds to another account.

We would expect the bank to want to setup permissions for the Client portal (some client would only have the ability to view their loan and savings data, some may be allowed to do account transfers)

It would also be helpful to have the ability to "turn on/off" the Client self service portal from an MFI perspective

We would also want to clearly demarcate the Client portal permissions from the back office permissions as in the only allowed permissions for a client are those listed above, a bank can not (even accidentally) associate any other permissions with a Client

Finally, we would expect that all account data is not safe for Client viewing (in the context of a loan, the client should have access to his basic loan data for only active and closed loans, we might not want to For ex: show loan notes to a customer or the internal approval cycles etc for other loan applications for a client). We also recognize that the Client portal API's would need to evolve independent of the back office API. 

New API's

We would expose a new root resource for Client portal wrapper API's from the existing MifosX codebase, say mifosng-provider/client-portal/api/v1 and expose wrappers for those API's which make sense from a Client perspective. This would help logically separate the Client portal API's from the back office API's

This can be done similar to http://stackoverflow.com/questions/10231854/multiple-jersey-applications-with-same-path-for-root-resource 

  1. View Savings Wrapper (/savings) : Returns all savings accounts of the logged in Client (might want to filter out accounts which are not yet active)
  2. View Loans Wrapper (/loans): Returns all loan accounts of the logged in Client after stripping notes and accounts which are not yet approved (might want to filter out accounts which are not yet active))
  3. Account Transfer Wrapper (/accounttransfer): Adds the ability to transfer funds from any of the Clients savings accounts to any other savings account 


Modifications to Existing API's

  1. Client Creation API (https://demo.openmf.org/api-docs/apiLive.htm#clients_create) should allow providing Client portal access ( and capture relevant fields like username, allowed roles etc)
  2. Client Edit API's () should allow toggling portal access and editing roles
  3. List / View Client API's () should also return portal access details of a customer
  4. Permissions API (https://demo.openmf.org/api-docs/apiLive.htm#permissions_list) should return only back office permissions by default. An optional query parameter "type"  (all/employee/customer) could be used to return specific subsets of permissions
  5. Roles API (https://demo.openmf.org/api-docs/apiLive.htm#roles_list) should only return back office roles by default. An optional query parameter "type"  (all/employee/customer) could be used to return specific subsets of roles
  6. Create Roles API () would also allow an organization to create Client portal specific roles by grouping together Client portal specific permissions. Validations to this API would ensure that non Client portal roles do not have 

Database changes

  1. m_permission table to capture a flag for tagging a permission as a Client portal permission

New Permissions / look-up data

  1. New row in c_configuration (client_portal) for enabling and disabling organization wide access to the Client portal 
  2. Permissions for  new Client portal API's

 

 

Staff has a Client account

It is fairly common for MFI's to provide savings/loans to their employees. However, the accounts related to employees usually have a different set of permissions.

We would need the ability to create a client account for a staff and introduce  a new set of update permissions for acting on loan/savings accounts belonging to Staff. This permission is checked for on all update operations related to any employee account, and helps prevent fraud on Employee accounts

Modifications to Existing API's

  1. Client Creation API (https://demo.openmf.org/api-docs/apiLive.htm#clients_create) and updation API's should allow identifying a Client account as that belonging to a Staff


Database changes

  1. Add a field in the client table for linking Client to a staff account
  2. Add a new set of permissions in m_permission table for update access to employee loans/savings/FD and RD  What is FD and RD?

New Permissions / look-up data

  1. New set of Permissions for all Employee loan/savings/FD and RD accounts. 

 

Staff Extensions (to a superset tentatively termed "Associates")

We would want to reuse staff to represent any back office entity (Bank Employees, partners & agents, funders etc). To avoid confusion, let's refer to the existing Staff API's as "associates" 

  • Extend the staff api to add the ability of associating classification discriminators for associates. Organizations should be able to define their own classifications for associates Ex: Employee,  Agent, partner, funding Partner and report on them intelligently.
  • We should also extend the data tables functionality to allow linking specific data tables to associates based on the classification
  • We should be able to specify data scoping (either branch: the default wherein the user has access to the entire branch he is linked to, or restricted: where he has scope only on those centers/groups/clients/loans/savings to which he is directly linked) on a per classification basis.
  • Organizations should also be able to define hierarchies of associates so that data scope of a Managing associate includes those of all the associates he manages (would be helpful in case of Partner/Agent models where the agents belong to the particular partner)
  • Allow linking multiple associates to a particular account (center/group/client/loan/savings). For Ex: We would want to link a Loan officer to a center so that he has data scope on the same, also if the loan for an entire center is sponsored by an external "Partner", say "Kiva", I would also be able to link the Kiva partner to the said center so that they could have data scope on the loans given out by them
  • Encapsulate create User A

Associate Classification and Data Tables


Associate Classification and Linked Data scoping


Associate Hierarchy and Data scoping


Associate and Center/Group/Client/Loan/Savings linkages


Discussions

Q) How many types of system users do you recognize?

Just two

  • Clients : Customers with read access on their accounts and the ability to make account transfers
  • Associates (for the lack of a better term) : Back office users. Any actors from the bank, or those acting on behalf of the bank ( encapsulates Staff, agents , partners, extension counter networks, funders who want visibility on loans funded by them etc) who could use the entire suite of API's provided they have the appropriate data scope and necessary roles/permissions

Q) I don't see any use of introducing Classification for associates? Can't we associate data scope directly to roles?

We allow attaching multiple roles for a user. Adding data scope to roles brings in additional complexity as a user can be assigned multiple roles each with different data scopes. So we suggest the approach of associating a data scope directly against the Associate classification

Also, data scope only makes sense to an Associate user (we currently do not see the need of data scopes for Client users)

These classification would also be used to attach appropriate data tables to Associates ( The data we would want to capture for different types of associates like staff/ partner / agent etc would be different)

Q)  Are you adding complexity by creating a new Entity called "Associates"

No, we are not. We are only extending the existing staff entity

Q) My requirement is to have a network of Agents. We want the Organization managing these agents (our partner) to have data scope on all loans managed by their Agents so that they can calculate commission for their agents etc

The design proposes adding a hierarchy for Associates. Parents would have visibility on the data scope of their children.

So, you would create an Associate discriminated as "Partner" and have all the employees (agents) of the the particular partner created as Associates (maybe discriminated as an "agent") with their parent set to the Partner.

Q) I do not like / understand how users and staff are currently modeled in MifosX

We originally had only users and API's for creating/editing users. All a user has is a first name, last-name and and email address. A user has complete data scope on the branch he is created in.

Roles and permissions are used to determine the kind of activity he can perform on this data scope.

The Staff entity was added in later and was used only for lookup purposes in the application (the ability to associate a staff to a user was added in only a couple of releases ago). Currently this association has no affect on the data scope

Q) How do you see Staff and users working in the future ?

We would expect that the Staff API's (which we refer to as associates in this wiki) encapsulate user creation.

So a client app developer would use the associates API to create an associate and optionally provide him with access to the system. Similarly the update associate API's could be used for changing the credentials for accessing the system

This means that we would no longer be using the User's API .

However, their would be no changes to the existing schema (only the API entry points change) i.e both Staff and the associated user would still sit in different tables and the firstname/lastname /email address of the User table would be populated based on the parameters passed into the associates API

Q) I am concerned that such encapsulation would result in cryptic errors due to constraints on the user table. For ex: A Client creation could throw an error if a Staff user with the same name is present etc and maybe very difficult for the end user to comprehend the root cause

Ideally the API should return a clear message saying "A client user with the current login already exists etc". So we should not run into any such issues

Also, the existing users API would only be modified to return only Staff users by default. By passing a query parameter to it we can retrieve either/both the staff and Client user so the UI for viewing any system users should still provide all the information a system admin would need

Q) I would suggest that all foreign keys point to the user table instead of the staff and Client table

This is currently not a part of our plan as all Associates/clients need not be users of the system. We can have some associates meant solely for lookup purposes like a Client relationship manager etc 

Q) There would be issues with managing firstname /lastname/ email address consistency across Client/Associates and User tables

We could always query these fields directly from the linked staff and client table

If the concern is about having unnecessary joins, we could make it the responsibility of the Client and Associates API to ensure any changes to firstname, lastname and email address are propagated to the User linked to the same.

An Associate transfer would also mean that the "Office" of the linked user would change etc.

Q) The changes suggested seem complex, we are deviating from the simplicity of the existing security (roles/permissions) architecture

The roles and permissions module is reused as is and there are no major changes suggested to the existing security infrastructure. All we are really adding is configurable data scoping for Associates and a separate set of wrapper API's built specifically for Client consumption

Q) We should then completely remove the Users API, shouldn't we?

We do not know, there might be some use cases where this API could still be used. Those who do not wish to use it can simply disable the User related API's (by not giving anybody the permission to access them)

and we can continue to have the API for backward compatibility.

Q) What if I need a Client self service portal where a Client can create a savings account for himself etc?

We have not thought through such scenarios. How would they work? Would a Client be able to to view all savings product in the system and  decide the account he wants to open? Would we have only a subset of Savings products which a Client can directly apply for ? Wouldn't we need a different lifecycle for such scenarios (Or would a application created by a client show up directly in the system)?  

It would be good to revisit the design once we have more such use cases listed down

Q) Hmm, so for the "pay as you go solar" agent (which was the original goal of this design). We would have a row for the agent in three tables! As a client, an associate and a user? Isn't this definitely one row too many?

The original intention was to make it worse! We would have four rows

  • An associate account and resulting access to the core mifosx portal: He would use this login for performing his "staff" like duties including creating customers, doing KYC for them (or playing any other role the organization sees fit)
  • A client account and access to the client portal: He would use this account to perform account transfers from his savings account to clients savings account etc

The reason for this separation is that the client account may outlast the Associate account, the agent would still have access to the client self service portal even if he is no longer a staff (deactivating an associate would immediately turn of the associate user). There is no reason to show this disjoint behaviour on a mobile app though (smile) . Here we could simply capture a separate user name and password for enabling account transfers.

If this is over engineered, then there is no real harm /extra effort in having a single user account for the agent too (the api restrictions would still be in place, so he would not be able to act on his own accounts using the core loan/savings api, but would only be able to do account transfers using the client portal account transfers API)