Flows

A flow is a special YAML file that represents a graphical conversation flow, as a graph consisting of nodes and links. Flows can be edited using a graphical flow editor.

Introduction¶

For simple bots and IVRs, having users use plain Bubblescript is often a bridge too far; the learning curve is simply too high for end users who just want to configure and "click together" a simple bot.

To overcome this, the Dialox platform offers a node-based conversation flow system, something that is quite common in other bot platforms as well. However, unlike other platforms, Bubblescript is still the backend of this flow system, giving it advantages in terms of extensibility and non-linearity.

Some design goals have been stated:

Each flow is managed in its own file
Flows have top-level properties (on which channel it executes, etc)
Each flow is flowchart that consists of typed nodes and links between nodes
Nodes and links have common properties, but also type-specific ones
Nodes can have variants that are more specific, e.g. 'show image', 'show audio', 'ask phone'
Nodes and links are aware of their capabilities and are only applicable on channels that support these capabilities
The types and variants of node is extensible so skills can add new node types and variants, in order to provide more specific functionality.
All configuration UI ("property panels") for flow/node/link properties is supported by React JSONSchema Form

The text/yaml+flow YAML schema defines a schema for a node-based dialog builder.

Nodes and links¶

A flow consists of nodes and links.

Nodes have a type and a variant, both of which can be extended by skills. Each type needs to have at least a single variant. Usually, the 'main' variant is called default.

Links have types and variants as well. The types of links are fixed, however. They are currently limited to the following:

next - 'go to' from one node to the next
labelled - for presenting choices and dialog branching with quick replies / intent matching
trigger - for implementing handling events, intent matches and unknown messages
condition - for specifying conditions on branching nodes

Flow extensibility¶

The flow_schema YAML file can be used to add additional node types and variants to the flow editor.

# adding new node types
types: []

# adding new node variants
variants: []

# removing platform-defined defaults
omit_types: []
omit_variants: []

For each bot, the flow system looks in all folders for script files called flow_schema, and merges these files together into a single definition file.

This way, you can add new variants and types, overwrite predefined variants or types, or disable certain variant/type combinations (by using the omit_ fields).

flow_schema files are merged in script order, so the 'highest' flow definition wins.

The platform defines a set of defaults, see flow platform defaults.

CMS definitions¶

To expose the flow building UI in a bot, a CMS definition file needs to be created, identical to creating CMS definitions.

A content definition for a single flow:

type: flow
title: "Single flow"

storage:
  type: script
  script_title: single_flow

generators:
  - type: flow
    script_title: generated/single_flow

A content definition for a collection of flows:

title: "My flows"
type: flow
storage:
  type: script
  collection: flows/
  collection_editable: true
generators:
  - type: flow
    script_title: generated/{{ data_script_title }}

Generated Bubblescript code ends up in the generated/ folder in these examples.

Flow Variables¶

In the flows editor, there are several places where the UI allows users to do things with variables and expressions. These places tend to be error prone, hard to explain, and lack discoverability. These are the following places:

The node text itself, where a variable can be placed inside #{...} block:

The place where a variable needs to be picked as an answer to a question:

To overcome this at design time, flow bots have a knowledge of which "variables" can be used on these places, allowing the variables to be created on the fly and be picked / autocompleted from a list.

As you can expect, these variables can differ between each bot, depending on what kind of product / service the bot represents. Bots for making appointments could use different variables than IVR bots, for instance. This is why there are several levels of customizability in these variables. From the most system-generic to the most bot-specific, these are the following layers that can define variables:

Base variables - these come from the platform and represent the common exposed bubblescript variables, for instance, exposing bot.title, user.first_name, etc.
Skill-defined variables - each skill can add variable definitions; for instance a taxi booking bot could expose a taxi object containing information like taxi.order_price, taxi.order_date, etc.
Studio variables - these are the contact fields and conversation fields that can be customized by users of the platform per bot, e.g. for exposing information in the CRM.
Custom variables - this is a list of extra variables that a flow developer can make on the fly, for instance for temporarily storing some information in a variable for use later in the flow.

Defining variables¶

The base variables and skill variables are defined in the variables section of each flow_schema file. The format of the variables property is a subset of JSON schema:

variables:
  taxi:
    type: object
    properties:
      order_price:
        type: string
        title: Order price
        description: "The price of the last order in euros"
      order_date:
        type: datetime
        title: Order price
        description: "The date/time of the last order"

At compile time, all of the flow schema files are merged, resulting in one big variables schema, which can then be used inside the flows editor.

Omitting variables¶

When skills decide that certain variables should not be usable in the current bot they do this using the omit_variables property:

# in this bot we cannot use user.first_name
omit_variables:
  - [user, first_name]

Custom variables¶

Custom variables are variables that are created while the flow developer is editing a flow. They can be created from the variables side panel in the editor, or on the fly while using the flow variable picker.

Custom variables are stored in the top-level flow_schema file as follows:

custom_variables:
  - name: my_answer
    type: string
    title: Answer
    description: The answer that we must give

custom_variables_editable: true

At least one flow_schema yaml file needs to have custom_variables_editable: true, otherwise the bot does not allow creating / editing custom flow variables.

Flow JSON schema validation¶

format: "interpolated" -- The JSON schema string format called "interpolated" is used to validate flow variable string expressions, to provide validation that the referenced variables are actually available in the current bot.
format: "variable" -- The JSON schema string format called "variable" indicates that the string value must be an existing flow variable.
format: "variable_name" -- The JSON schema string format called "variable_name" indicates that the format of the string value must be a valid flow variable name, although the variable itself does not need to exist.

Flow UI widgets¶

In the CMS UI schema there are two new UI widgets to facilitate flow variable support:

`ui:widget: interpolated`¶

Stores a string with interpolated variables. The variables are stored in mustache format. So in the screenshot below the stored string is Hello {{ user.first_name }} {{ user.last_name }}, how are you?

Typing a slash (/) to show the variable autocompleter and to insert an existing variable.

`ui:widget: variable_picker`¶

Allows one to pick an existing variable or create a new variable (if that is allowed via the flow_schema). The variable will be of the type string.