Forms
-----

Scenario: Configuring form applications for teams
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A client has a number of controlled groups. Membership of the group is via an application process with a form to collect details.


:Author:
    James Webster, Nov 2022

*Pre-requisites*

- Groups have been created.
- A form has been created.
- The groups have their joining policies set to "controlled"

*Solution*

- Connect the form to the group. This is currently only supported in T3.
- Test the user experience by beginning an application

The solution so far will create form responses for each application. The next step is to create a group membership for each application using an automated action.

- Create an automated action to create a group membership when a form response is created. The trigger is `form_response_state_submitted`, the action is `join group`
- The automate action requires a parameter `group_uri` to be a available. This variable controls which group the form submitted should join. The `group_uri` can be set on the automated action although this is typically not possible when configuring for multiple groups.
- If a `group_uri` parameter is not found the automation will look for the value from the form response. The answer must be called `control.group_uri`.
- The `join group` action will create an `accepted` group/team member. The parameter `status` can be used to set a different status. The `join group` action will not create a group/team member if the user is already a member of the group/team. Note: parameters updates are currently only supported by the API.

.. code-block:: http


    http http PUT https://sheepcrm.com/api/v1/example/action/63809919c4b68a4147aa0aa8/ "Authorization: Bearer $API_KEY" params='{"status":"applied"}'

    HTTP/1.0 200 OK

    {
        "errors": {},
        "updates": {
            "params": "{\"status\":\"applied\"}"
    }



* * *

Creating a form control section
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Form section ref are generally not important but they are used to identify the section when connecting to system automations. This section ref MUST be called `control`. (The ref is the not the name of the section, you are free to name the section whatever you choose.)

Will the user choose the team or will it be auto-filled for them?
If the user chooses the team then add or re-use a form section. Where the group is going to be fixed then create a new form section.

- Open the form in setting and select the form section.
- From the bottom of the form section copy the form section uri.
- Edit the form section using T3.
- Change the `ref` field to `control`, save the form section.

The form section is now configured and the question can be added.

- create a form question (the question can be any type that will capture the team/group uri as a string value)

Recommended:

- question type: "Choose a record from a Sheep segment"
- the question must be required
- set visibility to "internal" if the question should be hidden from users
- the segment should be "Teams" (or whatever you have called the segment that contains all the possible teams)

Name the question `group_uri`

- Open form section using T3 (see instructions above).
- Find the team question just created, click the blue link to open the question in T3
- edit the field name to `group_uri`