ODK Entities and Longitudinal Workflow

Use ODK Entities when one form needs to create or update records that another form will use later. An Entity List can represent households, clients, sites, trees, cases, or assets. A registration form creates the record, a follow-up form selects it, and later submissions update its properties over time.

Entities are different from a repeat group. A repeat group stores several related answers inside one submission. Entities create records that can be shared across forms and synchronized through ODK Central. Start with the ODK Entities documentation for the complete reference.

When should you use Entities?

Entities are a good fit when the workflow has a stable record and multiple interactions:

• A household is registered once and visited several times.
• A health or protection case is opened, followed up, and closed.
• A field team registers sites, trees, assets, or facilities and revisits them later.
• One form creates a roster that another form uses as a controlled list.
• Different forms need to read or update selected properties over the life of a project.

Use a repeat group when the repeated items belong inside one submission and do not need to be shared with another form. Use Entities when the records need their own identity, lifecycle, or cross-form access.

The basic Entity workflow

Plan the workflow as a record lifecycle:

1. Create: a registration form creates an Entity with a label and selected properties.
2. Distribute: ODK Central synchronizes the Entity List to forms that are allowed to use it.
3. Select: a follow-up form lets the enumerator choose an Entity, scan its ID, or otherwise identify the record.
4. Update: the follow-up submission writes approved fields back to the selected Entity.
5. Review: the team checks Entity values, conflicts, access, and the related submissions in Central.
6. Close: the workflow marks a case or asset as inactive through a property and the form stops showing it when appropriate.

Write the lifecycle down before building the form. Decide which form owns each property, which fields are editable, who can see each record, and how the team handles a duplicate or conflicting update.

Design the registration form

Add an entities sheet to the XLSForm. At minimum, define the Entity List name and a label expression. Then use save_to on selected survey fields to specify which answers become Entity properties.

Example structure:

entities
list_name | label
households | ${household_id}

survey
type | name | label | save_to
text | household_id | Household ID | household_id
text | head_name | Household head | head_name
geopoint | location | Location | geometry

Keep the Entity property set small. Save the values that later forms need to identify, filter, or update the record. Keep explanatory notes, one-time consent answers, and other submission-only data in the submission unless the longitudinal workflow genuinely needs them as Entity properties.

For the exact entities sheet, save_to, label, and entity_id rules, use the ODK Entity quick reference. Then run the XLSForm validation checklist before publishing.

Design a follow-up form

A follow-up form needs to read the Entity List and identify the specific Entity being updated:

1. Link the form to the intended Entity List in Central.
2. Use a question that lets the enumerator choose or scan the Entity ID.
3. Put that value in the entity_id column of the entities sheet.
4. Add save_to values only for properties the follow-up form is allowed to change.
5. Use update_if when the update should happen only after a condition, such as a supervisor approval.
6. Add a status property when the workflow needs to filter active, completed, or closed records.

Do not assume that every answer in a follow-up form becomes part of the Entity. The submission remains the detailed event record; only fields mapped with save_to update Entity properties.

Test the cross-form workflow safely

Entity workflows are harder to test than ordinary forms because the records live across forms and submissions. Use a temporary Central project for an end-to-end pilot:

1. Publish the registration form and create a small set of test Entities.
2. Publish the follow-up form and confirm it reads the Entity List.
3. Complete a follow-up interview while offline.
4. Reconnect and submit it.
5. Confirm the correct Entity was updated and unrelated properties were unchanged.
6. Repeat the test with an invalid, closed, or inaccessible Entity.
7. Export the Entity data and related submissions to check IDs and joins.

ODK Central's form drafts do not create real Entities from draft submissions. A temporary project or a controlled published test is the safer way to test the entire create-and-update workflow. Record which test Entities and submissions should be removed before production.

Plan access and synchronization

Entity access is part of data protection and device performance. By default, forms can receive Entity data from an attached list, but Central supports server-side ownership and property filters to limit what a user or public link receives.

Use access filters when:

• Enumerators should see only records assigned to their region or team.
• A device should download only the cases it needs for the current round.
• A project contains sensitive records that should not be distributed to every App User.
• A large Entity List would make synchronization or form loading slow.

Pair server-side filters with ODK Central user management and a clear App User plan. A form's choice filter can shape what the enumerator sees, but it is not the same as limiting what data the device receives.

Handle offline Entity conflicts

Two devices can update the same Entity from different offline versions. Central detects stale or parallel updates and marks conflicts for review. This is a workflow issue, not merely a form-validation error.

Reduce conflict risk by:

• Assigning each Entity to one team or device during a collection round.
• Keeping offline periods short when the same records are shared across teams.
• Using a status or ownership property to make responsibility visible.
• Testing two-device updates in a controlled project.
• Reviewing conflict warnings before treating the Entity data as current.

If a conflict occurs, compare the competing values with the related submissions and field context. Resolve it deliberately in Central or through the approved API workflow, then record why the chosen value is correct.

Export and review Entity data

Entities and submissions answer different analysis questions:

Data	What it represents	Typical use
Entity List	The current shared record and its properties	Current household, case, site, or asset state
Submissions	The event that created or updated a record	Visit history, audit trail, observations, and decisions
OData or CSV export	A view for analysis and reporting	Dashboards, longitudinal summaries, and archival copies

Export both the current Entity data and the related submissions when the study needs history. Use the ODK submission review checklist to preserve the original files, record filters, and document review decisions.

SurveyLoopr can provide the managed ODK Central server for this workflow. Your team still owns the Entity design, access rules, test project, conflict policy, and data-retention decisions.

If a service needs to create or update Entity data outside a form submission, review the ODK Central API and automation guide before granting it access.

Deploy a managed ODK server

Validate the forms before publishing