How to Add New UserType and SubType(Roles) in Sunbird

[vinod303]

User Types & SubTypes In Sunbird
When a new instance of SB is created, the default User Types available are Parent, Teacher, Students etc.. But, as an adopter you can create your own userTypes/Subtypes as per your requirement/domain.

This document will show the steps to create custom user types & Subtypes as per your requirement.

Example SCENARIO.
Assume that your new SB installation is in the domain of Agriculture and
you want to create and display Farmer, Front Line Extension Workers(FLEW), KVK Admin (KVK = Krushi Vigyan Kendra) as new User Types and to be displayed in the User Profile Screen instead of the default Teacher,Student , Parent etc..
And , all the users in the state of Assam, when they select “Front Line Workers” as a userType , they should also get to see two SubTypes/Subroles called ATM(Assistant Technology Manager) and BTM(Block Technology Manager).

STEP 1 : CREATE A NEW USER TYPE USING THE FORM CREATE API
Sunbird gives the flexibility to create new user types using its form creation APIs

curl --location '{{URL}}/api/data/v1/form/create' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{API_TOKEN}}' \ --data '{ "request": { "type": "config", "action": "get", "subType": "userType", "rootOrgId": "*", "component": "portal", "data": { "action": "get", "fields": [ { "index": 0, "code": "flew", "name": "Front Line Extension Workers", "searchFilter": [], "image": "guest-img1.svg", "visibility": true, "label": "frmelmnts.lbl.flew" }, { "index": 1, "code": "farmer", "name": "Farmer", "searchFilter": [], "image": "guest-img3.svg", "visibility": true, "label": "frmelmnts.lbl.farmer" }, { "index": 2, "code": "kvkadmin", "name": "KVK / Dept Admin", "searchFilter": [], "image": "guest-img3.svg", "visibility": true, "label": "frmelmnts.lbl.kvkadmin" }, { "index": 3, "code": "other", "name": "Other Users", "searchFilter": [], "image": "guest-img3.svg", "visibility": true, "label": "frmelmnts.lbl.other" } ], "templateName": "userType" } } }'
STEP 2: UPDATE THE profileConfig_v2 form to configure UserType and Subtype.
Creating/Updating profileConfig_v2 form is required, to display the newly created roles in the profile form. ie. When the user selects / clicks on Profile and selects “Edit” , profileCongif_v2 form is what is loaded with the userTypes and Subtypes values.

