Repository files navigation

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

ODK Briefcase is part of ODK, a free and open-source set of tools which help organizations author, field, and manage mobile data collection solutions. Learn more about the ODK project and its historyhere and read about example ODK deploymentshere.

• ODK website:https://getodk.org
• ODK Briefcase usage instructions:https://docs.getodk.org/briefcase-intro/
• ODK forum:https://forum.getodk.org
• ODK developer Slack chat:https://slack.getodk.org
• ODK developer wiki:https://github.com/getodk/getodk/wiki

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

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

    git clone https://github.com/YOUR-GITHUB-USERNAME/briefcase

We recommend usingIntelliJ IDEA for development. On the welcome screen, clickImport Project, navigate to your briefcase folder, and select thebuild.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 youimport the code style scheme for Briefcase atconfig/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 isorg.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 classBuildConfig. That class is generated by gradle and the warnings can be ignored.

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

• Java 8 Update 151 or later: Setcrypto.policy=unlimited in$JAVA_HOME/jre/lib/security/java.security
• Java 8: InstallUnlimited Strength Policy Files 8 in$JAVA_HOME/jre/lib/security
• Java 7: InstallUnlimited Strength Policy Files 7 in$JAVA_HOME/jre/lib/security

To run the project, go to theView menu, thenTool Windows > Gradle.run will be inodk-briefcase > Tasks > application > run. Double-clickrun to run the application. This Gradle task will now be the default action in yourRun 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 thejar 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 URLhttps://opendatakit.appspot.com leave username and password blank.

Briefcase usesSLF4J withLogback Classic binding. The project also loads thejcl-over-slf4j bridge for libraries that still use oldApache Commons Logging.

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

• Copytest/resources/logback-test.xml.example totest/resources/logback-test.xml. This conf will be used when running tests.
• Copyres/logback.xml.example tores/logback.xml. This conf will be used when launching Briefcase on your machine.

During the release process, we use a specific logback configuration which logs to abriefcase.log file in the folder Briefcase is launched from.

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 toINFO andDEBUG for components underorg.opendatakit:

<configuration>  <appendername="STDOUT"class="ch.qos.logback.core.ConsoleAppender">    <encoder>      <pattern>%d [%thread] %-5level %logger{36} - %msg%n</pattern>    </encoder>  </appender>  <loggername="org.opendatakit"level="debug"/>  <rootlevel="info">    <appender-refref="STDOUT"/>  </root></configuration>

More information on Logback configuration is availablehere.

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

• Briefcase export CSV format
• How to release a Briefcase version

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, seethe contribution guide.

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 theBriefcase testing plan.

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

Per-commit debug builds can be found onCircleCI. 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 theODK website.