Merged master into next

Author: lauren-mills

.github/auto_assign.yml

@@ -10,7 +10,10 @@ reviewers:
   - lauren-mills
   - lzc850612 
   - pavolum
+  - peterinnesmsft
   - ryanlengel 
+  - sidmore
+  - taicchoumsft
 
 # A number of reviewers added to the pull request
 # Set 0 to add all the reviewers (default: 0)

README.md

@@ -5,7 +5,7 @@ This repository is the home for a set of templates and solutions to help build c
 | Name | Description |  
 |:------------:|------------| 
 |[<img src="https://github.com/microsoft/botframework-solutions/blob/master/docs/assets/images/icons/virtual-assistant.png" width="48"><br/> **Virtual Assistant (Preview)**](https://microsoft.github.io/botframework-solutions/overview/virtual-assistant-solution/) | Customers and partners have a significant need to deliver a conversational assistant tailored to their brand, personalized to their users, and made available across a broad range of canvases and devices. <br/><br/>  This brings together all of the supporting components and greatly simplifies the creation of a new bot project including: basic conversational intents, Dispatch integration, QnA Maker, Application Insights and an automated deployment.|
-|[<img src="https://github.com/microsoft/botframework-solutions/blob/master/docs/assets/images/icons/skill.png" width="48"> <br/> **Skills (Preview).**](https://microsoft.github.io/botframework-solutions/overview/skills/)| Extend your assistant with reusable conversational Skills to add common functionality such as collection of re-usable conversational skills enabling you to add functionality to a Virtual Assistant. Try the sample Skills available like Calendar, Email, To Do, Point of Interest, and more.|
+|[<img src="https://github.com/microsoft/botframework-solutions/blob/master/docs/assets/images/icons/skill.png" width="48"> <br/> **Skills (Preview).**](https://microsoft.github.io/botframework-solutions/overview/skills/)| **Important**: The sample Skill code is migrating to the [Bot Framework Skills repository](https://www.github.com/microsoft/botframework-skills). The source code here will be removed in the next release.<br/><br/>Extend your assistant with reusable conversational Skills to add common functionality such as collection of re-usable conversational skills enabling you to add functionality to a Virtual Assistant. Try the sample Skills available like Calendar, Email, To Do, Point of Interest, and more. |
 |[<img src="https://github.com/microsoft/botframework-solutions/blob/master/docs/assets/images/icons/bi-dashboard.png" width="48"> <br/> **Analytics**](https://microsoft.github.io/botframework-solutions/solution-accelerators/tutorials/view-analytics/1-intro)| Gain key insights into your assistant’s health and behavior with the Bot Framework Analytics solutions, which includes: sample Application Insights queries and Power BI dashboards to understand the full breadth of your assistant's conversations with users.|
 
 ## Packages

docs/_docs/clients-and-channels/clients/virtual-assistant-client.md

@@ -14,7 +14,7 @@ toc: true
 ## Prerequisites
 1. Install [Android Studio](https://developer.android.com/studio/).
 
-1. Download the [**Virtual Assistant Client** app source code](https://aka.ms/virtualassistantclient).
+1. Download the [**Virtual Assistant Client** app source code](https://aka.ms/bfvirtualassistantclient).
 
 1. [Create a Virtual Assistant]({{site.baseurl}}/virtual-assistant/tutorials/create-assistant/csharp/1-intro) to setup your Virtual Assistant environment.
 
@@ -38,10 +38,15 @@ There are two configuration files used to provide your environment settings.
   "service_key": "SPEECH_SERVICE_SUBSCRIPTION_KEY", // Replace with your Speech Service subscription key
   "service_region": "westus2",
   "bot_id": "DIRECT_LINE_SPEECH_SECRET_KEY", // Replace with your Direct Line Speech secret
+  "custom_commands_app_id": "", // Optional, if you are connecting to a Custom Commands application
+  "custom_voice_deployment_ids": "", // Optional, to point to custom voices
+  "custom_speech_recognition_endpoint_id": "", // Optional, to point to a customized speech recognition endpoint
+  "barge_in_supported": false, // Whether or not to listen to keyword while TTS is playing. If true, TTS playback stops once Keyword is verified.
   "user_id": "android",
   "user_name": "Android",
   "locale": "en-us",
   "keyword": "computer",
+  "enableKWS": false, // Keyword spotting
   "linkedAccountEndpoint": "" // Optional if you enabled the Linked Accounts solution in the prerequisites
 }
 ```
@@ -179,4 +184,4 @@ Compatible with [Spotify](https://www.spotify.com/).
 This method sends the value of this event activity to any listening apps, like the [**Event Companion**]({{site.baseurl}}/clients-and-channels/clients/event-companion) app.
 
 ## Next steps
-Use the [**Event Companion**]({{site.baseurl}}/clients-and-channels/clients/event-companion) app to broadcast your Virtual Assistant's metadata and prototype advanced scenarios.
+Use the [**Event Companion**]({{site.baseurl}}/clients-and-channels/clients/event-companion) app to broadcast your Virtual Assistant's metadata and prototype advanced scenarios.

docs/_docs/clients-and-channels/tutorials/enable-speech/4-integrate-speech-channel.md

@@ -2,15 +2,19 @@
 layout: tutorial
 category: Clients and Channels
 subcategory: Extend to Direct Line Speech 
-title: Build speech sample app
+title: Select a Direct Line Speech client
 order: 4
 ---
 
 # Tutorial: {{page.subcategory}}
 
-## Integrating with the Speech Channel
+## Option A: Using the Bot Framework 
+1. Download the [latest release from the Bot Framework Emulator repository](https://github.com/Microsoft/botframework-emulator/).
+![Bot Framework Emulator with Direct Line Speech Configuration]({{site.baseurl}}/assets/images/dlspeech_emulator.png)
 
-1. Download the [latest release from the Direct Line Speech Client repository](https://github.com/Azure-Samples/Cognitive-Services-Direct-Line-Speech-Client/releases).
-1. Follow the [quickstart instructions](https://github.com/Azure-Samples/Cognitive-Services-Direct-Line-Speech-Client#quickstart) to set up your environment and connect to your Virtual Assistant.
+
+## Option B: Using a sample Cognitive Services Voice Assistant client
+1. Download the [latest release from the Cognitive Services Voice Assistant repository](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/releases).
+1. Follow the [instructions on getting started](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/master/samples/clients/csharp-wpf#getting-started) to set up your environment and connect to your Virtual Assistant.
 
 ![Direct Line Speech Client Configuration]({{site.baseurl}}/assets/images/dlspeechclient.png)

docs/_docs/help/known-issues.md

@@ -13,19 +13,20 @@ toc: true
 If you experience a HTTP 401 (authentication) error when invoking a Skill with an exception message as shown:
      `Exception Message: Error invoking the skill id: "SKILL_ID" at "https://SKILL_APP_SERVICE.azurewebsites.net/api/messages" (status is 401)`
 
-Validate your parent Bot (e.g. Virtual Assistant) `appSettings.json file` has a correctly populated `BotFrameworkSkills` section. For example you should see a complete fragment like the one shown below with the `AppId` of each configured Skill. This should be populated automatically by the `botskills` CLI.
+Validate your parent Bot (e.g. Virtual Assistant) `appSettings.json file` has a correctly populated `botFrameworkSkills` section. For example you should see a complete fragment like the one shown below with the `appId` of each configured Skill. This should be populated automatically by the `botskills` CLI.
 
 ```json
 {
-"BotFrameworkSkills" : [
+"botFrameworkSkills" : [
     {
-        "Id": "calendarSkill",
-        "Name": "calendarSkill",
-        "AppId": "SkillAppId",
-        "SkillEndpoint": "https://yourSkillAppService.azurewebsites.net/api/messages",
+        "id": "calendarSkill",
+        "name": "calendarSkill",
+        "description": "The Calendar skill provides calendaring related capabilities and supports Office and Google calendars.",
+        "appId": "SkillAppId",
+        "skillEndpoint": "https://yourSkillAppService.azurewebsites.net/api/messages",
 
     }],
-    "SkillHostEndpoint": "https://yourVAAppService.azurewebsites.net/api/skills"
+    "skillHostEndpoint": "https://yourVAAppService.azurewebsites.net/api/skills"
 }
 
 ```
@@ -34,21 +35,21 @@ Validate your parent Bot (e.g. Virtual Assistant) `appSettings.json file` has a
 If you experience a HTTP 500 (server error) error when invoking a Skill with an exception message as shown:
      `Exception Message: Error invoking the skill id: "SKILL_ID" at "https://SKILL_APP_SERVICE.azurewebsites.net/api/messages" (status is 500)`
 
-Validate your parent Bot (e.g. Virtual Assistant) `appSettings.json file` has a valid `SkillHostEndpoint` which should be pointing at the URL of your Parent Bot (e.g. Virtual Assistant) with a suffix of `/api/skills` as per the example below. Skills connect back to the caller through this endpoint.
+Validate your parent Bot (e.g. Virtual Assistant) `appSettings.json file` has a valid `skillHostEndpoint` which should be pointing at the URL of your Parent Bot (e.g. Virtual Assistant) with a suffix of `/api/skills` as per the example below. Skills connect back to the caller through this endpoint.
 
 ```json
 {
-"BotFrameworkSkills" : [
+"botFrameworkSkills" : [
     { }],
-    "SkillHostEndpoint": "https://yourVAAppService.azurewebsites.net/api/skills"
+    "skillHostEndpoint": "https://yourVAAppService.azurewebsites.net/api/skills"
 }
 ```
 
 If you are debugging a parent bot locally and invoking a Skill remotely you will need to configure tunneling software (e.g. ngrok) to ensure this connection can be made back to the calling bot from the Skill. If you are using ngrok, follow these instructions:
 
 1. Start a debugging session for your Virtual Assistant and make a note of the port it's hosted on (e.g. 3978)
 1. Assuming port 3978 run this command:L `ngrok.exe http 3978 -host-header="localhost:3978"`
-1. Retrieve the https forwarding URL (e.g. https:{name}.ngrok.io) and update `SkillHostEndpoint` with this URL suffixed with `/api/skills`
+1. Retrieve the https forwarding URL (e.g. https:{name}.ngrok.io) and update `skillHostEndpoint` with this URL suffixed with `/api/skills`
 1. Now, when a remote skill is invoked it will route all responses back to `https:{name}.ngrok.io` which will then tunnel responses back to your Virtual Assistant
 
 ## My Microsoft App Registration could not be automatically provisioned

docs/_docs/skills/handbook/add-skills-to-a-virtual-assistant.md

@@ -44,14 +44,27 @@ See the [Skills Overview]({{site.baseurl}}/overview/skills) section for details
 
 ## Adding Skills to your Virtual Assistant
 
-Run the following command to add each Skill to your Virtual Assistant. This assumes you are running the CLI within the project directory and have created your Bot through the template and therefore have a `skills.json` file present in the working folder.
+Run the following command to add each Skill to your Virtual Assistant. This assumes you are running the CLI within the project directory and have created your Bot through the template and therefore have a `appsettings.json` file present in the working folder.
 
 The `--luisFolder` parameter can be used to point the Skill CLI at the source LU files for trigger utterances. For Skills provided within this repo these can be found in the `Deployment/Resources/LU` folder of each Skill. The CLI will automatically traverse locale folder hierarchies. This can be omitted for any of the skills we provide as the LU files are provided locally. Also, you have to specify the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration.
 
 ```bash
 botskills connect --remoteManifest "{{site.data.urls.SkillManifest}}" --cs
 ```
 
+Once the connect command finish successfully, you can see under the `botFrameworkSkills` property of your Virtual Assistant's appsettings.json file that the following structure was added with the information provided in the Skill manifest.
+
+```json
+    "botFrameworkSkills": {
+        "id": "<SKILL_ID>",
+        "appId": "<SKILL_APPID>",
+        "skillEndpoint": "<SKILL_ENDPOINT>",
+        "name": "<SKILL_NAME>",
+        "description": "<SKILL_DESCRIPTION>"
+    },
+    "skillHostEndpoint": "<VA-SKILL_ENDPOINT>"
+```
+
 See the [Skill CLI documentation]({{site.baseurl}}/skills/handbook/botskills) for detailed CLI documentation.
 
 ## Authentication Connection configuration
@@ -72,7 +85,7 @@ botskills disconnect --skillId SKILL_ID
 
 To update a Skill to your assistant/Bot we provide a `botskills` command line tool to automate the process of adding the Skill to your dispatch model and creating authentication connections where needed.
 
-Run the following command to update a Skill to your Virtual Assistant. This assumes you are running the CLI within the project directory and have created your Bot through the template and therefore have a `skills.json` file present in the working folder.
+Run the following command to update a Skill to your Virtual Assistant. This assumes you are running the CLI within the project directory and have created your Bot through the template and therefore have a `appsettings.json` file present in the working folder.
 
 The `--luisFolder` parameter can be used to point the Skill CLI at the source LU files for trigger utterances. For Skills provided within this repo these can be found in the `Deployment/Resources/LU` folder of each Skill. The CLI will automatically traverse locale folder hierarchies. This can be omitted for any of the skills we provide as the LU files are provided locally. Also, you have to specify the `--cs` (for C#) or `--ts` (for TypeScript) argument for determining the coding language of your assistant, since each language takes different folder structures that need to be taken into consideration.
 

docs/_docs/skills/handbook/skill-oauth.md

@@ -0,0 +1,57 @@
+---
+category: Skills
+subcategory: Handbook
+title: OAuth for Skills
+description: Overview for achieving OAuth for skills
+order: 7
+toc: true
+---
+
+# {{ page.title }}
+{:.no_toc}
+{{ page.description }}
+
+## Overview
+
+In azure bot service, a bot can use OAuth to gain access to online resources that require authentication. It's documented here: [Add Authentication to a bot](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-authentication?view=azure-bot-service-4.0&tabs=aadv1%2Ccsharp) and [Bot authentication](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-authentication?view=azure-bot-service-4.0). When your bot is working as a skill, meaning to your users, instead of talking to your bot directly through various channels, they are actually using your skill as a backend service when talking to another bot/virtual assistant, OAuth is also supported. 
+
+## OAuth flow
+
+In a non-skill scenario, a bot goes through these steps to perform OAuth for users:
+
+1. bot configures OAuth connection in Bot Channel Registration page
+
+![OAuth Connection]({{site.baseurl}}/assets/images/OAuthConnection.png)
+
+1. once OAuth connection is configured correctly (Click 'Test Connection' to simulate an OAuth flow), in bot code, use OAuthPrompt (included in Microsoft.Bot.Builder.Dialogs library) to kick start an OAuth flow
+![Test OAuth Connection]({{site.baseurl}}/assets/images/OAuthConnection-TestConnection.png)
+1. the bot will use OAuthPrompt to retrieve SignInUrl (depending on the channel) and include it inside the OAuthCard that the bot returns to the user
+1. the user will see an OAuthCard in the client and click on the Login button to go through an OAuth flow
+1. after the OAuth flow is finished (either through magic code or not) the bot will receive the OAuth token needed for the respective resource, and use that to perform subsequent steps
+
+![OAuth Transcript]({{site.baseurl}}/assets/images/OAuth-Transcript.png)
+
+In a skill scenario, the overall flow is the same, with the virtual assistant being transparent, meaning that it would just be passing through the OAuthCard back to user from skill, or magic code back to skill from user. In the case of no magic code, the virtual assistant wouldn't pass through the actual token because that'll be considered unsafe (especially in the scenarios of 3rd party skills). In that case the skill will receive the token directly from Azure Bot Service TokenService. 
+
+In previous versions of Virtual Assistant Template, we used to use the Virtual Assistant as the component that acts on behalf of skills to retrieve token, and pass it along to skills. Compared to the new approach which is that the skill takes care of its own OAuth flow, it has these disadvantages:
+
+1. When Virtual Assistant is acting on behalf of the skill to retrieve token and pass it to the skill, VA always has a copy of the token. This is a security issue, especially when the skill is a 3rd party skill.
+1. The skill has to account for skill mode and non-skill mode, because the skill runtime has no knowledge how the user is calling it. When Virtual assistant is getting the token instead of the skill itself, the runtime has to perform differently than when it's being used directly by its user. That inconsistency will create confusion.
+
+## SSO
+
+The latest Azure Bot Service has infrastructure built in to support SSO (Single Sign on). Here are the documentation for it:
+
+1. [Single Sign on overview in Azure Bot Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-sso?view=azure-bot-service-4.0)
+1. [Add Single Sign on to a bot](https://review.docs.microsoft.com/en-us/azure/bot-service/bot-builder-authentication-sso?view=azure-bot-service-4.0&branch=pr-en-us-2084&tabs=csharp%2Ceml)
+1. [Identity Providers](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-identity-providers?view=azure-bot-service-4.0&tabs=adv1%2Cga2)
+
+
+## Troubleshooting
+
+During development we often run into issues when using OAuth. Here's some typical errors we get and how to troubleshoot for them
+
+1. Bad Request
+This happens when user clicks on the Login button in the OAuthCard. When this happens, it usually means when creating the OAuthPrompt instance, the connection name is wrong. The connection name needs to be the same as the connection setting in Bot Channel Registration page.
+1. API Error when calling the online resources
+This usually means the token you get back doesn't have enough permission to perform the tasks you're using the API for. Make sure you configure the correct Scope when you create the OAuth Connection.