New version 2.7.0 (#48)

- Added new event handler types LlmComponent and  LlmTransformation
- Added textStream message type 
- Added support for footerForm
- Added support for rich form layout

Author: stevendavelaar

CUSTOM_COMPONENT.md

@@ -7,17 +7,17 @@
     - [Using TypeScript](#ts)
     - [The Metadata Object](#metadata)
     - [The Invoke Method](#invoke)
-- [Control the Flow with keepTurn and transition](#flowControl)    
+- [Control the Flow with keepTurn and transition](#flow-control)    
 - [Access the Backend Using HTTP REST Calls](#rest)
 - [Code Samples](#samples)
-    - [How to Get a Component Property Value](#propertyValue)
-    - [How to Get a Context Variable Value](#getVar)
-    - [How to Get a User or Profile Variable Value](#getProfile)
-    - [How to Get a Skill's Custom Parameter Value](#getCustomParam)  
-    - [How to Set a Context Variable Value](#setVar)
-    - [How to Set a Composite Bag Item Value](#setBagItem)
+    - [How to Get a Component Property Value](#property-value)
+    - [How to Get a Context Variable Value](#get-var)
+    - [How to Get a User or Profile Variable Value](#get-profile)
+    - [How to Get a Skill's Custom Parameter Value](#get-custom-param)  
+    - [How to Set a Context Variable Value](#set-var)
+    - [How to Set a Composite Bag Item Value](#set-bag-item)
     - [How to Send Conversation Messages](#messages)
-    - [How to Keep Prompting for User Input](#keepPrompting)    
+    - [How to Keep Prompting for User Input](#keep-prompting)    
 
 ## Introduction <a name="introduction">
 
@@ -171,7 +171,7 @@ The argument of the `invoke` method is the `context` object. This object referen
 
 More information about creating conversation messages to send to the skill user can be found [here](https://github.com/oracle/bots-node-sdk/blob/master/MESSAGE_FACTORY.md).
 
-## Control the Flow with keepTurn and transition <a name="flowControl">
+## Control the Flow with keepTurn and transition <a name="flow-control">
 
 You use different combinations of the [CustomComponentContext](https://oracle.github.io/bots-node-sdk/CustomComponentContext.html) `keepTurn` and `transition` functions to define how the custom component interacts with a user and how the conversation continues after the component returns flow control to the skill.
 
@@ -238,7 +238,7 @@ The code to make REST calls with `node fetch` looks like this:
 
 ## Code Samples <a name="samples">
 
-### How to Get a Component Property Value <a name="propertyValue">
+### How to Get a Component Property Value <a name="property-value">
 
 You can call `context.properties()` to get an object that contains all the component properties. For example:
 
@@ -272,7 +272,7 @@ or
     const name = context.properties()['name'] || '';
 ```
 
-### How to Get a Context Variable Value <a name="getVar">
+### How to Get a Context Variable Value <a name="get-var">
 
 Add a `metadata` property to pass in the name of the context variable, verify that the property was passed in, and then call `context.getVariable(<variable name>)` to retrieve the value. For example:
 
@@ -286,18 +286,18 @@ if (latitudeVariable) {
 }
 ```
 
-### How to Get a User or Profile Variable Value <a name="getProfile">
+### How to Get a User or Profile Variable Value <a name="get-profile">
 
 To get the value of a user or profile variable, you prefix the name of the variable with `profile.` or `user.` as shown here.
 ```javascript
   let _profileVarValue = context.getVariable('profile.<name>');
   let _userVarValue = context.getVariable('user.<name>');  
 ```
-### How to Get a Skill's Custom Parameter Value <a name="getCustomParam">
+### How to Get a Skill's Custom Parameter Value <a name="get-custom-param">
 
 On the skill's **Settings** tab, add the custom parameter and provide a value (or set the value in the dialog flow). From the custom component, call `context.getVariable('system.config.<parameter-name>')` to retrieve the value.
 
-### How to Set a Context Variable Value <a name="setVar">
+### How to Set a Context Variable Value <a name="set-var">
 
 Add a `metadata` property to pass in the name of the variable, and then call `context.setVariable(<variable name>, <value>)` to set the value. For example:
 
@@ -324,7 +324,7 @@ if (addressVariable){
 }
 ```
 
-### How to Set a Composite Bag Item Value <a name="setBagItem">
+### How to Set a Composite Bag Item Value <a name="set-bag-item">
 
 In the skill, create a context variable and set its type to the name of the composite bag entity. In the custom component, add metadata properties to pass in the name of the composite bag entity variable and the name of the bag item. Add code to check if the entity variable is null, and set it to an empty object if it is. Create an object for the bag item with the desired values and set the bag item to that object. Update the entity variable and return to the skill.
 
@@ -364,7 +364,7 @@ You can call this function multiple times to send multiple messages. When you ca
 
 The payload can be a string or a rich message object. See the section on [Conversation Messaging](https://github.com/oracle/bots-node-sdk/blob/master/MESSAGE_FACTORY.md) for code samples on how to create the various message types, like text, card, attachment, table and (editable) form messages.
 
-### How to Keep Prompting for User Input <a name="keepPrompting">
+### How to Keep Prompting for User Input <a name="keep-prompting">
 
 This code sample keeps showing the user a random quote of the day until the user indicates they want to quit.
 

DATA_QUERY_EVENT_HANDLER.md

@@ -7,18 +7,18 @@
     - [Using TypeScript](#ts)
 - [Writing SQL Query Handler Functions](#writing)
 - [Supported Events](#events)
-    - [Entity Level Events](#entityEvents)
-    - [Attribute Level Events](#attributeEvents)
+    - [Entity Level Events](#entity-events)
+    - [Attribute Level Events](#attribute-events)
 - [Access the Backend Using HTTP REST Calls](#rest)
 - [Code Samples](#samples)
-    - [How to Set the Query Title](#queryTitle)
+    - [How to Set the Query Title](#query-title)
     - [How to Change the Response Message Layout](#layout)
-    - [How to Add a Footer Text](#footerText)
-    - [How to Add a Total Row](#totalRow)
-    - [How to Add a Global Follow Up Query Action](#followUpQueryGlobal)
-    - [How to Add a Row Level Follow Up Query Action](#followUpQueryRow)
-    - [How to Change Attribute Display Settings](#attributeDisplay)
-    - [How to Format an Attribute Value](#attributeFormat)
+    - [How to Add a Footer Text](#footer-text)
+    - [How to Add a Total Row](#total-row)
+    - [How to Add a Global Follow Up Query Action](#follow-up-query-global)
+    - [How to Add a Row Level Follow Up Query Action](#follow-up-query-row)
+    - [How to Change Attribute Display Settings](#attribute-display)
+    - [How to Format an Attribute Value](#attribute-format)
 
 ## Introduction <a name="introduction">
 
@@ -206,7 +206,7 @@ When using TypeScript, you will automatically get code completion support if you
 
 ## Supported Events <a name="events">
 
-### Entity Level Events <a name="entityEvents">
+### Entity Level Events <a name="entity-events">
 The table below lists all entity level events:
 
 | Event | Description | Event Properties |
@@ -215,7 +215,7 @@ The table below lists all entity level events:
 | `changeResponseData` | A handler that can be used to change the query result set. For a list of properties you can change, check the `QueryResult` interface in [Data Query Types](https://github.com/oracle/bots-node-sdk/blob/master/ts/lib/dataquery/dataQueryTypes.ts). | <ul><li><b>responseData</b>: The `QueryResult` object.</li></ul>
 | `changeBotMessages` | A handler that can be used to change the candidate bot message(s) that will be sent to the user. See the section on [Conversation Messaging](https://github.com/oracle/bots-node-sdk/blob/master/MESSAGE_FACTORY.md) for more info on adding or changing messages.| <ul><li><b>messages</b>: The list of messages.</li></ul>
 
-### Attribute Level Events <a name="attributeEvents">
+### Attribute Level Events <a name="attribute-events">
 The table below lists all attribute level events:
 
 | Event | Description | Event Properties |
@@ -266,7 +266,7 @@ All code samples are using TypeScript. If you are using JavaScript, you just nee
 
 Note that some of the samples below implement functionality that can also be implemented declaratively in the Query Entity page in the Oracle Digital Assistant user interface. However, the declarative settings apply to all types of queries that have the entity as root entity, which might not always be what you want. Using event handlers, you can add conditional behavior, for example, you can check for group-by queries by inspecting `context.getSQLQuery()`, and always display such queries in table layout, even if the number of rows is below the threshold for switching from form layout to table layout as configured in the Query Entity page.
 
-### How to Set the Query Title<a name="queryTitle">
+### How to Set the Query Title<a name="query-title">
 While we can set a static query title using the `Display Name` on the Query Entity page, we can create a dynamic title using the `changeUISettings` event:
 
 ```javascript
@@ -291,7 +291,7 @@ entity: {
   }
 ```
 
-### How to Add a Footer Text<a name="footerText">
+### How to Add a Footer Text<a name="footer-text">
 Here is a code snippet that adds a footer text that displays the execution time of the query. Note that the footerText is also used for the feedback message "Was this answer helpful?" when feedback is enabled, so we need to add our own text before existing footer text.
 
 ```javascript
@@ -314,7 +314,7 @@ changeBotMessages: async (event: ChangeBotMessagesEvent, context: DataQueryConte
 }
 ```
 
-### How to Add a Total Row <a name="totalRow">
+### How to Add a Total Row <a name="total-row">
 We can use the `changeResponseData` event to add a total row to the result. In the code example below, we add a total row when the query result contains more than 1 row and there is a `count` attribute present in the result rows.
 
 ```javascript
@@ -328,7 +328,7 @@ changeResponseData: async (event: ChangeResponseDataEvent, context: DataQueryCon
 }
 ```
 
-### How to Add a Global Follow Up Query Action <a name="followUpQueryGlobal">
+### How to Add a Global Follow Up Query Action <a name="follow-up-query-global">
 We can use the `changeBotMessages` event to add a button action that executes a global follow up query. The `DataQueryContext` contains a convenience method `createQueryAction` that takes care of most of the work. The global action button will be added to the `actions` array of the message.
 
 ```javascript
@@ -349,7 +349,7 @@ changeBotMessages: async (event: ChangeBotMessagesEvent, context: DataQueryConte
 }
 ```
 
-### How to Add a Row Level Follow Up Query Action <a name="followUpQueryRow">
+### How to Add a Row Level Follow Up Query Action <a name="follow-up-query-row">
 We can use the `changeBotMessages` event to add a button action that executes a row level follow up query. The `DataQueryContext` contains a convenience method `createFollowUpQueryAction` that takes care of most of the work. The row level action button will be added to the `actions` array within each `form` within the message.
 
 ```javascript
@@ -416,7 +416,7 @@ changeBotMessages: async (event, context) => {
 }
 ```
 
-### How to Change Attribute Display Settings <a name="attributeDisplay">
+### How to Change Attribute Display Settings <a name="attribute-display">
 We can use the attribute level `changeUISettings` event to change the display characteristics of an attribute. For example, we can completely hide it, or change whether the attribute is displayed in form layout or table layout:
 ```javascript
 hiredate: { 
@@ -430,7 +430,7 @@ hiredate: {
 }  
 ```
 
-### How to Format an Attribute Value <a name="attributeFormat">
+### How to Format an Attribute Value <a name="attribute-format">
 We can use the attribute level `format` event to format the attribute value. 
 ```javascript
 hiredate: { 

ENTITY_EVENT_HANDLER.md

@@ -7,8 +7,8 @@
     - [Using TypeScript](#ts)
 - [Writing Event Handler Functions](#writing)
 - [Supported Events](#events)
-    - [Entity Level Events](#entityEvents)
-    - [Entity-Item Level Events](#itemEvents)
+    - [Entity Level Events](#entity-events)
+    - [Entity-Item Level Events](#item-events)
 - [Access the Backend Using HTTP REST Calls](#rest)
 - [Code Samples](#samples)
     - [How to Conditionally Prompt for an Item](#prompt)
@@ -17,9 +17,9 @@
     - [How to Set or Update Bag Items](#update)
     - [How to Create a Summary Message](#summary)
     - [How to Use Custom Events](#custom)
-    - [How to Invoke a REST API](#restSample)
+    - [How to Invoke a REST API](#rest-sample)
     - [How to Send Rich Conversation Messages](#messages)
-    - [How to Modify Candidate Messages](#modifyMessage)
+    - [How to Modify Candidate Messages](#modify-message)
 
 ## Introduction <a name="introduction">
 
@@ -124,7 +124,7 @@ When using TypeScript you will automatically get code completion support when yo
 
 ## Supported Events <a name="events">
 
-### Entity Level Events <a name="entityEvents">
+### Entity Level Events <a name="entity-events">
 The table below lists all entity level events currently supported:
 
 | Event | Description | Event Properties |
@@ -139,7 +139,7 @@ The table below lists all entity level events currently supported:
 | `disambiguateBagItem` | A handler that can be used to modify the message that is shown to disambiguate between bag items when an entity match applies to more than one bag item. Note that this handler only fires when the skill configuration parameter `Use Enhanced Slot Filling` is switched on. | <ul><li><b>matchValue</b>: The entity value matched based on the user input</li><li><b>matchedBagItems</b>: list of the names of the bag items that are matched against the entity value.</li><li><b>userInput</b>: the last user input message that matched to multiple bag items.</li></ul>
 | `userInputReceived` | A handler that can be used to inspect and modify new item matches and disambiguation values before the bag items are validated and updated. The handler is invoked on every turn while resolving the composite bag entity. | <ul><li><b>currentItem</b>: The full name of the bag item currently being resolved.</li><li><b>userInput</b>: the last user input message.</li><li><b>newItemMatches</b>: a key-value map where each key is the full name of a bag item, and the value the candidate value for the item. The new item matches can be changed using `context.setItemMatches` and `context.clearItemMatch`.</li><li><b>disambiguationValues</b>: a key-value map where each key is the full name of a bag item, and the value a list of matched values for the item. The disambiguation values for an item can be changed using `context.setDisambiguationValues()` or `context.clearDisambiguationValues()`</li><li><b>disambiguationItems</b>: a key-value map where each key is the full name of a bag item, and the value a map with two properties: <ul><li><b>matchValue</b>: an entity value that matches against multiple bag items</li><li> <b>matchedBagItems</b>: list of the names of all the bag items that match against the entity value. The first item in the list is used as the key in the disambiguationItems map.</li></ul> A disambiguation value that matches multiple items can be removed by calling `context.clearDisambiguationItems()` and passing the full name of the first item in the list as argument.</li></ul>
 
-### Entity-Item Level Events <a name="itemEvents">
+### Entity-Item Level Events <a name="item-events">
 The table below lists all entity-item level events currently supported:
 
 | Event | Description | Event Properties |
@@ -347,7 +347,7 @@ custom: {
 }
 ```
 
-### How to Invoke a REST API <a name="restSample">
+### How to Invoke a REST API <a name="rest-sample">
 Calling a REST API from within an event handler is straightforward. Since all event handlers are async, you can use the `await` keyword in combination with an NPM HTTP request module that supports JavaScript Promises, like `node-fetch`. This allows you to write your asynchronous code in a synchronous matter.
 
 ```javascript
@@ -371,7 +371,7 @@ entity: {
 As you have seen in the previous examples, you can use `context.addMessage(<payload>)` to create a bot message that is sent to the user. 
 You can call this function multiple times to send multiple messages. See the section on [Conversation Messaging](https://github.com/oracle/bots-node-sdk/blob/master/MESSAGE_FACTORY.md) for code samples on how to create the various message types, like text, card, attachment, table and (editable) form messages.
 
-### How to Modify Candidate Messages <a name="modifyMessage">
+### How to Modify Candidate Messages <a name="modify-message">
 
 In the `publishXXX` event handlers, you can receive the list of candidate messages created by the component by calling `context.getCandidateMessageList()`. This method returns a class representation of every message type, allowing you to use various methods in the class and in the `MessageFactory` to modify the message. You can then use `context.addMessage(<payload>)` to send the message. Here is an example: