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.

Define your questions
Group questions into sections (you must have at least one)
Create the form template
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¶

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¶

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¶

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

Remove a section¶

$ 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¶

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

Remove a question¶

$ 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

    $ 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)

$ 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)

$ 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

$ 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

$ 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

$ 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

$ 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

$ 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.

$ 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.

$ 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.

$ 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

$ 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

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