Skip to content
ODK Briefcase is a Java application for fetching and pushing forms and their contents. It helps make billions of data points from ODK portable. Contribute and make the world a better place! 💼
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

ODK Briefcase

Platform License Build status Slack status

ODK Briefcase is a desktop application that can locally store survey results gathered with ODK Collect. It can also be used to make local copies and CSV exports of data from ODK Aggregate (or compatible servers) and push data to those servers.

ODK Briefcase is part of Open Data Kit (ODK), a free and open-source set of tools which help organizations author, field, and manage mobile data collection solutions. Learn more about the Open Data Kit project and its history here and read about example ODK deployments here.

Setting up your development environment

  1. Fork the briefcase project (why and how to fork)

  2. Clone your fork of the project locally. At the command line:

     git clone

We recommend using IntelliJ IDEA for development. On the welcome screen, click Import Project, navigate to your briefcase folder, and select the build.gradle file. Use the defaults through the wizard. Once the project is imported, IntelliJ may ask you to update your remote maven repositories. Follow the instructions to do so.

If you're using IntelliJ IDEA, we also recommend you import the code style scheme for Briefcase at config/codestyle/codestyle.xml. Once you activate that scheme, use the automatic reformatting tool to produce code that will comply with the checkstyle rules of the project.

The main class is org.opendatakit.briefcase.ui.MainBriefcaseWindow. This repository also contains code for three smaller utilities with the following main classes:

  • org.opendatakit.briefcase.ui.CharsetConverterDialog converts CSVs to UTF-8
  • org.opendatakit.briefcase.ui.MainClearBriefcasePreferencesWindow clears Briefcase preferences
  • org.opendatakit.briefcase.ui.MainFormUploaderWindow uploads blank forms to Aggregate instances

There might be some compile errors in the IDE about a missing class BuildConfig. That class is generated by gradle and the warnings can be ignored.

If you are working with encrypted forms you may get an InvalidKeyException. This is because you do not have an unlimited crypto policy enabled in Java. Do this:

Running the project

To run the project, go to the View menu, then Tool Windows > Gradle. run will be in odk-briefcase > Tasks > application > run. Double-click run to run the application. This Gradle task will now be the default action in your Run menu.

You must use the Gradle task to run the application because there is a generated class (BuildConfig) that IntelliJ may not properly import and recognize.

To package a runnable jar, use the jar Gradle task.

To try the app, you can use the demo server. In the window that opens when running, choose Connect, then fill in the URL leave username and password blank.


Briefcase uses SLF4J with Logback Classic binding. The project also loads the jcl-over-slf4j bridge for libraries that still use old Apache Commons Logging.

There are example configuration files that you can use while developing:

  • Copy test/resources/logback-test.xml.example to test/resources/logback-test.xml. This conf will be used when running tests.
  • Copy res/logback.xml.example to res/logback.xml. This conf will be used when launching Briefcase on your machine.

Logging tests vs development vs release

During the release process, we use a specific logback for release. This configuration sends exceptions to and also logs to a briefcase.log file, created in the same folder where Briefcase is launched by the user.

For testing and development purposes, customization of logback conf files is encouraged, especially to filter different levels of logging for specific packages. The following example sets the default level to INFO and DEBUG for components under org.opendatakit:

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
      <pattern>%d [%thread] %-5level %logger{36} - %msg%n</pattern>

  <logger name="org.opendatakit" level="debug"/>

  <root level="info">
    <appender-ref ref="STDOUT"/>

More information on Logback configuration is available here.

Extended topics

There is a /docs directory in the repo with more documentation files that expand on certain topics:

Contributing code

Any and all contributions to the project are welcome. ODK Briefcase is used across the world primarily by organizations with a social purpose so you can have real impact!

If you're ready to contribute code, see the contribution guide.

Contributing testing

All releases are verified on the following operating systems:

  • Ubuntu 16.04
  • Windows 10
  • OS X 10.11.6

Testing checklists can be found on the Briefcase testing plan.

If you have finished testing a pull request, please use a template from Testing result templates to report your insights.

Downloading builds

Per-commit debug builds can be found on CircleCI. Login with your GitHub account, click the build you'd like, then find the JAR in the Artifacts tab under $CIRCLE_ARTIFACTS/libs.

Current and previous production builds can be found on the ODK website.

You can’t perform that action at this time.