odk entities

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 osm-fieldwork / 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. 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. https://docs.getodk.org/central-entities/#building-a-form-that-updates-an-entity

Resources

• Here's the introductory page from ODK. discussing the rationale for and use of 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.
• Here's the ODK Central API documentation for dealing with Entities
• Here's the ODK Central API documentation for dealing with the "Datasets" they are part of
• Here's a discussion of how you can attach a draft form to an entity "dataset"
• OSM Diary Detailing Entity Usage