Conversation Designer going live (#188)

* convert external Twilio links to HTML style target="_blank" to open in new tab. * Secure bot reminder and ngrok command. If you're debugging through Cortana, then the Microsoft App credentials need to specified in both the Bot Framework portal and the Web.config file. I also found that bots always ran on port 3979. And lastly, unless I specified the host header the requests would fail with 400. * convert external links to open in new tab * update external links to open in new tab * Update bot-builder-nodejs-global-handlers.md Added missing comma's in the examples of trigger actions * Fixing link * Revert "Merging upstream into public" This reverts commit ed2438b, reversing changes made to f4200df. * Dotnet form flow updates (#161) * Updated .NET FormFlow articles to add links to sample code on GitHub. * Fixed broken link. * Updated .NET FormFlow articles to move Sample code section. * Fixed broken link. * Update IActivity.xml * Update IActivity.xml Fixing indentation. * Updating summary for ChannelData * Updating IActivity docs with ChannelData remarks * bugfix: domain parameter and log=false for compliance (#164) * fix bug - domain parameter * section link, class definition * document log=off for privacy compliance * fix heading * Change .NET Framework target version (#166) * Adding DirectLine to REST card (#167) * Typo fix * Removing location control from hub * little fixes (#169) Add an optional extended description… * clicking on a speech bubble reveals the JSON data underlying the message. (#171) * Microsoft.Bot.Builder template requires IIS Express; added download link. (#170) * The Microsoft.Bot.Builder template requires IIS Express, so now there's a link where you can download it. * occasional requirement: IIS Express download, a bit hard to find this link so now it's noted near the place where it's (occasionally) needed. * section: dialog-based proactive message - fix broken sample code & link to botadaptor.js file * add back comment with note about session.userData * fix typo * Anchor links (#173) * Promoting questions to H2s for anchor links * Updating title and H1 * Fixing outdated anchor links * VS Community isn't supported by the template * Update dos-and-donts.md * Update style-and-voice.md * Update style-and-voice.md * Fixing link to botadapter.js * section: dialog-based proactive message - fix broken sample code & link to botadaptor.js file * add back comment with note about session.userData * fix typo * ISO 639-2 recommends use of the language codes in lower case (#175) * Update bot-builder-dotnet-quickstart.md Restoring links to the controller & dialog templates that were present in previous documentation * Removing bad metadata (#183) * Conversation designer (#178)
MicrosoftDocs · RobStand · Aug 7, 2017 · Jul 7, 2017 · Jul 7, 2017 · Jul 8, 2017
commit 1e3591f94a8a51e0d1b056d59e39a99682dd75b3
diff --git a/articles/cognitive-services/TOC.md b/articles/cognitive-services/TOC.md
@@ -1,7 +1,7 @@
-# [Make bots smarter](../intelligent-bots.md)
+# [Make bots more intelligent](../intelligent-bots.md)
 # [Add language understanding](../cognitive-services-add-bot-language.md)
 # [Add knowledge extraction](../cognitive-services-add-bot-knowledge.md)
 # [Add speech recognition](../cognitive-services-add-bot-speech.md)
 # [Add search](../cognitive-services-add-bot-search.md)
 # [Add image recognition](../cognitive-services-add-bot-vision.md)
-# [Add location control](../cognitive-services-add-bot-location-control.md)
+# [Add location control](../cognitive-services-add-bot-location-control.md)
diff --git a/articles/conversation-designer/TOC.md b/articles/conversation-designer/TOC.md
@@ -0,0 +1,15 @@
+# [Conversation Designer Overview](index.md)
+## [Create a bot](conversation-designer-create-bot.md)
+## [Save bot](conversation-designer-save-bot.md)
+## [Test bot](conversation-designer-debug-bot.md)
+## [Task triggers](conversation-designer-tasks.md) 
+### [Language Understanding](conversation-designer-luis.md)
+### [Code recognizers](conversation-designer-code-recognizer.md)
+## [Task actions](conversation-designer-actions.md)
+## [Task dialogs](conversation-designer-dialogs.md)
+## [Shared dialogs](conversation-designer-dialogs-shared.md)
+## [Response templates](conversation-designer-response-templates.md)
+## [Adaptive cards](conversation-designer-adaptive-cards.md)
+## [Connect to channels](conversation-designer-deploy.md)
+## [API reference](conversation-designer-context-object.md)
+## [Release notes](conversation-designer-release-notes.md)
diff --git a/articles/conversation-designer/conversation-designer-actions.md b/articles/conversation-designer/conversation-designer-actions.md
@@ -0,0 +1,72 @@
+---
+title: Task actions | Microsoft Docs
+description: Learn how to set up actions for Conversation Designer bots
+author: vkannan
+manager: rstand
+ms.topic: article
+ms.prod: bot-framework
+ms.date: 07/04/2017
+---
+# Task actions
+
+Actions represent how a bot should respond to a specific task trigger. Available options are:
+
+- [Simple response](#simple-response): Defines a simple response with an optional adaptive card. 
+- [Script action](#script-action): Write custom script to call back-end service to complete task.
+- [Dialog](conversation-designer-dialogs.md): Build and execute a conversation model using a dialog flow.
+
+## Simple response
+
+To set up a simple response as the action, select **Simple response** from **DO** action drop down. You can then enter simple responses into the **Bot's response to user** field.
+
+You can optionally include an [adaptive card](conversation-designer-adaptive-cards.md) with the simple response. You can also optionally provide custom script function to execute before sending the response to the user. These options are available to you while you create or edit a task. 
+
+## Script action
+
+[Script action functions](conversation-designer-context-object.md#script-callback-functions) execute custom script you define to help complete the task. For example, calling into a service to actually set the thermostat to 74 degrees when the user says "Set my thermostat to 74 degrees." 
+
+To use custom script as the action, select **Script action** as the **DO** action type in the task editor. Then enter the name of the function that implements the action. Click **Edit** to bring up the **Scripts** editor and write your implementation for this function. 
+
+## Script action function parameter
+
+The specified action callback function will always be called with the [`context`](conversation-designer-context-object.md) object.
+
+The `context` object includes both `taskEntities` and `contextEntities`. Task entities are entities defined or generated for this task and context entities are a property bag where entities can be preserved across conversations with the user.
+<!-- TODO: Do we really mean across all conversations (as defined by a unique activity conversation ID) with a given user for this specific bot? 
+Would be good to include detail on lifetime management and how/when to clear these.-->
+
+<!-- ## Do action function expected return values
+TODO TBD -->
+
+## Return value
+**Script action** functions are expected to return a boolean.
+
+## Sample script action function
+The following sample function makes an HTTP call to get a response before returning a trigger matched.
+
+```javascript
+export function NewTask_do_onRun(context) {
+    var options =  {
+        host: 'HOST',
+        path: 'PATH',
+        method: 'post',
+        headers: {
+            "HEADER1" : "VALUE"
+        }, 
+        body: {
+            "BODY": VALUE
+        }
+    };
+
+    return http.request(options).then(function(response) {
+      // parse response payload
+      // Send a message to user
+      context.responses.push({text: "Done", type: "message"});
+    });
+} 
+
+```
+
+## Next step
+> [!div class="nextstepaction"]
+> [Task Dialogs](conversation-designer-dialogs.md)
diff --git a/articles/conversation-designer/conversation-designer-adaptive-cards.md b/articles/conversation-designer/conversation-designer-adaptive-cards.md
@@ -0,0 +1,114 @@
+---
+title: Adaptive cards | Microsoft Docs
+description: Learn how to configure adaptive cards.
+author: vkannan
+manager: rstand
+ms.topic: article
+ms.prod: bot-framework
+ms.date: 07/04/2017
+---
+
+# Configure adaptive cards
+
+<a href="http://adaptivecards.io" target="_blank">Adaptive Cards</a> is a new schema that defines rich UI cards for use in several 
+different endpoints including Microsoft Bot Framework channels. 
+
+Conversation Designer provides a deeply integrated authoring environment to author, preview, and use adaptive cards in your bots. 
+
+Adaptive cards can be defined in several different key places.
+
+- A simple response to [action](conversation-designer-actions.md) for a task.
+- In feedback state in a dialog.
+- In prompt states in a dialog. Note that prompts can have separate cards: one for the response and another for re-prompting.
+
+To define an adaptive card, navigate to the relevant editor. Browse and choose from one of the existing Adaptive Card 
+Templates or build your own in the JSON code editor. 
+
+<!--TODO: Insert screenshot -->
+
+As you are building a card, a rich preview of the card is rendered in the authoring portal.
+
+## Use entities and language generation templates
+Adaptive cards support full language generation resolution.
+
+* `entityName` uses entities inside the card.
+* `responseTemplateName` uses simple or conditional response templates inside the card.
+
+<!--
+# Binding form flow input fields to bot entities
+TODO: fill this out based on design/ implementation -->
+
+<!-- ## Adaptive Card schema
+
+You can learn more about adaptive cards here  TODO: Insert link to adaptive cards schema documentation -->
+
+## Sample adaptive card payload
+
+The following JSON shows the payload of an adaptive card.
+
+```json
+{
+    "$schema": "https://microsoft.github.io/AdaptiveCards/schemas/adaptive-card.json",
+    "type": "AdaptiveCard",
+    "version": "1.0",
+    "body": [
+        {
+            "speak": "<s>Serious Pie is a Pizza restaurant which is rated 9.3 by customers.</s>",
+            "type": "ColumnSet",
+            "columns": [
+                {
+                    "type": "Column",
+                    "size": "2",
+                    "items": [
+                        {
+                            "type": "TextBlock",
+                            "text": "[Greeting], [TimeOfDayTemplate], You can eat in {location}",
+                            "weight": "bolder",
+                            "size": "extraLarge"
+                        },
+                        {
+                            "type": "TextBlock",
+                            "text": "9.3 · $$ · Pizza",
+                            "isSubtle": true
+                        },
+                        {
+                            "type": "TextBlock",
+                            "text": "[builtin.feedback.display]",
+                            "wrap": true
+                        }
+                    ]
+                },
+                {
+                    "type": "Column",
+                    "size": "1",
+                    "items": [
+                        {
+                            "type": "Image",
+                            "url": "http://res.cloudinary.com/sagacity/image/upload/c_crop,h_670,w_635,x_0,y_0/c_scale,w_640/v1397425743/Untitled-4_lviznp.jpg",
+                            "size":"auto"
+                        }
+                    ]
+                }
+            ]
+        }
+    ],
+    "actions": [
+        {
+            "type": "Action.Http",
+            "method": "POST",
+            "title": "More Info",
+            "url": "http://foo.com"
+        },
+        {
+            "type": "Action.Http",
+            "method": "POST",
+            "title": "View on Foursquare",
+            "url": "http://foo.com"
+        }
+    ]
+}
+```
+
+## Next step
+> [!div class="nextstepaction"]
+> [Connect to channels](conversation-designer-deploy.md)
diff --git a/articles/conversation-designer/conversation-designer-code-recognizer.md b/articles/conversation-designer/conversation-designer-code-recognizer.md
@@ -0,0 +1,43 @@
+---
+title: Code recognizer | Microsoft Docs
+description: Learn how to use a custom code recognizer as a task trigger.
+author: vkannan
+manager: rstand
+ms.topic: article
+ms.prod: bot-framework
+ms.date: 07/04/2017
+
+---
+
+# Code recognizer as task trigger
+
+Code recognizers enable you to write custom scripts to help perform a task. Regex-based expression evaluation or calling into other services can be used to help determine the user's intent. The custom script will instruct the conversation runtime to trigger a task. 
+
+To use a script as a task trigger, choose "Script trigger" as the trigger type in the **Task** editor and then specify the name of the function that implements the custom script function. Click **Edit** to start editing the function. 
+
+## Script trigger function parameter
+
+The specified script callback function will always be called with the [`context`](conversation-designer-context-object.md) object.
+
+The `context` object includes both `taskEntities` and `contextEntities`. Task entities are entities defined or generated for this task and context entities are property bags where entities can be preserved across conversations with the user.
+
+## Return value
+
+**Script trigger** functions are expected to return a boolean.
+
+## Sample regex-based recognizer
+The following code sample uses regex to process the request and returns a boolean so the conversation runtime can determine which script trigger to execute.
+
+```javascript
+export function fnFindPhoneTrigger(context) {
+    if (context.request.text.includes("call") || context.request.text.includes("ring")) {
+        return true;
+    } else {
+        return false;
+    }
+} 
+```
+
+## Next step
+> [!div class="nextstepaction"]
+> [Task actions](conversation-designer-actions.md)
diff --git a/articles/conversation-designer/conversation-designer-context-object.md b/articles/conversation-designer/conversation-designer-context-object.md
@@ -0,0 +1,95 @@
+---
+title: API Reference for the context object | Microsoft Docs
+description: Learn how to reference the context object in your Conversation Designer bot.
+author: vkannan
+manager: rstand
+ms.topic: article
+ms.prod: bot-framework
+ms.date: 07/11/2017
+
+---
+# API Reference
+
+Conversation Designer gives you the ability to add custom business logic to your bot. These script functions are implemented in the **Scripts** editor. The functions are hooked up in various places like the conditional response templates, the task's *triggers* or *actions*, or the dialog states and they all receives a `context` object that is of type **[IConversationContext]** in their function parameters.
+
+The following code sample shows the signature for a conditional response function with the **context** object passed in.
+
+```javascript
+/**
+* @param {IConversationContext} context
+*/
+export function NewConditionalResponse_onRun(context) {
+    // Business logic here
+    return true; // Returns a boolean
+}
+
+```
+
+Through the `context` object, you can access information regarding the conversation between the user and the bot.
+
+## Script callback functions
+
+The custom script callback functions you create may take many forms. While you can give them different names, functionally, they take on one of the following forms.
+
+| Form | Parameter | Return type | Description |
+| ---- | ---- | ---- | ---- |
+| Before response function | context | **void** | Function that is executed before a response is given. |
+| Process function | context | **void** | Function that performs business logic. |
+| Decision function | context | **string** | Function that makes decisions and conditional response based on business logic. |
+| Code recognizer function | context | **boolean** | Custom business logic that gets run when a **Script trigger** occurs. |
+| Prompt function | context | **boolean** | Function that executes as part of a prompt. |
+
+
+## IConversationContext interface
+
+The `IConversationContext` interface tracks conversation information between the user and the bot. All custom functions that are hooked up through the Conversation Designer will receive a `context` object as parameter argument.
+
+## Context properties
+The `context` object exposes the following properties.
+
+| Name |  Code | Description |
+| ---- | ---- | ---- |
+| `contextEntities` | `context.contextEntities["entityName"][index].value` | Read-only. The **contextEntities** property persists until explicitly cleared or until the bot receives a new conversation (conversation update activity). |
+| `taskEntities` | `context.taskEntities["entityName"][index].value` | Read-only. The **taskEntities** property are cleared at the end of the current task execution. |
+| `flowState` | // Get the name of the  current task being executed. <br/> `context.flowState.task` <br/> // Get a handle to the stack for the current conversation. <br/> `context.flowState.stack` | The **flowState** maintains the *task* and *stack* state information for the current task. The *task* and *stack* states are of type [Entity](#entity-interface).  |
+| | `context.flowState.stack.type` | Get the type of current dialog state being executed (e.g.: process, decision, feedback, etc.) |
+| | `context.flowState.stack.dialogFlowName` | Get the name of the parent dialog flow if the current conversational state is in a dialog; otherwise, this property will be empty. |
+| | `context.flowState.stack.stateName` | Get the name of the current sate being executed. |
+| `output` | `context.output` | Read-only. The output from the code behind function. |
+| `request` | `context.request` | Get the request object that contains the bot's activity.  |
+| | `context.request.attachment` | An attachment activity that may contains an adaptive card. |
+| | `context.request.text` | A text activity that contains the incoming text message from the client. |
+| | `context.request.speak` | A speak activity that contains the spoken text (if available) from the client. |
+| | `context.request.type` | Specifies the activity type (Default: "message"). |
+| `response` | `context.response` | Maintains an array of activities that will be sent back to the client at the end of the current state or code behind execution. |
+| | `context.response.push` | Add an activity to the response. |
+| | `context.response.push` | Remove an activity from the top of the response array. |
+
+## Context methods
+The `context` object exposes the following methods.
+| Name | Return type | Code | Description |
+| ---- | ---- | ---- | ---- |
+| `addContextEntity` | **IConversationContext** | `context.addContextEntity("entityName", "entityValue");` | Add a context entity. Context entities persists until explicitly cleared or the bot receives a new conversation (conversation update activity).|
+| `addTaskEntity` | **IConversationContext** | `context.addTaskEntity("entityName", "entityValue");` | Add a task entity. Task entities are cleared at the end of the current task execution. |
+| `containsContextEntity` | **boolean** | `context.containsContextEntity("entityName", "entityValue");` | Indicates if **contextEntities** contains the entity. |
+| `containsTaskEntity` | **boolean** | `context.containsTaskEntity("entityName", "entityValue");` | Indicates if **taskEntities** contains the entity. |
+| `getCurrentTurn` | **number**| `context.getCurrentTurn();` | Get the turn from the Frame on top of the stack if you are executing a reprompt. |
+| `removeContextEntity` | **IConversationContext** | `context.removeContextEntity("entityName", "entityValue");` | Remove a context entity. |
+| `removeTaskEntity` | **IConversationContext** | `context.removeTaskEntity("entityName", "entityValue");` | Remove a task entity. |
+
+## Entity interface
+
+The **Entity** interface exposes the following **read-only** properties.
+
+| Name | Return type | Description |
+| ---- | ---- | ---- |
+| `type` | **string** | The entity type (e.g.: color, city, sport, etc...). |
+| `value` | **string** | The value of the entity extracted from the utterance (e.g.: red, Seattle, Football). |
+| `startIndex` | **number** | The starting index of the entity extracted from the utterance. |
+| `endIndex` | **number** | The ending index of the entity extracted from the utterance. |
+| `score` | **number** | The confidence score of an entity (e.g.: range between 0 to 1). |
+| `resolution` | **EntityResolution** | A property bag with more information about an entity. Look at [builtin.datetime](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/pre-builtentities) for an example of how the **score** is used. |
+
+## Next step
+> [!div class="nextstepaction"]
+> [Create a bot](conversation-designer-create-bot.md)