= ODK Collect Integration =
[[TOC]]

  ''Note:'' this is just a brain dump intended to be useful for developers involved with the new XForms module - proper documentation to follow upon completion of the module.

== Authentication ==

Since version 1.1.7, ODK Collect supports HTTP !BasicAuth '''if''' run via HTTPs and confronted with a proper HTTP-401 Auth challenge.

Recent Eden trunk versions implement the Auth challenge, and the best option to configure HTTPs access to Eden is to deploy it behind a web server (e.g. Apache2) with SSL.

== ODK Collect Settings ==

Under "General Settings", configure:

  - Platform: "Other"
  - Configure Platform Settings
    - URL: https://<your-server.domain>/eden/xforms
    - Username: your username
    - Password: your password
    - Form list path: /formList
    - Submission path: /submission

== Problem: No Peer Certificate ==

Unfortunately, ODK Collect will refuse to work with self-signed server certificates. A certificate signed by an official CA is though too expensive for developers, so therefore here a few notes how you can get around this:

=== Android 4+ User-Trusted Certificates ===

Android 4+ allows the user to install user-trusted certificates for use via WiFi. When you download a certificate in Chrome, it will automatically invoke the certificate manager which allows you to install it as "user trusted" certificate.

But the certificate manager may report successful installation even if nothing has been installed. To understand that, you need to know two things:

  a) Android does only accept CA certificates, not server certificates
  b) Android required the certificate to be in DER format

To achieve (a):

1) Create a new CA key
{{{
openssl genrsa -des3 -out rootCA.key 2048
}}}

2) Create a self-signed CA root certificate
{{{
openssl req -x509 -new -nodes -key rootCA.key -days 365 -out rootCA.crt
}}}

3) Create a server key (if you don't have one yet)
{{{
openssl genrsa -out host.key 2048
}}}

4) Generate a CSR with the server key (if you don't have one yet)
{{{
openssl req -new -key host.key -out host.csr
}}}

5) Sign the CSR with the rootCA key
{{{
openssl x509 -req -in host.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out host.crt -days 365
}}}

6) Use rootCA.crt, host.key and host.crt the SSL config in your vhost (paths may differ depending on your OS):
{{{
  SSLEngine On
  SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
  SSLCertificateFile /etc/apache2/ssl.crt/host.crt
  SSLCertificateKeyFile /etc/apache2/ssl.key/host.key
  SSLCACertificateFile /etc/apache2/ssl.crt/rootCA.crt
}}}

To achieve (b)

1) Convert the certificate into DER format:
{{{
openssl x509 -in rootCA.crt -outform der -out rootCA.der.crt
}}}

2) Publish the rootCA.der.crt on your web server
3) Open the certificate's URL in Chrome, install it as "user trusted certificate" as described above
4) Verify that the certificate is installed under Settings > Security > Trusted Certificates > User

== Problem: Invalid Response Status for HEAD Request ==

ODK Collect doesn't send the data to trigger the Auth challenge, but a HEAD request. Unfortunately, it would send the HEAD request to an interactive-format URL in Eden, so that Eden (correctly) redirects to the login page with a HTTP 303 status. This is seen as "invalid response status" by ODK Collect, so you see that error message.

There are two possible ways around this:

1) Catch the "xforms" controller in AuthS3.permission.fail() - and respond with a HTTP 401 Auth challenge instead of redirecting
2) Configure ODK Collect to submit to /submission.xml instead of /submission (which makes it a non-interactive URL)

Solution (1) will be implemented in future versions of the xforms module (still under development while writing this).

== Problem: ODK Collect crashes when attempting to download an xform ==

Possible causes:

1) web2py renders whitespace before the xml processing instruction in the xform
2) xform XML is not well-formed due to encoding problems (mismatching tags, restricted characters in attributes etc.)

These issues will be fixed in future versions of the xforms module (still under development while writing this).

== Problem: ODK Collect crashes when attempting to submit an xform ==

Possible cause:

1) xform module responds to the HEAD request with a HTTP 400 status (because it doesn't contain an XForm)

Solution: catch the HEAD request in submission() and respond with a HTTP 204 status (this is what ODK Collect expects).

This solution will be implemented in future versions of the xforms module (still under development while writing this).