-
-
Notifications
You must be signed in to change notification settings - Fork 27
Intent Callout to External Application
CommCare supports calling out to an intent on the filesystem and receiving a result from an activity which handles that intent. Further, CommCare expands on this capability and supports passing arguments from the current form context, passing encryption keys to ensure that data is not stored unencrypted to the filesystem, and receiving structured responses which can be integrated back into the form.
You can configure your application to receive these callouts and create and return structured data to a form upon request.
CommCare allows for the definition of an arbitrary number of intent element declarations in the head of a document declaration. These elements have the following structure
#!xml
<odkx:intent id="" class="" xmlns:odkx="http://opendatakit.org/xforms"> <!-- 0 or More: An intent definition which can be used by question declarations
id (Exactly One): The id of this intent. Will be referenced by form elements
class (Exactly One): The Android action which will be used in the intent callout-->
<extra key="" ref=""/> <!-- 0 or More: A data value which will be passed in the bundle of the intent
key (Exactly One): The string key for an extra value which will be included in the intent bundle
ref (Exactly One): An XPath reference to a string value which will be passed in the intent extra-->
<response key="" ref=""/> <!-- 0 or More: (Since 2.5) A value which will may be returned from a successful callout and should be loaded into the XPath reference specified
key (Exactly One): The string key for an extra value which will be included in the return bundle
ref (Exactly One): An XPath reference to node whose value should be set by the response intent (if it exists) -->
</odkx:intent>
A question can perform an intent callout by being defined with the appropriate datatype and appearance
#!xml
...
<bind nodeset="/data/myquestion" type="intent" ...>
...
<input ref="/data/myquestion" appearance="intent:MYINTENTID"> <!-- the value after the colon should be the id value used in the intent declaration -->
When CommCare makes an intent callout using an <intent> declaration, it will use the following intent structure:
Action: Defined by <intent> attribute class
**Extras: **
-
key_aes_storage[byte[]] (Since 2.6)(Optional) - A raw AES symetric key. If any file references are returned from this callout, they should be encrypted by this key. - Optional extras defined by
<extra>elements
The responding application should the appropriate response code (success v. cancelled) when it returns, along with one of the following extras if the response code is "success"
-
odk_intent_data[string] - A single string value that will set the value of the element for that question
and/or
-
odk_intent_bundle[bundle] (Since 2.6) - A bundle of values which will be processed according to the<intent>definition used in the callout.
Upon receiving a bundle response, CommCare will retrieve the intent callout and iterate through the <response> definitions one by one. For each, it will convert the string response into the appropriate datatype for the node's binding and set the value. If the node is bound to a binary value (Image, audio file, etc), CommCare will interpret the response value as a file path, and will copy the file into the appropriate location as if it were captured live (by the camera, sound recorder, etc).