Using ODK Briefcase¶
Warning
ODK Briefcase is no longer being updated. If you're using Briefcase for CSV exports, data decryption, or automation, use ODK Central instead.
Pulling forms¶
To pull blank forms and submissions:
Open the Pull tab.
Select a pull source option from the Pull from drop-down, and click on the Configure button. Fill in any information needed to use the selected source.
See more on the various sources below.
Select the forms you want to pull and click Pull.
You can see the details of the operation by clicking on the
button.You can cancel an ongoing pull operation at any point by clicking Cancel.
Central server¶
Briefcase will ask for the following information when choosing a Central server as the pull source:
A URL
A Project ID number
An Email address
A Password
Warning
The Start pull from last submission pulled setting will have no effect while pulling forms from a Central server.
Tip
See Using Central with Briefcase for more on the limitations of using Briefcase with Central.
Aggregate server¶
Briefcase will ask for the following information when setting an Aggregate server as the pull source:
A URL
A Username (optional)
A Password (optional)
Collect directory¶
Briefcase will ask for the directory on your computer where you have placed Collect's /odk directory. We recommend following these steps to get a copy of Collect's /odk directory into your computer:
Ensure all filled-in forms are finalized.
If you have incomplete forms that you cannot finalize before pulling into Briefcase, delete them. If you need to keep them, make a copy of your Collect directory before deleting them, and restore it after you are finished.
Using your device, create a zip archive of your Collect directory with a file managing app such as OI File Manager.
Transfer the zip file to your local hard drive via a USB cable. You can also use the Share feature in your file manager to transfer it to a third-party service like Google Drive then download it to your local hard drive.
Once the zip file is on your local hard drive, unzip the file.
Warning
When pulling from Collect, Briefcase pulls incomplete, saved, or finalized forms. After you pull forms into Briefcase, it is important that you delete them from Collect. Otherwise, the next time you pull, you will create duplicates.
Tip
If you have Android developer tools installed, another option is to use the Android Debug Bridge to pull filled forms:
$ adb pull <collect-directory>/instances
Form definition¶
Briefcase will ask for the location of the blank form definition in your computer.
Warning
Ensure that all attached media is available relative to the form definition file location.
Tip
This enables a workflow to upload blank form definitions with many media attachments to Aggregate:
Pull the form using the Pull from option.
Pushing forms¶
To push blank forms and submissions:
Open the Push tab.
Select a push target option from the Push to drop-down, and click on the Configure button. Fill in any information needed to use the selected source.
See more on the various targets below.
Select the forms you want to push and click Push.
You can see the details of the operation by clicking on the
button.You can cancel an ongoing push operation at any point by clicking Cancel.
Central server¶
Briefcase will ask for the following information when using a Central server as the push target:
A URL
A Project ID number
An Email address
A Password
Warning
Pushing forms and submissions to Central currently has the following limitations:
Central will reject files that might have already been pushed before, even if they're different the second time.
Central will reject submissions belonging to a form version that it doesn't know about.
Aggregate server¶
Briefcase will ask for the following information when using an Aggregate server as the push source:
A URL
A Username (optional)
A Password (optional)
Pull and push settings¶
The settings for push and pull can be configured in the Settings tab:
You can set a number of Maximum simultaneous HTTP connections. This can be increased to speed-up big pull operations or decreased to prevent saturating server bandwidth.
You can enable Start pull from last submission pulled to save time and bandwidth by not pulling from the first submission.
This is only available for Aggregate servers at this moment and only benefits forms with more than 100 submissions.
You can clear the pull history and pull every submission by clicking on Clear pull history.
You can enable Remember passwords (unencrypted). This will enable a couple of features:
Briefcase will remember the pull sources and push targets you configure when they require user credentials. As a result, you won't need to configure them when launching Briefcase again.
Briefcase will let you enable the Pull before export option when exporting forms.
You can enable Use HTTP proxy to route your HTTP requests through a proxy host. You will have to provide the proxy's Host (IP address or hostname), and the Port number.
Export forms to CSV¶
Open the Export tab.
Click on the Set Default Configuration button.
Set an Export directory.
If exporting Encrypted Forms, set the corresponding PEM file location. See the Encrypted forms section for more information.
If you wish, select a Start date and an End date to specify a limited date range to export.
Toggle export parameters as needed:
Export media files enables exporting media files into the chosen export directory
Overwrite existing files enables overwriting form submission data in the output files. The default behavior is to append data.
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).
Include GeoJSON enables generating a GeoJSON file with spatial data from all exported submissions.
Remove group names enables removing non-repeat group names from column names in the CSV.
Pull before export enables trying to pull the selected forms in case there are new form submissions to be exported.
Select the forms to export.
If you are selecting and exporting more than one form, you may need to set individual export settings. To do this, click the gear icon (⚙) next to the form name.
Click Export.
Tip
To import CSVs into Excel, you cannot download and open in one step; nor can you double-click on the CSV. You must open Excel and choose Import. If you are asked, the file origin or encoding is UTF-8.
Output files¶
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:
One main CSV file. For example: Form Name.csv
If the form includes any repeat group, one CSV file for each one of them. For example: Form Name-repeat group name.csv
If any submission includes binary attachments, they are copied to a media directory, relative to the export directory. For example: media/1538040007350.jpg
If the user enables the Include GeoJSON export configuration option, one GeoJSON file with spatial data. For example: Form Name.geojson
If the form includes audit metadata:
One CSV file with audit data from all submissions. For example: Form Name - audit.csv
One CSV audit file for each exported submission in the media directory, relative to the export directory. For example: media/audit-uuid56880d5e-ee8a-4832-b69d-6dfdd526e2dc.csv
Output file |
How many? |
Conditions |
Path |
Example |
|---|---|---|---|---|
Main CSV |
One |
./ |
Form Name.csv |
|
Repeat CSV |
One per repeat group |
./ |
Form Name-repeat group name.csv |
|
Binary attachment |
As many as there are in submissions |
./media |
media/1538040007350.jpg |
|
GeoJSON |
One |
The user enables Include GeoJSON export |
./ |
Form Name.geojson |
Audit CSV |
One |
The form includes audit metadata |
./ |
Form Name - audit.csv |
Individual audit CSV |
One per submission |
The form includes audit metadata |
./media |
audit-uuid56880d5e-ee8a-4832-b69d-6dfdd526e2dc.csv |
There's more information available about the CSV file content structure and filename patterns in the export format documentation.
Working with the command line¶
Briefcase has a command line interface (CLI) to enable scripting of many of the actions that can be taken in the graphical user interface (GUI).
Added in version 1.4.4: A CLI was added.
Added in version 1.9.0: The CLI first takes an operation parameter and then modifiers to that operation
Getting CLI help¶
To get help about the command line operation:
$ java -jar {path/to/briefcase-jar-file} --help
Pulling forms from Aggregate¶
CLI flag: -plla or –pull_aggregate
Usage:
$ java -jar {path/to/briefcase-jar-file} --pull_aggregate --storage_directory {path/to/briefcase-storage-location} --aggregate_url {aggregate-url} --odk_username {username} --odk_password {password}
Help section:
Params for -plla operation: -p,--odk_password <arg> ODK Password -sd,--storage_directory <arg> Briefcase storage directory -u,--odk_username <arg> ODK Username -url,--aggregate_url <arg> Aggregate server URL Optional params for -plla operation: -id,--form_id <arg> Form ID -ii,--include_incomplete Include incomplete submissions -mhc,--max_http_connections <arg> Maximum simultaneous HTTP connections (defaults to 8) -sfd,--start_from_date <arg> Start pull from date -sfl,--start_from_last Start pull from last submission pulled
Warning
This CLI operation will pull all forms Briefcase has permissions to if no -id parameter is defined.
Pulling forms from Collect¶
This command assumes you have already copied and unzipped the odk file as described here.
CLI flag: -pc or –pull_collect
Usage:
$ java -jar {path/to/briefcase-jar-file} --pull_collect --storage_directory {path/to/briefcase-storage-location} --odk_directory {path/to/unzipped-odk-file}
Help section:
Params for -pc operation: -od,--odk_directory <arg> ODK directory -sd,--storage_directory <arg> Briefcase storage directory Optional params for -pc operation: -id,--form_id <arg> Form ID
Warning
This CLI operation will pull all forms present on the odk directory if no -id parameter is defined.
Pushing forms to Aggregate¶
CLI flag: -psha or –push_aggregate
Usage:
$ java -jar {path/to/briefcase-jar-file} --push_aggregate --form_id {form-id} --storage_directory {path/to/briefcase-storage-location} --aggregate_url {aggregate-url} --odk_username {username} --odk_password {password}
Help section:
Params for -psha operation: -id,--form_id <arg> Form ID -p,--odk_password <arg> ODK Password -sd,--storage_directory <arg> Briefcase storage directory -u,--odk_username <arg> ODK Username -url,--aggregate_url <arg> Aggregate server URL Optional params for -psha operation: -fsb,--force_send_blank Force sending the blank form to the Aggregate instance -mhc,--max_http_connections <arg> Maximum simultaneous HTTP connections (defaults to 8)
Warning
This CLI operation will only update the blank form if it does not already exist, whereas the GUI will always update the form.
Exporting forms to CSV¶
CLI flag: -e or –export
Usage:
$ java -jar {path/to/briefcase-jar-file} --export --form_id {form-id} --storage_directory {path/to/briefcase-storage-location} --export_directory {path/to/output-directory} --export_filename {output-file-name.csv}
Help section:
Params for -e operation: -ed,--export_directory <arg> Export directory -f,--export_filename <arg> Filename for export operation -id,--form_id <arg> Form ID -sd,--storage_directory <arg> Briefcase storage directory Optional params for -e operation: -em,--exclude_media_export Exclude media in export -end,--export_end_date <arg> Export end date (inclusive) (yyyy-MM-dd or yyyy/MM/dd) -ig,--include_geojson Include a GeoJSON file with spatial data -oc,--overwrite_csv_export Overwrite files during export -pb,--pull_before Pull before export -pf,--pem_file <arg> PEM file for form decryption -rgn,--remove_group_names Remove group names from column names -ssm,--split_select_multiples Split select multiple fields -start,--export_start_date <arg> Export start date (inclusive) (yyyy-MM-dd or yyyy/MM/dd)
Clear saved preferences¶
CLI flag: -c or –clear_prefs
Usage:
$ java -jar {path/to/briefcase-jar-file} --clear_prefs
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.
How to use a custom log configuration¶
Optionally, you can use a custom log configuration file to override the default log settings on Briefcase.
First, you need to create a "logback.xml" file somewhere in your computer to contain your custom log configuration. This is a sample configuration file you can use as a template:
<configuration>
<appender name="ROLLINGFILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>briefcase.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>briefcase.%d{yyyy-MM-dd}.log</fileNamePattern>
<maxHistory>30</maxHistory>
<totalSizeCap>100MB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="info">
<appender-ref ref="ROLLINGFILE" />
</root>
</configuration>
Check the full syntax of Logback configuration files here.
You can set all sorts of new log configurations to adapt Briefcase to your needs:
Set a fixed log file location
Fine tune the log's verbosity by setting a different log level
Silence specific log lines while keeping others
Set a custom log format (see the Encoders chapter)
Set custom appenders, to define a file rolling policy (daily, by log file size, for example), for example (see the Appenders chapter)
Once you have your configuration file ready, you can use it by adding a -Dlogging.config argument when launching Briefcase:
$ java -Dlogging.config="{path/to/logback.xml}" -jar {path/to/briefcase-jar-file}