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