Submissions
=============

XForms supports three different modes of forms being submitted, via hand entered SMS, via XForm compliant HTTP POSTs, or via our own URL encoded SMS POSTS.  Each form has its own unique format, but each will pass through the same validation and signalling paths.

Manual SMS Submission
---------------------

The creation of an XForm creates a new SMS endpoint for that form.  The form's ``keyword`` will determine the SMS keyword that will trigger handling of said form.  If the form is successfully parsed and all constraints pass, then if set, the ``response`` element for the form will be sent back to the sender of the SMS message.

Note that we choose to be leniant about **extra** fields passed into SMS forms, these will be silently ignored.

Some examples SMS forms and responses for an XForm with the keyword ``survey`` and the required field of ``age`` and optional field of ``name``::

     >> survey +age 10
     << Thank you for submitting a new survey.

     >> survey
     << You are missing the required +age field.

     >> survey +age ten
     << The 'age' field must be an integer.

     >> survey +age 10 +name matt berg
     << Thank you for submitting a new survey.

     >> survey +name matt berg +age 10
     << Thank you for submitting a new survey.

     >> survey +name matt berg +age 10 +city new york
     << Thank you for submitting a new survey.

XForm HTTP Post
---------------

Any forms created will also be made available as standard XForms.  In order to expose your forms through this interface you will need to set the ``XFORMS_HOST`` variable in your ``settings.py`` to the host (and port if not 80) of your RapidSMS Server::

    XFORMS_HOST="rapidsms.unicef.org:8000"

You can download a free ODK Client from the Android market named ``ODK Collect``.  Once installed, just change the server to point to the same host specified above.  You will be able to list, install, and submit the forms you have created on your server using the native Android application.


Endpoints
*********

Two endpoints are implemented in order to work seamlessly with the ODK Collect client:

``/formList``
	Returns an XML document containing an index of all the form definitions installed on the server

``/submission``
	The end point that XForm clients POST their submissions to

Note that these URLs are hard coded in the ODK Collect client, so they cannot be changed.