How does external apps work in ODK-X

Support
1

We use a custom development fingerprint application which enrols or verifies a fingerprint depending on the use case. This is very crucial to our study and I don’t want to lose the biometric functionality once we move to ODK-X. We launch this as an external app on a prompt in the ODK form, the app does its job and returns a value back to the form.

Now that we plan on moving to ODK-X tools, I wonder how does the external apps work with them. I have looked through the documentation but I haven’t quite figured out.

2

This should be doable in ODK-X! It can work with external apps.

This is a bit jargon-y, but explains the idea – external apps are referred to as “arbitrary intents”

https://docs.opendatakit.org/odk-x/injected-interfaces/#odkcommon-js

3

The Android ability to call intents (i.e. use third party apps) mechanism from the link @elmps2018 provide is the doAction call. https://docs.opendatakit.org/odk-x/injected-interfaces-methods/#doaction

Other useful links if you want to do it within ODK-X Survey. You can even create your own prompt type using HTML/JavaScript.

https://docs.opendatakit.org/odk-x/xlsx-converter-using/#customizing-prompts

To define how to store multiple values or new value types used for whatever biometrics you want to store see:
https://docs.opendatakit.org/odk-x/xlsx-converter-reference/#custom-prompt-types

NOTE: Survey automatically looks for a file name “customPromptTypes.js” that is in the same directory as the XLSX file.

An example is the breathcounter custom type:
https://github.com/opendatakit/app-designer/tree/master/app/config/tables/breathcounter

Here is an example of a custom breathcounter and pulse-ox sensor:
https://github.com/clarlars/app-designer/tree/IMGCI-06-02/app/tables/mPneumonia/forms/mPneumonia
NOTE: this example uses an older file structure so not as relevant where to put the files, but helpful in the looking at the form XLSX. The file structue was revised to this: Application Configuration File Structure — ODK-X Docs

4

I have a related question. I have seen examples of how the external app can return the data (for eg. breathcounter). However, in my case, I want to pass the unique ID of my participant from the form to the external app. I modified the CustomPromptTypes.js file from the breathcounter sample and have tried using “intentParameters” and it worked with a hardcoded value that I wanted to pass. However, I don’t understand how to get the value of a field from my form here to pass it on to the external app. Any ideas how can this be done?

1 Like
5

I was able to figure this out. If it is of help for anyone else, this is what I did to make it work.
My objective was to pass the unique study ID (field:pid) and age (field:age) of the participant to the external app, and for that I created a custom prompt called ‘passPID’ and added the following code to the customPromptTypes.js. This launched the external application and passed the data as well. Of course, the external app must be programmed to capture this data.

"passPID" : promptTypes.launch_intent.extend({
    type: "passPID",
    datatype: "string",
    buttonLabel: {
        'default': 'Launch external app to pass participant ID',
    },
    configureRenderContext:
        function(ctxt){
            var that = this;
            var value  = that.getValue();
            that.intentParameters.extras.pid = that.database.getDataValue("pid")
            that.intentParameters.extras.age = that.database.getDataValue("age")
            that.renderContext.value=value;
            that.renderContext.buttonLabel = that.buttonLabel;
            ctxt.success();
        },
    intentParameters:{
        extras:{
            pid:"pid",
            age :"age"
        }     
    },
    intentString: 'com.xxxxxxxxxxxxxxxxxxx',     //intent name
    extractDataValue: function(jsonObject) {
        return jsonObject.result.value;
    }
})
2 Likes