Sync - 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 Sync update rev 127 (April 2015) is an update of this APK that is designed to work with the rev 126 (February 2015) tools suite; it contains a bug fix to address sync failures after resolving row conflicts. This update is designated Alpha software.

See Release Designations for the meaning of this designation.

To determine the ODK Sync release, click on overflow menu icon (the three vertical boxes on the right of the menu bar), and choose the About menu item. The release version will be displayed above the license information.

 

Overview

Sync is a program that allows you to sync data collected by the ODK 2.0 tools with an ODK Aggregate instance. The Sync application can be used to reset the Aggregate instance with the data that is on a tablet or to sync the data on the tablet with the what is currently on the Aggregate instance.

Downloading and Installing ODK Sync

To install the Alpha-2, you must enable downloading from unknown sources by checking the checkbox beside Unknown sources on the Security screen of your Android device's Settings application.

Then, open your Android device's browser and download the ODK Sync v2.0 Alpha-2 update rev 127 APK from here. Click on the ODK Sync v2.0 Alpha-2 update rev 127 APK link on that page and download the actual ODK Sync APK. The rev 127 APK is designed to work with the rev 126 tools suite; it contains a bug fix to address sync failures after resolving row conflicts.

You should then be able to install that APK onto your device by choosing the Android Notification of the completion of the download. On some devices, you may need to open a file manager and double-tap on the downloaded file in the Downloads directory to trigger the install. On others, you may need to rename the file in the Downloads directory to end with .apk before double-tapping it to trigger the install.

Compatible Servers

The ODK Sync rev 127 software requires ODK Aggregate v1.4.5. It will not work with earlier versions of ODK Aggregate. See Aggregate Tables Extensions for further information on how to configure the server to accept ODK 2.0 synchronization requests.

Reset App Server

This option should only be used to initialize or update your aggregate instance.

Resetting your app server pushes the configuration and data on your tablet up to the server.

WARNING: If a data table on the server does not exist on the device, that table, all of its data, and all associated files (e.g., forms) will be deleted from the server.

If an data table on the server is identical to one on the device, the data in that table will be synced and the files on the server will be updated to be exactly those present on the device (deleting any files associated with this table that existed only on the server).

Before resetting, it is critical that you first ensure that your device contains all the tables, files, and data you want to preserve in your application (e.g., by using "Sync Now" (below)).

Opening up the Sync application will take you to the Sync screen. You can also open up this application by pressing on the cloud icon in the action bar of the Tables and Survey applications. On this screen:

  1. Enter the full URL of the server running your Aggregate instance (if you open a browser to your server, this will be everything before the Aggregate.html)
  2. Select the account you would like to use to sync.
  3. Press “Save settings”.
  4. Press “Authorize account”.
  5. Press “Reset App Server”.
  6. A confirmation dialog will popup asking you to confirm resetting the App Server. Again, this can delete all data on this Aggregate instance! If you are sure you want to continue, click "Reset".

Sync will contact Aggregate and attempt to push all data currently on the tablet up to the specified Aggregate instance. The status of resetting the app server can be obtained by looking at the notifications generated by Sync in the notification area.

Sync Now

Use this option to submit and retrieve data.

Syncing has two phases:

In the first phase, it creates data tables on the device that correspond to the data tables on the server, and it ensures that the form definitions and other files on your device exactly match those available on the server (updating them as needed).

WARNING: If a data table on the device does not exist on the server, that data table and all associated forms and files will be removed from the device.

In the second phase, it synchronizes the contents of the local data tables with the contents on the server, including any media attachments associated with individual records in the data table.

Unlike ODK Collect, where individual forms can be added and removed at will, ODK Sync and the ODK 2.0 tools are organized around coherent, complete, "user applications" consisting of a set of interrelated data tables and forms. All the forms and tables on the server collectively define the "user application" and ODK Sync ensures that the device conforms to that "user application" definition. You can operate multiple independent "user applications" on a single device by placing their files and forms under different application folders within the /sdcard/opendatakit/ folder; each such application will publish to a different ODK Aggregate server. This is a very significant and powerful change from the ODK Collect mindset.

Opening up the Sync application will take you to the Sync screen. You can also open up this application by pressing on the cloud icon in the action bar of the Tables and Survey applications. On this screen:

  1. Enter the full URL of the server running your Aggregate instance (if you open a browser to your server, this will be everything before the Aggregate.html)
  2. Select the account you would like to use to sync.
  3. Press “Save settings”.
  4. Press “Authorize account”.
  5. Press “Sync now”.

Sync will contact Aggregate and perform the two synchronization phases (detailed above). The status of the sync can be obtained by looking at the notifications generated by Sync in the notification area. If there is no data on the tablet or the data on the tablet is the same as what is on the server, there will be no conflicts and no additional action will be necessary. If conflicts do exist, they will have to be resolved.

ODK Tools Resolving Sync Conflicts

When you return from ODK Sync and next access data from a data table, the ODK 2.0 tool (ODK Survey or ODK Tables) will scan all tables looking for conflicts arising from the synchronization process. If any conflicts are found, the user is required to resolve the conflict before proceeding to their activity. The options for resolving conflicts are as follows.

  1. Take Local
  2. Take Server

Choose the desired option. Once the changes are reconciled, you can then proceed to the activity you were accessing and when you next sync, the resolved conflicts and any new changes will be pushed up to the server; other users will receive those changes when they sync to the server.