Pull "next docs" into next branch

docs/Gemfile

@@ -25,6 +25,7 @@ group :jekyll_plugins do
   gem 'jekyll-octicons'
   gem 'jekyll-readme-index'
   gem 'jekyll-mentions'
+  gem 'jekyll-toc'
   gem 'jemoji'
 end
 

docs/Gemfile.lock

@@ -188,6 +188,8 @@ GEM
       jekyll-seo-tag (~> 2.0)
     jekyll-titles-from-headings (0.5.1)
       jekyll (~> 3.3)
+    jekyll-toc (0.12.2)
+      nokogiri (~> 1.9)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     jemoji (0.10.2)
@@ -255,6 +257,7 @@ DEPENDENCIES
   jekyll-readme-index
   jekyll-redirect-from
   jekyll-sitemap
+  jekyll-toc
   jemoji
   minima (~> 2.0)
   wdm (~> 0.1.0)

docs/_config.yml

@@ -41,4 +41,15 @@ plugins:
   - jekyll-mentions
   - jekyll-octicons
   - jekyll-sitemap
+  - jekyll-toc
   - jemoji  
+
+toc:
+  # Default is "section-nav":
+  list_class: nav flex-column
+  # Default is no class for sublists:
+  sublist_class: nav flex-column
+  # Default is "toc-entry":
+  item_class: nav-item no-underline py-1 text-gray-light
+  # Default is "toc-":
+  item_prefix: nav-item-

docs/_data/toc.yml

@@ -1,18 +1,23 @@
 Overview:
-- Samples
-Tutorials:
+Virtual Assistant:
 - Create a Virtual Assistant
 - Customize a Virtual Assistant
-- Create a skill
-- Customize a skill
-- Enable Speech
-- Enable Microsoft Teams
-How To:
-- Virtual Assistant
-- Skills
+- Deploy a Virtual Assistant
+- Enable speech
+- Extend to Microsoft Teams
+- View analytics using Power BI
+- Handbook
+- Samples
+Skills:
+- Create a Skill
+- Customize a Skill
+- Connect to a sample Skill
+- Convert a v4 Bot to a Skill
+- Extend a v4 Bot with Skills
+- Handbook
 - Samples
-Reference:
-- Virtual Assistant
-- Skills
+Additional resources:
 - Analytics
-- Samples
+- Deployment
+Help:
+- Reference

docs/_docs/_samples/_default.md

@@ -4,4 +4,5 @@ subcategory:
 language:
 title: 
 order: 1
+toc: true
 ---

docs/_docs/_samples/_tutorial-intro.md

