Guide: ODK Briefcase

Contents

As of December 2021, ODK Briefcase will no longer be updated. However, you can still use it to pull/push forms and data and decrypt forms. More information can be found on the ODK Forum.

What is ODK Briefcase?

ODK Briefcase is used to gather and pull data from (or push data to) an ODK Aggregate server, e.g. ona.io. Additionally, ODK Briefcase can be used to aggregate form submission data from ODK Collect when you are offline.

ODK Briefcase can:

Export forms with submissions from Ona or any other ODK Aggregate server – PULL
Make bulk form submissions to Ona and any other ODK Aggregate server – PUSH
Export form submission data in CSV format.
Pull forms and submissions collected by ODK Collect from a mobile device.
Decrypt form submission data: ODK Briefcase is required to decrypt form submission data from ona.io when exporting the data to CSV format.

Points 1 and 2 require an internet connection, while points 3-5 can be done offline.

Encrypted form submission data cannot be viewed on ona.io. Ona stores these form submissions in an encrypted format. In order to view the data, the user must export the submission data using ODK Briefcase and provide the private key while exporting the data in CSV format.

How to install ODK Briefcase

Since ODK Briefcase was deprecated in December 2021, the latest Java versions are not supported. You need to make sure your computer has Java installed, and the version should not be later than java-301. If you have a later version, you need to downgrade it by uninstalling and installing an earlier version. You can download it here.
Once Java is installed, download ODK Briefcase here: http://opendatakit.org/software/odk1/#briefcase

NOTE: If you are trying to export data with a background-audio question type or audit metadata type, you should use the ODK Briefcase version provided on this link.

How to PULL forms with submissions from Ona

When first starting ODK Briefcase, you will need to specify the location of the ODK Briefcase storage area on your computer. This will create the ODK Briefcase Storage folder, which will hold all your forms and submission data. This storage location can also be changed later under the settings tab.
On the tab Pull, click on the dropdown to the right of Pull data from, choose Aggregate server, and select the Configure button.
In the new window that opens, enter https://odk.ona.io/YOUR_USERNAME as the URL, along with your Ona username and password. Then, click on the Connect button.
In the main window, select the form(s) you wish to download and select the Pull button
at the bottom right of the window.
Wait until you see the Success message under the Pull status.

Below is a video that shows how you can pull submissions using ODK Briefcase:

Export data in ODK Briefcase

Once you have successfully pulled submissions from Ona, you can export the data in ODK Briefcase by following these steps:

Navigate to the Export tab in ODK Briefcase.
Click the settings icon next to the form that has successfully pulled submissions.
On the following page, choose the export directory where you would like to save the exported files and click OK.
In the main window, select the form(s) you wish to export, and click the Export button, located at the bottom right of the window.

Get data off your mobile devices and do bulk submissions to Ona with ODK Briefcase

ODK Briefcase can also be used to pull data from ODK Collect from your mobile device and then push it to Ona. This is especially useful for users who are unable to make form submissions directly to Ona due to slow or lack of internet connectivity on their mobile devices.

Before going through the steps below, please ensure that all forms on the mobile device are finalized; this is due to the fact that ODK Briefcase does not discriminate between incomplete and finalized forms when pulling form submissions from ODK Collect. Steps 3-5, below, are slightly different for Android 4.x, Android 2.x (or earlier), and Android 10.x (and later) devices.

Switch your Android device off and then on; this ensures that your device only shows the current set of files;
Mount your mobile device to your computer using the USB cable;
For Android 4.x devices, copy the entire odk directory (found in /sdcard/odk/) from the mounted MTP/Android device to a local hard drive. For Android 10.x (and later) devices, the directory can be found in /sdcard/Android/data/org.odk.collect.android/files. For Mac OS/X, use Android File Transfer. For Windows, drag and drop the entire odk directory into a folder on your PC.
Open ODK Briefcase. On the Pull tab, click on the drop-down menu to the right of Pull data and choose Collect Directory.
Click on the Configure button. In the window that opens, select either the odk folder that was copied onto your local hard drive (For Android 4. x or later devices) or the mounted SD card (Android 2. x or earlier devices).

Note: For Android 10.x or later devices, the folder is named files
In the main window, tick off the check box next to the form(s) you want to pull and click the Pull button at the bottom right corner. The form submissions that were copied off of the device will be loaded into the ODK Briefcase storage location.
Wait until you see the Success message for the form(s) you pulled.
Confirm that the form submissions have been successfully pulled by locating them within the instances directory inside the ODK Briefcase Storage folder (e.g., ODK Briefcase Storage/forms/Tutorial XLSForm 2/instances).
Once you have verified that the form submissions have been successfully transferred, you can delete the forms in ODK Collect to prevent duplicate form submissions.

Below is a video that outlines how to go about this process:

How to make bulk form submissions to Ona – PUSH

Once form submissions have been pulled from an ODK Aggregate server or from a mobile device’s ODK Collect application, ODK Briefcase can be used to Push these submissions to the Ona server.

In the ODK Briefcase application, click on the Push tab.
Click on the drop-down to the right of Push data to and choose Aggregate. Then click the Configure button next to it.
A dialog box will pop up; enter the server details, enter https://odk.ona.io/YOUR_USERNAME as the URL, along with your Ona account username and password, then click on the Connect button.
In the main window, check the box next to the form submission(s) you want to push to Ona then click on the Push button at the bottom right of the window and the data will be submitted to the Ona server.
Wait until you see the Success message in the Pull Status section on the application.

Note
If the form already exists in the Ona account that you are pushing data to, then the form publishing will fail but the data submission will pass, and the Push Status in this case will be Partially successful!