Skip to content

Commit

Permalink
[pre-commit.ci] auto fixes from pre-commit.com hooks
Browse files Browse the repository at this point in the history
for more information, see https://pre-commit.ci
  • Loading branch information
pre-commit-ci[bot] committed Mar 18, 2024
1 parent 8d87e0a commit fbbb310
Showing 1 changed file with 6 additions and 4 deletions.
10 changes: 6 additions & 4 deletions docs/about/odk-entities.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ Entities are a concept introduced into OpenDataKit (ODK) around 2022. The basic
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).
Expand All @@ -15,15 +17,15 @@ The ODK core development team has strongly suggested that the FMTM team use the
## Workflow Using Entities

The basic workflow would probably resemble:

- Create an XLSForm per task that refers to an Entity.
- 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).
- It appears (to be confirmed) that we can *then* upload a CSV file with the same name as the entity dataset, which will then populate the Dataset with the contents of the CSV.
- 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).
- It appears (to be confirmed) that we can _then_ upload a CSV file with the same name as the entity dataset, which will then populate the Dataset with the contents of the CSV.
- Creating a geography attachment per task that contains the actual geometry and fields/attributes of the existing features.
- 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).



# 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/)
Expand Down

0 comments on commit fbbb310

Please sign in to comment.