Hi folks,
Many thanks to Carl who was gracious enough to tolerate me expressing my
annoyances while trying to hook up ODK into my own server. Here is a FAQ
that I hope will be useful if anyone has to go through this again. It's been
delivered with a side of snark, but I really do think that ODK is a great
product that more than anything else suffered from a lack of documentation,
especially in the realm of standards and integration. Hopefully the below
will help towards that path...
cheers,
Cory
···
---- 1. What URL should I use and how should I configure it?Your URL can be anything, as long as it ends in /submission. In the phone
you should put the root of everything before submission, and ODK will
happily add /submission for you. You don't even have to tell it to! And in
fact, you can't tell it to without editing code and compiling ODK yourself.
So...
You put in phone: http://myserver.com/odk (note no trailing slash, this is
important)
Your server accepts posts at: http://myserver.com/odk/submission.
In django you can work around this pretty easily by redirecting both to the
same view. e.g.
urlpatterns = patterns('myapp.views',
url(r'^$', 'post', name='receiver_post'),
url(r'^/submission$', 'post', name="receiver_odk_post"),
....
--
2. How do I access the form data?
The form is submitted as a multipart POST. The xml formdata is in a part
named "xml_submission_file". To my knowledge this cannot be changed or
configured, but this isn't took big a problem. In django you can access it
like so:
xml_instance = request.FILES['xml_submission_file'].read()
--
3. What about multimedia?
Again these are just named parts. Again, in django each part will correspond
everything else in request.FILES, with the keys being the filenames and the
values being the handles to the file contents.
--
4. How do I respond?
However you want! Well almost.
You can put anything in the body.
Your status code MUST be 201 or ODK thinks it failed.
You MUST add a "Location" header
This location header MUST be part of the url that ODK submitted to. (If
you're sneaky you can always just set the Location header to "h", "t", "p",
":", or ".", but you should probably use the real server location in case
ODK decides to change this on you.)
Again, in django the easiest way to do this is the following:
response = HttpResponse("thanks ODK!", status=201)
response["Location"] = "." # but really use something like "http://%s" %
Site.objects.get_current().domain
return response
--
Cory L. Zue
Dimagi, Inc