EntityResolutionContext

Lib~ EntityResolutionContext

The Bots EntityResolutionContext is a class for querying, validating and changing a composite bag entity and its entity resolution status.

An EntityResolutionContext class instance is passed as an argument to every event handler function.

Constructor

new EntityResolutionContext(request)

Description:
  • Constructor of entity resolution context. DO NOT USE - INSTANCE IS ALREADY PASSED TO EVENT HANDLERS
Source:
Parameters:
Name Type Description
request object

Extends

Methods

addCandidateMessages()

Description:
  • Add the bot messages created by ResolveEntities or CommomResponse component to the response that will be sent to the user. Note that these messages are in the format of the conversation message model (CMM).
Source:

addMessage(payload, keepProcessingopt)

Description:
  • Adds a message to the bot response sent to the user.
Source:
Parameters:
Name Type Attributes Description
payload object can take a string message, a message created using MessageFactory, or a message created using the deprecated MessageModel.
keepProcessing boolean <optional>
 If set to false (the default), the message will be sent to the user and the ResolveEntities or CommonResponse component will stop any further processing, and wait for user input. If set to true, the component will continue processing, possibly sending more messages to the user before releasing the turn

addValidationError(itemName, error)

Description:
  • Add a validation error for a composite bag item. This marks the item invalid and the the item will not be set/updated with the new invalid value. The error mesage will be published as bot message to the user.
Source:
Parameters:
Name Type Description
itemName string name of composite bag iten that validation error applies to
error string the error message

cancel()

Description:
  • Cancels the entity resolution process and sets the 'cancel' transition on the ResolveEntities or Common Response component.
Source:

clearDisambiguationItems(itemName)

Description:
  • Removes the disambiguation items that are matched for a single entity value using the last user input.
Source:
Parameters:
Name Type Description
itemName string full name of the first composite bag item that matches the entity value, if not specified, all disambiguation items will be cleared

clearDisambiguationValues(itemName)

Description:
  • Removes the disambiguation values that are found based on the last user input for a specific bag item
Source:
Parameters:
Name Type Description
itemName string name of the composite bag item, if not specified, all disambiguation values of all items will be cleared

clearItemMatch(name) → {EntityResolutionStatus}

Description:
  • Clear the entity match for a specific bag item. Note that this method only takes effect when invoked from the userInputReceived event handler.
Source:
Parameters:
Name Type Description
name string the full item name for which the match needs to be removed.
Returns:
the status object
Type
EntityResolutionStatus

clearItemValue(fullName)

Description:
  • Remove the value of a composite bag item from the composite bag entity JSON object
Source:
Parameters:
Name Type Description
fullName string full name of the composite bag item

constructMessagePayload(payload) → {object}

Description:
  • Creates a message payload object
Source:
Overrides:
Parameters:
Name Type Description
payload object can take a string message, a message created by the MessageFactory, or a message created by the deprecated MessageModel.
Returns:
message payload in JSON format
Type
object

getCandidateMessageList() → {Array.<NonRawMessage>}

Description:
  • Returns a list of the candidate bot messages created by the the ResolveEntities or CommonResponse component that will be sent to the user when you use addCandidateMessages() function.
Source:
Returns:
list of candidate messages. The messages are returned in the class representation of each message type. You can modify it using the available class methods, and you can add the message by calling context.addMessage().

See Conversation Messaging

Type
Array.<NonRawMessage>

getCandidateMessages() → {Array.<NonRawMessagePayload>}

Description:
  • Returns a list of the candidate bot messages created by the the ResolveEntities or CommonResponse component that will be sent to the user when you use addCandidateMessages() function.
Source:
Deprecated:
  • Use getCandidateMessageList instead
Returns:
list of candidate messages. The messages are returned in the JSON format of the conversation message model (CMM).
Type
Array.<NonRawMessagePayload>

getChannelType() → {string}

Description:
  • Return the channel conversation type
Source:
Overrides:
Returns:
the channel type
Type
string

getCurrentItem() → {string}

Description:
  • Returns the name of the bag item that is currently being resolved
Source:
Returns:
the bag item name
Type
string

getCustomProperty(name) → {object}

Description:
  • Returns the value of a custom property that is stored in the entity resolution context. A custom property can be used to maintain custom state accross event handler calls while resolving the composite bag entity.
Source:
Parameters:
Name Type Description
name string name of the custom property
Returns:
value of the custom property
Type
object

