Library class
A library of related dialogs used for routing purposes. Libraries can be chained together to enable the development of complex bots. The UniversalBot class is itself a Library that forms the root of this chain. Libraries of reusable parts can be developed by creating a new Library instance and adding dialogs just as you would to a bot. Your library should have a unique name that corresponds to either your libraries website or NPM module name. Bots can then reuse your library by simply adding your parts Library instance to their bot using UniversalBot.library(). If your library itself depends on other libraries you should add them to your library as a dependency using Library.library(). You can easily manage multiple versions of your library by adding a version number to your library name.
To invoke dialogs within your library bots will need to call session.beginDialog()
with a fully qualified dialog id in the form of ':'. You'll typically hide
this from the developer by exposing a function from their module that starts the dialog for them.
So calling something like myLib.someDialog(session, { arg: '' }); would end up calling
session.beginDialog('myLib:someDialog', args); under the covers.
It's worth noting that dialogs are always invoked within the current dialog so once your within a dialog from your library you don't need to prefix every beginDialog() call your with your libraries name. It's only when crossing from one library context to another that you need to include the library name prefix.
Constructors
| Library(string) | Creates a new instance of the library. |
Properties
| name | The libraries unique namespace. This is used to issolate the libraries dialogs and localized prompts. |
| Route |
Supported routeType values returned by default from findRoutes(). |
Methods
| add |
Helper method called from the various route finding methods to manage adding a candidate route to the result set.
|
| begin |
Registers a global action that will start another dialog anytime it's triggered. The new dialog will be pushed onto the stack so it does not automatically end any current task. The current task will be continued once the new dialog ends. The built-in prompts will automatically re-prompt the user once this happens but that behaviour can be disabled by setting the promptAfterAction flag when calling a built-in prompt. |
| best |
Finds the best route to use within a result set containing multiple ambiguous routes. The following disambigution strategy will be used:
|
| clone(Library, string) | Returns a clone of an existing Library. |
| custom |
Registers a custom global action that will call the passed in onSelectAction handler when triggered. |
| dialog(string, Dialog | IDialog |
Registers or returns a dialog from the library. |
| end |
Registers a global action that will end the conversation with the user when triggered. |
| find |
Gets the active dialogs confidence that it understands the current message. The dialog must be a member of the current library, otherwise a score of 0.0 will be returned. |
| find |
Searches the library and all of its dependencies for a specific dialog. Returns the dialog if found, otherwise null. |
| find |
Searches the library to see if any global actions have been triggered. |
| find |
Searches for candidate routes to handle the current message. To actually initiate the
handling of the message you should call selectRoute() with one of the
returned results.
The default search logic can be overriden using onFindRoute() and only the
current library is searched so you should call |
| find |
Searches the sessions dialog stack to see if any actions have been triggered. |
| for |
Enumerates all of the libraries dialogs. |
| for |
Enumerates all of the libraries child libraries. The caller should take appropriate steps to avoid circular references when enumerating the hierarchy. In most cases calling libraryList() is a better choice as it already contains logic to avoid cycles. |
| library(Library | string) | Registers or returns a library dependency. |
| library |
Returns a list of unique libraries within the hierarchy. Should be called on the root of the library hierarchy and avoids cycles created when two child libraries reference the same dependent library. |
| locale |
Gets or sets the path to the libraries "/locale/" folder containing its localized prompts. The prompts for the library should be stored in a "/locale/<IETF_TAG>/.json" file under this path where "<IETF_TAG>" representes the 2-3 digit language tage for the locale and "" is a filename matching the libraries namespace. |
| on |
Replaces findRoutes() default route searching logic with a custom implementation. |
| on |
Replaces the default logic for selectRoute() with a custom implementation. |
| recognize(IRecognize |
Attempts to match a users text utterance to an intent using the libraries recognizers. See IIntentRecognizer.recognize() for details. |
| recognizer(IIntent |
Adds a new recognizer plugin to the library. |
| select |
Routes the current message to the active dialog. |
| select |
Routes the current message to a triggered global action. |
| select |
Triggers the handling of the current message using the selected route. The default logic can be overriden using onSelectRoute(). |
| select |
Routes the current message to a triggered stack action. |
Constructor Details
Library(string)
Creates a new instance of the library.
new Library(name: string)Parameters
- name
-
string
Unique namespace for the library.
Property Details
name
The libraries unique namespace. This is used to issolate the libraries dialogs and localized prompts.
name: stringProperty Value
string
RouteTypes
Supported routeType values returned by default from findRoutes().
static RouteTypes: ObjectProperty Value
Object
Method Details
addRouteResult(IRouteResult, IRouteResult[])
Helper method called from the various route finding methods to manage adding a candidate route to the result set.
- If the score is greater then the current best match in the set a new result set will be returned containing just the new match.
- If the score is equal to the current best match it will be added to the existing set.
- If the score is less than the current best match it will be ignored.
static function addRouteResult(route: IRouteResult, current?: IRouteResult[])Parameters
- route
- IRouteResult
The candidate route to add to the set.
- current
(Optional) result set to add the route too. If missing then a new set with just the route will be returned.
Returns
beginDialogAction(string, string, IDialogActionOptions)
Registers a global action that will start another dialog anytime it's triggered. The new dialog will be pushed onto the stack so it does not automatically end any current task. The current task will be continued once the new dialog ends. The built-in prompts will automatically re-prompt the user once this happens but that behaviour can be disabled by setting the promptAfterAction flag when calling a built-in prompt.
function beginDialogAction(name: string, id: string, options?: IDialogActionOptions)Parameters
- name
-
string
Unique name to assign the action.
- id
-
string
ID of the dialog to start.
- options
- IDialogActionOptions
(Optional) options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action, otherwise the action needs to be bound to a button using CardAction.dialogAction() to trigger the action. You can also use dialogArgs to pass additional params to the dialog being started.
Returns
bestRouteResult(IRouteResult[], IDialogState[], string)
Finds the best route to use within a result set containing multiple ambiguous routes. The following disambigution strategy will be used:
- : Custom route types are the highest priority and will alwsays be preferred. This lets the developer override routing within a bot in very powerful way.
- ActiveDialog: The active dialog is the next highest priority.
- StackAction: Stack actions are the next highest priority and the action with the deepest stack position will be returned.
- GlobalAction: Global actions are the lowest priority. If a
dialogStackis past in the actions from the library deepest on the stack will be favored. Otherwise the first one will be returned.
static function bestRouteResult(routes: IRouteResult[], dialogStack?: IDialogState[], rootLibraryName?: string)Parameters
- routes
Array of candidate routes to filter.
- dialogStack
(Optional) dialog stack used to determine which libraries global actions to favor.
- rootLibraryName
-
string
(Optional) library namespace to prefer when disambiguating global actions and there's no dialogs on the stack.
Returns
clone(Library, string)
Returns a clone of an existing Library.
function clone(copyTo?: Library, newName?: string)Parameters
- copyTo
- Library
(Optional) instance to copy the current object to. If missing a new instance will be created.
- newName
-
string
(Optional) if specified the returned copy will be renamed to a new name.
Returns
customAction(IDialogActionOptions)
Registers a custom global action that will call the passed in onSelectAction handler when triggered.
function customAction(options: IDialogActionOptions)Parameters
- options
- IDialogActionOptions
The options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action. Custom matching logic can be provided using onFindAction.
Returns
dialog(string, Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep, boolean)
Registers or returns a dialog from the library.
function dialog(id: string, dialog?: Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep, replace?: boolean)Parameters
- id
-
string
Unique ID of the dialog being regsitered or retrieved.
- dialog
(Optional) dialog or waterfall to register.
- dialog: {Dialog} - Dialog to add.
- dialog: {IDialogWaterfallStep[]} - Waterfall of steps to execute. See IDialogWaterfallStep for details.
- dialog: {IDialogWaterfallStep} - Single step waterfall. Calling a built-in prompt or starting a new dialog will result in the current dialog ending upon completion of the child prompt/dialog.
- replace
-
boolean
(Optional) if true, the dialog should replace the existing dialog if already registered.
Returns
endConversationAction(string, TextOrMessageType, ICancelActionOptions)
Registers a global action that will end the conversation with the user when triggered.
function endConversationAction(name: string, msg?: TextOrMessageType, options?: ICancelActionOptions)Parameters
- name
-
string
Unique name to assign the action.
(Optional) message to send the user prior to ending the conversation.
- options
- ICancelActionOptions
(Optional) options used to configure the action. If matches is specified the action will listen for the user to say a word or phrase that triggers the action, otherwise the action needs to be bound to a button using CardAction.dialogAction() to trigger the action.
Returns
findActiveDialogRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])
Gets the active dialogs confidence that it understands the current message. The dialog must be a member of the current library, otherwise a score of 0.0 will be returned.
function findActiveDialogRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void, dialogStack?: IDialogState[])Parameters
- context
- IRecognizeContext
Read-only recognizer context for the current conversation.
- callback
-
(err: Error, routes: IRouteResult[]) => void
Function that should be invoked with the found routes.
- dialogStack
(Optional) dialog stack to search over. The default behaviour is to search over the sessions current dialog stack.
findDialog(string, string)
Searches the library and all of its dependencies for a specific dialog. Returns the dialog if found, otherwise null.
function findDialog(libName: string, dialogId: string)Parameters
- libName
-
string
Name of the library containing the dialog.
- dialogId
-
string
Unique ID of the dialog within the library.
Returns
findGlobalActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)
Searches the library to see if any global actions have been triggered.
function findGlobalActionRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void)Parameters
- context
- IRecognizeContext
Read-only recognizer context for the current conversation.
- callback
-
(err: Error, routes: IRouteResult[]) => void
Function that should be invoked with the found routes.
findRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)
Searches for candidate routes to handle the current message. To actually initiate the
handling of the message you should call selectRoute() with one of the
returned results.
The default search logic can be overriden using onFindRoute() and only the
current library is searched so you should call findRoutes() seperately for each library
within the hierarchy.
function findRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void)Parameters
- context
- IRecognizeContext
Read-only recognizer context for the current conversation.
- callback
-
(err: Error, routes: IRouteResult[]) => void
Function that should be invoked with the found routes.
findStackActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])
Searches the sessions dialog stack to see if any actions have been triggered.
function findStackActionRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void, dialogStack?: IDialogState[])Parameters
- context
- IRecognizeContext
Read-only recognizer context for the current conversation.
- callback
-
(err: Error, routes: IRouteResult[]) => void
Function that should be invoked with the found routes.
- dialogStack
(Optional) dialog stack to search over. The default behaviour is to search over the sessions current dialog stack.
forEachDialog((dialog: Dialog, id: string) => void)
Enumerates all of the libraries dialogs.
function forEachDialog(callback: (dialog: Dialog, id: string) => void)Parameters
- callback
-
(dialog: Dialog, id: string) => void
Iterator function to call with each dialog.
forEachLibrary((library: Library) => void)
Enumerates all of the libraries child libraries. The caller should take appropriate steps to avoid circular references when enumerating the hierarchy. In most cases calling libraryList() is a better choice as it already contains logic to avoid cycles.
function forEachLibrary(callback: (library: Library) => void)Parameters
- callback
-
(library: Library) => void
Iterator function to call with each child libray.
library(Library | string)
Registers or returns a library dependency.
function library(lib: Library | string)Parameters
- lib
-
Library | string
- lib: {Library} - Library to register as a dependency.
- lib: {string} - Unique name of the library to lookup. All dependencies will be searched as well.
Returns
libraryList(boolean)
Returns a list of unique libraries within the hierarchy. Should be called on the root of the library hierarchy and avoids cycles created when two child libraries reference the same dependent library.
function libraryList(reverse?: boolean)Parameters
- reverse
-
boolean
(Optional) If true list will be generated from the leaves up meaning the root library will be listed last. The default value is false which means it will be generated from the roots down and the root library will be listed first.
Returns
Library[]
localePath(string)
Gets or sets the path to the libraries "/locale/" folder containing its localized prompts. The prompts for the library should be stored in a "/locale/<IETF_TAG>/.json" file under this path where "<IETF_TAG>" representes the 2-3 digit language tage for the locale and "" is a filename matching the libraries namespace.
function localePath(path?: string)Parameters
- path
-
string
(Optional) path to the libraries "/locale/" folder. If specified this will update the libraries path.
Returns
string
onFindRoutes(IFindRoutesHandler)
Replaces findRoutes() default route searching logic with a custom implementation.
function onFindRoutes(handler: IFindRoutesHandler)Parameters
- handler
- IFindRoutesHandler
Function that will be invoked anytime findRoutes() is called for the library.
onSelectRoute(ISelectRouteHandler)
Replaces the default logic for selectRoute() with a custom implementation.
function onSelectRoute(handler: ISelectRouteHandler)Parameters
- handler
- ISelectRouteHandler
Function that will be invoked anytime selectRoute() is called.
recognize(IRecognizeContext, (err: Error, result: IIntentRecognizerResult) => void)
Attempts to match a users text utterance to an intent using the libraries recognizers. See IIntentRecognizer.recognize() for details.
function recognize(context: IRecognizeContext, callback: (err: Error, result: IIntentRecognizerResult) => void)Parameters
- context
- IRecognizeContext
Read-only recognizer context for the current conversation.
- callback
-
(err: Error, result: IIntentRecognizerResult) => void
Function that should be invoked upon completion of the recognition.
recognizer(IIntentRecognizer)
Adds a new recognizer plugin to the library.
function recognizer(plugin: IIntentRecognizer)Parameters
- plugin
- IIntentRecognizer
The recognizer to add.
Returns
selectActiveDialogRoute(Session, IRouteResult, IDialogState[])
Routes the current message to the active dialog.
function selectActiveDialogRoute(session: Session, route: IRouteResult, newStack?: IDialogState[])Parameters
- session
- Session
Session object for the current conversation.
- route
- IRouteResult
Route result returned from a previous call to findRoutes() or findActiveDialogRoutes().
- newStack
selectGlobalActionRoute(Session, IRouteResult, IDialogState[])
Routes the current message to a triggered global action.
function selectGlobalActionRoute(session: Session, route: IRouteResult, newStack?: IDialogState[])Parameters
- session
- Session
Session object for the current conversation.
- route
- IRouteResult
Route result returned from a previous call to findRoutes() or findGlobalActionRoutes().
- newStack
selectRoute(Session, IRouteResult)
Triggers the handling of the current message using the selected route. The default logic can be overriden using onSelectRoute().
function selectRoute(session: Session, route: IRouteResult)Parameters
- session
- Session
Session object for the current conversation.
- route
- IRouteResult
Route result returned from a previous call to findRoutes().
selectStackActionRoute(Session, IRouteResult, IDialogState[])
Routes the current message to a triggered stack action.
function selectStackActionRoute(session: Session, route: IRouteResult, newStack?: IDialogState[])Parameters
- session
- Session
Session object for the current conversation.
- route
- IRouteResult
Route result returned from a previous call to findRoutes() or findStackActionRoutes().
- newStack