Use custom instanceName to link paper datasheets to ODK Forms

Sometimes an enumerator needs to find a form quickly based on some field values (e.g. household ID, patient number) among a long list of saved forms.
In the ODK Collect folder "Edit saved forms", the instance names default to the form title. This makes finding a particular form hard.

This showcase demonstrates

  • how to define a custom instance name, and
  • how to integrate data capture in an ODK form with paper datasheets.

Use case: Hybrid data capture using ODK forms and paper datasheets

Some data capture protocols require capturing all or part of the data of a survey on a paper datasheet. Examples include:

  • Harsh conditions: sand, wind, rain, night, humidity. Waterproof paper and pencil works where tablets won't.
  • Explosive conditions: data capture near gas plants requires intrinsically safe (spart-proof = expensive) devices. If you have $2k, get a spark-proof device, if not: here's your paper datasheet.
  • Data capture pace dictated by subject - e.g. animal handling, such as turtle tagging. An 80kg flatback turtle's pace on her way back to water after nesting is not open to discussions. Yet, PIT tags and flipper tags must be read, new ones applied, samples and measurements must be taken. (Note, wild animals can only be handled with an Animal Ethics Approval and several other official approvals.)
  • Data capture consists of several separate parts (form groups) which come up rapidly (at pace of animal handled) and in arbitrary and ever changing order.
    It's easier to jump between sections on a paper datasheet than to navigate up and down in a form (add looped groups and it gets hectic).

Even such harsh and chaotic conditions can be plied back into an ODK form by numbering datasheets with an ID and linking the ODK form via this ID to the datashet.

  • Pre-handling: Take an initial record in an ODK form (capture location, auto-timestamp, auto-username, datasheet ID), save, pack device away.
  • Hot phase, handling: Follow animal handling protocol, capture data on paper. Wipe off sand, sanitize hands, pack away tools.
  • Post-handling, backfilling: When enumerators find time (after hot phase, or next morning), open saved ODK form, backfill, add photo of datasheet, upload form.

Although ODK forms contain the datasheet ID, it is hard to distinguish them in the list of saved forms.
Luckily, instances can be named individually using an XPath expressions using data from form fields.

Example: define a custom instance name

As one example, a form with title "Turtle Tagging" has a group "encounter" with a text field "datasheet_id".

XForms - the hard way

In an XForm, one can add the following as sibling to the <bind> nodes:

<bind nodeset="/data/meta/instanceName" type="string" calculate="concat('Turtle Tagging ', /data/encounter/datasheet_id)"/>

XForms in ODK Build

If the XForm was created in ODK Build, one can enter into the menu Edit > Form properties > Instance Name the formula

concat('Turtle Tagging ', /data/encounter/datasheet_id)

Docs on form properties in ODK Build are here.


In an XLSForm, the instance name can be added to the "settings" sheet underneath the header instance_name as formula

concat('Turtle Tagging', ${datasheet_id})

Note the ${fieldname} interpolation.
Docs on XLSForm instance name are here.

As a result of either of the above examples, the saved forms are named

Turtle Tagging 0001
Turtle Tagging 0002
Turtle Tagging 0005

This allows to easily see the datasheet ID (0001, 0002, etc) from this list of saved forms. The datasheet ID here is ephemeral, as all data is backfilled from paper into the ODK form, and the datasheet itself is photographed as part of the form. The photograph of that datasheet is now forever linked to the form.

The expression can contain any XPath function and refer to any of the fields through an XPath Path.
XPath expressions are covered comprehensively in the docs here.

What use cases do you have for custom instance names?


Thanks for this writeup! I also want to point out that instance name can be searched and sorted from views that show lists of filled forms in Collect. That's not so useful in @Florian_May's specific case (maybe sorting?) but it can be really beneficial if values like names, dates or locations are included in the name.

1 Like