ODK-X Suitcase

ODK-X Suitcase is a cross-platform tool that provides access to data on an ODK-X Cloud Endpoint from a personal computer.

Data downloaded from an ODK-X Cloud Endpoints 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. Similarly, data to be uploaded to an ODK-X Cloud Endpoint must be stored in a properly formatted csv file.


  1. Set up an ODK-X Cloud Endpoints


Ensure you are using a compatible Cloud Endpoint from the same revision.

  1. Make sure Java 7 or higher is installed on the computer you plan to use. If it is not, download and install it.

Installing ODK-X Suitcase

  1. Navigate to https://github.com/odk-x/suitcase/releases/latest and download the latest ODK-X Suitcase.jar file.

  2. Double click the file to start. If that fails, try running:

$ java -jar path/to/jar
  1. Alternatively you can use command line operation. For help on the command line interface type:

$ java -jar path/to/jar --help

Using ODK-X Suitcase

Graphical Interface

If your ODK-X Cloud Endpoint allows for anonymous access then you can leave the username and password fields blank. Otherwise, please specify an ODK-X Cloud Endpoint username and password with sufficient permissions.

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

ODK-X Suitcase provides three options to customize the CSV file.

  • Download attachments:

    • If this option is selected, ODK-X Suitcase will download all attachments from the given table and the CSV generated will contain hyperlinks to the local files.

    • If this option is not selected, the CSV generated will contain hyperlink to the given ODK-X Cloud Endpoint.

  • Apply Scan formatting:

    • When this option is selected, ODK-X Suitcase will optimize the CSV by replacing certain columns added by ODK-X Scan.

  • Extra metadata columns

    • When this option is selected, two more columns will be included in the CSV, create_user and last_update_user.

Command Line Interface (CLI)

ODK-X 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 two interfaces should also be identical.

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

$ 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 suitcase.jar -download -a -cloudEndpointUrl "https://your-endpoint-server.com" -appId "default" -tableId "table_id"
  • To download CSV of table table_id from app default with attachments with username user and password pass to:file:` ~/Desktop`:

    $ java -jar suitcase.jar -download -a -cloudEndpointUrl "https://your-endpoint-server.com" -appId "default" -tableId "table_id" -username "user" -password "pass" -path "~/Desktop"

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