WebForm¶
A form displayed on the web. WebForm makes it possible to display a form to the web visitor which they should complete and submit to the iCC database as ScenarioResult/ScenarioResultValue records, or the records can be drawn from the query string parameters.
Important
WebForm is an application of the WebSite module. Before you can use it, you must install and configure it.
Optionally, the form may be associated with a specific call, message (e.g. e-mail), issue or contact. The form can also be used to start a chat - once information has been filled out in the form, a chat starts and the form is associated with the chat.
Another option is to start a full workflow when the form has been submitted.
Configuring scenarios for WebSite¶
WebForm uses dynamically defined forms. You need to define the form scenario as usual:
Screens - In the current rendering, the split into screens is not reflected in any way, but it can be useful on the agent side:
And individual elements, including their parameters:
XSS settings¶
The XSS filter controlled by the XssWebSiteApi configuration parameter is an important setting.
Logging¶
See also
General information about WebSite logging.
WebChat event types:
WebFormApp (100) - Download the script from ~/scripts/webchat.js, EventData=URL of the page that downloads the script; this event is always logged, regardless of the status of the LogEvent switch in the WebSiteRouting condition (among other things, it is because the conditions are not evaluated in any way for downloading the script).
WebFormSubmit (101) - The calling of ~/api/webform/submitform, EventData = JSON serialized form data, ReferenceId - ScenarioId scenarios, Result - ExtReponse value returned from the form page.
WebRoutingFormNone (110) - The calling of ~/api/routing/webform, but either the rule scenario was not filled in or the scenario definition was not available; EventData=URL of the page where the script is running; ReferenceId - ScenarioId of the scenario from the rule that was used; Result - Template (a name of the template from the applied rule).
WebRoutingFormFound (112) - The calling of ~/api/routing/webchat, a scenario was found according to which the form should be filled in, EventData=URL of the page where the script is running, ReferenceId - ScenarioId of the scenario found, Result - Template (a name of the template from the used rule).
WebChatRoutingBlocked (113) - The calling of ~/api/routing/webchat, in which a rule with a block flag was found, EventData=URL of the page where the script is running, ReferenceId - ScenarioId of the scenario from the rule that was used, Result - Template (a name of the template from the applied rule).
WebRoutingUserAgent (20) - Additional information accompanying the WebRoutingFormXXX events; the events are generated only if the request contained the QueryString parameter with IncludeSettings=true (in the standard script only after reloading the page); EventData=UserAgent (browser information); Result=PreferedCulture.
WebRoutingUserToken (20) - Additional information accompanying the WebRoutingFormXXX events; the events are generated only if the request contained the QueryString parameter with IncludeSettings=true (in the standard script only after reloading the page); EventData=UserToken (optional user information); Result=Template (the template name from the condition used).
Integration using JavaScript¶
See also
General information about WebSite application integration using JavaScript.
Applications that are rendered in a visible form use the template (.html extension) and settings (.json extension) files located in the Content folder for their rendering. The default templates have the same name as the application name. A standard script template that has the .js extension is used depending on the type of application in the following ways.
Example of an embedded script:
<script type="text/javascript" src="https://chat.example.cz/scripts/webform.js"></script>
Caution
The webform.js file is located in the Content folder. This file is just a template that is expanded with dynamic values. If you accidentally reference this file in the “script” tag above, the form may render but does not work at all. You must reference the Script virtual path.
Example (index-form.html):
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>FrontStage Website (F)</title>
<meta name="author" content="www.atlantis.cz" />
<script src="website/scripts/webform.js"></script>
</head>
<body>
<h1>FrontStage</h1>
<p>Empty page for form testing.</p>
<form id="icc3-form-box">
</form>
</body>
</html>
HTML templates, styling and settings¶
The template and the settings files are cached on the server side for the time of ScriptCaching. Before being sent to the browser, the macro expansion of the text ##WebSiteAddress## is performed by replacing the text from web.config from the WebSiteAddress parameter.
WebForm.html default template¶
Not used; the rendering is done to the prepared <form> element. The basic page styling is used to highlight the form (added to <head> in index-form.html):
<style>
#icc3-form-box {
font-family: Calibri, Arial, sans-serif;
background-color: #e0e0e0;
padding-top: 6px;
padding-bottom: 12px;
}
#icc3-form-box div {
display: block;
margin: 18px;
}
#icc3-form-box div label {
display: block;
font-weight:bolder;
}
#icc3-form-box div input, select, textarea {
min-width: 400px;
}
#icc3-form-box button {
margin-left: 18px;
}
</style>
Default settings of WebForm.json¶
{
"LabelOnly": "<div class='form-group'><label for='##ID##'>##DisplayName##</label><p class='form-control-static'>##ControlText##</p></div>",
"TextArea1": "<div class='form-group'><label for='##ID##'>##DisplayName##</label><input type='text' class='form-control' id='##ID##' placeholder='##Description##'></div>",
"TextAreaN": "<div class='form-group'><label for='##ID##'>##DisplayName##</label><textarea class='form-control' rows='##ControlNumber##' id='##ID##' placeholder='##Description##'></textarea></div>",
"DropDown": "<div class='form-group'><label for='##ID##'>##DisplayName##</label><select class='form-control' id='##ID##'>##Options##</select></div>",
"DropDown.Option": "<option value='##ResultText##'>##DisplayName##</option>",
"SubmitButton": "<button class='btn btn-primary' id='##ID##' type='submit' onclick='icc3_WebForm.submitForm(event);'>##Text##</button>",
"ResultOK": "<div class='alert alert-success'>##Text##</div>",
"ResultFail": "<div class='alert alert-danger'>##Text##</div>"
}
Meanings of elements and settings¶
The individual parameters are HTML macro elements and correspond to the types of form elements (ControlType); they are used directly to render the respective element with the following substitutions.
The following texts are replaced in LabelOnly - a template for a readable label:
##ID##- The element GUID (ScreenControlId)##DisplayName##- The form element name (title - DisplayName)##ControlText##- Text information on the element (ControlText); it can contain HTML.
In TextArea1 - A text box template for the number of lines of 1; the following texts are replaced:
##ID##- The element GUID (ScreenControlId)##DisplayName##- The form element name (title - DisplayName)##Description##- The element description (Description); it can contain HTML.
In TextAreaN - A text box template for a greater number of lines; the following texts are replaced:
##ID##- The element GUID (ScreenControlId)##DisplayName##- The form element name (title - DisplayName)##Description##- The element description (Description); it can contain HTML.
In DropDown - A template for a selection drop-down menu - main section:
##ID##- The element GUID (ScreenControlId)##DisplayName##- The form element name (title - DisplayName)##Options##- A set of expanded DropDown.Option templates for menus.
In DropDown.Option - One menu template for the DropDown element:
##DisplayName##- The option name (taken from ScreenControlParameters)##ResultText##- A value of the option in the text representation##ResultNumber##- A value of the option in a numeric representation
In SubmitButton - A template for the Submit button:
##ID##- The element GUID (ScenarioId) - once the form has been submitted, the element with this ID is set to hide display:none.##Text##- A sign on the button, taken from the localization; the SubmitButton element (102/100)
In ResultOK - A template that will be displayed once the form has been successfully submitted:
##Text##- A sign on the button, taken from the localization; the SubmitOK element (102/101)
In ResultFail - The template that will be displayed if the form cannot be submitted:
##Text##- A sign on the button, taken from the localization; the SubmitFail element (102/102)
Caution
In a production environment, we recommend disabling the Content folder using http (either by means of the ACL rights or by removing it from operational access in the IIS).
Localization¶
Group 102 texts are required in the localization in the LiteralLookup table:
EXEC DefineLiteralLookup 102, 100, 'cs-CZ', N'SubmitButton', N'Odeslat formulář'
EXEC DefineLiteralLookup 102, 101, 'cs-CZ', N'SubmitOK', N'Formulář byl úspěšně odeslán. Děkujeme za spolupráci.'
EXEC DefineLiteralLookup 102, 102, 'cs-CZ', N'SubmitFail', N'Formulář se nepodařilo odeslat, zkuste to prosím znovu.'
To determine the language of localization, the data is primarily from the condition of the given application. However, to avoid the need to map languages for each remaining condition setting (which would only lead to a multiplication of the number of conditions by the number of locale languages), the mapping can be defined using “Lang” type virtual application:
If the localization is not determined from the application rules (e.g. WebForm), then the system will try to determine the mapping according to the Lang application (all conditions are evaluated in the usual way). If even this evaluation does not provide data, then the default value of DefaultLangugage from web.config will be used.
Extending the localization with other languages is possible by adding items (e.g. using an analogous script as above) to the LiteralLookup table. Changing localization texts is possible directly in the LiteralLookup table, with the values being cached on the server side with the DatabaseCaching refresh interval.
Texts in the localization can contain HTML tags directly if the information is to be formatted or expressed in some way, e.g. by means of images.
Demo¶
To facilitate integration, the application also includes several demo pages that show the method of integration and procedures for implementing co-browsing.
The simplest page is in the default application directory and is called “index-chat.html”; the content is shown in the example at the beginning of the chapter.
The pages allow you to test parallel navigation, Page 2 then allows you to send co-browsing data.
Note
In a production environment, we recommend that you delete both the index-chat.html file and the Demo folder.
Integration using REST API¶
See also
General information about WebSite application integration using REST API.
Routing¶
See routing in website-overview.
TargetElementID - Identifies how the form application should be rendered; if NULL is specified, it should be rendered as an ovelay; if an element ID is specified, it should be rendered as an element (typically a FORM) with that ID; third-party scripts can use the parameter at their discretion.
WebResponse - A free parameter (up to 32 characters) that can be passed to a page or third-party script.
Signal - Not used
ChatRunning - Not used
Scenario - Structure of the [ScenarioModel] form to be drawn on the page to be filled in; if it is blank, the form will not be rendered.
PartyName - Not used
HtmlTemplate - An expanded template (file) stored on the server side in the Content folder with the .html extension and selected using the WebSiteRouting conditions; the field is sent only if it is requested by the “IncludeSettings” parameter; the template is typically used as overalls unless the TargetElementID parameter is specified; the default name is webform.html.
Settings - An expanded JSON dictionary structure of key-value stored on the server side in the Content folder, with the .json extension and selected using the WebSiteRouting conditions; the default name is webform.json.
Literals - A JSON key-value dictionary structure stored in the iCC DB in the LiteralLookup table for Group 102, and localization determined by the WebSiteRouting condition; the field is sent only if it is requested by the “IncludeSettings” parameter.
SolicitationTimeOut - Not used
SolicitationDuration - Not used
WebSiteRoutingId - An ID of the condition that is used for the page.
API¶
[POST] ~/api/WebForm/SubmitForm - (the ResultModel structure must be submitted in the request). In response, it gets a boolean value with an indication of 200 OK. A value of true indicates that the form has been submitted to the application server successfully, a value of false indicates that the submission failed, so the user should submit again.
Fields in the submitted request [ResultModel]:
UserToken - A free string of up to 320 characters designed to distinguish server-side requests; it can be used, for example, to indicate whether a visitor is logged in or not, etc .; an optional field.
ExtResponse - A free string of up to 32 characters, intended for processing in a subsequent workflow; an optional field.
ScenarioId - An ID of the scenario according to which the form was filled in; an optional field.
Values - Values of the associated form
Location - The URL from which the chat is started (this information is used as an alternative to the Referrer HTTP header; if it is not present, its completion is optional).
WebSiteRoutingId - An ID of the condition that is used for the page.