Use Form to capture Structured Data
  • Updated on 17 Aug 2019
  • 5 minutes to read
  • Contributors
  • Print
  • Share
  • Dark
    Light

Use Form to capture Structured Data

  • Print
  • Share
  • Dark
    Light

An App may drive a purposeful conversation; however, this does not necessarily mean that a conversation is always the best way to relay and process information. If certain information is a prerequisite of every transaction in a particular sphere then it may be best – i.e. most efficient – to process using a form.

Take, for example, a hotel booking. When searching for a hotel, criteria such as ‘Destination’, ‘Check In Date’, ‘Check Out Date’, ‘Number Of Guests’ and ‘Type Of Room’ are a prerequisite.

FrontM therefore allows such criteria to be entered in forms that are built dynamically as part of a conversation, allowing the processing of such structured data in a more user-friendly way.

A form will appear because the user needs it as a consequence of their intent - the intent in the above example being 'book a hotel room'. The developer must therefore enable the use of forms via the Intent class - specifically by implementing the onResolution() method to call the state object's addResponse(type, message) method, which passes all messaging (including forms) via the Abstraction Layer.

state.addResponse(type, message) therefore interfaces with the Capabilities Layer, where an object of the Message type form2Message will be implemented. This represents a form in which the user can enter structured data:

let Message = botContext.getCapability("Message");
let message = new Message();
message.form2Message(
  [
    {
      id: 'field name',
      title: "field label",
      type: "text_field",
      value: "",
      mandatory: true, //Default false
      readOnly: true //Default false
    },
    {
      id: 'field name',
      title: "field label",
      info: "Test to show in the I icon",
      type: "text_area"
    },
    {
      id: 'field name',
      title: "field label",
      type: "checkbox",
      options: ['box 1', 'box 2']
    },
    {
      id: 'field name',
      title: "field label",
      type: "radiobutton",
      options: ['option 1', 'option 2', 'etc']
    },
    {
      id: 'field name',
      title: "field label",
      type: "dropdown",
      options: ['option 1', 'option 2', 'etc']
      value: 'option 1'
    },
    {
      id: 'field name',
      title: "field label",
      type: "switch",
      value: false //Default false
    },
    {
      id: 'field name',
      title: "field label",
      type: "slider",
      value: 0 //Default 0 percent, maximum 100
    },
    {
      id: 'field name',
      title: "field label",
      type: "date",
      value: 0 //Default 0 percent, maximum 100
    },
    {
      id: 'field name',
      title: "field label",
      type: "multi_selection",
      options: ['option 1', 'option 2', 'etc']
    },
    {
      id: 'field name',
      title: "field label",
      type: "password_field"
    }
  ],
  {
    formId: 11111,
    title: "Vessel details",
    description: "Please fill the vessel details",
    confirm: "Save", //Default is Done
    cancel: "Cancel" //Default is Cancel
  }
);
tell(message, botContext);

Once the form is created, a flow is set up whereby the user interacts with the form, and the form then interacts with the App.

Response

When a form interacts with an App, it does so via the Message type formResponseMessage. This type may be populated in ways that reflect the types of responses sent from the form to the App:

  1. Confirm: When the user clicks on the ‘Confirm’ button, the formResponseMessage object will be passed with the field ‘formId’ set, the action set to ‘confirm’ and the values of the fields as shown in the response format below;
  2. Cancel: When the user clicks on the ‘Cancel’ button, or when the form receives a cancel request from the App, the formResponseMessage object will include the relevant ‘formId’ and the action ‘cancel’;
  3. Close: When the user closes the form window, or touches back on the phone, the formResponseMessage object must set the ‘formId’ field and the action to ‘close’;
  4. Search: When a user navigates to a ‘LookUp’ field (one which accesses data in another form) and touches the ‘Search’ icon, the form must send a formResponseMessage object set with the ‘formId’, the action set to ‘search’ and the ‘currentField’ set to the current field Id;
  5. Move: When the user moves from one field to another, or either a field dropdown, checkbox or radio button is selected, the form must send a formResponseMessage type with the ‘formId’ set, the action set to ‘move’ and the ‘currentField’ set with the field Id that the user is moving from and the value of the field.

Dynamic changes to the form

A form opened by the App in the conversation window can change dynamically owing to:

  1. Population by search results: After a 'search' the formResponseMessage object is sent to the App (see above) and the form will wait for the results. The App will send back the field ‘options’ (is 'options' a type not a field?).
    Inside 'options' is a property called 'action'. In this case the ‘action’ will be ‘results’. There is, in fact, another field within ‘options’ called 'results', which is an array of objects, including the actual results (that populate the form).
    Within each object there will be one 'text' field to be displayed (as the results), as well as an 'info' field to be shown as a drill down, offering more information similar to that displayed. This ‘info’ field is optional.
    While the form is waiting, it will show an activity indicator instead of the ‘Search’ button. Once the results are received, the activity indicator will disappear and the results shown.

  2. Field changes: After a ‘move’ action, the App might analyse the new value that has been set and change the options available in other fields, add more fields to the form, or remove fields from the form.
    The form will, in response, receive a call from the App with the ‘options’ type/field (?) property ‘action’ set to 'change'. The corresponding array will now contain modified form elements, and any new fields to be added. Fields that need to be removed will be added to a new field within ‘options’ called 'remove'.

Form response format (code needs changing to formResponseMessage?)

response = {
  formId: 11111,
  action: 'cancel', //confirm, cancel, close, search, move
  currentField: 'field.id',
  currentFieldValue: 'field.value',
  fields: [
    {
      id: 'field name',
      value: 12
    },
	// Other fields
  ]
};

Form live changes format

message.form2Message({
    field: id,
    remove: ['field.id1', 'field.id2', '...'],
    results: [
        {
            text: 'value',
            info: 'info'
        },
        '...'
    ],
    fields: [
        {
            id: 'field name',
            value: 12
        },
        // Other fields
    ]
},
{
    formId: 11111,
    action: results, //results, change
}
)
Was this article helpful?