This feature was released with v7.3 of the platform and is in (beta) state.

The Virtual Agents engage end-users primarily using a conversational interface that typically includes an exchange of a series of messages. But oftentimes, there is a need to gather information from the end-user to proceed further. Examples include providing delivery address while interacting with an eCommerce agent, details of an issue while reporting to ITSM agent, opportunity details while creating a CRM opportunity, capturing customer details to create a bank account, etc.

In a standard Dialog Task, this scenario is designed by placing a series of Entity Nodes connected back-to-back and the user is asked for values for each of these entities sequentially, which is quite tedious and frustrating. Instead, an interactive User Interface for easy and efficient capture of all the information from the user would be ideal.

Kore.ai’s Digital Form caters to such requirements by providing a range of input fields required for capturing the required details from end-users. After the users complete the form, the input can be submitted to the virtual agent to proceed with the task at hand.

In this document, we discuss the features and implementation for Digital Forms in the Kore.ai Bots platform. To jump to a use case example for a step-by-step implementation of a Digital Form click here.

Form Creation

A Digital Form includes a definition and various components to capture user input.

Steps in creating Forms:

1. From the left navigation menu, select Bot Tasks and then Digital Forms.
2. Use the New Form button to create a form.
3. In the New Form page, enter
   • Name of the Form
   • Display Name for the Form
   • Description of the Form
4. Save & Proceed with the Form Creation.

Components Addition

• You can drag and drop the components available on the left panel onto the canvas, and configure their properties to build the form. For details of the components & their properties, see below
• You can search for a given component, scroll through the list
• view them in a grid format.

Form Actions

From the Forms Listing page, you can:

• Create New Form, as seen above.
• Edit Form, see below;
• Use Branding option to customize the form, see here;
• Test the form, see here; and
• Delete the form.

Edit

You can use the Edit option from the form listing to edit the form. Following actions can be performed on the Form in edit mode:

• Component Listing can be used to select and add components to the Form by simple drag and drop action;
• Use View Toggler to switch between Desktop view and Mobile View;
• Use the Handle Bar against each of the components to change its location by a simple drag and drop action;
• Use Form Actions to:
  • Test the form to see the preview of the Digital Form in the Bot Builder;
  • Delete the Form;
  • Change the Form Settings like name, display name, and description.
• Use the Component Actions to access the Settings, Duplicate, and Delete the component.
• You can change the components’ properties from the Component Settings popup:
  • Use the Component Docker to dock/undock the settings panel to the screen
  • Use the Component Selector to navigate through the components on the Form

Branding

Use the Branding option to change the look and feel of the form to reflect your organization’s standards. An instant preview gives you an idea of how the form would look with the new colors and you have the option to Save or Restore Default scheme.

Test

Test the form to see a preview

Form Invocation

Following are the ways a Digital form can be invoked:

1. From a Task: You may include a form as a component in a dialog task for defining the task. The Dialog task offers ‘Form Experience’ and the usual ‘Conversation Experience’ for filling the form data. You can choose the preference based on ‘channel of interaction’ or any other criteria based on your requirements.
2. From a UI flow: You can add a Digital Form to a Panel and choose a dialog task to be triggered when the form is submitted from the panel.

In the following sections, we discuss each of the above invocation processes.

From Tasks

Digital Forms can be used inside Dialog Tasks for capturing user inputs through a Form Node.

Steps in invoking form from a Dialog task

1. Create/open the dialog from where you want to invoke the Digital Form.
2. Click + next to the node where you want to add the Form.
3. Select the Form option and then the form from the list presented. You can choose to add a Digital Form directly or use an existing Form Node.
   
4. You will be prompted to select the Form Experience, it can be
   
   • • Only Form UI – this would create a Form Node and associate it with the Digital Form selected. This is the default option.
       
     • Both Form UI and Conversation Experience – This would further prompt you to choose a channel. When a user is using one of the selected channels they would be presented with a Form UI, the rest of the channel users would get conversation experience.
       
       This option would create:
       • a Group encompassing the following nodes (see here for details). This grouping can be renamed and/or deleted.
         • a Logic Node to determine the transitions to the Form Node and the Sub-dialog Node based on the channels selected
         • a Form Node for the Digital Form, same as was generated for the Only Form UI above.
         • a Sub-dialog Node to capture the required entities (as defined in the Digital Form using components) for the conversational experience. See below for the mapping.

         

