sheepForms
==========

Forms in Sheep are built from a hierarchy: `questions` at the bottom, which can be grouped into a `section`, sections are added to a `form template` and templates are finally made public inside a `sheep from`.

To construct a form you must therefore start at the bottom and work up.

1. Define your questions
2. Group questions into sections (you must have at least one)
3. Create the form template
4. Create the Sheep Form that will use the template

(Once questions, sections or templates have been created they can be reused multiple times so consider carefully how to phrase questions to optimise re-use.)

Form Fields
-----------

:boolean:
	yes/no dropdown
:boolean-simple:
	renders as checkbox-simple
:boolean-switch:
	renders as switch with "yes/no"
:choice:
	single choice from a pre-defined list
:choice-from-url:
	single choice defined by a API endpoint
:date:
	browser date
:email:
	browser email
:extra-large-text:
	textarea
:file:
	single file upload
:image:
	single file upload
:profile_photo:
	single file upload with link to photo guidance
:large-text:
	textarea
:multi-choice:
	multiple choice from a pre-defined list
:multi-choice-checkbox:
	multiple choice from a pre-defined list rendered as check boxes
:multi-choice-from-url:
	multiple defined by a API endpoint
:multi-file:
	multiple file upload
:multi-select-from-url:
	multiples select, defined by a API endpoint
:number:
	browser number input
:telephone:
	browser text input
:text:
	browser text input
:text-list:
	multiple, text input
:time:
	browser text input

Create a new form
-----------------

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/sheep_form/ "Authorization: Bearer $API_KEY"

Create a new sheep form, a new form template and link them
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/$FLOCK/sheep_form/ "Authorization: Bearer $API_KEY" new_form_template=true


Sections in a form template
---------------------------

Add a section
^^^^^^^^^^^^^

.. code-block:: http

	$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/form_template/{ID}/section/ "Authorization: Bearer $API_KEY"


Remove a section
^^^^^^^^^^^^^^^^

.. code-block:: http

	$ http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_template/{ID}/section/ "Authorization: Bearer $API_KEY" section_uri=/example/form_section/5f904b1dcd59d5157793fb08/

Questions in a form section
---------------------------

Add a question
^^^^^^^^^^^^^^

.. code-block:: http

	$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/form_section/{ID}/question/ "Authorization: Bearer $API_KEY"


Remove a question
^^^^^^^^^^^^^^^^^

.. code-block:: http

	$ http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_section/{ID}/question/ "Authorization: Bearer $API_KEY" question_uri=/example/form_question/5f904b1dcd59d5157793fb08/


Form Responses
--------------

The Sheep Forms (templates, sections & questions) define the reusable form that a user will complete. The answers a user provides are stored in a `form_response`. A `form_response` will have a reference to the form it is referring too and the contact that is completing the form. A response will have a status (defined by the form), typically: `started`, `submitted`, `reviewing`, `accepted`, `rejected`, `withdrawn`, `flagged`. Status fields are configurable but certain statuses are required to exist.

:started:
	the users is in the process of answering.

:submitted:
	the users has completed and has submitted their form - further user edits are not possible

:withdrawn:
	the user has asked to withdraw their submission

:accepted:
	the response has been "accepted" (e.g. an application to join) or simply "closed" or "complete"

:rejected:
	the response has was not accepted

As a form response changes state Sheep trigger events are created. These can be connected through `actions` to deliver automation e.g. sending an email in response to a form moving to accepted.

The standard core API can be used to create, update and delete form responses. Deleting a form response will not delete any associated attachments or score sheets.


Submitting answers to a form response
-------------------------------------

:answers:
	a dictionary of question and answers

Or

:question:
	single question (uniq, fully qualified name)

:answer:
	single question (uniq, fully qualified name)

:skip_validation:
	boolean - default is False. questions are validated against the form before submitting

.. code-block:: http

	$ http PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/answers/ "Authorization: Bearer $API_KEY" answers:='{"fully-qualified-question": "my answer"}'

	{
    "data": {
        	"fully-qualified-question": "my answer"
    	}
	}


Commenting on a form response
-----------------------------

:section_uri:
	the section the comment refers to, required

:comment:
	the comment (markdown supported)


.. code-block:: http

	$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/comment/ "Authorization: Bearer $API_KEY"


Provide feedback on a form response
-----------------------------------

:section_uri:
	the section the comment refers to, required

:feedback:
	the comment (markdown supported)


.. code-block:: http

	$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/feedback/ "Authorization: Bearer $API_KEY"


Scoring a form
--------------

Forms can be scored (marked) directly or scored by a separate score sheet. Separate score sheets are only recommended if multiple independent scores are required.

Set the mark/score on the form response directly (not using score sheets)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:question:
	the question the mark or score applies to, required

:mark:
	the mark or score (numeric, integer), required

.. code-block:: http

	$ http PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/mark_question/ "Authorization: Bearer $API_KEY"


Delete / remove / reset mark for a question
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:question:
	the question the mark or score applies to, required

.. code-block:: http

	$ http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/mark_question/ "Authorization: Bearer $API_KEY"


Set the mark/score on a score sheet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:question:
	the question the mark or score applies to, required

:mark:
	the mark or score (numeric, integer), required

.. code-block:: http

	$ http PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_score/{ID}/mark_question/ "Authorization: Bearer $API_KEY"


Delete / remove / reset mark for a question
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:question:
	the question the mark or score applies to, required

.. code-block:: http

	$ http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_score/{ID}/mark_question/ "Authorization: Bearer $API_KEY"



Add a scorer to a form
^^^^^^^^^^^^^^^^^^^^^^

:user:
	the scorer, required

.. code-block:: http

	$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scorer/ "Authorization: Bearer $API_KEY"


Delete a scorer
^^^^^^^^^^^^^^^

:score_sheet:
	the score_sheet to delete, required

:force:
	optional param, a score sheet won't be deleted if it has been started by the scorer unless forced.

.. code-block:: http

	$ http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scorer/ "Authorization: Bearer $API_KEY"


Change the scorer
^^^^^^^^^^^^^^^^^

:user:
	the scorer, required

:score_sheet:
	the score_sheet to modify, required

:force:
	optional param, a score sheet won't be modified if it has been started by the scorer unless forced.

.. code-block:: http

	$ http PUT https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scorer/ "Authorization: Bearer $API_KEY"

View all the scores for a form response
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Get access to all the scores for a form response, their mean and the totals.

.. code-block:: http

	$ http GET https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/scores/ "Authorization: Bearer $API_KEY"


Assigning a user to a form response
-----------------------------------

Users can be assigned / pinned to a form response. What the assignment means will depend on the context and wider configuration. User assignments can be used in conjuntion with permissions to control access to certain form responses.

Add a user to a form
^^^^^^^^^^^^^^^^^^^^

:user:
	the user, required

.. code-block:: http

	$ http POST https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/users/ "Authorization: Bearer $API_KEY"

Remove a user from a form
^^^^^^^^^^^^^^^^^^^^^^^^^

:user:
	the user, required

.. code-block:: http

	$ http DELETE https://api.sheepcrm.com/api/v1/$FLOCK/form_response/{ID}/users/ "Authorization: Bearer $API_KEY"