getDisambiguationValues(itemName) → {Array.<object>}

Description:
  • Returns the disambiguation values that are found based on the last user input for a specific bag item
Source:
Parameters:
Name Type Description
itemName string name of the composite bag item
Returns:
the disambiguations values. This is a string array for bag items that have a custom entity type, and a JSONObject array for bag items with a system entity type
Type
Array.<object>

getDisplayValue(itemName) → {string}

Description:
  • Returns the display value for a composite bag item. For bag items with a custom entity type, the display value returned is the value property of the JSON Object value when isFullEntityMatches returns true. When isFullEntityMatches returns false, the actual value is returned. For STRING bag item types, the display value is the same as the actual value. For system entities, and for bag item types LOCATION and ATTACHMENT the configured display properties and display function determine the display value
Source:
See:
  • isFullEntityMatches
  • setSystemEntityDisplayProperties
  • setSystemEntityDisplayFunction
Parameters:
Name Type Description
itemName string full name of the composite bag item
Returns:
display value of composite bag item
Type
string

getDisplayValues(itemNames) → {Array.<object>}

Description:
  • Returns the display values for a composite bag entity.
Source:
See:
  • getDisplayValue
  • setSystemEntityDisplayProperties
  • setSystemEntityDisplayFunction
Parameters:
Name Type Description
itemNames string you can specify one or more item names as argument. If you do this, only the display values of these items will be returned. If you do not specify an item name, the display values of all items in the bag will be returned.
Returns:
list of display values of all bag items in the composite bag entity. Each display value is an object with two properties, the name and the value.
Type
Array.<object>

getEntity() → {object}

Description:
  • Returns the value of the composite bag entity currently being resolved
Source:
Returns:
The JSON object holding the composite bag item values
Type
object

getEntityItem(fullName) → {object}

Description:
  • Returns composite bag item definition for the (nested) bag item name
Source:
Parameters:
Name Type Description
fullName string the full name of the (nested) composite bag item for which the value is returned
Returns:
composite bag item definition
Type
object

getEntityItems() → {Array.<object>}

Description:
  • Returns list of top-level composite bag item definitions. Nested bag items can be retrieved by using the "children" property of a parent bag item.
Source:
Returns:
list of composite bag item definitions
Type
Array.<object>

getEntityName() → {string}

Description:
  • Returns the name of the composite bag entity type currently being resolved
Source:
Returns:
name of the composite bag entity type
Type
string

getEntityResolutionStatus() → {object}

Description:
  • Returns information about the entity resolution status
Source:
Returns:
the status object
Type
object

getEnumValues() → {Array.<object>}

Description:
  • Returns list of enumeration values for the bag item that is currently being resolved. This list is paginated, it only includes the values in current range
Source:
Returns:
list of enumeration values
Type
Array.<object>

getItemDefsMatched() → {Array.<string>}

Description:
  • Returns the composite bag item definitions that have gotten a new value extracted from the last user input
Source:
Returns:
list of composite bag item definitions
Type
Array.<string>

getItemDefsMatchedOutOfOrder() → {Array.<string>}

Description:
  • Returns the composite bag item definitions that have gotten a new value extracted from the last user input while the user was prompted for another bag item.
Source:
Returns:
list of composite bag item definitions
Type
Array.<string>

getItemDefsUpdated() → {Array.<string>}

Description:
  • Returns the composite bag item definitions that already had a value and have gotten a new value extracted from the last user input.
Source:
Returns:
list of composite bag item definitions
Type
Array.<string>

getItemValue(fullName) → {object}

Description:
  • Return value of a composite bag item in the composite bag entity currentyly being resolved
Source:
Parameters:
Name Type Description
fullName string the full name of the (nested) composite bag item for which the value is returned
Returns:
value of the composite bag item
Type
object

getItemsMatched() → {Array.<string>}

Description:
  • Returns the composite bag item (full) names) that have gotten a new value extracted from the last user input
Source:
Deprecated:
  • use getItemDefsMatched instead which returns the complete item definition instead of just the full name
Returns:
list of composite bag item full names
Type
Array.<string>

getItemsMatchedOutOfOrder() → {Array.<string>}

Description:
  • Returns the composite bag item (fulll) names that have gotten a new value extracted from the last user input while the user was prompted for another bag item.
Source:
Deprecated:
  • use getItemDefsMatchedOutOfOrder instead which returns the complete item definition instead of just the full name
