Access to internet may not always be available in the different settings in which you will conduct your data collection campaign. Compiling submissions from ODK Collect on the various mobile devices you are using for data collection will therefore not be possible through online connection with an ODK Aggregate server or other ODK-compatible servers such as Formhub, SurveyCTO, ONA or Kobo Toolbox. It is in these settings where ODK Briefcase comes in handy.
ODK Briefcase is a Java application developed to easily gather and aggregate data from ODK Collect without need for internet connectivity. ODK Briefcase is also an alternative for those who do not want to setup an ODK Aggregate server or other ODK-compatible servers indicated above. ODK Briefcase can therefore either be a complementary tool to an ODK Aggregate server particularly during periods of poor internet connectivity or as a replacement for ODK Aggregate altogether.
This tutorial describes how to utilise ODK Briefcase as an ODK Aggregate replacement. In particular, this tutorial shows how to use ODK Briefcase to pull form submissions from various mobile devices and aggregate them into a single directory. This tutorial assumes that:
- You have created a form in XLSForm standard. A guide on how to create XLSForm standard forms can be found here.
- You have converted the XLSForm into XForms. A guide on how to convert XLSForm standard forms into XForms using XLSForm Offline can be found here.
- You have uploaded the forms in XForms standard and all related media files to ODK Collect on your mobile devices.
- You have finalised forms saved in ODK Collect.
- You have installed ODK Briefcase onto your computer. A guide on how to install ODK Briefcase can be found here.
1. Copy ODK directory from your mobile devices to your computer
In newer Android-powered devices (Android 4 and higher), the USB-mounted media device transfer protocol (MTP) has replaced the previous USB-mounted device protocol used on older versions of Android. ODK Briefcase does not work with the new MTP protocol. This means that when Android devices running Android 4 or higher are connected to a computer running ODK Briefcase, the mobile device is not recognised by ODK Briefcase as a mounted drive hence will not be able to communicate with it directly to pull data from the device.
The work-around to this limitation is to copy the ODK directory from the mobile device to a directory on your computer from which ODK Briefcase can then extract the data.
Following are the steps to take to copy the ODK directory from your mobile device to your computer.
1.1 Connect mobile device to your computer
Using a USB to micro-USB cable, connect your mobile device with your computer as shown below.
1.2 Open the mounted drive of your mobile device on your computer
Once your mobile device is connected to your computer, the computer will recognise the mobile device as a USB-mounted media drive and the name of the mobile device will be listed as a media device on your computer (1). Open the storage device of your mobile device by double clicking it (2).
You will then see the different directories inside the mobile device’s storage. One of these directories is the directory for ODK named ‘odk’.
1.3 Copy the ODK directory on your mobile device to a directory on your computer
Select the ‘odk’ folder on your mobile device and copy it to a directory on your computer. In this example, the ‘odk’ directory is copied to the Desktop.
The ‘odk’ directory is now on the desktop of your computer.
2. Pull submissions from ODK directory
Open ODK Briefcase by double clicking on the ODK Briefcase executable file saved on your computer or by running a command on the command line.
There are three tabs on the top menu portion of the application. These tabs are:
- Pull (1);
- Push (2); and,
- Export (3).
These are the three key functionalities provided by ODK Briefcase. However, it should be remembered that when ODK Briefcase is being used as a replacement for an ODK Aggregate server, the Push functionality is not available.
By default, when ODK Briefcase is opened, the Pull options are shown as below.
Following are the steps to pull submissions from the ODK directory copied from the mobile device in Step 1.
2.1 Select where to pull submissions from
First, you need to select where to pull submissions from. Click on the arrow indicating the drop-down menu for the selection of where to pull submissions from.
The drop-down menu provides four options from which to pull submissions from:
- Aggregate 0.9.x
- Aggregate 1.0
- Mounted Android SD Card
- Custom Path to ODK Directory
Since this example is using ODK Briefcase as a replacement for ODK Aggregate, select the fourth option ‘Custom Path to ODK Directory’.
2.2 Select ODK directory to pull submissions from
Second, select the ODK directory from which to pull submissions from.
Click on ‘Choose’ button.
A dialog box will appear from which you can select the folder in your computer that contains the ODK directory copied from the mobile device in Step 1. For this example, select the ‘odk’ folder copied in the Desktop (1).
Then click on ‘Choose’ (2).
2.3 Pull submissions from the selected ODK directory
Once you have selected the ODK directory to pull submissions from, the names of the forms that have submissions will be listed in the bottom window of the application as shown below. In this example, the is one form available for pulling submissions from.
Select this form by checking the tick box on the left side of the form name (1).
Then, click on ‘Pull’ button at the bottom right corner of the application (2).
You will then be notified that the pulling of data from the selected form has been successful.
Congratulations, you have now been able to pull data from the ODK directory copied from your mobile device.
3. Check the ODK Briefcase Storage folder
Once you have pulled the data, it would be good to check the ODK Briefcase Storage folder to see whether the forms you have pulled earlier have indeed been copied into your specified directory.
Locate the directory where you have placed the ODK Briefcase Storage. In the example below, the ODK Briefcase Storage is on the Desktop. Open the ODK Briefcase Storage folder (double-click or right-click then select Open).
Inside the ODK Briefcase Storage folder you will see a sub-folder labeled ‘forms’ (1) and a text document labeled readme (2).
Open the sub-folder labeled ‘forms’ (double-click or right-click then select Open).
Inside the ‘forms’ sub-folder is another sub-folder labeled ‘Incidence حالات الإصابة‘. This is the same name for the forms that has been submitted to the server.
Open this folder (double-click or right click then select Open).
Inside the ‘Incidence حالات الإصابة‘ sub-folder are three other sub-folders labeled ‘Incidence حالات الإصابة-media’ (1), info.db (2), and instances (3) and an XML document labeled ‘Incidence حالات الإصابة‘ (4).
Of these, the most important to check is the sub-folder labeled ‘instances’. Open this sub-folder (double-click or right-click then select Open).
Inside the ‘instances’ sub-folder are another set of sub-folders each of which corresponds to the forms that have been pulled using ODK Briefcase.
You should then count the number of sub-folders inside ‘instances’ to check whether the number of forms finalised and submitted match with the number of forms pulled using ODK Briefcase.
In this example, there are seven (7) sub-folders inside ‘instances’ which is the same number of forms pulled using ODK Briefcase.
4. Delete filled-in forms in ODK Collect
Once you have pulled the form submissions from ODK Collect in your mobile device, you should now delete the saved forms in ODK Collect. Doing this step ensures that for the next incremental pull of form submissions from ODK Collect, only new forms submissions will be pulled. This prevents previous form submissions from being pulled twice into the aggregate directory created by ODK Briefcase.
Deletion of filled-in forms is done in ODK Collect through the following steps.
4.1 Open ODK Collect
On your mobile device, tap on ODK Collect.
4.2 Tap on Delete Saved Form
Once you are in ODK Collect, you will notice that there are still finalised forms that are waiting to be sent (1) even if you have already pulled these forms into ODK Briefcase. These are the forms that we need to delete.
Tap on ‘Delete Saved Form’ button (2).
4.3 Select saved forms to be deleted
You will now see a list of the saved forms on ODK Collect.
Select the forms for deletion by either checking the tick box on the right hand side of the forms (1) or by tapping on the ‘Toggle All’ button on the bottom left hand corner of the screen (2) to select all the saved forms.
4.4 Tap on Delete Selected
You will now see that the saved forms you want deleted are checked. In this example, ‘Toggle All’ was tapped and all the forms have been selected for deletion (1). For most cases, this is what would you would need to do as all finalised forms that have been pulled already using ODK Briefcase need to be deleted.
Now tap on ‘Delete Selected’ (2).
4.5 Confirm deletion of saved forms
You will then be asked whether you want to delete the forms you have selected (1). Tap on ‘Delete Forms’ to confirm deletion (2).
4.6 Saved forms deleted
The saved forms are now deleted. A message will come out on your screen confirming the deletion.
5. Delete ‘odk’ folder copied from mobile device
You will now need to delete the ‘odk’ folder that you copied from the mobile device. It is important to delete this because it will prevent confusion later on when you need to pull new submissions (either from other mobile devices or on different data collection days) into ODK Briefcase.
Locate the directory on your computer where you copied the ‘odk’ folder. In this example, we copied it onto the Desktop.
Delete the ‘odk’ folder.
The ‘odk’ folder is now deleted. In this example, the folder has been deleted from the Desktop.
6. Pulling data from various ODK directories from multiple mobile devices or from different data collection periods
If you have multiple mobile devices to compile submissions from for the same form or multipel data collection periods, follow Steps 1 and 2 for each ODK directory copied from each mobile device or from different data collection periods.
Because these different ODK directories are associated with the same form, when ODK Briefcase pulls the submissions, it will recognise the different directories as containing submissions for the same form hence it will aggregate the submissions from these different directories and store them accordingly in the appropriate directory in the ODK Brieface Storage location. This is the aggregating capability of ODK Briefcase that makes it able to replace an ODK Aggregate server for this purpose.
It is important that you remember the following:
- Before pulling submissions from mobile devices, make sure that all the forms in ODK Collect in the mobile device has been finalised. ODK Briefcase does not discriminate between incomplete and finalized forms on the device. It will pull all submissions off of the device. To keep your data set clean, you must ensure that all forms are complete before being pulled off of the device.
- Step 3 is important. ODK Briefcase cannot discriminate between duplicates of the same filled-in form. After you pull the submissions into ODK Briefcase, it is important that you delete it from ODK Collect. Otherwise, the next time you follow this process, you will end up with two copies of the filled-in forms from the first pull.