Chatbot Controls with Action Forms

Action forms allow for automatic mapping to controls in forms. For example you could use an action form to map controls for a light, to turn it on/off up and down. With an Action form you define an object and what it can do, Sedro then will call the corresponding controls when they are requested in the text or chat.

There are many ways in language to ask for something simple, such as control for a light, it can come as a question, command or be ambiguous. Some examples:

Turn the lights on. 
Turn the lights up. 
Close the light. 
Hit the lights. 
Lights on! 
Please lower the lights. 
lights on. 
Dim the lights please.
please get the lights.
If the lights are off, turn them on.
lights brighter.
lights brightest, now!
Make the lights lower.
Will you please lower the lights?

Here we will use a light example to show what can be done with Action forms

Adding a Action Form / Object

Action forms can be used to define an object, such as a light or a kitchen light in this case. They are the same as all other forms, but are added as an ‘action’ form in the Persona Manager.

 <form name='kitchen light' data-type='action'
 data-classifier='light'  
 data-object-type='thing' 
 > ....
</form>

The basic action form has data-type=’action’ so the system knows to map this to objects in the ontology. data-classifier=’light’ is set to map the object type of this form/object, this is a light and will be added to the ontology as a light. data-object-type=’thing’ tells Sedro that this is a physical object. There are some optional attributes covered later that allow more explicit mapping

Adding Controls

To get the Form to respond in a chat we must add a control, which is just an input like in all forms. Here we add a comment control to send a message when we ask to open or close the light.

 <input name="answer" data-crmd='comment' data-ability='open, close' data-type="comment" />
 <label for="answer" state='wake'>You want me to %current/cmd_action% the %current/cmd_object_instance%?</label> 

Control Input attributes

This has a few new attributes added to it to allow it to map the specific abilities.

data-ability=’open, close’ defines abilities or actions that the form/object is capable of. If added to a form defines what an object can do, if added to an input maps that input to the ability.

data-crmd=’comment’ is used to tell sedro that this control is a comment; the full set of options are create/read/modify/delete/comment. read is the default.

data-mod=’up, down, brighter’ defines modifications that the object is capable of, if added to the object. If added to an input, the input is then mapped to these modifications.

data-state=’on, off, broken’ defines states that the object can be in or set to, if added to an object. If added to an input, the input is then mapped to these modifications.

REST API Control

To call a REST API an input is added of type post, just as in all other forms. Here we define an input to turn the light on, it has a few states and abilities added to it to make it an easy example to work with.

 <input name="on" data-crmd='modify'  data-ability='turn, raise, flip, toggle, switch'  data-state='on, bright, open'  data-status-value='10' data-status-op='set'  data-type="post" data-posturl='http://api.sedro.xyz/api/1.0/test/testformgetpost'/>  <label for="on" state='done'>Updated, the light is now %current/status%</label> 

Standard Params

Each API Call will have a set of system parameters that will provide more context, use them or ignore them. In addition any inputs added to the form (that are not controls) will also be passed in with the value set.

  • cmd_action – the action turn / flip / switch
  • cmd_mod – the modification on / off
  • cmd_object – object and object class: kitchen light / light
  • cmd_object_instance – instance object ‘kitchen light’
  • lang – language
  • ctok – caller token passed into chat or sedro instance
  • chid – channel id
  • status – (next section)

The Status value

The status parameter is auto filled by sedro based on the information it finds in the question or command. It will automatically use the meaning of the words to determine what value to set based on the type of status you need as specified the status input via attributes

  • data-value-type – has options of range/list/none
  • data-value-min – should be set to the minimum value if range
  • data-value-max – should be set to the maximum value if range

For controlling a light a range is used (dimmable) with a min of 0 and a max of 10. This will send to the api a status with val=’set’, ‘increment’, or ‘decrement’ and val2=0-10

Overriding Status Value

An input/control can override the auto setting of the status value with the follow attributes on the input

  • data-status-value=<the value to send> – value or string
  • data-status-op=<operation to perform> – set/increment/decrement

Form Attributes detailed

There are 2 additional attributes that can be added to a an action form to provide it mappings to alternate names, that are not already know to the language or are not working correctly.

  • data-alias=‘my kitchen light’ – specifies other phrases or words that will be globally equal to the name of the form/object
  • data-ref=‘big kitchen light’ – specifies non-global but possible alternates in context for the name of the form/object
  • data-synonym=’xxx’ – specifies one or more objects that will get the same controls, that are synonyms for this object

Optional Verification

Prior to executing the input a verification will requests user to confirm, just as in other forms. Add this to any control input in the form.

 <label for="on" state='verify'>You would like to %current/cmd_action% the lights?</label> 

NOTE: be cautious with these in non-interactive content, they may block further progress.

Full Example

The following example Action form is for controlling the kitchen light (it has some unneeded elements to aid as examples)

 <form name='kitchen light' data-type='action'
 data-classifier='light'  
 data-object-type='thing' 
 data-seq='%action% X:lights:%'  
 data-alias='my kitchen light' data-ref='big kitchen light'
 >
 <input name="status" data-type="input" data-value-type='range' data-value-min='0' data-value-max='10'/>
 <input name="location" data-type="input" value='kitchen'/> 
 
 <input name="answer" data-crmd='comment' data-ability='touch' data-type="comment" />
 <label for="answer" state='wake'>You want me to %current/cmd_action% the %current/cmd_object_instance%?</label>
 
 <input name="read" data-crmd='read' 
 data-ability='status, level, brightness, is'
 data-type="post" data-posturl='http://api.sedro.xyz/api/1.0/test/testformgetpost'/>
 <label for="read" state='done'>The light is %current/status%</label>
 
 <input name="modify" data-crmd='modify'
 data-mod='up, down, brighter, darker, dimmer, lower, higher'
 data-ability='turn, shut, dim, raise, hit, get, flip, toggle, switch'
 data-state='bright, dark, dim, high, low'
 data-type="post" data-posturl='http://api.sedro.xyz/api/1.0/test/testformgetpost'/>
 <label for="modify" state='verify'>You would like to %current/cmd_action% the lights?</label>
 <label for="modify" state='done'>Updated, the light is now %current/status%</label>
 
 <input name="on" data-crmd='modify'
 data-ability='turn, raise, flip, toggle, switch'
 data-state='on, bright, open'
 data-status-value='10' data-status-op='set'
 data-type="post" data-posturl='http://api.sedro.xyz/api/1.0/test/testformgetpost'/>
 <label for="on" state='verify'>You would like to %current/cmd_action% the lights?</label>
 <label for="on" state='done'>Updated, the light is now %current/status%</label>
 
 <input name="off" data-crmd='modify'
 data-ability='turn, shut, dim, flip, toggle, switch'
 data-state='off, dark, closed'
 data-status-value='0' data-status-op='set'
 data-type="post" data-posturl='http://api.sedro.xyz/api/1.0/test/testformgetpost'/>
 <label for="off" state='verify'>You would like to %current/cmd_action% the lights?</label>
 <label for="off" state='done'>Updated, the light is now %current/status%</label>
 </form> 

This can be added to a persona like any other and the POST actions mapped. Make changes to the abilities and modifiers to see how it works in practice.

To Be Continued…

In the next blog on Forms we will focus on filter input that allows for lists of input parameters to be gathered, and modified by text.