Using ODK Briefcase

Pulling forms from Aggregate

To download blank forms and completed form instances from an Aggregate server:

  1. Open the Pull tab.

  2. Select Aggregate in the Pull data from drop-down.

  3. Click the Connect button and enter the URL and login credentials for your Aggregate server.

    If you have anonymous login enabled on Aggregate, no login credentials are needed here.

    To connect to the Aggregate Demo Server, the URL is https://opendatakit.appspot.com.

  4. Select the forms you want to download and click Pull. The selected forms will be pulled to ODK Briefcase Storage on your local system.

    For each selected form, Briefcase will pull down:

    • The form definition file (that is, the blank XForm).
    • All media associated with the form.
    • Completed form instances.

    If you have previously pulled the form:

    • New instances will be downloaded to the same location as previously downloaded ones.
    • The form definition file and media files will not be re-copied.

    Warning

    If your local copy and the remote copy of the blank form definition file are different, the pull will be aborted.

    Workaround

    If the form definition has changed, but the changes only affect the question text and do not alter the structure of the collected data (or change the form ID or version), you can:

    1. In Settings, temporarily change the location of ODK Briefcase Storage.
    2. Pull data into to the new location.
    3. Manually copy the instances from the temporary location to your original storage location.
    4. Update Settings back to the original storage location.

Note

Pull forms faster with parallel connections

To speed up pulling forms from Aggregate, enable Pull submissions in parallel in the Settings tab.

../_images/pull-in-parallel.png

However, if your Aggregate server is installed on Google App engine, this setting may cause problems with large attachments. If your form has submission attachments (file uploads, videos, images, sound recordings) you should experiment with this setting and see if it improves or worsens performance.

Pushing forms to Aggregate

To upload blank forms and completed form instances to Aggregate:

  1. Open the Push tab.

  2. Select Aggregate in the Push data to drop-down.

  3. Click the Connect button and enter the URL and login credentials for your Aggregate server.

    If you have anonymous login enabled on Aggregate, no login credentials are needed here.

    To connect to the Aggregate Demo Server, the URL is https://opendatakit.appspot.com.

  4. Select the forms you want to upload and click Push. The selected forms will be pushed from ODK Briefcase Storage on your local system to the Aggregate server.

    For each selected form, Briefcase will upload:

    • If not on the server already:
      • The form definition file (that is, the blank XForm).
      • All media associated with the form.
    • Completed form instances.

    Warning

    If your local copy and the remote copy of the blank form definition file are different, the push will be aborted.

    Workaround

    If the form definition has changed, but the changes only affect the question text and do not alter the structure of the collected data (or change the form ID or version), you can:

    1. In Settings, temporarily change the location of ODK Briefcase Storage.
    2. Manually copy the form directory from your original storage location to the temporary location.
    3. Replace the local form definition file with a copy of the version from your Aggregate server.
    4. Push your form instances.
    5. Update Settings back to the original storage location.

Tip

By pulling data into the local Briefcase Storage location and then pushing data up to an Aggregate instance, Briefcase provides a mechanism to transfer data across upgrade-incompatible versions of Aggregate.

Pulling forms from Collect

  1. 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 /sdcard/odk before deleting them, and restore it after you are finished.

  2. Create a zip archive of the entire odk directory.

    Tip

    You'll need to use an app for this.

    One option is OI File Manager.

  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 Custom Path to ODK Directory in the pull data from drop-down.

  8. Select the unzipped odk folder.

  9. Click Pull.

  10. On the Android device, open ODK Collect and delete the filled-in forms.

    Tip

    • You can use the Custom path to ODK Directory any time you want to pull forms from custom location.
    • You can confirm that the forms have been successfully pulled into Briefcase by confirming a successful pull status or by verifying the data appearing in a CSV export file.

Warning

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.

Note

ODK Briefcase does not support pushing blank forms to ODK Collect. Instead, manually load the forms on your ODK Collect device.

Export forms to CSV

  1. Open the Export tab.

  2. Choose an Export Location.

  3. If exporting Encrypted Forms, identify the location of your PEM file.

  4. If you wish, select Start and End dates to specify a limited date range to export.

  5. Select the forms to export.

    If you are selecting and exporting more than one form, you may need to individualize your export settings (export location, PEM file, start date, end date). To do this, click the gear icon () next to the form name.

  6. Click Export.

Working with the command line

New in version 1.4.4: A CLI was added.

New 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 form data from Aggregate

$ java -jar {path/to/briefcase-jar-file} --pull_aggregate --form_id {form-id} --storage_directory {path/to/briefcase-storage-location} --aggregate_url {aggregate-url} --odk_username {username} --odk_password {password}

Pulling form data from Collect

This command assumes you have already copied and unzipped the odk file as described here.

$ java -jar {path/to/briefcase-jar-file} --pull_collect --form_id {form-id} --storage_directory {path/to/briefcase-storage-location} --odk_directory {path/to/unzipped-odk-file}

Pushing form data to Aggregate

$ 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}

Exporting form data to CSV

$ 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}

The export operation also accepts these optional parameters to set encryption private keys, to set a range of dates, to exclude media files, or to toggle overwriting output files. Check how to get help for more information.

Clear saved preferences

$ java -jar {path/to/briefcase-jar-file} --clear_prefs