1. Home
  2. Data Management
  3. Guide: ODK Briefcase

Guide: ODK Briefcase

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:

  1. Export forms with submissions from Ona or any other ODK Aggregate server – PULL
  2. Make bulk form submissions to Ona and any other ODK Aggregate server – PUSH
  3. Export form submission data in CSV format.
  4. Pull forms and submissions collected by ODK Collect from a mobile device.
  5. 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

  1. Java 6 or higher must be installed on your computer. If you do not have Java on your computer, you can download it here: http://java.com/en/download/index.jsp.
  2. Once Java is installed, download ODK Briefcase here: http://opendatakit.org/software/odk1/#briefcase

How to PULL forms with submissions from Ona

  1. 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.
  2. On the tab Pull, click on the dropdown to the right of Pull data from, choose Aggregate server, and select the Configure button.
  3. 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.
  4. In the main window, select the form(s) you wish to download and select the Pull button
    at the bottom right of the window.
  5. Wait until you see the Success message under the Pull status.

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.

  1. Switch your Android device off and then on; this ensures that your device only shows the current set of files;
  2. Mount your mobile device to your computer using the USB cable;
  3. 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.
  4. Open ODK Briefcase. On the Pull tab, click on the drop-down menu to the right of Pull data and choose Collect Directory.
  5. 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

  6. 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.
  7. Wait until you see the Success message for the form(s) you pulled.
  8. 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).
  9. 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.

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.

  1. In the ODK Briefcase application, click on the Push tab.
  2. Click on the drop-down to the right of Push data to and choose Aggregate. Then click the Configure button next to it.
  3. 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.
  4. 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.
  5. Wait until you see the Success message in the Pull Status section on the application.

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!

Difference between pulling from a directory and drive

Android 4.x (and later) devices

Android 2.x devices

Related Articles