Use ODK Briefcase to easily gather and aggregate data from ODK Collect when you are without internet connectivity or do not want to set up an ODK Aggregate server (or other ODK-compatible server).
Additionally, you can use ODK Briefcase to incrementally pull data from ODK Aggregate (or push data to ODK Aggregate); the resulting local copy of your data can then archived or transformed by your own tools and transmitted to a third-party application.
ODK Briefcase can:
- pull blank forms and finalized forms (submissions) from ODK Collect or ODK Aggregate into a local ODK Briefcase Storage location.
- push blank forms and finalized forms (submissions) from the ODK Briefcase Storage location up to an ODK Aggregate 1.0 instance.
- export the finalized forms (submissions) to a CSV file for processing by other applications.
By pulling data into the local ODK Briefcase Storage location and then pushing data up to an ODK Aggregate instance, ODK Briefcase provides a mechanism to transfer data across incompatible upgrades of ODK Aggregate (e.g., between ODK Aggregate 0.9.8.1 and ODK Aggregate 1.0.x).
If a form is encrypted, ODK Briefcase is also the only mechanism to decrypt the finalized forms and generate a CSV of their unencrypted contents.
- Make sure Java 6 or higher is installed on the computer you plan to use. If it is not, download and install it.
- Navigate to http://code.google.com/p/opendatakit and in the green Featured Downloads selection, download ODK Briefcase vN.N.N.jar.
- Double click the file to start. If that fails, try running 'java -jar path_to_jar' from the command line.
Upon first starting, Briefcase will ask for the directory under which to create the ODK Briefcase Storage area. An ODK Briefcase Storage folder will be created here to hold all the blank forms and finalized forms (submissions). Once created, you can copy and transport this storage folder across systems, just like a briefcase of paper documents.
When pulling forms from ODK Aggregate, you can either leave the username blank if the
anonymousUser is granted Data Viewer permissions, or specify an ODK Aggregate user (Account Type 'ODK') that has been granted Data Viewer permissions. ODK Briefcase does not work with Google accounts (Account Type 'Google').
When pushing forms to ODK Aggregate, you can either leave the username blank if the
anonymousUser is granted Form Manager permissions, or specify an ODK Aggregate user (Account Type 'ODK') that has been granted Form Manager permissions. ODK Briefcase does not work with Google accounts (Account Type 'Google').
ODK Briefcase will abort a pull attempt if the local copy of the form definition file differs in any way from the copy being pulled from the server or ODK Collect device. In this case, if the changes only affect the question text and do not alter the structure of the collected data (or change the formId or version), you can create a new ODK Briefcase Storage area, pull data into that, then manually copy the instances from there into your original storage area. If you do this, and need to continue to incrementally pull data from that ODK Aggregate, you should keep this new ODK Briefcase Storage area for future pull attempts; as long as that storage area retains all copies of the data already fetched, incremental pulls can be efficiently performed; if the copies are missing, the data will be re-fetched in its entirety, which can be expensive and time consuming.
Similarly, ODK Briefcase will abort a push attempt if the form definition already on the ODK Aggregate server differs in any way from the form definition in the ODK Briefcase Storage area. In this case, if these changes do not affect the data model, you can make a copy of the storage area, replace the copy's form definition file with that from the server, and then push the data up from this storage area copy.
Usage on Android 4.x and higher
Unfortunately, briefcase is designed to interface with mounted drives which means the MTP protocol that replaced the USB drive protocol in Android 4.x does not quit fit how Briefcase was designed to access mounted drives. One solution until a Java to MTP solution is found (suggestions and/or code patches welcome) is to use a computer's operating system that can recognized an MTP device and copy the ODK directory files into a local directory on the OS. The use the 'Custom Path to ODK Directory' option to specify the path to the local copy of the ODK directory.
- Mount an Android device running 4.x or later version of Android.
- Copy the 'odk' directory from the mounted MTP/Android device to a local hard drive
- Point Briefcase's 'Pull' functionality to the copied 'odk' directory.On the "Pull" tab in Briefcase you can use the "Pull data from:" drop-down to select "Custom Path to ODK Directory, then use the browse button to point Briefcase at the copied 'odk' folder on your local hard drive.
- Click the 'Pull' button and everything should happen automatically.
As a Replacement for ODK Aggregate
ODK Briefcase can pull data off ODK Collect devices, but does not support pushing blank forms to ODK Collect. To use ODK Briefcase as a replacement for ODK Aggregate, you must manually install the forms on your ODK Collect device. To do so, connect the device to your PC with a USB cable and turn on USB storage. On the PC, copy the form definition and media folder to the /odk/forms directory. Then turn off USB storage, run ODK Collect, and choose Fill Blank Form. ODK Collect will scan the directory for new forms, parse them, and make them available in this list. It can take several moments for large forms to appear. When ODK Collect has completed scanning for new forms, it will display
Finished scanning. All forms loaded. in the second line at the top of this screen.
- The developer wiki has release notes.