Suitcase - rev 206

The documentation on this page corresponds to rev 206 (August 2016) of the tools suite. See Older Versions for documentation on earlier releases of this suite.

Release Designation

See Release Designations for the meaning of this designation.

ODK Suitcase is a cross-platform tool that downloads data from ODK Aggregate server.

Data downloaded from ODK Aggregate server is stored as spreadsheets in csv format. This format is compatible with most spreadsheet software, for example Excel or Numbers. Once downloaded, the spreadsheets will be available for offline viewing.

Installation

  1. Make sure your ODK Aggregate server is version 1.4.9 or higher.
  2. Make sure Java 7 or higher is installed on the computer you plan to use. If it is not, download and install it.
  3. Navigate to downloads/download-category/suitcase/ and download ODK Suitcase.
  4. Double click the file to start. If that fails, try running 'java -jar path_to_jar' from the command line.
  5. Alternatively, for command line operation, type java -jar path_to_jar --help for help on the command line interface.

Usage

If the anonymousUser is granted Data Viewer permissions you can leave the username and password fields blank. Otherwise, please specify an ODK Aggregate username and password with sufficient permissions. ODK Suitcase does not work with Google accounts (Account Type 'Google').

By default ODK Suitcase creates a "Download" directory where the ODK Suitcase jar is located and saves data in that directory. To specify a different directory for ODK Suitcase to store downloaded data in, click on the "..." button.

ODK Suitcase provides three options to customize the csv file.

  • Download attachments
    This options effects 2 aspects of ODK Suitcase,
    1. If this option is selected, ODK Suitcase would download all attachments from the given table.
    2. If this option is selected, the csv generated would contain hyperlinks to the local files.
    If this option is not selected, the csv generated would contain hyperlink to the given ODK Aggregate server.
  • Apply Scan formatting
    When this option is selected, ODK Suitcase would optimize the csv by replacing certain columns added by ODK Scan.
  • Extra metadata columns
    When this option is selected, 2 more columns would be included in the csv, create_user and last_update_user.

Command Line Interface (CLI)

ODK Suitcase also provides a command line interface that can be easily called by scripts and other programs.

The CLI has the same features as the graphical user interface. csv files produced by the 2 interfaces should also be identical.

For a list of all available options, open command prompt/power shell or terminal. Type in

java -jar path_to_jar.jar --help

Combine the individual commands described in the help to perform the actions needed. Examples are as follows.

To download csv of table "table_id" from app "default" with attachments as an anonymous user to the default directory.

java -jar --aggregate-url https://your-aggregate-server.com --app_id default --table_id table_id -a

To download csv of table "table_id" from app "default" with attachments with username: user and password: pass to ~/Desktop.

java -jar --aggregate-url https://your-aggregate-server.com --app_id default --table_id table_id 
          --username user --password pass -o ~/Desktop -a

To script the CLI, write the commands you would like to execute in a scripting language (e.g., Bash, Batch, Python, Ruby) and use a scheduler (e.g., Cron, Windows Task Scheduler) to schedule the tasks. To skip over ODK Suitcase's prompts to overwrite, pass -f as an argument to ODK Suitcase.