< All Topics

Pushing, Pulling, and Logs in ODKBriefcase


Pushing forms to ODK Aggregate 

  1. Open the Push tab.
  2. Select Aggregate server in the Push to drop-down.
  3. Click the Configure button.
  4. Enter the URL and login credentials for your Aggregate server in the dialog that pops up and click the Connect button.
    1. If you have anonymous login enabled on Aggregate, no login credentials are needed here.
  5. Select the forms you want to upload and click Push. The selected forms will be pushed from your Briefcase Storage to the Aggregate server.
    1. For each selected form, Briefcase will upload:
    2. The form definition file (that is, the blank XForm).
    3. All media associated with the form.
    4. Completed form instances, including all their attached media files.


Pulling from ODK Collect (in relation to ODK Aggregate online)

ODK Collect is an open source Android app that replaces paper forms used in survey-based data gathering. It supports a wide range of question and answer types, and is designed to work well without network connectivity. Please refer the the Handbook section on ODK Collect installation before proceeding with these steps, if it is the tool you want to use. 

Please use ODK Collect if you are are using KoBo Toolbox, instead of ODK Collect.


  1. Ensure all filled-in forms are finalized.
    1. If you have incomplete forms that you cannot finalize before pulling into Briefcase, delete them.
  2. Create a zip archive of the entire odk directory
    1. You’ll need to use an app to do this, we would recommend OI File Manager as an option.
  3. Connect your Android device to your computer using a USB cable and choose to mount it as a Media device.
  4. Copy the zip file you created from the Android device to your local hard drive.
  5. Once it is copied onto your local hard drive, unzip the file.
  6. In Briefcase, open the Pull tab.
  7. Select Collect directory in the Pull from drop-down.
  8. Click the Configure button and select the unzipped odk folder.
  9. Select the forms you want to download and click Pull. The selected forms will be pulled to your Briefcase Storage location.
  10. On the Android device, open Collect and delete the filled-in forms

Briefcase cannot discriminate between duplicate form instances. After you pull completed forms into Briefcase, it is important that you delete them from Collect. Otherwise, the next time you pull in forms, you will create duplicates.

Pulling form definitions 

  1. Open the Pull tab.
  2. Select Form definition in the Pull from drop-down.
  3. Click the Configure button and select the .xml form definition file.
  4. Select the form and click Pull. The form will be pulled to your Briefcase Storage location.

Exporting forms to CSV/Excel 

  1. Open the Export tab.
  2. Click on the Set Default Configuration button.
  3. Set an Export directory.
  4. If exporting Encrypted Forms, set the corresponding PEM file location. See the Encrypted forms section for more information.
  5. If you wish, select a Start date and an End date to specify a limited date range to export.
  6. Toggle export parameters as needed:
  7. Export media files enables exporting media files into the chosen export directory
  8. Overwrite existing files enables overwriting form instance data in the output files. The default behavior is to append data.
  9. Split select multiples enables splitting select multiple fields. Enabling this setting will create an extra output column per select choice, with a 1 if the choice was selected, or 0 otherwise. This only affects select fields without a choice filter and that are not from an external file (including widgets with search appearance).
  10. Include GeoJSON enables generating a GeoJSON file with spatial data from all exported submissions.
  11. Remove group names enables removing non-repeat group names from column names in the CSV.
  12. Pull before export enables trying to pull the selected forms in case there are new form instances to be exported.
  13. Click Export

Output files

  1. Briefcase will generate a different number of files and directories depending on the form’s contents and the export configuration selected by the user. This can include, per form:
  2. One main CSV file.
    1. For example: Form Name.csv
  3. If the form includes any repeat group, one CSV file for each one of them.
    1. For example: Form Name-repeat group name.csv
  4. If any submission includes binary attachments, they are copied to a media directory, relative to the export directory.
    1. For example: media/1538040007350.jpg
  5. If the user enables the Include GeoJSON export configuration option, one GeoJSON file with spatial data.
    1. For example: Form Name.geojson
  6. If the form includes audit metadata:
  7. One CSV file with audit data from all submissions.
    1. For example: Form Name – audit.csv
  8. One CSV audit file for each exported submission in the media directory, relative to the export directory.
    1. For example: media/audit-uuid56880d5e-ee8a-4832-b69d-6dfdd526e2dc.csv


Briefcase log files

Briefcase creates a log file with warnings and errors that might be useful for troubleshooting.

Default log file location

  • If something goes wrong while using Briefcase and you look for help, it’s possible that you’re asked to provide your log file.
  • The default location for the log file is the directory where you are when launching Briefcase, and the default filename is “briefcase.log”
  • Briefcase will create the log file on launch if it doesn’t previously exist. Otherwise, it will append lines at the end of a pre-existing log file.–


What is the Open Data Kit?

Was this article helpful?
0 out Of 5 Stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Table of Contents