5. You can set the Properties for each of the node added
   • the Form node (see here for details).
     Of special interest are the following Component Properties
     • Submit Message – Message displayed to the end-user on successful submission of the form
     • Web/Mobile SDK Form Behavior – Using this option you can either have the form displayed inline the chat window or open in a full page.
   • Logic Node, in case of the conversation experience flow, can also be configured (see here for details)
     Of special interest are the following:
     • Manage Context Variables can be used to create and set values for the context variables. Remember to use the full path of the variable in the key field ie. context.BotUserSession.<variable_name>
     • We strongly urge you not to make changes to the connection settings as this might affect the bot performance.
   • Sub-dialog Node can be configured as normal (see here for details)
     Of special interest are the following:
     • Use the Entity Post-assignment to capture the user input.
       
     • In case you modify the sub-dialog or the source form, you will be presented with an option to Regenerate Dialog. This would ensure that the changes are reflected in the task without having to rebuild the entire task. Be aware that the changes would be reflected in all places this sub-dialog is used.
       
6. The user input can be accessed as follows:
   • Form component values can be accessed (see here for details) using {{context.forms.<form_name>.<component_name>}}
   • In case of the sub-dialog, the variables used in the post-assignment settings as {{context.<variable_name>}}
7. You can continue with the Dialog Task as per your business needs. For example, you can use the Form Component values as input to a Service Node to update the data or use the Script Node to process it further. If you are using the conversation experience too, remember to connect the auto-generated sub-dialog to the process flow.

From Panels

Digital Forms can be rendered in Digital Views by configuring Widgets & Panels, see here for more on Digital Views.

Steps in invoking form using Widgets and Panels

1. Create a widget to invoke the Digital Form.
   1. Enter the name.
   2. Select Digital Forms as Source
   3. Add Form by selecting from the drop-down list
   4. Select the Dialog to Invoke on Submit from the drop-down list.
      Note that while a Digital Form can be used to define multiple Widgets and also be added to multiple Panels, it will be associated with the single Dialog Task across all Widgets and Panels.
   5. Save the widget.
      
2. Add Widget to an existing Panel or create a new Panel.
   You can Add Form directly to a Panel, it would create a Widget by default.
   
3. You can Test the Panel.
4. Follow the steps given here to publish and host the Panels.

Process Flow

When the end-user initiates the dialog and reaches the node connecting to Form node the following events take place. Depending upon the experience selected at design time and the channel of invocation, the following would be the flow:

• Form experience:
  • A link to the form is presented to the user
    
  • Clicking the link would open the form in either full-screen or inline mode, based on the selection. Special notes about the link:
    • The link is active only for a certain duration of time, it becomes inactive after that.
    • Even within the active period, it can be used only a limited number of times.
  • End-user can fill the values for the components/fields.
    
  • Every form comes with a default Submit button. This would validate the form entries, prompt for any missing values.
    
  • Once the form is validated and submitted, the values will be available in the context variable and can be accessed using the following code: context.forms.<form_name>.<component_name>
    Here we are capturing the user entry and displaying it using a message node.
    
• Conversation Experience:
  • From the channel of operation, the end-user would be prompted to enter values for each and every component in the form.
  • The values will be available in the sub-dialog context and can be captured using Entity Post Assignment as mentioned above.
  • Following is the user experience in Conversation mode
    

Exceptions

When exceptions are encountered during the dialog execution with a Form Node, they are handled as follows:

Panel Flow

Users can access the form using Panels & Widgets. The experience is the same as for the Process Flow with Form experience.

Once the form is validated and submitted, the values will be available in the context variable and can be accessed using the following code: context.forms.<form_name>.<component_name>

The following would be the experience:

Bot Management

Publish

The publishing flow for a bot with Digital Forms has the following special cases:

