Skip to content

Form

A form is like a collection of menus or raw responses and it is basically collecting information from the user.

It is composed by a header, a body and a footer. The body represents form items and these can be slightly modified menus or raw responses.

The form items are being processed in a successive manner. After all the form items have been processed, the user can confirm his choices or reset any of them.

JSON Structure

All fields prefixed with a star (*) are required

Form

A top level component used to acquire information from the user

KEY TYPE NOTES
*body array Sequence of FormItem objects used to acquire information from user
footer string The footer of the form. It can be overwritten by each body component
header string The header of the form. It can be overwritten by each body component
meta object FormMeta object. Contains configuration flags
method string HTTP method indicating how to trigger the callback path. Defaults to "POST"
available: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"
*path string The callback path used to send the serialized form data
*type string Indicates the type of the object, defaults to "form"

FormMeta

Form related component holding configuration fields for the form

KEY TYPE NOTES
completion_status_in_header boolean If true will indicate the status in the header. Defaults to false, which means it will be shown below header if the completion status is shown
completion_status_show boolean If true will show a completion status. Defaults to false
confirmation_needed boolean If false will not ask for confirmation. Defaults to true

FormItem

Form related component used to acquire certain information from the user

KEY TYPE NOTES
body array Composed of MenuItemFormItem objects
required only for type=form-menu
chunking_footer string Shown in the footer of the sms chunks
confirmation_label string Shown in the confirmation menu
*description string The description of this FormItem
footer string If provided will overwrite the Form.footer
header string If provided will overwrite the Form.header
max_length integer Validates the user input
applies only for type=string
max_length_error string Message to be shown on max_length error
max_value number Validates the user input
applies only for type=int|float
max_value_error string Message to be shown on max_value error
meta object MenuFormItemMeta object
applies only for type=form-menu
method string Http method, how the callback url should be triggered
available: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"
min_length integer Validates the user input
applies only for type=string
min_length_error string Message to be shown on min_length error
min_value number Validates the user input
applies only for type=int|float
min_value_error string Message to be shown on min_value error
*name string The name of this FormItem, used in form serialization
required boolean User can SKIP this FormItem if set to false
status_exclude boolean If true this step will be excluded from the form completion status
status_prepend boolean If true this step will be prepended to the body of the response. Appended otherwise
*type string Indicates the type of the object
available: "string", "date", "datetime", "hidden", "int", "float", "form-menu", "email", "url", "location"
url string Callback url triggered right after the choice has been set for this form item
validate_type_error string An error message to be shown on basic type validation
validate_type_error_footer string Shown in the error message footer
validate_url string The callback url path "GET" triggered to validate user input.
A query string is sent by ONEm: ?form_item_name=user_input
The validate_url must return a json response: {"valid": true/false, "error": "Some message in case of validation errors"}
value string Value to pass in the form serialization data
applies only for type=hidden

FormItem related component used to display menu items, selectable or raw

KEY TYPE NOTES
*description string The description for this MenuItemFormItem
text_search string If the user does not send a proper option marker and sends some input, this field will be used to search and narrow down the options against the user input
max 1000 chars
*type string Indicates the type of the object
available: "option", "content"
value string The value for this MenuItemFormItem, used in form serialization
required only for type=option

FormItem related component holding configuration field for a menu inside a form item

KEY TYPE NOTES
auto_select boolean Will be automatically selected if set to true and in case of a single option in the menu
multi_select boolean Allows multiple options to be selected
numbered boolean Displays numbers instead of letter option markers

Swagger

The schema can also be found on Swagger Hub here

JSON Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
    "body": [
        {
            "type": "string",
            "name": "descr",
            "description": "Provide a description",
            "min_length": 5,
            "min_length_error": "Please write a longer description",
        },
        {
            "type": "date",
            "name": "due_date",
            "header": "due date",
            "description": "Provide a due date"
        },
        {
            "type": "form-menu",
            "name": "prio",
            "header": "priority",
            "body": [
                {
                    "type": "option",
                    "value": "high",
                    "description": "High priority"
                },
                {
                    "type": "option",
                    "value": "low",
                    "description": "Low priority"
                }
            ]
        }
    ],
    "header": "create task",
    "footer": null,
    "meta": {
        "confirmation_needed": false
    },
    "method": "POST",
    "path": "/task/create",
    "type": "form"
}

Notice the 'type': 'form' key value pair, which indicates the form response.

So when the user sends a to access the New todo option item, as mentioned here ONEm will send a GET request to http://your-callback.url/task/create/. This url should return something like the above json structure.

The user will be taken through a wizard and it will look like:

1
2
#TODO CREATE TASK
Provide a description

This is the first step and whatever the user replies with will be set as the task description. This is a string and it will be POSTed to path as indicated in the json structure. Notice there is no header or footer mentioned at this step, so form header and footer will be used as fallbacks.

1
2
#TODO DUE DATE
Provide a description

This is the second step and the user needs to reply with a date. There is no callback path so no HTTP request will be performed after this step. The header is present here, so it will be displayed instead of the form header.

1
2
3
4
#TODO PRIORITY
A High priority
B Low priority
--Reply A-B

This is the last step and the user needs to choose one option.

After all steps have been processed, as indicated through method and path, the form will be serialized and an HTTP POST will be sent to the path which is relative to the callback url: http://your-callback.url/task/create/

So the POST will look like: ?descr=some_description&due_date=2019-10-10&prio=high

Type

The response type should be equal to form to indicate a form response.

The header of the form is indicated through header key. This value is not final and will be altered by the ONEm platform, by making it uppercased and placing the name of your app in front of it.

Body

The body holds an array of objects. Each object is called a FormItem and it is described in the Json Structure

The footer of the form is indicated through footer key and like the header of the form, it is not final and will be altered by the ONEm platform. If no footer is specified, a default might be set.

Path & Method

The path set in the Form object is triggered right after the form has been finished and confirmed by the user.

All the values will be sent to your callback path as a form serialized data, ie object with key value pairs: name_of_the_form_item = user_input

If there is a form-menu FormItem with multi_select set and the user chooses more than one option, then the value of the corresponding pair will be an array of the selected values.

Meta

The meta key holds a FormMeta object used to indicate certain behaviors for the Form.