Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ControlManager

Defines the high-level functionality for a skill built with Controls.

Each skill that uses controls should define a concrete sub-class that implements createControlTree and optionally overrides other methods.

Summary:

  • createControlTree() creates a hierarchy of controls that cooperatively manage the skill behavior.

    • The methods on the root control will be called to process the user's input and to generate system initiative.
  • render() is the entry-point for the render-phase.

    • High-level overrides and multi-act rendering should be performed by controlManager.render(). The default is to render each act one-by-one by calling control.renderAct(act). This builds up a result by concatenation of response fragments which is sufficient in many cases.
  • The ControlResult contains a list of SystemActs that describe what should be communicated to the user but generally should not describe how to present it.

  • handleInternalError provides an entry-point for custom handling of internal errors.

  • buildInteractionModel provides an entry-point for building the Control-specific aspects of skill's Interaction Model.

Internationalization and Localization

  • Controls themselves are location-agnostic. They consume abstract inputs (Intents, etc) and produce abstract outputs (SystemActs)

  • Mapping localized input to abstract inputs is the role of NLU and the necessary information is stored in the Interaction Model.

    • The ControlManager props includes a bag of localization data that is used during interaction-model building for a given locale.
    • The framework ships with a default set of interaction model data for en-US.
  • Mapping abstract output to physical output (prompts, APL strings) etc is the role of the rendering phase. This information is part of the skill definition but can be located in various places: either in a monolithic render() function, or scattered around the various Controls and Acts.

Hierarchy

Implements

Constructors

constructor

  • Creates an instance of a Control Manager.

    Parameters

    Returns ControlManager

Properties

props

props: Readonly<Required<ControlManagerProps>>

The complete props used during construction.

Optional rawProps

The custom props provided during construction

Static DEFAULT_CONTROL_STATE_ATTRIBUTE_KEY

DEFAULT_CONTROL_STATE_ATTRIBUTE_KEY: string = "__controlState"

Default key name used to store control state data between turns.

Methods

buildInteractionModel

  • Builds interaction model content required by the Control tree.

    Usage:

    • The imDataMap has 'en-US' modelData registered by default

    • The developer may configure and register additional imDataMap instances to support additional locales

    • If imDataMap doesn't have data for the requested locale a LocaleNotSupportedError will be thrown

    Parameters

    Returns void

Abstract createControlTree

  • Creates a tree of controls to handle state management and dialog decisions for the skill.

    Usage:

    • Each control in the tree can and should be created with empty state.

    • In advanced scenarios the tree shape may change as the skill session progresses. Dynamic controls should be rebuilt during ControlManager.reestablishControlStates().

    Returns Control

    A Control, typically a ContainerControl, that is the root of a tree.

handleInternalError

  • Handles an internal error.

    This is intended for logging, reporting and perhaps mentioning the situation to the user. The user session will be automatically closed.

    Default: The error object is converted into an object with enumerable properties and logged at logLevel=error

    Parameters

    Returns void

loadControlStateMap

  • loadControlStateMap(handlerInput: HandlerInput): Promise<object>
  • Load the control state map from durable storage.

    Default: loads from Session Attributes.

    Parameters

    • handlerInput: HandlerInput

    Returns Promise<object>

reestablishControlStates

  • reestablishControlStates(rootControl: IControl, stateMap: object): void
  • Reestablish the state of all controls.

    Purpose:

    • On the second and subsequent turns this method reestablishes the state of controls from saved/serialized information.
    • This method should also reestablish any dynamic controls (controls that are added at runtime, rather than being statically created by createControlTree)

    Notes:

    • To keep serialized state to a minimum, and due to the lack of object-aware serialization in Javascript, re-creation of the complete control tree occurs in two phases:
      1. Build the static control tree as in the very first turn.
      2. Reattach state and rebuild the dynamic portions of the control tree.
    • This approach keeps the props and state of controls separate and keeps the common cases as simple as possible.

    Parameters

    • rootControl: IControl
    • stateMap: object
      • [key: string]: any

    Returns void

render

  • Transforms the information in ControlResult into user-facing content (prompts and APL).

    Default: The default rendering strategy renders each SystemAct in turn by calling act.control.render(act). This strategy leads to prompts that are a concatenation of the prompt-fragment for each SystemAct.

    Usage:

    • In many situations rendering the acts one-by-one is sufficient as the concatenation of prompt fragments leads to usable prompts. For example
       [ValueSetAct(ageCtrl, 5), RequestValueAct(nameCtrl)]

    may be rendered sequentially to produce:

       -> 'OK, 5. What is your name?"
    • For more complex situations, override this method and implement a custom rendering strategy. Often the solution will be to implement some special cases and otherwise fallback to the default by calling super.render() or by directly calling ControlManager.renderActsOneByOne().

    Parameters

    Returns void | Promise<void>

saveControlStateMap

  • saveControlStateMap(state: any, handlerInput: HandlerInput): Promise<void>
  • Saves the control state map for use in subsequent turns of this session.

    Default: saves to the Session Attributes.

    Parameters

    • state: any
    • handlerInput: HandlerInput

    Returns Promise<void>

Static loadControlStateMapFromSessionAttributes

  • loadControlStateMapFromSessionAttributes(handlerInput: HandlerInput, attributeKey: string): object
  • Parameters

    • handlerInput: HandlerInput
    • attributeKey: string

    Returns object

    • [key: string]: any

Static mergeWithDefaultProps

  • Merges the user-provided props with the default props.

    Any property defined by the user-provided data overrides the defaults.

    Parameters

    Returns Required<ControlManagerProps>

Static saveControlStateToSessionAttributes

  • saveControlStateToSessionAttributes(state: any, handlerInput: HandlerInput, attributeKey: string): void
  • Parameters

    • state: any
    • handlerInput: HandlerInput
    • attributeKey: string

    Returns void