Library class

Package:

botbuilder

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.
RouteTypes	Supported routeType values returned by default from findRoutes().

Methods

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.
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.
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 dialogStack is past in the actions from the library deepest on the stack will be favored. Otherwise the first one will be returned.
clone(Library, string)	Returns a clone of an existing Library.
customAction(IDialogActionOptions)	Registers a custom global action that will call the passed in onSelectAction handler when triggered.
dialog(string, Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep, boolean)	Registers or returns a dialog from the library.
endConversationAction(string, TextOrMessageType, ICancelActionOptions)	Registers a global action that will end the conversation with the user when triggered.
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.
findDialog(string, string)	Searches the library and all of its dependencies for a specific dialog. Returns the dialog if found, otherwise null.
findGlobalActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)	Searches the library to see if any global actions have been triggered.
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.
findStackActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])	Searches the sessions dialog stack to see if any actions have been triggered.
forEachDialog((dialog: Dialog, id: string) => void)	Enumerates all of the libraries dialogs.
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.
library(Library | string)	Registers or returns a library dependency.
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.
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.
onFindRoutes(IFindRoutesHandler)	Replaces findRoutes() default route searching logic with a custom implementation.
onSelectRoute(ISelectRouteHandler)	Replaces the default logic for selectRoute() with a custom implementation.
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.
recognizer(IIntentRecognizer)	Adds a new recognizer plugin to the library.
selectActiveDialogRoute(Session, IRouteResult, IDialogState[])	Routes the current message to the active dialog.
selectGlobalActionRoute(Session, IRouteResult, IDialogState[])	Routes the current message to a triggered global action.
selectRoute(Session, IRouteResult)	Triggers the handling of the current message using the selected route. The default logic can be overriden using onSelectRoute().
selectStackActionRoute(Session, IRouteResult, IDialogState[])	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: string

Property Value

string

RouteTypes

Supported routeType values returned by default from findRoutes().

static RouteTypes: Object

Property 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

IRouteResult[]

(Optional) result set to add the route too. If missing then a new set with just the route will be returned.

Returns

IRouteResult[]

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

Dialog

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:

1. : 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.
2. ActiveDialog: The active dialog is the next highest priority.
3. StackAction: Stack actions are the next highest priority and the action with the deepest stack position will be returned.
4. GlobalAction: Global actions are the lowest priority. If a dialogStack is 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

IRouteResult[]

Array of candidate routes to filter.

dialogStack

IDialogState[]

(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

IRouteResult

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

Library

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

Library

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

Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep

(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

Dialog

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.

msg

TextOrMessageType

(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

Dialog

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

IDialogState[]

(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

Dialog

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

IDialogState[]

(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

Library

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

IntentDialog

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

IDialogState[]

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

IDialogState[]

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

IDialogState[]