Skip to content

Intent Callout to External Application

ctsims edited this page Apr 3, 2019 · 3 revisions

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 <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

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"

  • 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.

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).

You can’t perform that action at this time.