• As with any bot, the Digital Forms exist in the following states:
  • In-development when a form is created;
  • Awaiting approval when a form is submitted for Publish and the request is waiting for the admin to take action;
  • Rejected when the Publish request is rejected by the admin;
  • Published when the Publish request is approved by the admin;
  • Suspended when a published form is suspended by the admin
• The following validations are performed before a Publish request is processed:
  • A Dialog Task that contains a Digital Form can be published only if:
    • The corresponding Digital Form is already published, or
    • The corresponding Digital Form is also selected for publishing.
  • A Digital Form that is configured to trigger a Dialog Task can be published only if:
    • The corresponding Dialog Task is already published, or
    • The corresponding Dialog Task is selected for publishing.
  • While the dependencies are published together, chances are that all the dependencies might not be available at run-time, in such cases:
    • If the Dialog Task is in a published state, but the Digital Form is not in a published state this would trigger
      • the Task Failure Event and the corresponding behavior will be invoked or
      • a relevant Standard Response will be displayed and
      • logged as Failed Task in Analytics.
    • Digital Form is in a published state, but the Dialog Task is not available then on Form submission, the end-user would be presented with the Form’s Error Message.

Import/Export

Bot Export

• Option to export Digital Forms in In-development and Published copies are available.
• Digital Forms can be selected/deselected from the Bot Export page under the Bot Tasks category.
• Choose the option to “Include dependent dialogs” to export Dialog Tasks that are integrated with the selected Digital Forms for defining Widgets. Note that this does not include the Sub-dialog Tasks generated using Digital Forms.
• Complete information of each of the selected forms will be available in the export file and this includes
  • Fields
  • Field properties
  • Form integrations

Bot Import

• Digital Forms are included in the full and incremental import of the bot.
• For Full Import:
  • As with all other bot components, the full import would replace the entire Digital Forms and form details in the bot.
• For Incremental Import:
  • You can choose to include/exclude the Digital Forms in the import.
  • This import would fully replace the Digital Forms that are common to the import file and the bot.
  • Additional forms in the file will be imported into the bot.
  • Additional forms in the bot will be retained.
  • Post import, any invalid Digital Form integration details will be disassociated with the corresponding forms.

Component Details

Components List

Following is a list of available components. For details on the properties of each component, see below

Component	Description	Sample
Basic
	Text Field – used for single-line input.
	Text Area – used for multi-line entry
	Number – used for numerical entries
	Radio Button – used as a selection option from a given list
	Dropdown – Used as a selection option from a given list; can be multi-select
	Checkbox – Used for multi-select option from a given list
	Date – Used for date entries, gives a date picker for the user to choose the date.
	Date & Time – Used for date & time entries, gives a date and time picker for the user to choose the date and time. Use the Date component and set the Time option to yes; choose from 12- or 24-hour format
	Phone Number – Used for phone number entries, allows the user to choose the country code.
	Email – Used for email address entries, validates for xxx@uuu.com format
	Toggle – Used for switching between two values, ideal for yes/no type of inputs
	Address – Used for address entries
	URL – Used for web URL entries, validates for xxx.com format
	Range Slider – Value selection between a specified min and max values; can be represented as a percentage
Advanced
	Button – Used as a clickable component to submit, or reset, or open an external URL the form. Choose from Primary, Secondary, Tertiary, Ghost, or Danger.
	Label – Used to display a static text box, no action required from the user
	Protip – Used to mark important information for the end-user, no user action required.
	Note – Used to mark information for the end-user, no user action required.

Component Properties

The following are the properties that can be set for each of the components.

Note not all the properties will be valid for all the components, refer to the property matrix for the mapping:

Component Mappings

Properties

Basic

Advanced

Dialog Node

The following mapping gives the type of entities included in the sub-dialog when it is auto-generated from a Digital Form

Context Object

The following mapping gives the context object to capture the component value along with a sample context object.

Limitations

• Digital Forms will not work as expected on the following channels:
  • Amazon Alexa
  • Cisco Jabber
  • Google Assistant
  • IVR Voice
  • Twilio Voice
  • Webhook (synchronous)

  You are advised to choose the Conversation Experience for these channels.

• Digital Forms created in the parent bot will not be inherited to Smart Bots.
• The Digital Forms functionality will not be applicable for Universal Bots.