XLSForm spec proposal: auto-location type for background location capture with setlocation action

A long, long time ago, an ODK XForms specification for Auto-gps implementation on ODK Collect was approved at Spec addition proposal: location preload :

The odk:setlocation action sets the current location's geopoint value in the instance data node specified in the ref attribute. Any value attribute or text content will be ignored. Failure to retrieve the location will result in an empty string value.

For example:

<odk:setlocation ref="/data/location" event="odk-instance-first-load" />

I would like to propose the following XLSForm spec to enable the collection of a single geopoint in the background on form load:

Introduce a new auto-location type to the metadata section of the specification. Unlike the other metadata types, with auto-location, the text in the name column is chosen by the user. The provided name is used to name the target node.

For example, given the following row in an XLSForm:

type name
auto-location my-location

A node named my-location would be added to the primary instance. That node would be given a type of geopoint and be the target of a setlocation action triggered by the odk-instance-first-load event:

<bind nodeset="/data/my-location" type="geopoint" />
<odk:setlocation ref="/data/my-location" event="odk-instance-first-load" />

Of course, there’s a lot more that can be done with setlocation when combined with xforms-value-changed events and soon with odk-new-repeat events. I think those should be addressed by a different spec.



And we'll likely have to add an 'end of record' event when we're deprecating preloaders. So we'll be able to use this (and any calculation) for 4 events in total.

1 Like

In the TSC call, there was discussion of changing the action name to setgeopoint. Let's finalize that naming at Spec addition proposal: location preload and then this spec can be made consistent with the action name.

Excellent point. Is that an argument for naming the type something more like auto-start-location, then? Or perhaps just start-location since the fact that it's linked to a particular event implies that it's automatic? That would be nicely analogous to the start and end time preloads.

I think I muddied the waters when I described this to the TSC.

This proposal is very narrow and rightfully so. It is only to enable the collection of a single geopoint in the background on form load and it's really about the XLSForm syntax. Other background location gathering (e.g., on value change, in repeats) will require different syntax (probably an on_change column).

In the generated XForms, this seems reasonable to me.

<bind nodeset="/data/my-location" type="geopoint" />
<odk:setgeopoint ref="/data/my-location" event="odk-instance-first-load" />

odk:setgeopoint is a proposed change to the current spec that we can discuss more at Spec addition proposal: location preload. My argument for that change is that current geopoint format is bad and we should change it to some standard format and it seems reasonable to maybe save odk:setlocation for that.

In XLSForms, this seems reasonable to me:

  • type: start-geopoint, end-geopoint

It's reasonable because we are adding a geopoint at first load, which is analogous to adding a timestamp at first load. We called that start and calling this start-geopoint seems reasonable (maybe we can add a start-datetime alias).

  • I don't like auto because it's not a differentiator. We'll never have a manual-start-location because we already have geopoint.
  • I don't like location it could be confusing. If you have start-location and end-location, someone might expect that those are action that start a background trace. Also, we might want to save the location word for a different format. I don't feel super strongly about that though.

That's a good point. Having start or end as prefixes make the names sound like commands. How about geopoint-start (and eventually geopoint-end)?