@@ -0,0 +1,20 @@
+---
+layout: tutorial
+category: Tutorials
+subcategory: [Tutorial Name]
+title: Intro
+language: [C#, TypeScript or None]
+order: 1
+---
+
+# Tutorial: {{page.subcategory}} ({{page.language}})
+
+## {{ page.title }}
+
+### Purpose
+
+### Prerequisites
+
+### Time To Complete
+
+### Scenario

docs/_docs/_samples/_tutorial.md

@@ -5,4 +5,8 @@ subcategory: [Tutorial Name]
 title: Intro
 language: [C#, TypeScript or None]
 order: 1
----
+---
+
+# Tutorial: {{page.subcategory}} ({{page.language}})
+
+## {{ page.title }}

docs/_docs/help/faq.md

@@ -0,0 +1,156 @@
+---
+category: Help
+title: Frequently asked questions
+order: 1
+toc: true
+---
+
+
+# {{ page.title }}
+{:.no_toc}
+
+## Virtual Assistant
+
+### What is the Bot Framework Virtual Assistant Solution Accelerator?
+{:.no_toc}
+The Bot Framework Virtual Assistant template enables you to build a conversational assistant tailored to your brand, personalized for your users, and available across a broad range of clients and devices.
+This greatly simplifies the creation of a new bot project by providing basic conversational intents, a dispatch model, Language Understanding and QnA Maker integration, SKills, and automated ARM deployment.
+
+### What is the architecture of a Virtual Assistant solution?
+{:.no_toc}
+Learn more about the [Virtual Assistant solution architecture]().
+
+### How do I create a Virtual Assistant?
+{:.no_toc}
+Follow a guided tutorial to create a Virtual Assistant (available in [C#]() or [Typescript]()).
+
+### How do I customize a Virtual Assistant?
+{:.no_toc}
+Follow a guided tutorial to customize a Virtual Assistant (available in [C#]() or [Typescript]()).
+
+### How do I deploy a Virtual Assistant?
+{:.no_toc}
+Learn how to deploy a Virtual Assistant by [automated scripts]() or [manual configuration]().
+
+### How do I test a Virtual Assistant?
+{:.no_toc}
+Learn how to [test a Virtual Assistant]().
+
+### How do I pass events to a Virtual Assistant?
+{:.no_toc}
+Event activities are used to pass metadata between a Bot and user without being visible to the user. The data from these activities can be processed by a Virtual Assistant to fulfill scenarios like providing a summary of the day ahead or filling semantic action slots on a Skill.
+Learn more on [sample event activities packaged with the Virtual Assistant template]().
+
+### How do I link user accounts to a Virtual Assistant?
+{:.no_toc}
+Learn how to [link user accounts to a Virtual Assistant]().
+
+### How do I collect feedback from users for a Virtual Assistant?
+{:.no_toc}
+Learn more about using the [sample feedback middleware that enables you to capture feedback from a Virtual Assistant's users]() in Application Insights telemetry.
+
+### How does localization work for a Virtual Assistant?
+{:.no_toc}
+Learn how to [manage localization across a Virtual Assistant environment]().
+
+### How do I send proactive messages to users?
+{:.no_toc}
+Learn how to [send proactive messages to users]().
+
+### How do I convert from the Enterprise Template to the Virtual Assistant Template?
+{:.no_toc}
+Learn how to [convert from the Enterprise Template to the Virtual Assistant Template]().
+
+### What happened to the Virtual Assistant solution (v0.3 and earlier)?
+{:.no_toc}
+The Virtual Assistant solution from v0.3 and earlier was delivered with multiple sample SKills to support productivty and point of interest scenarios. These are now available as indepdendent [Bot Framework SKills], reusable Skills that can be added to an existing bot.
+
+## Skills
+
+### What is a Bot Framework Skill?
+{:.no_toc}
+Bot Framework SKills are re-usable skill building blocks covering conversational use-cases, enabling you to add extensive functionality to a Bot within minutes.
+Skills include Language Understanding models, dialogs, and integration code, and are delivered in source code - enabling you to customize and extend as required.
+
+### What sample Skills are available?
+{:.no_toc}
+The following sample Skills are available out of the box, with appropriate steps required to deploy and configure for your own use/
+- [Calendar]()
+- [Email]()
+- [To Do]()
+- [Point of Interest]()
+- [Experimental]()
+
+### How do I create a Bot Framework Skill?
+{:.no_toc}
+Follow a guided tutorial to create a Bot Framework Skill (available in [C#]() or [Typescript]()).
+
+### How do I customize a Bot Framework Skill?
+{:.no_toc}
+Follow a guided tutorial to customize a Bot Framework Skill (available in [C#]() or [Typescript]()).
+
+### What are the best practices when developing custom Bot Framework Skills?
+{:.no_toc}
+Learn the [best practices when developing a custom Bot Framework Skill]().
+
+### How do I add Skills to a Virtual Assistant?
+{:.no_toc}
+Learn how to [add SKills to a Virtual Assistant]().
+
+### What is a Bot Framework Skill manifest?
+{:.no_toc}
+The [Bot Framework Skill manifest]() enables Skills to be self-describing in that they communicate the name and sceription of a SKill, it's authentication requirements (if appropriate), along with discrete actions it exposes.
+
+This manifest provides all of the metadata required for a calling Bot to know when to trigger invoking a Skill and what actions it provides. The manifest is used by the Botskills command line tool to configure a Bot to make use of a SKill.
+
+### How does Bot Framework Skill authentication work?
+{:.no_toc}
+A Skill needs to be able to authenticate the request from a Virtual Assistant, [learn how a Skill uses JWT and whitelist authentication]().
+
+### What is the Botskills Command Line (CLI) tool?
+{:.no_toc}
+[Botskills command line tool]() allows you to automate teh connection between a Virtual Assistant and your Skills; this includes the process of updating your dispatch models and creating authentication connections when needed.
+
+### How do I enable Bot Framework Skills on an existing v4 Bot?
+{:.no_toc}
+Learn how to [enable Bot Framework Skill support on an existing v4 Bot]().
+
+### How do I convert an existing v4 Bot to a Bot Framework Skill?
+{:.no_toc}
+Learn how to [convert an existing v4 Bot to a Bot Framework Skill]().
+
+## Analytics
+
+### How do I enable analytics for a bot or a Virtual Assistant?
+{:.no_toc}
+[Application Insights](https://azure.microsoft.com/en-us/services/application-insights/) is an Azure service which enables analytics about your applications, infrastructure and network. Bot Framework can use the built-in Application Insights telemetry to provide information about how your bot is performing and track key metrics. The Bot Framework SDK ships with several samples that demonstrate how to add telemtry to your bot and produce reports (included).
+
+[Power BI](https://powerbi.microsoft.com/) is a business analytics services that lets you visualize your data and share insights across your organization. You can ingest data from Application Insights into live dashboards and reports.
+
+[Learn more]({{site.baseurl}}/overview/analytics/)
+
+### How do I configure Application Insights for a bot or Virtual Assistant?
+{:.no_toc}
+Bot Framework can use the Application Insights telemetry to provide information about how your bot is performing, and track key metrics. The Bot Framework SDK ships with several samples that demonstrate how to add telemetry to your bot and produce reports (included).
+
+Common queries for bot analytics are available in [Application Insights Analytics]().
+
+Examples of Power BI dashboards are provided in the [Power BI Analytics sample](https://aka.ms/botPowerBiTemplate), highlighting how to gain insights on your bot's performance and quality.
+
+### Where can I download the sample Power BI for a Virtual Assistant?
+{:.no_toc}
+Examples of Power BI dashboards are provided in the [Power BI Analytics sample](https://aka.ms/botPowerBiTemplate), highlighting how to gain insights on your bot's performance and quality.
+
+## Samples
+
+### How do I set up Enterprise Notifications for a Virtual Assistant?
+{:.no_toc}
+Learn how to [set up the Enterprise Notifications sample for a Virtual Assistant](https://aka.ms/enterprisenotificationssample).
+
+### How do I use the Virtual Assistant Android Client?
+{:.no_toc}
+Learn how to [configure your Virtual Assistant with the Virtual Assistant Android Client](https://aka.ms/bfvirtualassistantclientdocs).
+
+### How do I use the Hospitality Assistant sample?
+{:.no_toc}
+The [Hospitality Aassistant sample](https://aka.ms/hospitalityassistantdocs) is a prototype of a Virtual Assistant solution that helps to conceptualize and demonstrate how an assistant could be used in a hospitality-focused scenario. It also provides a starting point for those interested in creating an assistant customized for this scenario.

docs/_docs/reference/knownissues.md → docs/_docs/help/known-issues.md

@@ -1,26 +1,16 @@
 ---
-category: Reference
-title: Known Issues
+category: Help
+title: Known issues
 order: 2
+toc: true
 ---
 
 # {{ page.title }}
 {:.no_toc}
 
-## Contents
-{:.no_toc}
-
-* 
-{:toc}
-
-
 ## My Microsoft App Registration could not be automatically provisioned
 
-Some users might experience the following error when running deployment `Could not provision Microsoft App Registration automatically. Please provide the -appId and -appPassword arguments for an existing app and try again`. In this situation, create your own Azure Active Directory App through [this](https://ms.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredAppsPreview) part of the Azure portal.
-
-- Click `New Registration`
-- Provide a name
-- Select `Accounts in any organizational directory`
+Some users might experience the following error when running deployment `Could not provision Microsoft App Registration automatically. Please provide the -appId and -appPassword arguments for an existing app and try again`. In this situation, [create and register an Azure AD application](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-authentication?view=azure-bot-service-4.0&tabs=csharp%2Cbot-oauth#create-and-register-an-azure-ad-application) manually.
 
 Once created, retrieve the `Application (ClientId)` and create a new client secret on the `Certificates & secrets` pane
 
@@ -149,3 +139,46 @@ botskills connect --botName "<YOUR_VA_NAME>" --localManifest "<YOUR_LOCAL_MANIFE
 ```
 
 So, to avoid this, it's highly recommended to use `PowerShell 6` to execute the CLI tool commands. Also, you can remove the trailing backslash of the argument.
+
+## Skill dialog telemetry is not showing up in the Power BI dashboard
+In the Bot Builder SDK version 4.5.3 and below, there is a bug which causes the Activity ID and Conversation ID to be null on all telemetry logged over a web socket connection. This causes the Skill dialog telemetry to not populate properly in the [Conversational AI Power BI sample](https://aka.ms/botPowerBiTemplate). To resolve this issue, follow these steps:
+
+1. Update to the latest Microsoft.Bot.Builder packages
+    1. Add the following package source to your project: **https://botbuilder.myget.org/F/botbuilder-v4-dotnet-daily/api/v3/index.json**
+    1. Update all Microsoft.Bot.Builder packages to version **4.6.0-preview-191005-1** and above
+1. Add the following code to **Startup.cs**:
+    ```
+        // Configure telemetry
+        services.AddApplicationInsightsTelemetry();
+        services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();
+        services.AddSingleton<ITelemetryInitializer, OperationCorrelationTelemetryInitializer>();
+        services.AddSingleton<ITelemetryInitializer, TelemetryBotIdInitializer>();
+        services.AddSingleton<TelemetryInitializerMiddleware>();
+        services.AddSingleton<TelemetryLoggerMiddleware>();
+    ```
+1. Update your **DefaultAdapter.cs** and **DefaultWebsocketAdapter.cs** with the following:
+    ```
+      public DefaultAdapter(
+            BotSettings settings,
+            TemplateEngine templateEngine,
+            ConversationState conversationState,
+            ICredentialProvider credentialProvider,
+            TelemetryInitializerMiddleware telemetryMiddleware,
+            IBotTelemetryClient telemetryClient)
+            : base(credentialProvider)
+        {
+            ...
+            Use(telemetryMiddleware);
+            // Uncomment the following line for local development without Azure Storage
+            // Use(new TranscriptLoggerMiddleware(new MemoryTranscriptStore()));
+            Use(new TranscriptLoggerMiddleware(new AzureBlobTranscriptStore(settings.BlobStorage.ConnectionString, settings.BlobStorage.Container)));
+            Use(new ShowTypingMiddleware());
+            Use(new FeedbackMiddleware(conversationState, telemetryClient));
+            Use(new SetLocaleMiddleware(settings.DefaultLocale ?? "en-us"));
+            Use(new EventDebuggerMiddleware());
+        }
+    ```
+
+For more information, refer to the following resources:
+- [Bot Builder SDK issue](https://github.com/microsoft/botbuilder-dotnet/issues/2474)
+- [Bot Builder SDK pull request](https://github.com/microsoft/botbuilder-dotnet/pull/2580)