Spin off from
What is the general goal of the feature?
To streamline ability for API users to easily import data into Power BI/PowerQuery and similar tools, as they will no longer have to put in code to extract the “name” of each field without including the “group”.
At the moment, if a user calls API (v1 or v2) to get submissions data (https://[kpi-url]/api/v2/assets/{asset_uid}/data/ (access submitted data), e.g. https://kobo.humanitarianresponse.info/api/v2/assets/a6krNsaSnJFJDM9BgMSU3r/data/) then they get JSON response keys that include the group (s) as well as the names. This means that
- the field names are long and not instantly identifiable when turned into column headings,
- manual string manipulation (to remove the groups) is required if wanting to map the submission data back to the original XLSform in order to return human-readable “label” (in whatever language) rather than the “name” that is used under-the-hood.
"g_socioec/data_repeat_se_count": "1", "g_NS_info/g_contact1/contact1_phone": "sdf", "_uuid": "551e46fb-c9e1-46e8-b3b4-6348a61dc53e", "g_health/all_indicators/choose_indicators": "testing rcce emt", "g_ns/nsar_q": "no", "_submitted_by": null, "_xform_id_string": "a6krNsaSnJFJDM9BgMSU3r", "g_ns/nss_fr_q": "no", "g_socioec/se_indicators/choose_indicators_se": "na", "_validation_status": {}, "g_health/data_repeat": [ { "g_health/data_repeat/this_selection": "testing", "g_health/data_repeat/indicator_data/agd": "gender", "g_health/data_repeat/indicator_data/this_total": "379978", "g_health/data_repeat/indicator_data/d": "no", "g_health/data_repeat/indicator_data/gender/female_noa": "34543", "g_health/data_repeat/indicator_data/gender/male_noa": "345435", "g_health/data_repeat/indicator_data/total_g": "379978", "g_health/data_repeat/indicator_data/reporting_total": "379978" }, { "g_health/data_repeat/indicator_data/total_direct": "55",
…
"g_health/count_indicators": "3", "g_ns/vol_coverage_q": "partial", "formhub/uuid": "9281fe9a70c748c6928b30c8ddaa01d1", "meta/instanceID": "uuid:551e46fb-c9e1-46e8-b3b4-6348a61dc53e", "end": "2021-05-16T01:09:11.816+12:00", "g_ns/nsr_q": "no",
This means that it’s not possible to map the keys from the JSON to the list of “names” from the XLSForm - and also makes it more complicated for users to read (e.g. 20179, 17316, and others previously e.g.
I would propose having a parameter option to allow the user to specify whether or not they want groups to be included - in the same way as the XLS download option to “include groups in headers” or exclude groups:
Names are unique in the XLSForm so it shouldn’t be a problem to just remove the groups for non-repeat scenarios. The curly case will be where there are repeats - e.g. where the square brackets are in example JSON above - these will likely need to keep group names (or alternative identifiers of some kind) in order for there to be something returned at the top level. Would take dev advice on this.
What are the most likely user stories for how and when this would be used by someone on your team?
Anyone integrating with the API programmatically
Can you sketch out graphically how you think this should look/work in practice?
A flag on the API parameters
How useful would this feature be to other users or organizations?
Useful, as per other conversations linked above.
What can you contribute to making this feature a reality?
Test support
