Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Intent Callout to External Application
CommCare Intent Callout Callout
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 Form Structure
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 -->
External Application Callout
When OpenDataKitCollect makes an intent callout using an
<intent> declaration, it will use the following intent structure:
Action: Defined by
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
External Application Response
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"
string] - A single string value that will set the value of the element for that question
bundle] (Since 2.6) - A bundle of values which will be processed according to the
<intent>definition used in the callout.
Bundle Response Parsing
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).