From a49042abe464e8c4fa71713884d0fd5a999bddf1 Mon Sep 17 00:00:00 2001 From: Ivan Gayton Date: Mon, 25 Mar 2024 00:20:55 +0900 Subject: [PATCH] docs: add info about ODK Entities (#239) * Began documenting work on Entities-based FMTM work * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: extra info on entity creation --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: spwoodcock --- docs/about/odk-entities.md | 70 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/about/odk-entities.md b/docs/about/odk-entities.md index 9399329ab..a42d7f417 100644 --- a/docs/about/odk-entities.md +++ b/docs/about/odk-entities.md @@ -1 +1,71 @@ # ODK Entities + +Entities are a concept introduced into ODK around 2022. The basic goal +of them is to allow updating of data using ODK, specifically by revisiting +specific things (features, people, whatever) and adding new data attached +to the same entity (data people refer to this as "longitudinal data"). For +example, revisiting the same patient in a clinical study, such that the +patient ID is constant and the new data from each visit is referenced to +the same person. For field mapping, the use-case is obvious: visit a +previously digitized building and add data from in-person observation or +surveying the people in it. + +As of time of writing (March 2024), Entities in ODK are working and more +or less implemented, but not yet in wide use or well debugged. + +# Use of Entities with FMTM + +In FMTM, we want to: + +- Be aware of features that have already been mapped + - the ODK map views don't yet support styling features differently + based on attributes like "already_field_mapped", so we're actually + working on a navigation app within FMTM external to ODK, but we still + hope that ODK Collect may support styling in the future, which will + almost certainly be based on Entity attributes. +- Pre-fill questions in the form when features already have data attached + to them (for example, if a building already has a "name" tag, the field + mapper should see this pre-filled in the form, to be overwritted if wrong + but otherwise swiped past). + +The ODK core development team has strongly suggested that the FMTM team +use the Entities to achieve the above goals. + +## Workflow Using Entities + +The basic workflow would probably resemble: + +- Create an Entity registration form. + - In standard ODK settings, this simply means adding an `entities` + tab to the XLSForm (as per + [the example Entities form created by the ODK team](https://docs.google.com/spreadsheets/d/1xboXBJhIUlhs0wlblCxcQ3DB5Ubpx2AxLDuaXh_JYyw/edit#gid=2050654322). + This seems to create what ODK refers to as a Dataset (in developer-facing documenation only; + they avoid this word in user-facing documentation). +- Upload the Entities via the API: + - There is currenltly no way to bulk upload Entities to a Dataset via the API. + - Instead we must upload each Entity individually, including a geometry field + in JavaRosa geometry format. + - Until time of writing, FMTM creates geography attachments in GeoJSON, + which does not work for Entities, which require a CSV file with a + `geography` column (which must be in JavaRosa format, which no self-respecting + GIS utility can export). +- Create a form for the data collection, referencing the `{dataset_name}.csv` for + the `select_one_from_file` field. +- Dynamically insert the `task_id` field on the `choices` sheet, with `name` and + `label` set to the task id (for filtering later). +- Create a field `task_id` in the survey, prior to the `select_one_from_file` field. +- Set `choice_filter` column to task_id=${task_id}, which links the selected task + ID in the survey with the task_id field in the Entities (used for filtering). +- Load the form via intent, with `task_id` and `entity_id` fields in query params. +- On form completion we can update the Entity label and fields. + - Set the field `status` to COMPLETE, IN_PROGRESS, INVALID. + - Update the entity label to be prefixed with ✅ ❌ for a nicer visual cue. + + +# Resources + +- [Here's the introductory page from ODK discussing the rationale for and use of Entities](https://docs.getodk.org/central-entities/). It has some example forms you can use to get started figuring out how to use Entities. +- [Here's the specification for Entities in the XForms language](https://getodk.github.io/xforms-spec/entities). +- [Here's the ODK Central API documentation for dealing with Entities](https://docs.getodk.org/central-api-entity-management/) +- [Here's the ODK Central API documentation for dealing with the "Datasets" they are part of](https://docs.getodk.org/central-api-form-management/#related-datasets) +- [Here's a discussion of how you can attach a draft form to an entity "dataset"](https://docs.getodk.org/central-api-form-management/#linking-a-dataset-to-a-draft-form-attachment)