article by Frank Nimphius, May 2020
This article explains how composite bag entity items that are based on complex entities like DATE, NUMBER or CURRENCY can have their values set using a custom component. The use case for this is e.g. to set a DATE item to a current date or set an item to a derived value.
About entities
Oracle Digital Assistant skills use entities in natural language processing to extract information from user messages based on patterns or values represented by an entity. By doing so, entities represent a single piece of information like a product name, a color, a size or similar.
There are two general types of entities: system entities and custom entities. System entities are built-in entities that include DATE, TIME, DURATION, NUMBER, CURRENCY, EMAIL, PERSON, URL, LOCATION and more. When extracted from a message, system entities may return single values or complex objects. In the image below, DATE, NUMBER, PERSON and URL entities return objects whereas EMAIL returns a single value.
About composite bag entities
Composite bag entities are objects that use attributes known as "bag items" to reference entities or use string, Location or Attachment as a type. An order, for example, may reference the DATE entity for the order date, the ADDRESS entity for users to provide a shipping address and a custom "Products" value list entity. Using the System.CommonResponse component or System.ResolveEntities component you can resolve composite bag entities without the bot designer needing to write dialog flow states for each of the contained entities.
Setting bag item values
Composite bag entity item values are set from the initial user message through NLP (Natural Language Processing) and through the System.CommonResponse and System.ResolveEntities components prompting the user to provide data input.
You can use the System.MatchEntity component to validate a string against a variable of a composite bag entity type. The result of the latter is that all matching bag items will be updated and the component follows the match or nomatch action transition dependent on whether or not a bag item could be updated with the content of the string.
To set individual bag item values programmatically, you could use the System.SetVariable property to set composite bag entity item values directly if they are based on primitive or custom entities. For entities that use complex data objects (e.g. DATE) the System.SetVariable component may not work. Here however a custom component may come to the rescue.
Why setting composite bag items programmatically
Use case matters. Assume a subscription skill that users use to sign up for or extend a subscription. Assume that the subscription start date should be set to the current date, which means there is no need to ask the user to provide the date. Instead you would want to generate a system date and set it. This is where a custom component can help. The BotML and custom component code shown below allows developers to set a DATE entity value to a bag item. If no DATE value is defined then the current date is used.
Composite bag entity items
BotML
When testing the component, the DATE bag item is set as shown in the image below
Notice in the image above, how the custom component set all DATE entity attributes. Using one of the properties in the before image you can pass a specific date either in milliseconds or as a string. This allows you to control the setting of e.g. a start and end DATE bag item. If a developer passes time in milliseconds and the date as a string, then time in milliseconds takes precedence. Also notice how you can set the time offset so date gets set in local time.
Custom component code
The custom component package you can download contains the following custom components for you to try and customize
All custom components use the sample principle for setting the bag item values
- Access the composite bag entity variable referenced for each custom components
- Determine whether the composite entity contains values. If not it creates an empty object to start with
- Set a new attribute with the name of the composite bag item name that is passed to the component
- Add an object with the attribute for a specific entity type (e.g. DATE has date, originalString and entityType as an attribute). You can use the intent tester to determine attributes for the complex built-in types
The code below sets the DATE value to a bag item that is of type DATE
Summary and disclaimer
The content in this article may look like a solution looking for a problem. Indeed, the primary means for resolving composite bag entities are NLP and the the System.CommonResponse and System.ResolveEntities components. However, for use cases for which you need to set default values or set values manually you can use a custom component as provided with this article. The components you can download are a starting point and may not suite the particular use case you have. As it is with samples, feel free to change the code to fit your needs.
Download
The ZIP you can download contains custom components that allow you to set a specific entity type to a composite bag entity bag item. All components require the following properties to be set
variable – the name of the variable that references the composite bag entity
bagItem – the name of the bag item to update. The bag item must be of the entty type matching the name of the component e.g. DATE for "setDateBagItem" component
- Unzip
- edit components if required
- call npm install on the root folder
- cal bots-node-sdk pack to create a deployable TGZ file (bots-node-sdk requires installation of the Bots Node SDK (https://github.com/oracle/bots-node-sdk)
Related Content
TechExchange: How-to Use the System.ResolveEntities Component in Oracle Digital Assistant
TechExchange Quick-Tip: How to Intelligently Cancel Composite Bag Entity Driven User Dialog Flows
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
Custom component development tutorial