Returns:
list of composite bag item full names
Type
Array.<string>

getItemsUpdated() → {Array.<string>}

Description:
  • Returns the composite bag item (full) names that already had a value and have gotten a new value extracted from the last user input.
Source:
Deprecated:
  • use getItemDefsUpdated instead which returns the complete item definition instead of just the full name
Returns:
list of composite bag item full names
Type
Array.<string>

getLogger() → {object}

Description:
  • Retrieves the logger object.
Source:
Overrides:
Deprecated:
  • use logger() function instead
Returns:
The logger object.
Type
object

getMessageFactory() → {MessageFactory}

Description:
  • Returns the MessageFactory class for creating bots messages
Source:
Overrides:
Returns:
The MessageFactory class
Type
MessageFactory

getMessageList() → {Array.<NonRawMessage>}

Description:
  • Returns the list of messages that will be sent to the user
Source:
Returns:
list of messages, returned in the class representation of each message type.
Type
Array.<NonRawMessage>

getMessageModel() → {MessageModel}

Description:
  • Returns the MessageModel class for creating or validating messages to or from bots.
Source:
Overrides:
Deprecated:
  • Use getMessageFactory() instead
See:
  • MessageModel.js
Returns:
The MessageModel class
Type
MessageModel

getMessages()

Description:
  • Returns the list of messages that will be sent to the user
Source:
Returns:
list of messages

getRequest() → {object}

Description:
  • Retrieves the request object.
Source:
Overrides:
Returns:
The request object.
Type
object

getResponse() → {object}

Description:
  • Retrieves the response object.
Source:
Overrides:
Returns:
The response object.
Type
object

getUserInput() → {string}

Description:
  • Returns the last user input message. If the last message was not a text message, this function returns undefined
Source:
Returns:
the user text message
Type
string

getUserMessage() → {NonRawMessage}

Description:
  • Returns the last user message.
Source:
Overrides:
Returns:
the last user message. You can cast this message to the appropriate message type.
Type
NonRawMessage

getValidationErrors() → {object}

Description:
  • Returns validation errors
Source:
Returns:
validation errors keyed by item name
Type
object

getVariable(name) → {object}

Description:
  • Returns the value of a context or user variable
Source:
Overrides:
Parameters:
Name Type Description
name string name of the variable
Returns:
variable value
Type
object

getVariableDefinition(name)

Description:
  • Get the definition of a variable
Source:
Overrides:
Parameters:
Name Type Description
name string The name of the variable

isFullEntityMatches() → {boolean}

Description:
  • Returns boolean flag indicating whether the component used to resolve the composite bag entity (System.ResolveEntities or System.CommonResponse) has set the useFullEntityMatches property to true. When set to true, custom entity values are stored as JSON object, similar to the builtin entities that are always stored as JSON object.
Source:
Returns:
fullEntityMatches flag
Type
boolean

isSkippedItem(name) → {boolean}

Description:
  • Returns true when item is marked as skipped, returns false otherwise
Source:
Parameters:
Name Type Description
name string full name of the composite bag item
Returns:
skip item flag
Type
boolean

logger() → {object}

Description:
  • Retrieves the logger object.
Source:
Overrides:
Returns:
The logger object.
Type
object

nlpResult(nlpVariableNameopt) → {NLPResult}

Description:
  • Returns an NLPResult helper object for working with nlpresult variables. See the NLPResult documentation for more information.

    If your skill uses visual flows, you don't need to specify a variable name. If your skill uses a YAML flow, you may specify a particular nlpresult by name (if you have multiple nlpresult variables defined in the flow), or omit the name if you only have 1 nlpresult.

Source:
Overrides:
Parameters:
Name Type Attributes Description
nlpVariableName string <optional>
 variable that holds the nlpResult
Returns:
The nlp resolution result.
Type
NLPResult

setCustomProperty(name, value)

Description:
  • Sets the value of a custom property that is stored in the entity resolution context. A custom property can be used to maintain custom state accross event handler calls while resolving the composite bag entity. If you set the value to null, the custom property will be removed.
Source:
Parameters:
Name Type Description
name string name of the custom property
value object value of the custom property

setDisambiguationValues(itemName, disambiguationValues)

Description:
  • Sets the disambiguation values for a specific bag item
Source:
Parameters:
Name Type Description
itemName string name of the composite bag item
disambiguationValues Array.<object> this is a string array for bag items that have a custom entity type, and a JSONObject array for bag items with a system entity type

setEntity(newEntity)

Description:
  • Sets the value of the composite bag entity currently being resolved
Source:
Parameters:
Name Type Description
newEntity object The JSON object holding the composite bag item values

setItemMatches(matches) → {EntityResolutionStatus}

Description:
  • Set the bag item matches. Note that this method only takes effect when invoked from the userInputReceived event handler.
Source:
Parameters:
Name Type Description
matches map map where the key is the full item name and the value the item match object.
Returns:
the status object
Type
EntityResolutionStatus

setItemValue(fullName, value)

Description:
  • Set value of a (nested) composite bag item in the composite bag entity currentyly being resolved
Source:
Parameters:
Name Type Description
fullName string the full name of the composite bag item for which the value is set
value object value of the composite bag item

setSystemEntityDisplayFunction(entityName, displayFunction)

Description:
  • A bag item of type system entity, LOCATION and ATTACHMENT has a JSON Object as value. With this function you can override the default display function that is applied to the display property values. The function is called with each display property as an argument For example, this is the default display function for DURATION: ((startDate,endDate) => new Date(startDate)+" - "+new Date(endDate)) If you want to format the dates differently, you can use a library like moments.js and call this function to override the display function Object that should be used to print out a string representation of the value.
Source:
Parameters:
Name Type Description
entityName string name of the system entity, or 'ATTACHMENT' or 'LOCATION' For an entity with a subtype, you need to include the subtype separated by a dot, for example DATE_TIME.INTERVAL.
displayFunction object the display function applied to the display properties

setSystemEntityDisplayProperties(entityName, properties)

Description:
  • A bag item of type system entity, LOCATION and ATTACHMENT has a JSON Object as value. With this function you can override the default display properties of the JSON Object that should be used to print out a string representation of the value.
Source:
Parameters:
Name Type Description
entityName string name of the system entity, or 'ATTACHMENT' or 'LOCATION'. For an entity with a subtype, you need to include the subtype separated by a dot, for example DATE_TIME.INTERVAL.
properties Array.<string> array of property names

setTransitionAction(action)

Description:
  • Set a transition action. When you use this function, the entity resolution process is aborted, and the dialog engine will transition to the state defined for this transition action.

    NOTE: This method cannot be used in the init event handler

Source:
Parameters:
Name Type Description
action string name of the transition action

setVariable(name, value)

Description:
  • Sets the value of a context or user variable
Source:
Overrides:
Parameters:
Name Type Description
name string name of the variable
value object value of the variable

skipItem(name)

Description:
  • Mark a composite bag item as skipped, which means the ResolveEntities or CommonResponse component will no longer prompt for a value for the bag item
Source:
Parameters:
Name Type Description
name string full name of the composite bag item

translate(rbKey, …rbArgs) → {string}

Description:
  • Get translated string using a resource bundle key defined in the skill.
Source:
Overrides:
Parameters:
Name Type Attributes Description
rbKey string key of the resource bundle entry defined with the skill that should be used to translate
rbArgs string <repeatable>
 substitution variables
Returns:
resource bundle freemarker expression that will be resolved when event handler or custom component response is received by dialog engine
Type
string

unskipItem(name)

Description:
  • Unmark a composite bag item as skipped, which means the ResolveEntities or CommonResponse component will prompt again for a value for the bag item
Source:
Parameters:
Name Type Description
name string full name of the composite bag item

variable(name, valueopt)

Description:
  • Read or write variables defined in the current flow. It is not possible to change the type of an existing variable through this method. It is the caller's responsibility to ensure that the value being set on a variable is of the correct type. (e.g. entity, string or other primitive, etc).

    A new variable can be created. However, since the variable is not defined in the flow, using it in the flow subsequently may be flagged for validation warnings.

    This function takes a variable number of arguments.

    The first form: variable(name); reads the variable called "name", returning its value. The name could be in the form of <scope>.<variableName>. For example, a variable firstName in the profile scope needs to be retrieved as variable("profile.firstName").

    The second form: variable(name, value); writes the value "value" to the variable called "name".
Source:
Overrides:
Example
let firstName = conversation.variable("profile.firstName");
let lastName = conversation.variable("profile.lastName");
conversation.variable("fullName", firstName + ' ' + lastName);
Parameters:
Name Type Attributes Description
name string The name of variable to be set or read
value string <optional>
 value to be set for variable