> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-content-gov.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Digital Forms
AI Agents primarily engage end-users through a conversational, message-by-message interface. But often you need to gather several pieces of information at once — a delivery address for an eCommerce agent, issue details for an ITSM agent, opportunity details for a CRM, or customer details to book a flight.
Asking for each value one at a time via a chain of Entity Nodes in a Dialog Task is tedious for the user. **Digital Forms** solve this by presenting an interactive form that captures all the required details from end-users in a single interaction, then submits the input to the AI Agent to proceed with the task at hand.
In this article, we discuss the features and implementation of Digital Forms in the Platform. For a use case example and a step-by-step implementation of a Digital Form click [here](/ai-for-service/automation/digital-skills/configure-digital-forms).
## Features
* Improved user experience with a single interface for input collection.
* Easy form creation using simple drag and drop actions.
* Vast component library to cater to all your form requirements.
* Provision to define rules for input validations and visibility suiting your use case.
* Automatic dialog task generation from the *Form* enabling switching between Form or Conversation experience based on the channel of interaction.
## General Setup
You can access **Digital Forms** from **Automation AI > Use Cases > Digital Skills**.
Here's the overall usage process for Digital Forms within the Platform
* **Form Creation**: Define a Digital Form by adding components and configuring their properties.
* **Form Invocation**: Forms are invoked from inside a task or process:
* A form is included as a component in the task. The dialog task offers a Form Experience and Conversation Experience based on the channel of interaction.
* A Digital Form is added to a Digital View with a dialog task triggered when a form is submitted from there.
* **Form Submission**: When it's submitted, the component values are validated and any errors are highlighted. Based on the mode of invocation, post successful validation:
* The AI Agent execution proceeds as per dialog flow in case of dialog task invocation.
* The selected task is triggered.
## Create a Form
A Digital Form includes a definition and various components to capture user input.
To create forms, follow the steps below:
1. Under **Automation AI > Use Cases > Digital Skills**, select **Digital Forms**.
2. On the **Digital Forms** screen, click **New Form**.
3. On the **New Form** page, enter the following:
* **Name** of the Form.
* **Display Name** for the Form.
* **Description** of the Form.
4. **Select form’s Header Style**: You can choose a specific header style from the listed illustrations – the circle indicates the position of logo/icon with respect to the title of the form in the header. Click the card to select the style. If it has a logo, you can upload an image file (jpg or png) for the logo.
During the Export of the app, the logo isn't exported along with Digital Forms. So, when importing this App, you need to separately copy the logo image file and then manually reupload the logo.
5. Turn on the **Description** toggle if you want to show a description of the form in the header.
6. **Form Security** – Enable **Secure Form Data** to redact form data from the App Context, Debug Logs, Service Calls, Agent Transfer, and the Bot Kit.
While enabling, you can also choose whether to display the **Secure Form icon** to your end users.
Once enabled, the Platform will replace the user input with a unique random system-generated alphanumeric value in all the modules. Also, the **Secure Form** icon and a tip will be displayed, notifying the user that the form is secure.
Secure Form feature ensures data security at form level. You can achieve securing data at component level too. [Read here](/ai-for-service/automation/digital-skills/configure-digital-forms#form-editor) to know more.
7. **Pre-Processor script**—The Pre-Processor script in the form settings can be used by the developer to manipulate all the data required for the form that can't be customized from the UI design view.
For example, in the case of a multilingual AI Agent, the user can customize the form UI & standard responses of the components in the digital form so that they appear based on the selected app language.
Moreover, you can provide dynamic variables to replace the static content in the pre-processor script for use in the form using environment, content, and context variables.
The platform processes and resolves the pre-processor script as the first step in the form node execution. The same can be seen in the debug log. As part of this, the updated definition from the pre-processor script is passed to webUI to render the form.
**Example:**
Suppose you want to change the standard response of a field of URL type in a digital form based on the app language. You've added English, Spanish, German, and Japanese as your app languages.
```
let formDef = koreUtil.getFormDefinition();
if(context.currentLanguage === 'en'){
formDef.formMsgMeta.URL_INVALID_FORMAT = 'Invalid URL';
}
elseif(context.currentLanguage === 'de'){
formDef.formMsgMeta.URL_INVALID_FORMAT = 'ungültige URL';
}
elseif(context.currentLanguage === 'es'){
formDef.formMsgMeta.URL_INVALID_FORMAT = 'URL invalida';
}
else{
formDef.formMsgMeta.URL_INVALID_FORMAT = '無効なURL';
}
```
* This field will be available **only while updating** the form and not at the creation time.
* Defining a pre-processor script is **not mandatory**. The default standard responses will always be present.
* This feature is available **only for Automation AI**.
Please click here to learn more about the digital form’s pre-processor script.
8. Click **Save & Proceed**.
### Configuration setup using Pre-Processor script
Earlier, our digital forms can be created only in one language and hence multiple forms need to be created to provide the flexibility to render the forms in different languages for multi lingual app. Also the messages and errors were available only in English and can't be customized. This posed a limitation as it didn't support all app languages. Additionally, users lacked the ability to customize the forms using the dynamic data from context.
The pre-processor script has been introduced to counter the above limitations. You can provide values to the relevant keys based on the app language or any other condition that requires customization of aspects like field labels or standard responses.
To get the form definition that's provided as a response in the `koreUtil.getFormDefinition` and keys that need to be customized, refer to the digital form's **JSON view**. Navigate to **Automation AI > Use Cases > Digital Skills > Digital forms** and open the form that you wish to configure. Click **Test** on the Form Design view, then select the **JSON** tab.
The pre-processor script allows you to:
* Make Language specific customizations
* Populate Dynamic data from external sources (Eg: data file or API)
* Populate Dynamic data using variables
* Pre-fill the form with static or dynamic data (default value using value or context variable)
Remember that you must create a form definition object using `koreUtil.getFormDefinition` before adding any code to customize any field’s property or standard response. This object consists of the form meta, form components & form messages. Make sure that this is the first line in your javascript code, with the syntax:
```
let formDef = koreUtil.getFormDefinition();
```
The below sections contain the keys that you may need to manipulate:
* **Components**: for field and form level customizations like Form Header, Description, Field Names, Descriptions, Default Text, Validation rules etc.
* **formMsgMeta**: for customizing Standard Messages and Standard Error Responses
The entire JSON is usually large, and it may be a challenge to find out the keys that need to be manipulated. You may consider copying the entire JSON, pasting it in any JSON Viewer application wherein you can collapse and expand the sections. You can expand only the components and formMsgMeta sections for convenience.
#### Components
The **Components** section is a container for all the fields on the form and the keys that can be manipulated in the pre-processor script for customization.
Upon expanding the **components** section, which appears as an array in the JSON viewer, you see an indexed sub-sections that indicates the number of fields in the form. For example, the components section in the below screenshot shows that there are 12 fields in the form.
You can see any field’s keys and their values by expanding the sub-section, and then expanding **metaData**. Usually the index of sub-sections represents the sequence of the fields on the form.
You can customize the properties of a field by referencing it using its index number within the array using the below syntax:
```
formDef.components[<>].metaData.<> = '<>';
```
**Example:** to customize the **displayName** of the first field in the form, below is the code:
```
formDef.components[0].metaData.displayName = '名前';
```
Here’s a list of keys and their purpose:
| Key | Form Setting | Purpose |
| --------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| metaData.displayName | Display Name | The field name visible to the user |
| metaData.placeHolder | Placeholder | The text pre-populated in the field, but isn't captured as field data |
| metaData.toolTip | Tooltip Text | The tooltip text associated with the field |
| metaData.isVisible | Is visible | To change the visibility setting; it can be true or false. |
| metaData.required | Required | To establish whether the field is a mandatory one |
| metaData.defaultvalueInput | Default Value | To provide a default value to the field |
| metaData.validateOn | Validate | To mention the event that would trigger validation. Can be onChange or onBlur. |
| metaData.description | Description | Description of the field |
| metaData.disabled | Read-only | To establish whether the field is read only. |
| metaData.options.locale.format (Only for **Date** fields) | Date Format and Time Format | To choose the format of date and time |
| metaData.options.timePicker (Only for **Date** fields) | Time | To show/hide the time picker within the date picker |
| metaData.options.timePicker24Hour (Only for **Date** fields) | Time Format | To choose the time format between 12 Hour or 24 Hour |
| metaData.options.locale.applyLabel (Only for **Date** fields) | – | The label of **Apply** button on the date-time picker; visible only if timePicker is set to true |
| metaData.options.locale.cancelLabel (Only for **Date** fields) | – | The label of **Cancel** button on the date-time picker; visible only if timePicker is set to true |
| metaData.countryCode (Only for **Phone Number** fields) | Default Country Code | The Default Country code Eg: +1 |
| metaData.countryName (Only for **Phone Number** fields) | Default Country Code | The default Country Name (Eg: United States) |
| metaData.enableDropDownSearch (Only for **Dropdown** fields) | – | To establish whether search box is available in the dropdown |
| metaData.isMultiSelect (Only for **Dropdown** and **Radio Button** fields) | Multi Select | To establish whether multiple items can be selected from the dropdown |
| metaData.minSelection (Only for **Dropdown** fields) | – | To establish the minimum number of items to be selected. If metaData.isMultiSelect is **false** , this value will be ignored. |
| metaData.maxSelection (Only for **Dropdown** fields) | – | To establish the maximum number of items that can be selected. Works only if metaData.isMultiSelect is **true.** |
| metaData.values (Only for **Dropdown** and **Radio Button** fields) | Dropdown values | An array containing the items in the dropdown. Every item is represented by an index number. |
| metaData.values\[\< >].value (Only for **Dropdown** and **Radio Button** fields) | Dropdown values > Edit Values > Value | The dropdown item |
| metaData.values\[\< >].selected (Only for **Dropdown, Checkbox** and **Radio Button** fields) | Dropdown values > Edit Values > Default | To establish whether the dropdown item is selected by default |
| metadata.toggleDefaultValue (Only for **Toggle** fields) | – | Default state of the toggle, can be **true** or **false** |
| metaData.toggleEnabledValue (Only for **Toggle** fields) | Value > Yes | Value to be read by platform if the toggle is enabled |
| metaData.toggleDisabledValue (Only for **Toggle** fields) | Value > No | Value to be read by platform if the toggle is disabled |
| metaData.minRange (Only for **Range Slider** fields) | Value > Min | Minimum value of the range slider |
| metaData.maxRange (Only for **Range Slider** fields) | Value > Max | Maximum value of the range slider |
| metaData.defaultvalueInput (Only for **Range Slider** fields) | Default value | Default value of the range slider |
| metaData.buttonAction (Only for **Button** component) | Button Action | The action triggered on clicking the button. Can be **submit, cancel, reset or goToUrl** |
| metaData.url (Only for **Button** component) | URL | URL to navigate to when user clicks the button if Button Action is goToUrl. |
#### formMsgMeta
The formMsgMeta section contains the keys that contain the Standard Responses and Error Messages. If you want to customize these messages and responses, or customize them based on the AI Agent’s language, you can do so in the pre-processor script by manipulating the values of these keys.
These messages and responses can't be customized from the form design UI. The pre-processor script provides you the required mechanism to create status or dynamic responses based on your requirements.
Upon expanding the **formMsgMeta** section, you can see the keys that you can customize.
You'll need to set useFormMsgMeta to **yes** to ensure that the customized formMsgMeta values are passed on to WebUI for rendering the form. This is an optional key, but not mentioning it'll make the form display the system default responses and error messages.
The syntax to set it is `formDef.formMsgMeta.useFormMsgMeta = 'yes';`
The syntax to provide value to a key of the formMsgMeta section is `formDef.formMsgMeta.<> = '<>';`
The response message customizations are at the form level, that is, a response message of a particular nature will be applicable to all the fields across the form. For example, the customized response message for invalid URL will be the same for all the fields of URL type within the form.
**Example:** Suppose you want to customize the system response for mandatory fields. The default system response is ‘This field is required’, but you want the response to be ‘This is a mandatory field; please provide a value’. This is how you can do it:
```
formDef.formMsgMeta.FIELD_MANDATORY = 'This is a mandatory field; please provide a value';
```
Here’s a list of keys and their purpose:
| Key | Purpose |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| formMsgMeta.FIELD\_MANDATORY | Response message if no data is provided in a mandatory field |
| formMsgMeta.FIELD\_INVALID\_FORMAT | Response message if the data provided in the field isn't valid. |
| formMsgMeta.URL\_INVALID\_FORMAT | Response message if the url entered in the field is of invalid format. |
| formMsgMeta.FIELD\_TOO\_LONG | Response message if the data entered in the field exceeds the maximum permitted length.. |
| formMsgMeta.FIELD\_TOO\_SHORT | Response message if the data entered in the field falls below the required minimum length. |
| formMsgMeta.EMAIL\_INVALID\_FORMAT | Response message if the data entered in an Email type field in invalid format. |
| formMsgMeta.ERROR\_PREVIEW | Response message if error occurs in preview. |
| formMsgMeta.ERROR\_DOWNLOAD\_ATTACHMENT | Response message if error occurs while downloading attachment. |
| formMsgMeta.FILE\_SIZE\_EXCEED | Response message if file size exceeds the maximum limit. |
| formMsgMeta.FILE\_UPLOAD\_EXISTING | Response message if the file has already been uploaded. |
| formMsgMeta.FILE\_UPLOAD\_ERROR | Response message if error occurs while uploading a file. |
| formMsgMeta.FILE\_TYPES\_SUPPORTED | Response message if user tries to upload a file of unsupported type. |
| formMsgMeta.INVALID\_PHONE\_NUMBER | Response message if user enters an invalid phone number in a field of Phone Number type. |
| formMsgMeta.ERROR\_PROCESS\_APP.PUBLISH | Response message when process app isn't published |
| formMsgMeta.ERROR\_PROCESS\_APP.EXPIRE\_INVALID | Response message when the process app being accessed has expired or is invalid. |
| formMsgMeta.FORM\_DISCARD.CONFIRM | Header text of the popup that appears on discarding a form |
| formMsgMeta.FORM\_DISCARD.DESC | Text within the popup that appears on discarding the form |
| formMsgMeta.FORM\_DISCARD.SUBMIT | Caption of the ‘Confirm’ button of the popup. Confirms the action. |
| formMsgMeta.FORM\_DISCARD.CLOSE | Caption of the ‘Close’ button of the popup. Closes the popup without discarding the form. |
| formMsgMeta.FORM\_SUBMISSION\_CONFIRMATION.HEADER | Header text of the popup that appears on submitting a form |
| formMsgMeta.FORM\_SUBMISSION\_CONFIRMATION.DESC | Text within the popup that appears on submitting the form |
| formMsgMeta.FORM\_SUBMISSION\_CONFIRMATION.CLOSE | Caption of the ‘Confirm’ button of the popup. Confirms the action. |
| formMsgMeta.FORM\_SUBMISSION\_CONFIRMATION.CONFIRM | Caption of the ‘Close’ button of the popup. Closes the popup without submitting the form. |
| formMsgMeta.FORM\_SUBMISSION\_FAILED | Message that's displayed when form submission fails |
| formMsgMeta.FORM\_LINK\_EXPIRY | Message that's displayed when the form link expires. **Note** : The expiry message of the digital form can't be customized. The expiry message will be displayed according to the app's language settings. |
| formMsgMeta.FORM\_CANCEL | Message that's displayed when the form is canceled. |
| formMsgMeta.DROPDOWN\_MESSAGE | Message displayed on dropdown |
| formMsgMeta.FORM\_LOADING | Message displayed when the form is loading |
| formMsgMeta.FORM\_DATE\_PICKER.FORMAT | The format in which the date entered in the date picker will be saved |
| formMsgMeta.FORM\_DATE\_PICKER.CONFIRM | Caption of the Confirm button on date picker |
| formMsgMeta.FORM\_DATE\_PICKER.CANCEL | Caption of the Cancel button of the date picker |
| formMsgMeta.FORM\_DATE\_PICKER.DAYS\_OF\_WEEK\[ ] | Array containing the names of weekdays. They can be customized using the array index based on language or which day does the user want to be the start of the week on the form. |
| formMsgMeta.FORM\_DATE\_PICKER.MONTHS\[ ] | Array containing the names of months. |
| formMsgMeta.FORM\_DATE\_PICKER.TIME | Caption of the ‘Time’ part of date picker |
| formDef.formMsgMeta.FORM\_SUBMIT\_SUCCESS | Message displayed when form submission is successful |
| formDef.formMsgMeta.FORM\_SUBMIt\_FAILURE | Message displayed when form submission fails |
| formMsgMeta.FORM\_CLOSE\_MESSAGE | Message displayed when form is closed |
| formMsgMeta.FORM\_CLOSE\_BUTTON | Caption of the Form Closing button |
The below use cases explain the steps to make various customizations using the pre-processor script. The digital form to gather data for opening a bank account is being used as an example. Japanese and German languages have been added to the AI Agent.
#### Use Case 1: Language specific customizations
**Components:**
Suppose you want to customize the display names of the Name and Date of Birth fields based on the selected App language.
Since these are the first two fields on the form, their index values are 0 and 1, respectively.
Below is the code to customize the display names:
```
let formDef = koreUtil.getFormDefinition();
if(context.currentLanguage === 'en'){
formDef.components[0].metaData.displayName = 'Name';
formDef.components[1].metaData.displayName = 'Date of Birth';
}
else if(context.currentLanguage=== 'de'){
formDef.components[0].metaData.displayName = 'Name';
formDef.components[1].metaData.displayName = 'Geburtsdatum';
}
else{
formDef.components[0].metaData.displayName = '名前';
formDef.components[1].metaData.displayName = '生年月日';
}
```
Let’s assume that currently the App language is Japanese. This is how the form would look in the run-time:
**formMsgMeta:**
Suppose you want to customize the standard response for mandatory fields based on the App language. Below is the pre-processor script for that:
```
let formDef = koreUtil.getFormDefinition();
if(context.currentLanguage === 'en'){
formDef.formMsgMeta.FIELD_MANDATORY = 'This is a mandatory field. Please provide a value';
}
else if(context.currentLanguage === 'de'){
formDef.formMsgMeta.FIELD_MANDATORY = 'Dies ist ein Pflichtfeld. Bitte geben Sie einen Wert ein';
}
else{
formDef.formMsgMets.FIELD_MANDATORY = 'これは必須フィールドです。値を入力してください';
}
```
This is how the standard message would look if the app language is Japanese:
#### Use case 2: Dynamically generating form text and data using Variables
**Component**
Suppose you want to ask the user’s name and pre-fill it in the form fields and labels. In this example, the user’s name is captured in an entity node, and that name is used to:
* Pre-fill the **name** field
* Personalize the labels of the other fields
You can use the value captured in the entity node using the context variable in the pre-processor script to pre-populate the **Name** field using the below code:
```
formDef.components[0].metaData.defaultvalueInput = context.entities.entName;
```
This is how it would look at the time of run:
To personalize the labels of other fields like Date of Birth, Phone Number, Email etc. as well, you can add the below code to manipulate the **displayName**:
```
formDef.components[1].metaData.displayName = context.entities.entName + ''s Date of Birth';
formDef.components[2].metaData.displayName = context.entities.entName + ''s Phone Number';
formDef.components[3].metaData.displayName = context.entities.entName + ''s E-Mail';
formDef.components[4].metaData.displayName = context.entities.entName + ''s Address for Correspondence';
```
This is how it would look at run time:
**formMsgMeta:**
Suppose, in addition to personalizing the field labels and pre-filling the Name field, you want to personalize the form’s Response Message text for Mandatory fields by adding the user’s name so that it becomes `User's Name`, this is a mandatory field. Please provide a value\*\*. You can achieve this by adding the below code:
```
formDef.formMsgMeta.useFormMsgMeta = 'yes';
formDef.formMsgMeta.FIELD_MANDATORY = context.entities.entName + ', this is a mandatory field. Please provide a value.';
```
This is how it would look at run time:
#### Use Case 3: Dynamically generating form data from external sources
You can use external sources of data, like data tables, data fetched from API etc to dynamically generate form data.
The syntax to do that is:
```
var resultSet = context.<>.response.body.queryResult;
for (var i=0; i>].metaData.<> = context.<>.response.body.queryResult[i].<>
}
```
Please note that in such scenarios you'll need to add a service node prior to the digital form node, that will fetch the data to be used for dynamically generating the form data.
### Add Components
Once you configure the basic details for your form, the Platform takes you to the form builder, where you can add the components you require.
You can drag and drop the components available on the left pane to the canvas and configure their properties to build the form. For details of the available components & their properties [see here](/ai-for-service/automation/digital-skills/configure-digital-forms#form-editor).
You can search for a given component, or scroll through the list to find what you require.
You can view the components list in a grid format by clicking the icon on the top right of the list.
If you hover in-between components within the form itself, you can find an in-form **Add Component** button which also allows you to search and add new components without having to navigate to the left-side list.
### Add Form Sections
If you're working with a longer and more complex form, you can split it into sections. Hover your cursor in-between form components to reveal an **Add Section** button. Clicking it'll add a title and description to your form, which you can use to organize the other fields into sections.
### Form Actions
From the Forms Listing page, you can:
* Create a **New Form**, as seen above.
* **[Edit](#edit)** the Form.
* Use the **[Branding](#branding)** option to customize a form.
* **[Test](#test)** forms.
* **Delete** forms.
#### Edit
You can use the **Edit** option from the form listing to edit the form. The following actions are performed on the Form in edit mode:
* **The Component Listing** is used for selecting and adding components to the Form by simple drag and drop action.
* Use the **View Toggler** to switch between **Desktop View** and **Mobile View**.
* Use the Move Component *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 Platform.
* **Delete** the Form. Please keep in mind that deleted forms can't be restored.
* Change the Form **Settings** such as name, display name, and description.
* Use the **Component Actions** to access the **Settings**, **Duplicate,** and **Delete** options for each of the form’s components.
* You can change the components’ properties from the **Component Settings** popup:
* Use the **Component Docker** to dock/undock the settings pane 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.
Change the colors and click **Save**. To restore the original appearance, click **Restore Default**.
#### Test
**Test** the form to see a preview of what it would look like to the end user. You can do this at any point while you work on the form.
## Invoke a Form
A digital form can be invoked as follows:
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 the *channel of interaction* or any other criteria based on your requirements.
2. **From a UI flow**: You can add a Digital Form to a pane and choose a dialog task to trigger when the form is submitted from the pane.
In the following sections, we discuss each of the above invocation processes.
### Invocation from Dialog Tasks
Digital Forms are used inside Dialog Tasks for capturing user inputs through a Form Node.
To invoke a form from a dialog task, follow the below steps:
1. Create/open the dialog from where you want to invoke the Digital Form.
2. Click the **+** icon next to the node where you want to add the Form.
3. Select the **Digital Form** option and then the form from the list. You can choose to add a Digital Form directly or use an existing Form Node.
4. You're prompted to select the **Form Experience**, it can be:
* **Only Form UI** – This creates a Form Node and associates it with the Digital Form selected. This is the default option.
* **Both Form UI and Conversation Experience (DRAFT)** – This further prompts you to choose a channel. When a user is using one of the selected channels they're presented with a Form UI, the rest of the channel users get a conversation experience.
This option creates:
* A **Bot Action 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.
* A **Group** encompassing the following nodes. This grouping can be renamed and/or deleted. [Learn more](/ai-for-service/automation/dialogs/manage-dialogs#manage-node-groups).
5. You can set the **Properties** for each of the nodes added.
* The [Form Node](/ai-for-service/automation/dialogs/node-types/form-node). Following Component Properties are of special interest:
* **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 on a full page*. Also, you can either go ahead with the default submit prompt or configure the setting to display a custom and more specific message to be shown in chat. [Learn more](/ai-for-service/automation/dialogs/node-types/form-node#component-properties).
* **Bot Action Node,** in case of the conversation experience flow, can also be configured in the [Logic Node](/ai-for-service/automation/dialogs/node-types/logic-node) as follows:
* **Manage Context Variables** is 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.`
We urge you not to make changes to the connection settings as this affects the AI Agent's performance.
* **Sub-dialog Node** is configured as a normal [Dialog Node](/ai-for-service/automation/dialogs/node-types/dialog-node) as follows:
* Use the **Entity Post-assignment** to capture the user input.
* In case you modify the sub-dialog or the source form, you're presented with an option to **Regenerate Dialog**. This ensures that the changes are reflected in the task without having to rebuild the entire task. Be aware that the changes are reflected in all places this sub-dialog is used.
6. The user input can be accessed as follows:
* Form component values are accessed from the Context Object using `{{context.forms.form_name.component_name}}`
* In the case of the sub-dialog, the variables used in the post-assignment settings as `{{context.}}`
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're using the conversation experience too, remember to connect the auto-generated sub-dialog to the process flow.
### Invocation from Panels
Digital Forms are rendered in Digital Views by configuring Widgets & Panels. [Learn more](/ai-for-service/automation/digital-skills/digital-views).
To invoke a form using Widgets and Panels, follow the below steps:
1. **Create a widget** to invoke the Digital Form within **Digital Views** from **Automation AI > Use Cases > Digital Skills**.
2. Enter the name.
3. Select *Digital Forms* as the **Source.**
4. **Add a Form** by selecting it from the drop-down list.
5. Select the **Dialog to Invoke on Submit** from the drop-down list.
6. Click **Save**.
7. **Add the Widget** to an existing panel or create a new panel.
You can add a form directly to a panel, it creates a widget by default.
8. You can **Test** the panel.
9. Follow the steps provided [here](/ai-for-service/app-settings/dev-tools/kore-ai-web-sdk) to publish and host the panels.
While a Digital Form is used to define multiple Widgets and also add to multiple panels, it'll be associated with a single Dialog Task across all Widgets and Panels.
## The User Experience
When the end-user initiates the dialog and reaches the node connecting to the Form node, the following events take place. Depending upon the experience selected at design time and the channel of invocation, the flow is the following:
### Form Experience
A **link to the form** is presented to the user. Note that for a synchronous WebHook channel, instead of a link the complete form definition is sent [here](/ai-for-service/channels/add-webhook-channel).
Clicking the link opens the form in either full-screen or inline mode, based on the selection. Please note the following details 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-users can fill in the values for the components/fields.
Every form comes with a default **Submit** button. This validates the form entries, prompts for any missing values.
Once the form is validated and submitted, the values are available in the context variable and accessed using the following code: `context.forms..`
Here we're capturing the user entry and displaying it using a message node.
### Conversation Experience
From the channel of operation, the end-user is prompted to enter values for every component in the form.
The values are available in the sub-dialog context and are 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're handled as follows:
| EXCEPTION | EXCEPTION BEHAVIOR |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The user tries to continue the conversation without opening the form link. | The AI Agent asks if the user wants to switch to a new task. |
| The user tries to continue the conversation (in the chat window) without submitting the form responses. | The AI Agent asks if the user wants to switch to a new task. |
| The user closes the form or browser without submitting responses. | If the app is configured to cancel the ongoing task, the form displays a warning message that the task will be canceled. If the user accepts, the form will be closed, and a message is displayed saying that the previous task is canceled. Otherwise, the ongoing task goes on, and based on the configuration, the user is taken to the next step of the task. |
| The user tries to relaunch the form while the form is already open. | The form link won't open the form and a message will be displayed saying that the form link is no longer valid. |
| The user tries to relaunch the form after moving ahead in the conversation. | The form link won't open the form and a message will be displayed saying that the form link is no longer valid. |
### 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 are available in the context variable and accessed using the following code: `context.forms..`.
## Manage AI Agents with Digital Forms
### Publish
The publishing flow for an App with Digital Forms has the following special cases:
As with any AI Agent, the Digital Forms exist in the following states:
* **In-development** when a form is created.
* **Awaiting approval** when a form is submitted to Publish and the request is waiting for the admin to take action.
* **Rejected** when the Publish request is rejected by the admin.
* **Published** In the Platform, the status of a Digital Form remains In Development even after publishing.
On publishing the form, you can see the form listed under **Publish Status → View Publishing Summary**, but the status on the Digital Forms main page remains as *In Development*.
The *In Development* and *Published* versions of the AI Agent can be viewed by toggling between the respective statuses in the top search-bar.
If any edits are done to the Digital Form while it's In Development, the changes would be reflected in the Published version as soon as you publish the form.
* **Suspended** when a published form is suspended by the admin.
### Pre-publishing Validations
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's configured to trigger a Dialog Task is 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 isn't in a published state this triggers:
* The Task Failure Event and the corresponding behavior is invoked or
* A relevant Standard Response is displayed and
* Logged as Failed Task in Analytics.
* Digital Form is in a published state, but the Dialog Task isn't available then on Form submission, the end-user is presented with the Form’s Error Message.
### Import
Digital Forms are included in the full and incremental import of the AI Agent.
For Full Import:
* As with all other AI Agent components, the full import replaces the entire Digital Forms and form details.
For Incremental Import:
* You can choose to include/exclude the Digital Forms in the import.
* This import fully replaces the Digital Forms that are common to the import file and the AI Agent.
* Additional forms in the file are imported into the AI Agent.
* Additional forms in the AI Agent are retained.
* Post import, any invalid Digital Form integration details are disassociated with the corresponding forms.
### Export
The App Export option is available for Digital Forms with a status of *In Development* or *Published*.
* Digital Forms can be selected/deselected from the **App 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 to define widgets.
**Note that this doesn't include the Sub-dialog Tasks generated using Digital Forms.**
* Complete information for each of the selected forms are available in the export file and this includes:
* Fields
* Field properties
* Form integrations
## Form Component Details
### Components List
Following is a list of the available components.
**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.
**Note** : The Date picker displays the month and week names in Japanese characters if the app language is Japanese. This support will be extended to more languages in the future.
* **Date & Time** – Used for date & time entries. The system displays 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](mailto: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 specified min and max values; can be represented as a percentage.
* **Password** - Used to display passwords in their masked form `*****`
**ADVANCED**
* **Button** – Used as a clickable component to submit 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.
Not all the properties are valid for all the components, refer to the [Property Matrix](#component-properties) for the mapping.
| PROPERTY | DESCRIPTION |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Display Name** | This is the text which appears against the component for the end-users. |
| **Name** | This is the reference name that can be used for referencing the component in the other components of the form and form level operations |
| **Description** | Help information about a field to be displayed to the end-user. |
| **Placeholder Text** | A prompt message for the end-user |
| **Button Style** | For button component, can be: Primary, Secondary, Tertiary, Ghost, or Danger |
| **Button Action** | For button component, can be: Submit, Reset, or Go to URL – in this case, you need to enter a URL in the corresponding field. |
| **Read Only** | To mark the component value isn't changeable |
| **Required** | To define whether input for this field is necessary or optional for the end-user entry. |
| **Tool-tip** | Additional information about a field to be shown on demand to the end-user. Has three entries: Tip Text – text message for the additional information about the component Tool-tip Type – whether the tip appears on hover or click Tool-tip Position – where the tooltip should be displayed |
| **Date Format** | Time format to be presented to the end-user can be mm/dd/yyyy – default dd/mm/yyyy yyyy/mm/dd yyyy/dd/mm |
| **Time** | To enable the end-user to enter Time along with Date |
| **Time Format** Used in conjunction with the above Time property | Time format to be presented to the end-user can be 12 hrs or 24 hrs |
| **Default Country Code** | Choose the desired default country code that should be shown to the end-user. Default is United States +1 |
| **Secure Field Data** | To Secure the user information collected by this field. |
| **Masking Type** Available only when Secure Field Data is enabled | Choose how to display the redacted data in the App Context, Debug Logs, Service Calls, Agent Transfer and the Bot Kit. Following actions are available: Redaction – The platform will replace the user input with a unique random system-generated alphanumeric value. This is the default setting when the Secure Field Data is enabled Replacement – The platform will replace the user input with a static value or reference to a context object as entered in the replacement value field. Mask with Character – The platform will replace the first few and last few characters of the user input with symbols. You can specify the number and position of characters to mask, symbol for masking (+ or #). |
| **Mask Input** Available only when Secure Field Data is enabled | Enable this option to mask the end-user’s input for this field in the chat window. |
| **Checkbox Layout** | Choose the number of columns to present the checkbox values in the grid view. You can select a minimum of 1 and a maximum of 4 columns, with 4 columns being the default selection. |
| **Data Settings** | |
| **Default Value** | In case the component needs to be pre-populated with a default value |
| **Values** | For Radio Button, Dropdown and Checkbox, add values to be given for selection by the end-user. You can mark one value as a default value |
| **Multi-Select** | For Dropdown, if the user can select multiple values. |
| **Validation Settings** | |
| **Default Error Message** | To be displayed in case user entry fails validation |
| **Validate** | To define when the validations defined for a field are to be checked. Options are: On blur – Validations would be done when the end-user moves away from the component On change – Validations would be done when the component value is changed |
| **Validation Rule** | Rules in the following format can be added **Operator** – Choose the required option based on the validation condition you want to set for the input field. Each component type supports specific operators that enable the validation. Note The Platform now supports **Regular Expression (Regex)** for more complex validations. It provides a powerful and flexible pattern-matching capability, allowing for precise validation of input formats. Regex checks the input field against the specified pattern, which includes the format and conditions that the input must meet. For example, if the age limit should be 18 and above for vaccination, the regular expression is /^(1\[89]\|\[2-9]\d)\$/gm . **Comparison Type** – Set to either value or field/component or value type. **Comparison With** – The value or component name or type, as per the above selection. Multiple rules added to an existing rule would be taken as an AND condition, whereas a new rule would be an OR condition. You can add multiple Simple rules or a single Advanced rule by toggling between Simple and Advanced Modes. |
| **Custom Error Message** | This would be displayed when a particular validation fails |
| **Visibility Settings** | |
| **Is Visible** | Whether the given component is visible to the end-user or not |
| **Visibility Rules** | You can define conditions when a particular component would be visible or hidden Hide or Visible Add Visibility Rules by defining the following: Component/Field which determines this component behavior- choose from the list Operator – choose from the list Comparison Type – set to either value or field/component or value type Comparison With – the value or component name or type, as per the above selection Multiple rules added to an existing rule would be taken as an AND condition, whereas a new rule would be an OR condition. You can add multiple Simple rules or a single Advanced rule by toggling between Simple and Advanced Modes |
| **Auto Populate** | |
| **Auto Population** | Whether the given component should be auto-populated or not |
| **Auto population rules** | Field or Value from which to auto-populate Field name or the actual value based on the above selection |
| **Custom Validation** | |
| **Custom Validation** | Perform complex field and form level validations on dynamic variables by defining a JavaScript code for the Post Processor script. When the **Submit** button is clicked, the script runs to perform custom validations on multiple form fields before the form submission. For example, create a script that ensures the phone number field accepts only 10-digit numbers and rejects any alphabets or special characters. **Failure Scenario** If the defined Post-Processor script fails, a task failure event is triggered, and the reason for the failure is logged under **Task Execution Logs** > **Debug Log** for the **Form** node. When a field-level validation error occurs, the specific error field is highlighted, and the error message defined in the script is displayed below the field and above the **Submit** button. |
### Component Mapping Properties
#### Basic
| Property | Text Field | Text Area | Number | Radio Button | Check Box | Drop Down | Date | Phone Number | Email | Address | Url | Toggle | Range Slider |
| ---------------------------- | ---------- | --------- | ------ | ------------ | --------- | --------- | ---- | ------------ | ----- | ------- | --- | ------ | ------------ |
| **General Settings** | | | | | | | | | | | | | |
| **Display Name** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Name** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Description** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Placeholder Text** | Yes | Yes | Yes | No | No | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes |
| **Read Only** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Required** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Tool-tip** | | | | | | | | | | | | | |
| **Tip Text** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Tool-tip Type** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Tool-tip Position** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Date Format** | No | No | No | No | No | No | Yes | No | No | No | No | No | No |
| **Time &** **Time Format** | No | No | No | No | No | No | Yes | No | No | No | No | No | No |
| **Default Country Code** | No | No | No | No | No | No | No | Yes | No | No | No | No | No |
| **Checkbox Layout** | No | No | No | No | Yes | No | No | No | No | No | No | No | No |
| **Secure Data** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Masking Type** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Mask Input** | Yes | No | Yes | No | No | No | No | No | No | No | No | No | No |
| **Data Settings** | | | | | | | | | | | | | |
| **Data Source** | No | No | No | Yes | Yes | Yes | No | No | No | No | No | No | No |
| **Default Value** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Multiselect** | No | No | No | No | No | Yes | No | No | No | No | No | No | No |
| **Auto Fill** | | | | | | | | | | | | | |
| **Auto Populate** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Auto Populate Settings** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Visibility Settings** | | | | | | | | | | | | | |
| **Is Visible** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Visibility Settings** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Validations** | | | | | | | | | | | | | |
| **Default Error Message** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Validate** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Equals To** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | TBD | Yes | Yes | Yes |
| **Not equal to** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | Yes | Yes | Yes |
| **Contains** | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No |
| **Doesn't contain** | Yes | Yes | No | No | No | No | No | No | No | | No | No | No |
| **Regex** | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Max Length** | Yes | Yes | No | No | No | No | No | Yes | Yes | | Yes | No | No |
| **Min Length** | Yes | Yes | No | No | No | No | No | Yes | Yes | | Yes | No | No |
| **Part of** | Yes | No | No | No | No | No | No | No | No | | No | No | No |
| **Not part of** | Yes | No | No | No | No | No | No | No | No | | No | No | No |
| **Greater than** | No | No | Yes | No | No | No | Yes | No | No | | No | No | Yes |
| **Less than** | No | No | Yes | No | No | No | Yes | No | No | | No | No | Yes |
| **Greater than or equal to** | No | No | Yes | No | No | No | Yes | No | No | | No | No | Yes |
| **Less than or equal to** | No | No | Yes | No | No | No | Yes | No | No | | No | No | Yes |
#### Advanced
| PROPERTY | BUTTON | RICHTEXT | PRO-TIP |
| -------------------------------------- | ------ | -------- | ------- |
| **General Settings** | | | |
| **Display Name** | Yes | Yes | Yes |
| **Name** | Yes | Yes | Yes |
| **Description** | Yes | No | Yes |
| **Placeholder Text** | No | No | No |
| **Tool-tip** | Yes | Yes | No |
| **Error Message** | Yes | No | No |
| **Required** | No | No | No |
| **Validate** | Yes | No | No |
| **Read Only** | Yes | No | No |
| **Action Type** (Submit, Reset, Clear) | Yes | No | No |
| **Data Settings** | | | |
| **Data Source** | No | No | No |
| **Default Value** | No | No | No |
| **Auto Fill** | | | |
| **Auto-Populate** | No | No | No |
| **Auto-Populate Settings** | No | No | No |
| **Visibility Settings** | | | |
| **Is Visible** | Yes | Yes | Yes |
| **Visibility Settings** | Yes | Yes | Yes |
#### Dialog Node
The following mapping gives the type of entities included in the sub-dialog when it's auto-generated from a Digital Form.
| Form Component Property | Dialog Task Node Property |
| ----------------------- | ------------------------- |
| Name | Name |
| Display Name | Display Name |
| Placeholder Text | Entity Prompt |
| Error Message | Error Prompt |
| Digital Form Component Type | Dialog Task Node Type |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text Field | String |
| Text Area | Description |
| Number | Number |
| Radio Button | LoI (Enum) with each of the options in the radio button group copied as list items |
| Dropdown | LoI (Enum) with each of the values in the dropdown list copied as list items. Multi-select would be enabled based on the ‘is multi-select’ option of the Form Component |
| Checkbox | LoI (Enum) with each of the options in the checkbox group copied as list items Multi-select is enabled by default |
| Date | Date |
| Phone Number | Phone Number |
| Email | Email |
| Address | Address |
| URL | URL |
| Toggle | LoI (Enum) with each of the options in the toggle copied as list items |
| **Advanced** | |
| Button | Not Applicable |
| Label | Not Applicable |
| Protip | Not Applicable |
| Note | Not Applicable |
#### Context Object
The following mapping gives the context object to capture the component value along with a sample context object.
| COMPONENT TYPE | CONTEXT OBJECT |
| -------------- | -------------------------------------------------------------------------------- |
| Text Field | context.forms. . |
| Text Area | context.forms. . |
| Number | context.forms. . |
| Radio Button | context.forms. . |
| Dropdown | context.forms. . \[ ] |
| Checkbox | context.forms. . \[ ] |
| Date | context.forms. . In mm/dd/yyyy format |
| Date & Time | context.forms. . In mm/dd/yyyy hh:mm AM/PM format |
| Phone Number | context.forms. . prefixed with the area code of the country selected by the user |
| Email | context.forms. . |
| Address | context.forms. . |
| URL | context.forms. . |
| Toggle | context.forms. . Yes/No values |
| Range Slider | context.forms. . |
**SAMPLE CONTEXT OBJECT**
```js theme={null}
"forms": {
"basicpropertieslist": {
"TextField": "text",
"Textarea": "text area",
"Number": 123,
"Radio": "Male",
"Dropbox": [
"UnderGrad",
"Other"
],
"Checkbox": [
"Education",
"Technology"
],
"Date": "07/08/2020",
"Date&Time": "07/08/2020 19:00 PM",
"PhoneNumber": "+919999999999",
"Email": "john.doe@example.com",
"toggle": "Yes",
"Address": "Address",
"Url": "test.com",
"rangeSlider": 26.1
}
}
```
### Prefill Form
You can specify data that can be used to pre-populate the form fields. Platform will check for the availability of any form prefill information before launching the form. If any information is available, then the corresponding fields in the form are pre-populated before presenting the form to the user. The values can be static or from a context object.
You can specify pre-fill form data using the following context object: `context.prefillForms`.
You can use the following in Javascript to populate the above-mentioned context object:
```js theme={null}
context.prefillForms = {
: {
fields: {
: "",
: ,
: [