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...)
| Table of Contents |
|---|
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.
...
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.
...
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
...
- View Savings Wrapper (/savings) : Returns all savings accounts of the logged in Client (might want to filter out accounts which are not yet active)
- 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))
- 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
- 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)
- Client Edit API's () should allow toggling portal access and editing roles
- List / View Client API's () should also return portal access details of a customer
- 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
- 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
- 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
- m_permission table to capture a flag for tagging a permission as a Client portal permission
New Permissions / look-up data
- New row in c_configuration (client_portal) for enabling and disabling organization wide access to the Client portal
- 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
- 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
- Add a field in the client table for linking Client to a staff account
- 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
- 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
...
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.
...
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.
...
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
...
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
...