-
Notifications
You must be signed in to change notification settings - Fork 14
CommCareProfile
This document outlines the structure of the global application configuration which will be used in the converged CommCare app.
In addition to the modular suites which structure interactions in CommCare, individual applications will require a more global configuration in order to replicate the configuration of a fully customized application.
Many aspects of configuration are not declarative for the application's long-term usage (default property values, for instance) so although the profile is used to configure and update an application's behavior, it cannot be considered a purely declarative description of how the app is set up at any given time.
An application's profile is considered to consist of the following types of data (with examples)
- Properties ** Default Locale ** Purge Frequency ** Logging Enabled ** etc...
- User/Login Data ** Image to be used on Login Page ** User Decorator Options (possibly)
- Feature Activation ** Form Checkoff ** Authentication ** HQ Integration
- Package Details ** Link to where the most trustworthy Application Profile is ** Suites which should be included, and their locations
- Storage Connectors
CommCare applications will store the details of their profile in a somewhat decentralized manner after parsing a file and retrieving the configuration details. Profiles cannot meaningfully be stacked, that is to say that multiple profile documents won't be considered in effect at the same time.
An application's initial profile will generally be defined by the jad property
Profile:
which will provide an OpenRosa URI link to an XML definition (Often made available as an application resource).
Profile documents (once parsed and read) can trigger the following actions:
- Set the value of a property
- Force the value of a property to change
- Trigger a suite update
The XML definition of a profile document is as follows
<profile version="" update="" requiredMajor="" requiredMinor="" uniqueid="" name="">
<!-- version provides a standard version integer. update provides a URI for an application to check for the next version of this profile. requiredMajor and requiredMinor are optional, but specify a minimum version of the CommCare specification that the application needs to support. IE, 1, and 3 respectively would require CommCare 1.3's specification to be met on the application. uniqueid and name are optional but highly recommended, as they are used to provide full functionality in multiple application seating -->
<property key="" value="" force=""/> <!-- 0 or More : JR Properties. 'force' is one of "true"/"false" and if not present is assumed to be "false". Set 'force' to "true" to override any settings already on the phone. -->
<!-- Roots are not currently supported in CommCare's specification -->
<!--root prefix="" readonly=""> <!-- 0 or More : Resource ID for jr://id/. readonly is one of "true"/"false", and is assumed "true" if not present-->
<!-- Can only have 1 child -->
<!--resource path=""/> <!-- 0 or 1 : Java Resource -->
<!--filesystem path=""/> <!-- 0 or 1 : Filesystem Access -->
<!--/root-->
<features> <!-- 0 or 1: Features which should be included/excluded from the application -->
<checkoff active=""> <!-- 0 or 1: Whether From Checkoff is enabled. active is one of "true"/"false". If not present, defaults to false -->
</checkoff>
<!-- Reminders are not currently supported in CommCare's specification -->
<!--reminders active=""> <!-- 0 or 1: Whether Referral Reminders are enabled. active is one of "true"/"false". If not present, defaults to false -->
<!--time/> <!-- 1: # of days delay before reminder pops up -->
<!--/reminders-->
<package active=""> <!-- 0 or 1: Whether custom suite management app is enabled. active is one of "true"/"false". If not present, defaults to false -->
<location/>
</package>
<user active=""> <!-- 0 or 1 : Whether users should be used in the binary. Defaults to true-->
<registration/> <!-- 0 or 1 : The XMLNS of an xform which will be used to collect user details. Must be installed by a suite -->
<logo/> <!-- 0 or 1 : A jr:// reference to an image which should be displayed on the login page -->
</user >
<dependencies active="true"> <!-- 0 or 1 : Specifies any dependencies on external android applications that must be present on device before user can use this application -->
<android_package id="org.commcare.test"/> <!-- 0 or more : Describes individual android package dependency with id being the android package id for the external android package -->
</dependencies>
</features>
<suite> <!-- 0 or More: Suites which should be installed and their version -->
<resource/> <!-- 1 or More: Location/authority of the resource for the suite definition -->
</suite>
</profile>
CommCare has a number of settings which can be used to customize the user experience once the application is running. These are set by the properties in the profile file when they are available in a CommCare client. Properties which are not available in an environment will be ignored.
A list of these properties is provided at:
An Example Profile is provided from CommCare Pathfinder
<profile version="1" update="jr://resource/profile.xml" requiredMajor="1" requiredMinor="0">
<property key="purge-freq" value="7" force="true"/>
<property key="PostURL" value="http://data.commcarehq.org/receiver/submit/test" force="true"/>
<property key="PostTestURL" value="http://staging.commcarehq.org/receiver/submit/test" force="true"/>
<property key="ota-restore-url" value="http://data.commcarehq.org/ota_restore/"/>
<property key="ota-restore-url-testing" value="http://staging.commcarehq.org/ota_restore/"/>
<property key="cc-review-days" value="7"/>
<property key="cur_locale" value="sw"/>
<property key="logenabled" value="Enabled"/>
<property key="log_prop_weekly" value="log_short"/>
<property key="log_prop_daily" value="log_never"/>
<features>
<checkoff active="true"/>
<package active="false"/>
<users active="true">
<registration>http://dev.commcarehq.org/Pathfinder/user_registration</registration>
</users>
</features>
<suite><resource id="pathfinder_houshold" version="1">
<location authority="local">jr://resource/pathfinder_household.xml</location>
</resource></suite>
</profile>