Tech5 Integration - Enrollment updates #2701

avazirna · 2023-08-29T22:21:42Z

Summary

This PR is part of an ongoing initiative to integrate CommCare with Tech5 SDK. The goal of the current changes is to be able to capture biometric templates and send back to CommCare in a Base64 encoded String as part of a app callout question response.

Safety Assurance

I have confidence that this PR will not introduce a regression for the reasons below

shubham1g5

PR looks good to me though I think lack completion -

We should update the API docs
We need to write tests for new API in here

shubham1g5 · 2023-08-30T15:21:15Z

commcare-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricUtils.java

+
+public class BiometricUtils {
+
+    public enum BiometricIdentifier {


potentially worth to put into a separate file of it's own.

shubham1g5 · 2023-08-30T15:33:06Z

commcare-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricUtils.java

+import java.util.HashMap;
+import java.util.Map;
+
+public class BiometricUtils {


code formatting is off in the class.

shubham1g5 · 2023-08-30T15:45:03Z

commcare-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricUtils.java

+        // Base64 encoded String
+        Map<Integer, String> templatesBase64Encoded = new HashMap<>(templates.size());
+        for (Map.Entry<BiometricUtils.BiometricIdentifier, byte[]> template : templates.entrySet()) {
+            templatesBase64Encoded.put(template.getKey().ordinal(),


any reason we are double encoding templates, here and then later again at the end of this method ?

This is because JSON is used to represent the Map object, and considering that the values are byte arrays, the first encoding avoids representing them in JSON, which would increment the size due to the comas used to split the elements.

I am struggling to understand how will this gets used in the form. With current design, Seems like we are going to store into form the whole template string instead of storing the individual templates in individula field like Simprint. Any reason we are deviating away from Simprints pattern ?

@shubham1g5 the principle here is to use CC just to store the biometric templates and in the most simple way, so in a case property. any biometric operations will be preceded by the retrieval and restoration of the templates to their original format.

I meant why not store individiual templates in separate fields in form like here ?

It's more to avoid having to handle different form questions and case properties, when there is no apparent advantage to doing that. From my understanding, we are not doing anything with the biometric templates in CC. But I think that for the sake of standartization we could adopt the same pattern, but I wonder if you see any other gains from this.

If we store it together and an app is capturing multiple templates, how will they separate this data out in future without writing a script ? I think storing them seprately makes any future data management on those templates much simpler for project teams.

bee8e72b93a3b35d429a6ebc260b5df36b1bfa35

avazirna · 2023-09-04T09:13:31Z

@damagatchi retest this please

avazirna · 2023-09-04T11:31:37Z

@damagatchi retest this please

avazirna · 2023-09-04T12:52:38Z

@damagatchi retest this please

shubham1g5 · 2023-09-04T15:44:35Z

app/unit-tests/src/org/commcare/android/tests/formentry/IdentityCalloutTests.kt

+    fun testRegistrationWithTemplates() {
+        val formEntryActivity = ActivityLaunchUtils.launchFormEntry("m0-f1")
+
+        var templates : HashMap<BiometricIdentifier, ByteArray> =


seems to be duplicated here and then again in intendRegistrationWithTemplatesIntent

yeah, in the principle of separation of concerns, but we can move it to a global var

you can just pass the templates as a method param instead of making it a global var

That's a better option

shubham1g5 · 2023-09-04T15:46:45Z

...t-library/src/main/java/org/commcare/commcaresupportlibrary/identity/identity_integration.md

@@ -20,6 +20,11 @@ Often you will need this generated guid to be passed back to CommCare so that it
 IdentityResponseBuilder.registrationResponse(guid)
    .finalizeResponse(activity)
 ````
+Alternatively, in case the biometric templates are to be stored in CommCare, use the following instead -


We should add info on how a third party should construct templates as well.

Absolutely, I missed that one

shubham1g5 · 2023-09-04T16:02:34Z

...e-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricIdentifier.java

@@ -0,0 +1,7 @@
+package org.commcare.commcaresupportlibrary;


can we make sure that all biometric classes are in org.commcare.commcaresupportlibrary.identity package.

shubham1g5 · 2023-09-04T16:22:59Z

...e-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricIdentifier.java

@@ -0,0 +1,7 @@
+package org.commcare.commcaresupportlibrary;
+
+public enum BiometricIdentifier {


I don't think we wanna allow UNKNOWN or INVALID here.

shubham1g5 · 2023-09-04T16:35:17Z

commcare-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricUtils.java

+        // Base64 encoded String
+        Map<Integer, String> templatesBase64Encoded = new HashMap<>(templates.size());
+        for (Map.Entry<BiometricUtils.BiometricIdentifier, byte[]> template : templates.entrySet()) {
+            templatesBase64Encoded.put(template.getKey().ordinal(),


I am struggling to understand how will this gets used in the form. With current design, Seems like we are going to store into form the whole template string instead of storing the individual templates in individula field like Simprint. Any reason we are deviating away from Simprints pattern ?

shubham1g5 · 2023-09-04T16:35:47Z

commcare-support-library/src/main/java/org/commcare/commcaresupportlibrary/BiometricUtils.java

+     * @param base64EncodedTemplates String containing Base64 encoded biometric templates
+     * @return Map containing biometric templates
+     */
+    public static Map<BiometricIdentifier, byte[]> convertBase64StringTemplatesToMap(


where will this be used ?

In the biometric app, once the biometric templates are retrieved from the CC database, this will them be used to revert them into the original form.

avazirna · 2023-09-26T21:24:52Z

@damagatchi retest this please

avazirna · 2023-09-27T07:26:52Z

@damagatchi retest this please

avazirna · 2023-09-27T10:02:27Z

@damagatchi retest this please

shubham1g5 · 2023-09-28T17:34:36Z

app/src/org/commcare/provider/IdentityCalloutHandler.java

@@ -212,4 +236,11 @@ public static boolean isRegistrationResponse(Intent intent) {
    public static boolean isVerificationResponse(Intent intent) {
        return intent.hasExtra(IdentityResponseBuilder.VERIFICATION);
    }
+
+    public static void main(String[] args) {


How is main useful here ?

Shoot, just residual code from some testing I was conducting, I could swear that I removed everything by somehow some was left behind. My bad.

shubham1g5 · 2023-09-28T17:36:23Z

app/src/org/commcare/provider/IdentityCalloutHandler.java

+        if (registrationResult.getTemplates().isEmpty()) {
+            result = guid;
+        } else {
+            result = Localization.get("intent.callout.biometrics.capture.result",
+                    new String[]{String.valueOf(numOfTemplatesStored), String.valueOf(numOfTemplates)});
+        }


I see that we store this for Simprints, but we should be consistent in our implementation and can always store guid in the node value. (Unless you see a strong reason to do otherwise)

My reasoning here is to provide some feedback to the user in terms of the number of biometrics that was successfully captured (and stored). It can be that we scan 4 fingers but the callout handler is only able to store 2 due to a misconfiguration in the app. But not a hard requirement, I'm happy to drop this and maybe wait for feedback.

Got it. That makes sense to me although I am worried about supporting 2 different return formats to the callout question. I am thinking about case exports where some fields might have guid and some fields this string which might be confusing to interpret for the data systems incorporated by a project.

That said I do like the idea of telling to user whether everything was saved correctly or not. How about we just say All data stored successfully or Failed to store some data to indicate failure vs success in both templates and non templates use cases here.

shubham1g5 · 2023-09-28T17:51:16Z

...pport-library/src/main/java/org/commcare/commcaresupportlibrary/identity/BiometricUtils.java

+        String templatesInJson = new Gson().toJson(templatePairBase64Encoded);
+        return Base64.encodeToString(templatesInJson.getBytes(), Base64.DEFAULT);


why convert to Json before encoding instead of just doing Base64.encodeToString(template, Base64.DEFAULT)

Here's the idea is to bundle the BiometricIdentifier with the template. It is redundant as we use the callout response key to identify the type of biometric but I think it could be useful to have a second layer of identification. For instance, the app builder can make a poor choice of case property name and have difficulties later to know if the template is of a finger or a face. We could also use the position 0 of the array for this. Any thoughts?

For instance, the app builder can make a poor choice of case property name and have difficulties later to know if the template is of a finger or a face

I don't think its a valid concern. App builders can name the properties of other fields poorly too (First Name to Last Name for ex) and we should not take into account such mistakes to make decisions at platform level. I would rather rgo for simplicity here and just store the template directly in the case property.

shubham1g5 · 2023-09-28T17:54:39Z

app/unit-tests/resources/commcare-apps/identity_callouts/modules-0/forms-0.xml

@@ -1,58 +1,91 @@
 <h:html xmlns:h="http://www.w3.org/1999/xhtml" xmlns:orx="http://openrosa.org/jr/xforms" xmlns="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://openrosa.org/javarosa" xmlns:vellum="http://commcarehq.org/xforms/vellum">
-	<h:head>


nit: diffs like this are very hard to review and should be avoided. Will you be able to highlight what's changed here with comments at the very least.

it is confusing, do we have a practice around this? I just made the modification in HQ, downloaded the app and replaced the files.

We should only change the parts that changed. I generally edit the files by hand manually to add the new/modified parts.

I undid this and followed your advice - e81b21b

shubham1g5 · 2023-09-28T18:10:13Z

app/unit-tests/src/org/commcare/android/tests/formentry/IdentityCalloutTests.kt

@@ -96,6 +99,25 @@ class IdentityCalloutTests {
        assertEquals(guidToConfidenceMap.elementAt(2), "★★★")
    }

+    @Test
+    fun testRegistrationWithTemplates() {


Can we also verify that converting back base 64 encoded templates to original templates using the support lib method indeed matches with original templates as part of this test.

shubham1g5 · 2023-09-28T18:11:27Z

...t-library/src/main/java/org/commcare/commcaresupportlibrary/identity/identity_integration.md

+IdentityResponseBuilder.registrationResponse(guid, templates)
+    .finalizeResponse(activity)
+````
+* `templates` is a [`Map`](https://docs.oracle.com/javase/8/docs/api/java/util/Map.html) containing all the biometric templates and whose _keys_ are [`BiometricIdentifier`](BiometricIdentifier.java) elements and _values_ are the actual biometric templates in the form of a byte array


We should add a sample code below this to give an example of how to construct templates using Biometric indentifiers.

avazirna · 2023-09-29T23:05:09Z

app/unit-tests/src/org/commcare/android/util/TestUtils.java

+    public static Object getFormValue(String expr) throws XPathSyntaxException {
+        FormDef formDef = FormEntryActivity.mFormController.getFormEntryController().getModel().getForm();
+        FormInstance instance = formDef.getMainInstance();
+        EvaluationContext ec = new EvaluationContext(instance);
+        return ExprEvalUtils.xpathEval(ec, expr);
+    }


@shubham1g5 I have created this method to retrieve a value from a form question, but I wonder if there isn't a method to do this already.

shubham1g5

looks great, one minor comment.

shubham1g5 · 2023-10-02T18:27:06Z

commcare-support-library/build.gradle

@@ -57,6 +57,8 @@ dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.android.support:appcompat-v7:26.1.0'
    implementation 'com.android.support.constraint:constraint-layout:1.0.2'
+    implementation 'com.google.code.gson:gson:2.9.0'


do we still need this ?

good catch, it's not needed.

avazirna added 5 commits August 29, 2023 23:55

Add biometric templates to RegistrationResult

df52ded

Add new registrationResponse that support biometrics template

35902ce

Add Gson dependency

e437a58

Add Biometrics utility class

07aae64

Store templates in form

770a917

avazirna requested a review from shubham1g5 August 29, 2023 22:42

avazirna added 3 commits August 30, 2023 11:17

Add method to convert Base64 string to map

8562c78

Refactor

752c3cb

Update biometric identifiers

4a79c49

shubham1g5 requested changes Aug 30, 2023

View reviewed changes

avazirna added 2 commits September 1, 2023 18:18

Refactor

8072f09

Add Tests around registration with templates

b01cf21

avazirna self-assigned this Sep 1, 2023

avazirna marked this pull request as ready for review September 1, 2023 22:27

avazirna requested a review from shubham1g5 September 4, 2023 08:03

Update documentation

7cbaa5d

shubham1g5 requested changes Sep 4, 2023

View reviewed changes

avazirna added 3 commits September 5, 2023 23:51

Refactor

c19496b

Remove unnecessary biometric identifiers

73d6a98

Refactor

9d5df75

avazirna added this to the 2.54 milestone Sep 14, 2023

avazirna added 2 commits September 26, 2023 15:32

Add callout response key to biometric identifiers

9371986

Change conversions to work with individual templates instead of a map

1786eb2

avazirna requested a review from shubham1g5 September 26, 2023 14:34

shubham1g5 requested changes Sep 28, 2023

View reviewed changes

avazirna added 5 commits September 30, 2023 00:18

Add biometric templates to callout response individually

756586f

Add method to retrieve value from form question

2128bd8

Update tests

e81b21b

update documentation

118435a

Remove BiometricUtils class

1d1d439

avazirna force-pushed the tech5-support-library-update branch from c49a74e to 1d1d439 Compare September 29, 2023 22:44

avazirna commented Sep 29, 2023

View reviewed changes

avazirna requested a review from shubham1g5 September 29, 2023 23:07

shubham1g5 reviewed Oct 2, 2023

View reviewed changes

Drop GSON library

7fcc0a3

shubham1g5 previously approved these changes Oct 2, 2023

View reviewed changes

Resolve merge conflicts

891b338

avazirna dismissed shubham1g5’s stale review via 891b338 October 3, 2023 09:11

avazirna requested a review from shubham1g5 October 3, 2023 12:02

shubham1g5 approved these changes Oct 3, 2023

View reviewed changes

avazirna merged commit c0340d4 into master Oct 3, 2023
4 of 11 checks passed

avazirna deleted the tech5-support-library-update branch October 3, 2023 14:43


		public class BiometricUtils {

		public enum BiometricIdentifier {

		@@ -0,0 +1,7 @@
		package org.commcare.commcaresupportlibrary;

		public enum BiometricIdentifier {

		String templatesInJson = new Gson().toJson(templatePairBase64Encoded);
		return Base64.encodeToString(templatesInJson.getBytes(), Base64.DEFAULT);

		@@ -1,58 +1,91 @@
		<h:html xmlns:h="http://www.w3.org/1999/xhtml" xmlns:orx="http://openrosa.org/jr/xforms" xmlns="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://openrosa.org/javarosa" xmlns:vellum="http://commcarehq.org/xforms/vellum">
		<h:head>

Tech5 Integration - Enrollment updates #2701

Tech5 Integration - Enrollment updates #2701

Conversation

avazirna commented Aug 29, 2023

Summary

Safety Assurance

shubham1g5 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avazirna Sep 1, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avazirna commented Sep 4, 2023

avazirna commented Sep 4, 2023

avazirna commented Sep 4, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avazirna commented Sep 26, 2023

avazirna commented Sep 27, 2023

avazirna commented Sep 27, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shubham1g5 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avazirna Sep 1, 2023 •

edited

Loading