APIs & services / commons-report-service

Load the work-node (geography) hierarchy for the work-node picker.

Endpointtoday's app

Call: GET /gateway/commons-report-service/api/v1/datasets/name/PlusOneUrviGeoDataForVOs/execute
Service: commons-report-service
Features: Village, Habitation and VO selection, Login
When: On login (ap.gov users)
Auth: X-SESSIONID header (AuthInterceptor adds it; re-auth on 401/400)
In the App Service: GET /session/bootstrap

Use case

Verified live on 2026-10-22 against the dev server (debug build, emulator, ap.gov test user). Runs during first setup for ap.gov tenant users (SplashActivity -> SetUpWorknode.run -> fetchWorkNodeHierarchy). The app sends the user's VO alias ids and gets one flat row per VO with its habitation and village. It groups the rows village -> habitation -> VO, builds synthetic WorkNode ids, and saves the tree with Data.repository.saveWorkNodeHierarchyList for the work-node picker. Network IOExceptions surface as SetUpException.BadNetwork; an empty or failed response saves nothing.

Headers

Header	Value	Notes
`X-SESSIONID`	<session token>	Not set by the call site. AuthInterceptor (OkHttpClientInterceptor) adds it from AndroidSessionManager. On a 401 or 400 it invalidates the token, gets a fresh one and retries once.

Parameters

Param	In	Required	Example	Notes
`datasetName`	path	Yes	`PlusOneUrviGeoDataForVOs`	Dataset name in the path of commons-report-service /api/v1/datasets/name/{name}/execute.
`version`	query	Yes	`1`	Dataset version. Always 1.
`format`	query	Yes	`json`	Response format. Always json, so the body is a JSON array of row objects.
`params`	query	Yes	`IN_PARAM_VO_LIST=VO-ALIAS-001,VO-ALIAS-002`	Dataset input parameters as KEY=value pairs joined with "--". IN_PARAM_VO_LIST = comma-separated WorkNodeAliasId values from PlusOneTenantUserData.

Request

No body. params built from work-node alias ids

Response

Example response body (synthetic data)

[
  {
    "WorkNodeVillageAlias": "V01",
    "WorkNodeVillageName": "Village A",
    "WorknodeVillageMajorType": "MAJOR_TYPE.VILLAGE",
    "WorkNodeHabitationAlias": "H01",
    "WorkNodeHabitationName": "Habitation A",
    "WorknodeHabitationMajorType": "MAJOR_TYPE.HABITATION",
    "WorkNodeVoAlias": "VO-ALIAS-001",
    "WorkNodeVoName": "VO A",
    "WorknodeVOMajorType": "MAJOR_TYPE.VO"
  },
  {
    "WorkNodeVillageAlias": "V01",
    "WorkNodeVillageName": "Village A",
    "WorknodeVillageMajorType": "MAJOR_TYPE.VILLAGE",
    "WorkNodeHabitationAlias": "H02",
    "WorkNodeHabitationName": "Habitation B",
    "WorknodeHabitationMajorType": "MAJOR_TYPE.HABITATION",
    "WorkNodeVoAlias": "VO-ALIAS-002",
    "WorkNodeVoName": "VO B",
    "WorknodeVOMajorType": "MAJOR_TYPE.VO"
  }
]

Field	Type	Notes
`WorkNodeVillageAlias / WorkNodeVillageName / WorknodeVillageMajorType`	string	Top-level WorkNode (aliasId, ENG name, majorType). Rows are grouped by village alias; it must not be null. Observed formats: village alias 11 digits, habitation alias 13 digits, VO alias 15 digits; names carry the alias in brackets, e.g. "Village A (01000000001)".
`WorkNodeHabitationAlias / WorkNodeHabitationName / WorknodeHabitationMajorType`	string	Child WorkNode of the village. Observed formats: village alias 11 digits, habitation alias 13 digits, VO alias 15 digits; names carry the alias in brackets, e.g. "Village A (01000000001)".
`WorkNodeVoAlias / WorkNodeVoName / WorknodeVOMajorType`	string	Leaf WorkNode under the habitation. Saved in the work_node_hierarchy table. Observed formats: village alias 11 digits, habitation alias 13 digits, VO alias 15 digits; names carry the alias in brackets, e.g. "Village A (01000000001)".

Errors

Status	When	What the app does
`401 / 400`	Session token expired or rejected	AuthInterceptor refreshes the token and retries once; if the retry also fails, fetchWorkNodeHierarchy saves nothing (no hierarchy for the picker). IOException is rethrown as SetUpException.BadNetwork.
`5xx`	Dataset query failed on the server	fetchWorkNodeHierarchy saves nothing (no hierarchy for the picker). IOException is rethrown as SetUpException.BadNetwork.
`network error`	No connectivity or timeout	fetchWorkNodeHierarchy saves nothing (no hierarchy for the picker). IOException is rethrown as SetUpException.BadNetwork.

Source

data/src/main/java/org/mindtree/app/agricultor/data/setup_new/SetupServiceNew.kt
data/src/main/java/org/mindtree/app/agricultor/data/setup/SetUpWorknode.kt
data/src/main/java/org/mindtree/app/agricultor/data/setup_new/WorkNodeHierarchyDTO.kt
app/src/main/java/org/platformcommons/urvi/view/splash/SplashActivity.kt
data/src/main/java/org/mindtree/app/agricultor/data/net/AuthInterceptor.kt