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.
1 Like

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)?

I think of it as start-time and end-time and so I prefer start-geopoint and end-geopoint.

I'd like to invite @TSC-1 (and especially @Ukang_a_Dickson) to this conversation and see if they can, over the next 3 business days, help us with the following:

  1. Read over the entire thread to get the necessary context
  2. See if the concerns raised during the previous call have been resolved
  3. Settle on a final name for the XLSForm
1 Like

For what's worth, I think the most coherent option would be to have start-geopoint and end-geopoint.


start-geopoint or geopoint-start sound both fine with me. I'm not sure which I prefer yet.

I was initially thinking it would be good to already figure out a direction for how we want to add the ability to record a geopoint upon the xforms-value-changed event in the future (and odk-new-repeat though that is less challenging). But now I think that's not really necessary to figure out before adding this XLSForm feature. We can always add an alias if we end up wanting a more consistent way to create setvalue actions upon the occurrence of the 4-or-so different events we support.

1 Like

Consensus on the TSC call is start-geopoint. I've sent in a PR at https://github.com/XLSForm/pyxform/pull/341 to add this to pyxform.

1 Like

A post was split to a new topic: Install odk aggregate for windows 8 64 bits