Forms

Last Updated: 25.10.2019

Overview

Hala can respond to the user with a form. You can use the forms in case you need to collect from the user more than three values. In case you ask the user ten questions, they can become tedious, and the process for them will be more complicated. With forms, you can collect all the information in one step and simplify the process.

Following image represent the example of the form in the chat:

There are the following types of text fields that you can use to create the form.

Type	Description
Text	A text field is a graphical control element intended to enable the user to input text information into the form
Select box	The select box element is used to create a drop-down list and give the user the opportunity to select one of the value
Radio button	A radio button is an element that allows the user to choose only one of a predefined set of mutually exclusive options
Checkbox	Checkboxes are used to let a user select one or more options for a limited number of choices
Long text	With this field, users can enter the long text, for example, a description of the problem for the creation of a new incident
Date	The date field is designed for the date selection
Text with suggestions	The element is providing to the users' different predefined text to speed up the form entering. Users can click on one of the suggestions and Hala will take this value as an input

You can find more information about the adding the forms and fields in sections below.

How it works

The following diagram describes the process flow when we are sending the form to the user, and then we process the response from the user.

1. The end-user sends the request to create a new user in the external application.

2. Hala matches the user input with the condition of the skill "Create a new user." Based on the output configuration in the skill node, Hala responds to the user with the form.

3. The end-user is filling out the form and save results.

4. Hala is storing the results (values that the user entered in the form) in context variable context.formResult. Later you can access the information that users provided in the Form by using context.formResult.key_field_name

5. In case the user wants to cancel the Form, the result will be stored in context variable context.formCanceled. We need to process each action of the user to provide the appropriate response. For example, if the user will cancel the form, then we will trigger the child node with the condition context.formCanceled. Also, we can configure our response for this child node like this: "The form is canceled. How can I help you else?"

Accessing of the context variables of the Form

When users will fill out the form, then we would need to get the values that the users entered in the form. We need these values, because, for example, we can send the results to the backend software and create some object on the backend side.

All the results of the forms are storing into the two context variables:

Context Variable	Description
context.formResult	In case the user presses "Save" after filling the form, all values will be stored in this context variable.
context.formCanceled	In case user will press "Cancel" after the filling the form, all values will be stored in this context variable.

For example, you have sent to the user next form:

[
  {
    "type": "form",
    "title": "Create new user",
    "formData": [
      {
        "key": "key_username",
        "label": "Username",
        "type": "text",
        "value": "",
        "required": true,
        "description": "Additional text to explaine the purpose of the field"
      },
      {
        "key": "key_country",
        "label": "Country",
        "type": "text",
        "value": "",
        "required": true,
        "description": ""
      }
    ]
  }
]

Users will see two fields: "Username" and "Country."

Let's assume that in the field "Username" they have entered the value Andrew, and in the field "Country" they have entered the value Estonia.

So if you want to access those values in the following nodes, you can use next syntax:

{{context.formResult.key_username}} - this variable has the value "Andrew"

{{context.formResult.key_country}} - this variable has the value "Estonia"

Adding forms in expert mode

You can use the expert mode to add the forms. The expert mode becomes available by pressing the button next to the word "Output."

Access the Expert mode

Here is the example of JSON format for the forms:

[
  {
    "type": "form",
    "title": "This is the form name",
    "formData": [
      {
        "key": "key1",
        "label": "The field hame",
        "type": "text",
        "value": "",
        "required": true,
        "description": "Additional text to explaine the purpose of the field"
      },
      {
        "key": "key2",
        "label": "The field hame",
        "type": "text",
        "value": "",
        "required": true,
        "description": ""
      },
      {
        "key": "key3",
        "label": "Select box example",
        "type": "select",
        "value": "",
        "options": [
          "First",
          "Second",
          "Third"
        ],
        "required": false,
        "description": ""
      },
      {
        "key": "key4",
        "label": "Gender",
        "type": "radio",
        "options": [
          "Male",
          "Female"
        ],
        "value": "",
        "required": true,
        "description": ""
      },
      {
        "key": "key5",
        "label": "Finance",
        "type": "checkbox",
        "value": "",
        "required": true,
        "description": ""
      },
      {
        "key": "key6",
        "label": "Description",
        "type": "longText",
        "value": "Some default text",
        "required": true
      },
      {
        "key": "key7",
        "label": "Posting date",
        "type": "date",
        "value": "",
        "required": true
      },
      {
        "key": "key8",
        "label": "Company name",
        "type": "text",
        "value": "",
        "required": true,
        "suggestion": {
          "title": "Common values",
          "options": [
            "Hala Digital OU",
            "Hala SIA"
          ]
        }
      }
    ]
  }
]

The Form has header information and the items information.

Header information:

Parameter	Description
type	For the form output always value form
title	The name of the form that will be displayed in the chat
formData	An array of all the input fields included in the Form. Each object contains the information required for building an input field.

Item information:

Parameter	Description
label	The name of the input field.
key	A unique key to distinguish each input field in the form and for storing the value that the user will enter.
type	The HTML type of the input field. It can be: "text", "select", "radio", "checkbox", "longText", "date"
required	A Boolean value indicating if the input field is mandatory or optional
value	The value of the input, it is empty by default when creating a new form, and populated with the info, when using the form to edit an existing form
suggestion	You can use it only with field type "text." It contains title - a String value describing the values, and suggestions - an Array with suggested values that the user can use to populate the input field.
description	String value describing the form field
validationObject	An object with validation rules. More info on https://github.com/yiminghe/async-validator
options	An array of string values to populate the options of the "radio" and "select" output types

Field: Text

A text field is a graphical control element intended to enable the user to input text information into the form.

{
  "key": "key1",
  "label": "The field hame",
  "type": "text",
  "value": "",
  "required": true,
  "description": "Additional text to explaine the purpose of the field"
}

How it looks like in the chat

Field: Select box

The select box element is used to create a drop-down list and give the user the opportunity to select one of the value.

{
  "key": "key2",
  "label": "Select box example",
  "type": "select",
  "value": "",
  "options": [
    "First",
    "Second",
    "Third"
  ],
  "required": false,
  "description": ""
}

How it looks like in the chat

Field: Radio button

A radio button is an element that allows the user to choose only one of a predefined set of mutually exclusive options.

{
  "key": "key3",
  "label": "Gender",
  "type": "radio",
  "options": [
    "Male",
    "Female"
  ],
  "value": "",
  "required": true,
  "description": ""
}

How it looks like in the chat

Field: Checkbox

Checkboxes are used to let a user select one or more options for a limited number of choices.

{
  "key": "key4",
  "label": "Company name",
  "type": "checkbox",
  "value": "",
  "required": true,
  "description": ""
}

How it looks like in the chat

Field: Long text

With this field, users can enter the long text, for example, a description of the problem for the creation of a new incident.

{
  "key": "key5",
  "label": "Description",
  "type": "longText",
  "value": "Some default text",
  "required": true
}

How it looks like in the chat

Field: Date

The date field is designed for the date selection.

{
  "key": "key6",
  "label": "Posting date",
  "type": "date",
  "value": "",
  "required": true
}

How it looks like in the chat

Field: Text with suggestions

The element is providing to the users' different predefined text to speed up the form entering. Users can click on one of the suggestions and Hala will take this value as an input.

{
  "key": "key7",
  "label": "Company name",
  "type": "text",
  "value": "",
  "required": true,
  "suggestion": {
    "title": "Common values",
    "options": [
      "Hala Digital OU",
      "Hala SIA"
    ]
  }
}

How it looks like in the chat