GPS Coordinates Collection on Questionnaire Submission

[qiarie]

Background

There is a request to have the ability to capture the geographical location where a questionnaire was filled. The location information will be used to validate activities by agents in the field. The location capture should be done in the background without the need for user input.

The feature to collect the location on questionnaire submission should be configurable. For applications that have this feature enabled, location services must be enabled and permissions granted for the feature to work.

Proposed Implementations

1. Configure Google Play services dependency in quest's build.gradle

   implementation 'com.google.android.gms:play-services-location:{version}'
   

2. Request for ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions in AndroidManifest.xml

   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
   

3. Add a config parameter to ApplicationConfiguration to control whether location information should be captured on questionnaire submission

   val logQuestionnaireLocation: boolean = false
   

4. Before launching a questionnaire, check the application config parameter logQuestionnaireLocation is set to true.
   If location logging is set, check whether the application has ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions and prompt the user to grant the permissions if not granted.

   if (ActivityCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED &&
       ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED
   ) {
     // launch permissions dialog
   }
   

5. Options on how to pick the current location

   a. Approach 1 - Use FusedLocationProviderClient (preferred)

   Create and instantiate an instance of the Fused Location Provider Client

   private lateinit var fusedLocationClient: FusedLocationProviderClient
   

   override fun onCreate(savedInstanceState: Bundle?) {
     ...
     fusedLocationClient = LocationServices.getFusedLocationProviderClient(this)
   }
   

   On questionnaire submission (*), get the current or last location using the fusedLocationClient.

   From Android documentation:

   • getLastLocation() gets a location estimate more quickly and minimizes battery usage that can be attributed to your app. However, the location information might be out of date, if no other clients have actively used location recently.
   • getCurrentLocation() gets a fresher, more accurate location more consistently. However, this method can cause active location computation to occur on the device

   fusedLocationClient
     .getCurrentLocation(Priority.PRIORITY_HIGH_ACCURACY, null)
     .addOnSuccessListener { location: Location? ->
       ...
     }
   

   b. Approach 2 - Implement a background location service worker

   class LocationWorker(context: Context, param: WorkerParameters) :
       CoroutineWorker(context, param) {
       companion object {
           val workName = "LocationWorker"
       }
   
       private val locationClient = LocationServices.getFusedLocationProviderClient(context)
   
       override suspend fun doWork(): Result {
           if (ActivityCompat.checkSelfPermission(
                   applicationContext,
                   Manifest.permission.ACCESS_FINE_LOCATION,
               ) != PackageManager.PERMISSION_GRANTED
           ) {
               return Result.failure()
           }
           locationClient.getCurrentLocation(
               Priority.PRIORITY_BALANCED_POWER_ACCURACY, CancellationTokenSource().token,
           ).addOnSuccessListener { location ->
               location?.let {
                   Timber.d(
                       "Current Location = [lat : ${location.latitude}, lng : ${location.longitude}]",
                   )
               }
           }
           return Result.success()
       }
   }
   

6. In QuestionnaireActivity.handleQuestionnaireSubmit(), check that the application config parameter logQuestionnaireLocation is set to true and the application has ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION permissions.
   Add the geo-coordinates items - longitude, latitude & altitude - to the QuestionnaireResponse.

7. Add a util method to create a location resource capturing the details listed below.

   • Location.identifier - same id as that assigned to the Group resource in the questionnaire
   • Location.position - absolute geographic location
     • longitude - [required]
     • latitude - [required]
     • altitude - [optional]

8. The location resource above will be added to the QuestionnaireResponse's contained attribute.

Notes:

• • • should we process the current location when launching the questionnaire or when the questionnaire is submitted? @dubdabasoduba @f-odhiambo @ageryck

References

• Android Developers > Sensors and location > Access location in the background
• Android Developers > Sensors and location > Request location permissions
• Android Developers > Sensors and location > Get the last known location

[pld]

@qiarie looks great! Some questions below:

a. Is the background worker in (3) always running or do we call it on demand when we want to get the gps, if always, is that so we do not need to wait for the gps to sync when we want to collect it?
b. Can you describe step (4) in more detail, how does this retrieve the location from the background worker?
c. In (5) and generally, how do we associate the newly created location with the QR created on submit? The obvious approach might be to link the QR to an Encounter, and link that Encounter to a Location, does all QR processing already create an Encounter? I think the answer is yes, or if it is no, it's reasonable that it should be yes.
d. Related (c) where do we hook this to the current code? It's reasonable that this a required post QR creation (pre or post save?) that always creates an Encounter and a Location
e. This will need to fail gracefully if the user does not provide the app with location permissions, any thoughts on how to manage that?

[qiarie]

@pld Currently investigating and updating the description to address the queries

[qiarie]

@pld
a. Is the background worker in (3) always running or do we call it on demand when we want to get the gps, if always, is that so we do not need to wait for the gps to sync when we want to collect it?
- The initial option of using a service worker may be too resource-intensive. I have added the implementation option to pick the current location when launching/submitting the questionnaire without the need to start a worker

b. Can you describe step (4) in more detail, how does this retrieve the location from the background worker?
- Added the FusedLocationProviderClient option that does not require an always-running service worker

c. In (5) and generally, how do we associate the newly created location with the QR created on submit? The obvious approach might be to link the QR to an Encounter, and link that Encounter to a Location, does all QR processing already create an Encounter? I think the answer is yes, or if it is no, it's reasonable that it should be yes.
- One of the items discussed with the team is to leave the geo-coordinates in the QR for use at any other time

