Services - 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.

To determine the ODK Services 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

Services is a program that handles database access, file access, and data synchronization services between all the ODK 2.0 applications. Mostly this happens behind the scenes, but you will need to install ODK Services as a prerequisite to using the other ODK 2.0 tools.

It also allows you to sync data collected by the ODK 2.0 tools with an ODK Aggregate instance. The Services 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 Services

To install this version, 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 Services rev 206 APK from here. Click on the ODK Services rev 206 APK link on that page and download the actual ODK Services APK.

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

To synchronize data between devices ODK Services rev 206 requires ODK Aggregate v1.4.12. 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 sync icon (two curved arrrows) in the action bar of the Tables and Survey applications. On this screen:

  1. If you have not configured the application, from the menu, choose the Settings
  2. Choose Server Settings
  3. Choose Server URL and specify your server URL (if using Google App Engine, be sure to specify https://...).
  4. If your server is not configured to allow anonymous access, change the Server Sign-on Credential to either Username or Google Account and enter the appropriate credentials in the other settings fields.
  5. Exit out of the Server Settings page, and then the Settings page, by using the back button.
  6. By default, the sync interaction will synchronize all row-level data and file attachments with the server (Fully Sync Attachments). Other options are to only upload attachments from the device to the server (Upload Attachments Only), only download attachments from the server to the device (Download Attachments Only), or to not sync any attachments (Do Not Sync Attachments). When resetting the server, you typically want Fully Sync Attachments to be selected.
  7. Click on Reset App Server
  8. 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".

NOTE: One quirk with this release is that if you configure the anonymousUser to have Synchronized Tables permissions, then if you want to use an ODK Aggregate username to Reset App Server, you must temporarily remove that permission from the anonymousUser in order for the reset to proceed.

Sync will contact Aggregate and attempt to push all configuration and data currently on the tablet up to the specified Aggregate instance. A progress dialog will be displayed and, alternatively, the status of resetting the app server can be obtained by looking at the notifications generated by Services in the notification area.

The sync will proceed whether or not you remain on this page and you can use the back button to back out of it and return to your work. Should you begin modifying data rows in this application, the changes to those rows will not be sync'd until you save them as incomplete or finalize the row, and the act of editing will generally mark the sync has having ended with conflicts. This simply means that you must complete your edits and re-issue the sync to ensure that your changes are propagated up to the server.

 

Sync Now

Use this option to update your device's configuration to match that of the server and to submit and retrieve data.

Syncing has two phases:

In the first phase, data tables are created on the device that correspond to the data tables on the server, and the form definitions and other files on your device are made to 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, the configuration files and all associated forms for that table will be removed from the device. To prevent data loss, the table itself will not be deleted, but, by removing all of the configuration files for that table, the data will generally be unusable.

In the second phase, it synchronizes the contents of the local data tables with the contents on the server, including any row-level file attachments associated with individual records in the data table. Row-level file attachments are bundled and synced one row at a time.

Unlike ODK Collect, where individual forms can be added and removed at will, ODK Services 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 Services 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 Services application will take you to the Sync screen. You can also open up this application by pressing on the sync icon (two curved arrows) in the action bar of the Tables and Survey applications. On this screen:

  1. If you have not configured the application, from the menu, choose the Settings
  2. Choose Server Settings
  3. Choose Server URL and specify your server URL (if using Google App Engine, be sure to specify https://...).
  4. If your server is not configured to allow anonymous access, change the Server Sign-on Credential to either Username or Google Account and enter the appropriate credentials in the other settings fields.
  5. Exit out of the Server Settings page, and then the Settings page, by using the back button.
  6. By default, the sync interaction will synchronize all row-level data and file attachments with the server (Fully Sync Attachments). Other options are to only upload attachments from the device to the server (Upload Attachments Only), only download attachments from the server to the device (Download Attachments Only), or to not sync any attachments (Do Not Sync Attachments). In general, Fully Sync Attachments should be selected.
  7. Click on Sync Now

Services will contact Aggregate and perform the two synchronization phases (detailed above). A progress dialog will be displayed and, alternatively, the status of sync can be obtained by looking at the notifications generated by Services in the notification area.

The sync will proceed whether or not you remain on this page and you can use the back button to back out of it and return to your work. Should you begin modifying data rows in this application, the changes to those rows will not be sync'd until you save them as incomplete or finalize the row, and the act of editing will generally mark the sync has having ended with conflicts. This simply means that you must complete your edits and re-issue the sync to ensure that your changes are propagated up to the server.

ODK Tools Resolving Sync Conflicts

When you return from ODK Services and next access data from a data table, the ODK 2.0 tools (e.g., 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 Version
  2. Take Server Version
  3. Merge Changes as Indicated Below

Choose the desired option (the last will be enabled once all conflicts in the row's data fields have been decided). 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; then, other users will receive those changes when they sync to the server.