curl --location '{URL}/api/data/v1/form/update' \ --header 'Authorization: Bearer {API_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "request": { "type": "profileConfig_v2", "action": "get", "subType": "18", "rootOrgId": "*", "component": "*", "data": { "templateName": "profileconfig_v2", "action": "get", "fields": [ { "code": "name", "type": "input", "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "Name" } }, "hidden": true, "placeHolder": "Enter Name", "multiple": false }, "validations": [ { "type": "required" } ] }, { "code": "persona", "type": "nested_select", "templateOptions": { "hidden": true, "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "Role" } }, "placeHolder": "Select Persona", "multiple": false, "dataSrc": { "marker": "SUPPORTED_PERSONA_LIST" } }, "validations": [ { "type": "required" } ], "children": { "farmer": [ { "code": "state", "type": "select", "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "State" } }, "placeHolder": "Select State", "multiple": false, "dataSrc": { "marker": "STATE_LOCATION_LIST", "params": { "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "subPersona", "type": "select", "default": null, "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "Subrole" } }, "placeHolder": "Select Subrole", "multiple": true, "dataSrc": { "marker": "SUBPERSONA_LIST", "params": { "useCase": "SIGNEDIN" } }, "options": [] }, "validations": [ { "type": "required" } ] }, { "code": "district", "type": "select", "context": "state", "default": null, "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "District" } }, "placeHolder": "Select District", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "district", "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "block", "type": "select", "context": "district", "default": null, "templateOptions": { "label": "Block", "placeHolder": "Select Block", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "block", "useCase": "SIGNEDIN" } } }, "validations": [] } ], "flew": [ { "code": "state", "type": "select", "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "State" } }, "placeHolder": "Select State", "multiple": false, "dataSrc": { "marker": "STATE_LOCATION_LIST", "params": { "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "subPersona", "type": "select", "default": null, "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "Subrole" } }, "placeHolder": "Select Subrole", "multiple": true, "dataSrc": { "marker": "SUBPERSONA_LIST", "params": { "useCase": "SIGNEDIN" } }, "options": [ { "value": "atm", "label": "ATM" }, { "value": "btm", "label": "BTM" } ] }, "validations": [ { "type": "required" } ] }, { "code": "district", "type": "select", "context": "state", "default": null, "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "District" } }, "placeHolder": "Select District", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "district", "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "block", "type": "select", "context": "district", "default": null, "templateOptions": { "label": "Block", "placeHolder": "Select Block", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "block", "useCase": "SIGNEDIN" } } }, "validations": [] } ], "kvkadmin": [ { "code": "state", "type": "select", "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "State" } }, "placeHolder": "Select State", "multiple": false, "dataSrc": { "marker": "STATE_LOCATION_LIST", "params": { "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "district", "type": "select", "context": "state", "default": null, "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "District" } }, "placeHolder": "Select District", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "district", "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "block", "type": "select", "context": "district", "default": null, "templateOptions": { "label": "Block", "placeHolder": "Select Block", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "block", "useCase": "SIGNEDIN" } } }, "validations": [] } ], "other": [ { "code": "state", "type": "select", "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "State" } }, "placeHolder": "Select State", "multiple": false, "dataSrc": { "marker": "STATE_LOCATION_LIST", "params": { "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "district", "type": "select", "context": "state", "default": null, "templateOptions": { "labelHtml": { "contents": "<span>$0&nbsp;<span class=\"required-asterisk\">*</span></span>", "values": { "$0": "District" } }, "placeHolder": "Select District", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "district", "useCase": "SIGNEDIN_GUEST" } } }, "validations": [ { "type": "required" } ] }, { "code": "block", "type": "select", "context": "district", "default": null, "templateOptions": { "label": "Block", "placeHolder": "Select Block", "multiple": false, "dataSrc": { "marker": "LOCATION_LIST", "params": { "id": "block", "useCase": "SIGNEDIN" } } }, "validations": [] } ] } } ] } } }'
Note:
In the above curl
_1. subType: ”18” : It is the location code for the state “Assam”. The location for a state can be found using the location search api.
By passing this location code, we are telling the system that, this configuration will reflect only for the state “Assam”, ie. when the user selects ASSAM in the state down.

2. “Children” : This object will have an array for each of the userTypes.

3. “subPersona” : This is where you define the “subType” values. Ie. in this case, when the user select “FLEW” , a
   “SUB ROLE” option is enabled which displays a list of “subrole”

4. And the Subroles are defined within the “options” array within each userTypes._

Once the above configuration is done, when a user logs in, and go to his profile and click on Edit, and when he selects STATE as “Assam”, and ROLE as “FLEW”, he will see SUBROLE as “ATM” or “BTM”.

Please note that, since we set this configuration for the state “Assam”(subType: ”18), when the user selects any other states , they will NOT see the “subrole” option/values.

FAQs
Can we have different values in the SUBROLE for different user Types?
Yes, you can set the different subrole values for different user types. You need to define those in the “subPersona” sections for each of the userTypes.

How do I find the location code for each of the states?

curl --location '{URL}/api/data/v1/location/search' \ --header 'Content-Type: application/json' \ --header 'x-authenticated-user-token: {USER_TOKEN}' \ --header 'Authorization: Bearer {API_KEY}' \ --data '{ "request": { "filters": { "type": "state" }, "sort_by": { "code": "asc" }, "limit": 5000 } }'
@rhwarrier @Jayaprakash8887 done this doc on how to add UserTypes and Subtypes in SB. Please review the same.

[rhwarrier]

Thank you very much, @vinod303 ! Every contribution will go a long way in taking the SB community forward - your efforts are much appreciated!
@Jayaprakash8887 please review and add it this doc to the Lern microsite - possibly here

[AmiableAnil]

This information is added in Lern microsite https://lern.sunbird.org/learn/product-and-developer-guide/user-and-org-service/add-new-user-type-and-location