feat(#507): add setgeopoint action #594

latin-panda · 2025-12-18T19:02:19Z

Closes #507

ODK XForms spec: https://getodk.github.io/xforms-spec/#events
User-facing docs: start-geopoint (odk:setgeopoint with odk-instance-first-load)

These questions were already answered by the team; see the summary here.

Does it need to show an indicator just like Collect does? (I think we decided not add it, but double-checking)

Any time a survey with a start-geopoint question is opened in Collect, the enumerator will see a warning that the form tracks device location .... A location icon will be displayed in the Android status bar while the geolocation is being requested by Collect.
The odk-new-repeat is fired when a new repeat instance is created. At that moment, geolocation is requested once. Subsequent repeat instances reuse this same geolocation reading, so all instances end up with the same location value. That's expected, correct?
The background-geopoint is an odk:setgeopoint with xforms-value-changed, that, as per the specs:

lets you automatically capture a single geolocation in geopoint format when the user changes the value of another question.

3.1 The location is requested once, and subsequent value changes reuse the same geolocation reading (or empty string if no permissions given) for all questions. Is that correct? This is a lighter and less complex option than requesting the location every time a question value changes.

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Displays error message when it cannot access the geolocation

Displays multiple messages in the top error banner

Tests all events except new repeat instance

test-all-events.mp4

Tests new repeat instance event

test-setgeopoint.mp4

Why is this the best possible solution? Were any other approaches considered?

Reuses the existing action structure, sets the value without re-evaluating the expression (since it comes from the geolocation provider), and reuses geopoint codecs for validation.

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Existing features will continue to work as usual with no changes.
Forms with setgeopoint will now request geolocation in the background, which may affect low-end phones by increasing resource usage (battery, CPU), as expected. The geolocation request stops after 20 seconds, in accordance with the specs.

Do we need any specific form for testing your changes? If so, please attach one.

There are 3 forms in the common package to test the feature. I also have a form that includes all events in one form:

Form: setgeopoint with events

<?xml version="1.0" encoding="utf-8"?>
<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://openrosa.org/javarosa" xmlns:odk="http://www.opendatakit.org/xforms">
  <h:head>
    <h:title>combined-setgeopoint-test</h:title>
    <model>
      <instance>
        <data id="combined-setgeopoint-test">
          <required_text />
          <location_first_load />
          <location_instance_load />
          <trigger_text />
          <location_value_changed />
          <setvalue_target />
          <person jr:template="">
            <age />
            <location_new_repeat />
          </person>
        </data>
      </instance>
      <bind nodeset="/data/required_text" type="string" required="true()" />
      <bind nodeset="/data/location_first_load" type="string" readonly="true()" />
      <bind nodeset="/data/location_instance_load" type="string" readonly="true()" />
      <bind nodeset="/data/trigger_text" type="string" />
      <bind nodeset="/data/location_value_changed" type="string" readonly="true()" />
      <bind nodeset="/data/setvalue_target" type="string" readonly="true()" />
      <bind nodeset="/data/person/age" type="integer" />
      <bind nodeset="/data/person/location_new_repeat" type="string" readonly="true()" />
      <odk:setgeopoint ref="/data/location_first_load" event="odk-instance-first-load" />
      <odk:setgeopoint ref="/data/location_instance_load" event="odk-instance-load" />
    </model>
  </h:head>
  <h:body>
    <input ref="/data/required_text">
      <label>Required Text</label>
    </input>
    <input ref="/data/location_first_load">
      <label>Location (odk-instance-first-load)</label>
    </input>
    <input ref="/data/location_instance_load">
      <label>Location (odk-instance-load)</label>
    </input>
    <input ref="/data/trigger_text">
      <label>Trigger Text (change to trigger value-changed)</label>
      <odk:setgeopoint ref="/data/location_value_changed" event="xforms-value-changed" />
      <odk:setvalue ref="/data/setvalue_target" event="xforms-value-changed" value="/data/trigger_text" />
    </input>
    <input ref="/data/location_value_changed">
      <label>Location (xforms-value-changed)</label>
    </input>
    <input ref="/data/setvalue_target">
      <label>Setvalue Target</label>
    </input>
    <group ref="/data/person">
      <label>Person Repeat Group</label>
      <repeat nodeset="/data/person">
        <input ref="/data/person/age">
          <label>Age</label>
        </input>
        <odk:setgeopoint event="odk-new-repeat" ref="/data/person/location_new_repeat" />
        <input ref="/data/person/location_new_repeat">
          <label>Location (odk-new-repeat)</label>
        </input>
      </repeat>
    </group>
  </h:body>
</h:html>

What's changed

Introduces a geolocation provider interface in the engine and enables support for consuming it in the primary instance, which is later used for dispatching geolocation actions in createInstanceValueState.ts.
Reuses most of the action structure implemented for setValue
Adds scenario tests
Introduces a singleton geolocation service that operates independently without affecting other question types requesting location permission. It includes a tear-down method to free memory.

changeset-bot · 2025-12-18T19:02:22Z

🦋 Changeset detected

Latest commit: de7cdbe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@getodk/xforms-engine	Minor
@getodk/web-forms	Minor
@getodk/scenario	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts

latin-panda · 2025-12-18T19:12:21Z

packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts

 		if (action) {
-			registerAction(context, setValue, action);
+			if (action.element.nodeName === 'odk:setgeopoint') {
+				context.parent.rootDocument.getBackgroundGeopoint()?.then((value: string) => {


The primary instance is the parent, not the context itself :(

latin-panda · 2025-12-18T19:20:15Z

@garethbowen This code isn't pretty and still experimental, but I wanted to get a version working first and get your thoughts from the engine side.

In the screenshot, the xform-engine is working; it sets the value when the event runs, and the value comes from a promise.

…et-geometry-function # Conflicts: # README.md # feature-matrix.json

latin-panda · 2025-12-26T10:26:31Z

Testing is complete, and I need to clarify a few small questions with the team later before moving this PR to ready.

garethbowen

Fantastic. Looks like a nice generalisation of the setvalue code!

I haven't tried running it yet (hopefully will do that later today), but thought I'd get this feedback to you ASAP.

packages/scenario/test/actions-events/set-geopoint-action.test.ts

packages/web-forms/src/components/OdkWebForm.vue

garethbowen · 2026-01-06T23:10:00Z

packages/web-forms/src/lib/services/geolocationService.ts

+		const { latitude, longitude, accuracy } = position.coords;
+		const altitude = position.coords.altitude ?? 0;


I think you can do this...

Suggested change

const { latitude, longitude, accuracy } = position.coords;

const altitude = position.coords.altitude ?? 0;

const { latitude, longitude, accuracy, altitude=0 } = position.coords;

It doesn't catch the case when altitude is null (mdn ref)

packages/web-forms/src/lib/services/geolocationService.ts

packages/xforms-engine/src/instance/PrimaryInstance.ts

packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts

garethbowen · 2026-01-07T00:18:55Z

packages/web-forms/src/lib/services/geolocationService.ts

+	private watcherId: number | null = null;
+	private activePromise: Promise<string> | null = null;
+	private bestPoint: GeolocationPosition | undefined = undefined;
+	private options: PositionOptions = { enableHighAccuracy: true, maximumAge: 0 };


I can't find anywhere maximumAge is used - should this be removed or implemented?

Do you mean the audit attributes ? I didn't consider them as part of the scope. I think we can implement that in a separate PR

I've removed maximumAge because it's zero by default anyway.

garethbowen · 2026-01-07T00:28:04Z

packages/web-forms/src/lib/services/geolocationService.ts

+				this.complete(resolve, reject, 'No geolocation readings received within the time window.');
+			}, timeoutSeconds * 1000);
+		});
+		return this.activePromise;


Running this in the browser there's an imperfect behaviour if you happen to submit the form in under 20 seconds then the geopoint value is empty. I guess not many forms will be that simple but still, it's a shame that if the browser has returned a perfectly good point, that we throw it away. I think an improved version would set the value every time the watchPosition returns a better accuracy point so we get the best possible data when the submit button is pressed.

This could also lead to interesting custom validations, for example, requiring a certain level of accuracy.

The reason I think it's worth looking into this now is because it will require an API change because Promises can't be resolved twice. Instead it would follow the event emitter pattern, just like watchPosition does.

The 20s timeout is implemented on the client side, so the client can also resolve that promise immediately to assign the point before submission.

I remember we talked about using emitters, but having the engine subscribe to client-side emitters feels a bit backwards. It could lead to a deep callback chain. Promises are much cleaner for this 'one-and-done' data flow.

The challenge is just catching those last few promises or reactive updates (Solid.js) that fire right before submission. I've added a helper that just flushes the event loop to make sure the engine has fully 'digested' all the reactivity before we capture the payload. It’s tiny and feels like a good safety net, guaranteeing we’re submitting the most accurate state possible. The engine might eventually provide this helper utility as "settle()", but for now, adding it on the client side (lib/async/event-loop.ts) is a non-invasive way to avoid race conditions.

This is one of rare cases I've seen this kind of helpers make sense :)

…et-geometry-function

lognaturel · 2026-01-13T20:32:10Z

I just realized I missed questions in this PR descriptions, my apologies! We've discussed but I want to make sure the answers are captured here. High-level, the location capture triggered by events other than form load are only relevant for mobile usage, not for desktop. When a form is being filled on a mobile device/laptop, those events can be used to ensure that background location capture is tied to a specific moment in time like after the person filling out the form has confirmed who lives in a certain structure.

The odk-new-repeat is fired when a new repeat instance is created. At that moment, geolocation is requested once. Subsequent repeat instances reuse this same geolocation reading, so all instances end up with the same location value.

Here's a sample form demonstrating the intended usage:
setgeopoint-action-with-repeats.xml

The idea is that each repeat can represent a record and the location of the thing represented by that record can be captured in the background without user intervention. For usage like this, we'd expect the data collector to be moving so it's important that a new location capture session starts when the event is triggered.

lets you automatically capture a single geolocation in geopoint format when the user changes the value of another question. The location is requested once, and subsequent value changes reuse the same geolocation reading (or empty string if no permissions given) for all questions

The intended usage of setgeopoint triggered by a xforms-value-changed event is to ensure that location capture happens after the user has performed certain actions. For example, the person filling out the form might be instructed to go to the front door or ask the respondent to take them to their largest tree. When they confirm they are at the intended location, for example by checking "yes", then the location capture is triggered.

In general, I would expect the client implementation of the action not to care what event triggers it. However, there are some considerations around what should happen if the same action is triggered again. For example, xforms-value-changed is emitted at each keystroke for any given input control. There are two options:

Reset the 20s counter and highest accuracy each time a new event is received
If a location capture session is already in progress, drop subsequent triggering events

Collect does the first: https://github.com/getodk/collect/blob/d574284887015412eb48e9be58f591e19491c3fe/collect_app/src/main/java/org/odk/collect/android/location/client/MaxAccuracyWithinTimeoutLocationClientWrapper.java#L50

I don't think it's terribly important to align on this because it is an edge case.

Hopefully all this aligns with what you're already thinking. Happy to talk through more of the intended behavior if helpful. I'm sure you've already looked at this but also cross-linking the Collect implementation for reference:

latin-panda · 2026-01-14T19:11:32Z

@garethbowen This is ready for review!

latin-panda added 2 commits December 18, 2025 01:40

trying ideas

5a18e2f

experimenting

dbc8036

latin-panda commented Dec 18, 2025

View reviewed changes

packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts Show resolved Hide resolved

latin-panda commented Dec 18, 2025

View reviewed changes

packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts Outdated Show resolved Hide resolved

latin-panda commented Dec 18, 2025

View reviewed changes

latin-panda requested a review from garethbowen December 18, 2025 19:23

latin-panda added 6 commits December 23, 2025 16:22

Merge branch 'main' of https://github.com/getodk/web-forms into add-s…

de3570b

…et-geometry-function # Conflicts: # README.md # feature-matrix.json

merge

835f4d6

Implementation engine and scenario

0b9610c

Adds missing scenario utility

9e75c40

changeset

5d5c87e

add test case in scenario

05a6660

latin-panda changed the title ~~feat: add setgeometry function~~ feat: add setgeopoint function Dec 24, 2025

latin-panda changed the title ~~feat: add setgeopoint function~~ feat: add setgeopoint function (start-geopoint) Dec 24, 2025

latin-panda added 4 commits December 26, 2025 14:38

adds geolocation service in client

883a086

only cache request if no empty

147c4be

fixes xforms-value-changed

eba3248

fixes lint

91f6799

latin-panda changed the title ~~feat: add setgeopoint function (start-geopoint)~~ feat(#507): add setgeopoint function Dec 26, 2025

garethbowen requested changes Jan 6, 2026

View reviewed changes

garethbowen reviewed Jan 7, 2026

View reviewed changes

latin-panda added 3 commits January 13, 2026 19:48

Merge branch 'main' of https://github.com/getodk/web-forms into add-s…

32a9e7f

…et-geometry-function

Fixes scenario tests

6760c17

Feedback

15f1dc4

lognaturel changed the title ~~feat(#507): add setgeopoint function~~ feat(#507): add setgeopoint action Jan 13, 2026

latin-panda added 4 commits January 14, 2026 17:11

Feedback - rename of function and exit early

e6e25a5

Removes cache for point, gets a new point for repeats and value change

2710a6c

fixes CI

851631b

resolves async before submit

c0dac71

latin-panda marked this pull request as ready for review January 14, 2026 18:30

latin-panda added 2 commits January 15, 2026 01:36

removes unnecessary type

2a2c599

prints error

de7cdbe

latin-panda requested a review from garethbowen January 14, 2026 19:10

		const { latitude, longitude, accuracy } = position.coords;
		const altitude = position.coords.altitude ?? 0;

	const { latitude, longitude, accuracy } = position.coords;
	const altitude = position.coords.altitude ?? 0;
	const { latitude, longitude, accuracy, altitude=0 } = position.coords;

feat(#507): add setgeopoint action #594

Are you sure you want to change the base?

feat(#507): add setgeopoint action #594

Uh oh!

Conversation

latin-panda commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I have verified this PR works in these browsers (latest versions):

What else has been done to verify that this works as intended?

Why is this the best possible solution? Were any other approaches considered?

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

Do we need any specific form for testing your changes? If so, please attach one.

What's changed

Uh oh!

changeset-bot bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

latin-panda Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

latin-panda commented Dec 18, 2025

Uh oh!

latin-panda commented Dec 26, 2025

Uh oh!

garethbowen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

garethbowen Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

latin-panda Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

garethbowen Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

latin-panda Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

garethbowen Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

latin-panda Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

lognaturel commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

latin-panda commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

latin-panda commented Dec 18, 2025 •

edited

Loading

changeset-bot bot commented Dec 18, 2025 •

edited

Loading

latin-panda Dec 18, 2025 •

edited

Loading

garethbowen Jan 7, 2026 •

edited

Loading

lognaturel commented Jan 13, 2026 •

edited

Loading