Legacy XML - rev 126

The documentation on this page corresponds to rev 126 (February 2015) of the tools suite. See Older Versions for documentation on earlier releases of this suite.

This is an older version of our software.

The websites referenced in this documentation will generally have been updated to work with the newer software, and therefore may not function with this older release.

Where practical, we have provided zip files of the ApplicationDesigner environment used in creating those sites. See Survey and Tables Aux Files

Release Designation

ODK Legacy XML rev 126 (February 2015) conversion tool is designated Alpha software.

See Release Designations for the meaning of this designation.


The ODK Legacy XML conversion tool converts formDef.json files generated from the XLSXConverter into ODK 1.x-style XML files that can be used to create ODK 1.x submission data tables on ODK Aggregate for submissions from ODK Survey.

NOTE: The XForms definition file (.xml) is unusable by ODK Collect 1.x. It only contains enough information to support publishing of data into ODK Aggregate.

NOTE: The ODK Legacy XML rev 126 (February 2015) tool produces a legacy ODK 1.x form definition compatible with rev 124. You can continue to use the form definition created from the rev 124 tool unchanged. Otherwise, if you were using an earlier version of the tool, you must delete the older form definition and use the new form definition in order to publish into your ODK Aggregate server.

The legacy XML form is the mechanism for using ODK Survey as a replacement for ODK Collect.  This mechanism constructs an ODK 1.x XML form for the underlying ODK 2.0 data table. This XML form definition, when uploaded to ODK Aggregate, enables the uploading of data from ODK Survey into ODK Aggregate's ODK 1.x (ODK Collect) data pipeline. Additionally, the ODK Survey forms that manipulate data in this table can be uploaded to the server as a media zip file. When the user chooses to download this 'legacy form' via ODK Survey's Form Download tab, the zip file will be downloaded and expanded. In this way, the same mechanisms for downloading 1.x forms can be used to manage and download ODK Survey table definitions and forms. Note, however, that this is not the ODK 2.0 synchronization mechanism, but a mechanism for integrating ODK Survey into the ODK 1.x data pipeline.

In future releases of the ODK 2.0 tools, we may move this functionality entirely to the ODK Aggregate server, and use only the new ODK 2.0 synchronization mechanism to exchange data with the server. This would eliminate the upload and download tabs on ODK Survey, leaving only the cloud tab; this same legacy submissions functionality, or its equivalent, would be implemented within the server.

Uploading Survey Forms to ODK Aggregate

Once you have produced a form definition file (formDef.json) from the new XLSXConverter form definition, you can use the backward-compatibility function of ODK Survey to publish submissions into an existing ODK Aggregate 1.x server.

  1. Create a forms directory on your system.
  2. Copy the table directories from the App Designer into this directory. Rename these directories to be tableId-media. The name of these sub-directories must end with -media.  For example, if you were going to upload the tables for household and household_member, you would have copied the App Designer's app/tables/household and app/tables/household_member directories into the forms directory and renamed them. The forms directory would then look like:
  3. Run the Legacy XML converter on one of the forms within these copied directories to produce an ODK 1.x XML form definition. You can access this tool via the Legacy XML tab of the ODK Application Designer tool.
  4. To generate the XML form definition, drag and drop the formDef.json file for the chosen form into the Legacy XForms XML Generator.
  5. Click the 'Save' button to save the output. Rename the file to tableId.xml and save it into the forms directory that was created in Step 1.
  6. Repeat steps 4-5 to produce a tableId.xml that corresponds to each tableId-media directory. In our example, your forms directory should now look like the following:
  7. Now, within each -media directory, replace any sub-directories with zip files of their contents. There will usually be only one sub-directory, forms, which contains your ODK Survey form definitions. On Windows, you can generate the zip file by right-clicking the sub-directory (e.g., forms), and choosing Send to / Compressed (zipped) folder.
  8. After generating the zip files, delete the sub-directories. For example, before generating the zip files, the household_member-media directory looked like this:
    form-media-dirAnd afterward, it looks like this:
  9. Now, run the ODK FormUploader 1.x tool available here to upload the form definition files (and their -media folders) to your ODK Aggregate 1.x instance.  You should see the following screen.
  10. Choose the xml form for the tableId that you would like to upload.
  11. Hit the 'Configure' button and enter the URL, username, and password to be used with the server.
  12. You will have to repeat Steps 11-12 for each tableId.xml file.  In this example, these files are household.xml and household_member.xml.
  13. You can now run ODK Survey, download these forms from ODK Aggregate 1.x, and submit data into ODK Aggregate 1.x from ODK Survey.