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.
Installing ODK-X Suitcase¶
Navigate to https://github.com/odk-x/suitcase/releases/latest and download the latest
Double click the file to start. If that fails, try running:$ java -jar path/to/jar
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¶
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.
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
defaultdirectory.$ 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.