d. Related (c) where do we hook this to the current code? It's reasonable that this a required post QR creation (pre or post save?) that always creates an Encounter and a Location
- This is to be done during handleQuestionnaireSubmit() in QuestionnaireActivity
- Still in discussions on how to handle extractions if any

e. This will need to fail gracefully if the user does not provide the app with location permissions, any thoughts on how to manage that?
- I have included checks for permissions and the logging config option in the description

[pld]

For (c) if we leave them in the QR how do we attach them to that QR? I think we'd need to on-the-fly edit QR and matching Q, which does not sound like a good idea.

For (d) that makes sense for where in the code.

The broader issue related to (c) and (d) is that we want to be able to

1. always store the location in the same format whenever a QR is created, so on the analytics side we can consistently query the location, and
2. have an interface to access the location data in the extraction step, in case extraction wants to do something special with the location.

(1) certainly is a requirement. It's not clear to me if (2) is a requirement or a nice-to-have, @ageryck do you have a perspective on this?

[dubdabasoduba]

@qiarie @pld

How to store the collected GPS coordinates.

• I think based on our last conversation we agreed to bind the GPS coordinates to the QR by using the QuestionnaireResponse.contained attribute. We currently use it to store references of all the resources generated from that QR.

• The idea is to Create a Location resource and add it to the QuestionnaireResponse.contained attribute.

• When editing questionnaire responses we generate a new QR, this means that each QR will contain its own Location Resources binding.

When to collect the GPS coordinates.

• I think we should collect the GPS coordinates when the user exits the form. The user can exit the form by clicking Submit or going back (this means we can still collect the GPS data even for partially saved forms)

[qiarie]

This is noted @dubdabasoduba

[pld]

Two questions

1. In the case of editing, those this mean a Questionnaire may have multiple Locations linked to it through contained? Basically the list of Locations whenever it was interacted with?
2. Relatedly, if you go back, do we save a draft QR that is opened later? That sounds like a prerequisite for what you're describing, I didn't realize we are doing that if we are
3. Because it takes time to get a GPS fix, would this process happen in the background and to the user the form would appear completed, or would it need to block on submission and wait for a GPS fix? Both seem problematic from a UX perspective, if it appears completed but if actually backgrounded while getting a GPS fix, the user will not a see eg a Patient they were expecting to show up in the Patient list until that background task is complete. If it's foregrounded, the user has to wait an unpredictable amount of time to get the GPS fix / for the QR to submit. Maybe best solution is to split it, save the QR, have the background task only for adding the Location. What's the plan here?

[ageryck]

Thanks @qiarie for the elaborate scope, I am a bit late to the party.

@pld @dubdabasoduba

1. For editing the contents of the QR would be overwritten with the new edits, the behavior should not be any different for location however there's a caveat based on how field teams work. Currently, we do not support editing however when we are finally able to edit, the feature will support CHWs making edits on various locations different from where they originally collected the data, I, therefore, think we can limit GPS capture to initiate on questionnaire launch and once collected not to be overwritten on edits and here are my reasons;

• Having single capture would ensure a single, authentic, and consistent location data captured from where the questionnaire was launched which is highly likely where the service occurred
• Initiating capture on form launch will allow for backgrounding the GPS capture process while the user fills the questionnaire (this will need to be tested for the short questionnaires)

2. That's what we should do but we aren't doing that currently, agree it would be a prerequisite
3. If my proposed capture GPS on questionnaire launch may have limitations then an isolated background task attaching locations to completed QRs is an option

Additionally, @qiarie's steps 6 above can rely on the SDK GPS capture work that will use a questionnaire extension to add a hidden location picker that somewhat will need auto-capture and not user-initiated. Adding the locations readings to a normal questionnaire response item or in the proposed QuestionnaireResponse's contained attribute is OK as long this is consistent

[dubdabasoduba]

@pld

1. In the case of editing, those this mean a Questionnaire may have multiple Locations linked to it through contained? The list of Locations whenever it was interacted with?

I corrected a typo. Each QR will have a Location resource tied to it. Since we generate new QRs during editing it's highly likely that each QR will end up having 1 Location.

2. Relatedly, if you go back, do we save a draft QR that is opened later? That sounds like a prerequisite for what you're describing, I didn't realize we are doing that if we are

Yes, we have this. It was done when scoping the Health Tasks workflow #1557 and worked on this ticket #1631

3. Because it takes time to get a GPS fix, would this process happen in the background and to the user the form would appear completed, or would it need to block on submission and wait for a GPS fix? Both seem problematic from a UX perspective, if it appears complete but is backgrounded while getting a GPS fix, the user will not a see eg a Patient they were expecting to show up in the Patient list until that background task is complete. If it's foregrounded, the user has to wait an unpredictable amount of time to get the GPS fix / for the QR to submit. Maybe best solution is to split it, save the QR, have the background task only for adding the Location. What's the plan here?

This raises valid concerns. I would go with the option of splitting the processes. We can combine the suggestion by @ageryck and the splitting. i.e. Start the service to pick the GPS coordinates when the form is launched but only create the Location once the form is submitted.

[qiarie]

@pld @ageryck @dubdabasoduba On point 3

3. Because it takes time to get a GPS fix, would this process happen in the background and to the user the form would appear completed, or would it need to block on submission and wait for a GPS fix? Both seem problematic from a UX perspective, if it appears completed but if actually backgrounded while getting a GPS fix, the user will not a see eg a Patient they were expecting to show up in the Patient list until that background task is complete. If it's foregrounded, the user has to wait an unpredictable amount of time to get the GPS fix / for the QR to submit. Maybe best solution is to split it, save the QR, have the background task only for adding the Location. What's the plan here?

This is in order. We can process the location tagging in the background.