Various docs issues (#2310)

* Updated all skill READMEs with appropriate aka.ms links to documentation * #2288 Add User.Read reference * #2274 - Rephrased step to get the LUIS Authoring Key * #2309 Add formatting/additional details to each experimental skill regarding configuration and incoming/outgoing events * Fix typo * Add note to escape special characters per 2332
microsoft · Sep 10, 2019 · 6d44f8f · 6d44f8f
1 parent cadc709
commit 6d44f8f
Show file tree

Hide file tree

Showing 20 changed files with 152 additions and 73 deletions.
diff --git a/docs/_docs/reference/skills/experimental.md b/docs/_docs/reference/skills/experimental.md
@@ -17,40 +17,29 @@ order: 12
 
 ## Overview
 
-[Experimental Skills](https://aka.ms/bfexperimentalskills) are early prototypes of Skills to help bring skill concepts to life for demonstrations and proof-of-concepts along with providing different examples to get you started.
+These experimental Bot Framework Skills are early prototypes to help bring skill concepts to life for demonstrations and proof-of-concepts along with providing different examples to get you started.
 
 These skills by their very nature are not complete, will likely have rudimentary language models, limited language support and limited testing hence are located in a experimental folder to ensure this is understood before you make use of them.
 
-## Restaurant Booking Skill
+### Skill Deployment
 
-The [Restaurant Booking skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/restaurantbooking) provides a simple restaurant booking experience guiding the user through booking a table and leverages Adaptive Cards throughout to demonstrate how Speech, Text and UX can be combined for a compelling user experience. No integration to restaurant booking services exists at this time so is simulated with static data for testing purposes.
-
-![Restaurant Example]({{site.baseurl}}/assets/images/skills-restaurant-transcript.png)
-
-## News Skill
-
-The [News skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/newsskill) provides a simple Skill that integrates with the Bing News Cognitive Service to demonstrate how a news experience can be integrated into a Virtual Assistant.
-
-Once deployed create a [Bing News Cognitive Services Key](https://azure.microsoft.com/en-us/services/cognitive-services/bing-news-search-api/) and update the appropriate configuration within appSettings.config.
-
-This skill supports the following scenarios:
-- Find articles: *Find me news about sports*
-- Trending articles: *What news is trending now?*
-- Show favorite topic: *Find news for me*
-
-![News Example]({{site.baseurl}}/assets/images/skills-news-transcript.png)
+The Experimental Skills require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
 
-## Weather Skill
+- Azure Web App
+- Azure Storage Account (Transcripts)
+- Azure Application Insights (Telemetry)
+- Azure CosmosDb (State)
+- Azure Cognitive Services - Language Understanding
 
-The [Weather skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/weatherskill) provides a basic Skill that integrates with [AccuWeather](https://developer.accuweather.com) to demonstrate how a weather experience can be integrated into a Virtual Assistant. Provide an API key from [AccuWeather Getting Started](https://developer.accuweather.com/getting-started) in the appsettings to configure the skill.
+> Review the pricing and terms for the services and adjust to suit your scenario.
 
-## Music Skill
+**To deploy the experimental skills using the default configuration, follow the steps in this common [deployment documentation page]({{site.baseurl}}/tutorials/csharp/create-assistant/4_provision_your_azure_resources) from the folder where your have cloned the GitHub repo.**
 
-The [Music skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/musicskill) integrates with [Spotify](https://developer.spotify.com/documentation/web-api/libraries/) to look up playlists and artists and open via the Spotify app. Provide credentials after you [create a Spotify client](https://developer.spotify.com/dashboard/) in the appsettings to configure the skill.
+## Skills
 
-## Bing Search Skill
+### Bing Search Skill
 
-The [Bing Search Skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/bingsearchskill) provides a simple Skill that integrates with the [Bing Search cognitive service](https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/).
+The [Bing Search Skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/bingsearchskill) provides a simple Skill that integrates with the [Bing Search Cognitive Service](https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/).
 
 This skill has a very limited LUIS model (available in English, French, Italian, German, Spanish and Chinese) and demonstates three simple scenarios:
 
@@ -60,17 +49,35 @@ This skill has a very limited LUIS model (available in English, French, Italian,
 
 ![Search Example]({{site.baseurl}}/assets/images/skills-experimental-bingsearch.png)
 
-Once deployed create a [Bing Search Cognitive Services Key](https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/) for BingSearchKey and a [Project Answer Search Key](https://labs.cognitive.microsoft.com/en-us/project-answer-search) for BingAnswerSearchKey, then update the appropriate configuration within appSettings.config.
+#### Configuration
+
+1. Get your own [Bing Search Cognitive Services Key](https://azure.microsoft.com/en-us/services/cognitive-services/bing-web-search-api/).
+1. Get your own [Project Answer Search Key](https://labs.cognitive.microsoft.com/en-us/project-answer-search).
+1. Provide these values in your `appsettings.json` file.
 
-## Event Skill
+```
+  "BingSearchKey": "{YOUR_BING_SEARCH_COGNITIVE_SERVICES_KEY}",
+  "BingAnswerSearchKey": "{YOUR_PROJECT_ANSWER_SEARCH_KEY}"
+```
 
-The [Event Skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/eventskill) provides a simple skill that integrates with [Eventbrite](https://www.eventbrite.com/platform/) to show information about events happening in the specified area. Provide an API key from the [Eventbrite API Keys](https://www.eventbrite.com/platform/api-keys) page in the appsettings to configure the skill.
+### Event Skill
+
+The [Event Skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/eventskill) provides a simple skill that integrates with [Eventbrite](https://www.eventbrite.com/platform/) to show information about events happening in the specified area.
 
 This skill currently supports one scenario to get local event information.
 
 ![Event Example]({{site.baseurl}}/assets/images/skills-event-transcript.png)
 
-## Hospitality Skill
+#### Configuration
+
+1. Get your own [Eventbrite API Key](https://www.eventbrite.com/platform/api-keys).
+1. Provide this value in your `appsettings.json` file.
+
+```
+  "eventbriteKey":  "YOUR_EVENTBRITE_API_KEY"
+```
+
+### Hospitality Skill
 
 The [Hospitality Skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/hospitalityskill) demonstrates experiences that would be useful in a hospitality specific scenario, such as being able to check out of a hotel, ordering room service, and requesting hotel amenities. This skill does not integrate a hotel service at this time, and is instead simulated with static data for testing purposes.
 
@@ -82,48 +89,109 @@ This skill demonstrates the following scenarios:
 - Room service: *I want to see a room service menu*
 - Check out: *Can I check out now?*
 
-The [Hospitality Sample VA]({{site.baseurl}}/reference/virtual-assistant/hospitalitysample) leverages this skill and a number of other skills to demonstrate a more in-depth hospitality experience.
-
 ![Hospitality Example]({{site.baseurl}}/assets/images/skills-hospitality-transcript.png)
 
-## IT Service Management Skill
+The [Hospitality Sample VA]({{site.baseurl}}/reference/samples/hospitalitysample) demonstrates this skill and a number of other skills to demonstrate a more in-depth hospitality experience.
+
+### IT Service Management Skill
 
 The [IT Service Management skill](https://github.com/microsoft/AI/tree/next/skills/src/csharp/experimental/itsmskill) provides a basic skill that provides ticket and knowledge base related capabilities and supports SerivceNow.
 
+#### Configuration
+
 To test this skill, one should setup the following:
 
-* Create a ServiceNow instance in [Developers](https://developer.servicenow.com/app.do#!/instance) and update the serviceNowUrl of appsettings.json: `"serviceNowUrl": "https://YOUR_INSTANCE_NAME.service-now.com"`
-* Create a [scripted REST API](https://docs.servicenow.com/bundle/geneva-servicenow-platform/page/integrate/custom_web_services/task/t_CreateAScriptedRESTService.html) to get current user's sys_id and please raise an issue if simpler way is found
+1. Create a ServiceNow instance in the [ServiceNow Developer Site](https://developer.servicenow.com/app.do#!/instance).
+1. Provide this value in your `appsettings.json` file.
+`"serviceNowUrl": "{YOUR_SERVICENOW_INSTANCE_URL}`
+1. Create a [scripted REST API](https://docs.servicenow.com/bundle/geneva-servicenow-platform/page/integrate/custom_web_services/task/t_CreateAScriptedRESTService.html) to get current user's sys_id and please raise an issue if simpler way is found
     - In System Web Services/Scripted REST APIs, click New to create an API
     - In API's Resources, click New to add a resource
     - In the resource, select GET for HTTP method and input `(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) { return gs.getUserID(); })(request, response);` in Script
     - Update the serviceNowGetUserId of appsetting.json: `"serviceNowGetUserId": "YOUR_API_NAMESPACE/YOUR_API_ID"`
-* Set up endpoint by [this document](https://docs.servicenow.com/bundle/london-platform-administration/page/administer/security/task/t_CreateEndpointforExternalClients.html#t_CreateEndpointforExternalClients) for Client id and Client secret to be used in the following OAuth Connection
+1. Set up endpoint by [this document](https://docs.servicenow.com/bundle/london-platform-administration/page/administer/security/task/t_CreateEndpointforExternalClients.html#t_CreateEndpointforExternalClients) for Client id and Client secret to be used in the following OAuth Connection
     - Redirect URL is https://token.botframework.com/.auth/web/redirect
-* Add an OAuth Connection in the Settings of Web App Bot named 'ServiceNow' with Service Provider 'Generic Oauth 2'
+1. Add an OAuth Connection in the Settings of Web App Bot named 'ServiceNow' with Service Provider 'Generic Oauth 2'
     - Authorization URL as https://instance.service-now.com/oauth_auth.do
     - Token URL, Refresh URL as https://instance.service-now.com/oauth_token.do
     - No Scopes are needed
     - Click Test Connection to verify
 
 To test this skill in VA, one should setup the following:
 
-* Add https://botbuilder.myget.org/F/aitemplates/api/v3/index.json as NuGet package source
-* Update VA's Microsoft.Bot.Builder.Solutions and Microsoft.Bot.Builder.Skills to 4.6.0-daily27 as this skill
-* Add VA's appId to AppsWhitelist of SimpleWhitelistAuthenticationProvider under Utilities
-* Add OAuth Connection as skill
-* The remaining steps are same as normal skills
+1. Add https://botbuilder.myget.org/F/aitemplates/api/v3/index.json as NuGet package source
+1. Update VA's Microsoft.Bot.Builder.Solutions and Microsoft.Bot.Builder.Skills to 4.6.0-daily27 as this skill
+1. Add VA's appId to AppsWhitelist of SimpleWhitelistAuthenticationProvider under Utilities
+1. Add OAuth Connection as skill
+1. The remaining steps are same as normal skills
 
-## Experimental Skill Deployment
+### Music Skill
 
-The Experimental Skills require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
+The [Music skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/musicskill) integrates with [Spotify](https://developer.spotify.com/documentation/web-api/libraries/) to look up playlists and artists and open the Spotify app via URI.
+This is dependent on the [SpotifyAPI-NET](https://github.com/JohnnyCrazy/SpotifyAPI-NET) wrapper for the Spotify Web API.
 
-- Azure Web App
-- Azure Storage Account (Transcripts)
-- Azure Application Insights (Telemetry)
-- Azure CosmosDb (State)
-- Azure Cognitive Services - Language Understanding
+#### Configuration
 
-> Review the pricing and terms for the services and adjust to suit your scenario.
+1. Get your own client id and secret when you [create a Spotify client](https://developer.spotify.com/dashboard/).
+1. Provide these values in your `appsettings.json` file.
 
-**To deploy the experimental skills using the default configuration, follow the steps in this common [deployment documentation page]({{site.baseurl}}/tutorials/csharp/create-assistant/4_provision_your_azure_resources) from the folder where your have cloned the GitHub repo.**
+```
+  "spotifyClientId": "{YOUR_SPOTIFY_CLIENT_ID}",
+  "spotifyClientSecret": "{YOUR_SPOTIFY_CLIENT_SECRET}"
+```
+
+#### Event Activity integration
+
+This Skill supports an outgoing `OpenDefaultApp` Event Activity that provides a Spotify URI for chat clients to open on their own.
+
+```
+{ 
+   "type":"event",
+   "name":"OpenDefaultApp",
+   "value":{ 
+      "MusicUri":"{SPOTIFY_URI}"
+   }
+}
+```
+
+
+### News Skill
+
+The [News skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/newsskill) provides a simple Skill that integrates with the Bing News Cognitive Service to demonstrate how a news experience can be integrated into a Virtual Assistant.
+
+Once deployed create a [Bing News Cognitive Services Key](https://azure.microsoft.com/en-us/services/cognitive-services/bing-news-search-api/) and update the appropriate configuration within appSettings.config.
+
+This skill supports the following scenarios:
+- Find articles: *Find me news about sports*
+- Trending articles: *What news is trending now?*
+- Show favorite topic: *Find news for me*
+
+![News Example]({{site.baseurl}}/assets/images/skills-news-transcript.png)
+
+#### Configuration
+
+1. Get your own [Bing News Cognitive Services Key](https://azure.microsoft.com/en-us/services/cognitive-services/bing-news-search-api/)
+1. Provide this value in your `appsettings.json` file.
+
+```
+  "BingNewsKey": "{YOUR_BING_NEWS_COGNITIVE_SERVICES_KEY}"
+```
+
+### Restaurant Booking Skill
+
+The [Restaurant Booking skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/restaurantbooking) provides a simple restaurant booking experience guiding the user through booking a table and leverages Adaptive Cards throughout to demonstrate how Speech, Text and UX can be combined for a compelling user experience. No integration to restaurant booking services exists at this time so is simulated with static data for testing purposes.
+
+![Restaurant Example]({{site.baseurl}}/assets/images/skills-restaurant-transcript.png)
+
+### Weather Skill
+
+The [Weather skill]({{site.repo}}/tree/master/skills/src/csharp/experimental/weatherskill) provides a basic Skill that integrates with [AccuWeather](https://developer.accuweather.com) to demonstrate how a weather experience can be integrated into a Virtual Assistant.
+
+#### Configuration
+
+1. Get your own API Key when by following the instructions on [AccuWeather Getting Started](https://developer.accuweather.com/getting-started).
+1. Provide this value in your `appsettings.json` file.
+
+```
+  "WeatherApiKey": "{YOUR_ACCUWEATHER_API_KEY}"
+```
diff --git a/docs/_docs/reference/skills/productivity-todo.md b/docs/_docs/reference/skills/productivity-todo.md
@@ -61,7 +61,8 @@ To deploy your services using the default configuration, follow the steps in thi
 ### Authentication Connection Settings
 
 If you plan to use the skill as part of a Virtual Assistant the process of registering a skill with your Virtual Assistant will create the supporting authentication connection information automatically for your Virtual Assistant. This skill uses the following authentication scopes which are registered automatically:
-- `Notes.ReadWrite` 
+- `Notes.ReadWrite`
+- `User.Read`
 - `User.ReadBasic.All`
 - `Tasks.ReadWrite`
 

diff --git a/docs/_docs/tutorials/csharp/create-assistant/1_intro.md b/docs/_docs/tutorials/csharp/create-assistant/1_intro.md
@@ -17,8 +17,8 @@ Install Bot Framework development prerequisites and create your first Virtual As
 - Azure Subscription
 - LUIS Authoring Key
     - Review the [LUIS regions](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-reference-regions) documentation page for the correct LUIS portal for the region you plan to deploy to. Note that www.luis.ai refers to the US region and an authoring key retrieved from this portal will not work within a Europe deployment.
-    - Once signed in replace your name in the top right hand corner.
-    - Choose Settings and make a note of the Authoring Key for the next step.
+    - Once signed in, select your initials in the uppermost righthand corner of the page to view the profile menu.
+    - Select Settings and make a note of the Authoring Key for the next step.
 
 ### Time To Complete
 20 minutes

diff --git a/docs/_docs/tutorials/csharp/create-assistant/5_run_your_assistant.md b/docs/_docs/tutorials/csharp/create-assistant/5_run_your_assistant.md
@@ -25,6 +25,8 @@ When deployment is complete, you can run your Virtual Assistant debugging throug
 
 4. Populate the fields in the **Open a Bot** modal with your bot's configuration settings. Provide the endpoint of your running bot, e.g: `http://localhost:3978/api/messages`. Provide the AppId and Secret values. Find these in your `appsettings.json` file, under the `microsoftAppId` and `microsoftAppPassword` configuration settings.
 
+> **Note**: If you password has any JSON reserved characters (backslash, quote, etc.), they must be properly escaped to connect to your bot.
+
     ![]({{site.baseurl}}/assets/images/quickstart-virtualassistant-openbotmodal.png)
 
 5. Congratulations, you've built and run your first Virtual Assistant!

diff --git a/docs/_docs/tutorials/typescript/create-assistant/1_intro.md b/docs/_docs/tutorials/typescript/create-assistant/1_intro.md
@@ -20,8 +20,8 @@ Install Bot Framework development prerequisites and create your first Virtual As
 
 * Retrieve your LUIS Authoring Key
   - Review the [LUIS regions](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-reference-regions) documentation page for the correct LUIS portal for the region you plan to deploy to. Note that www.luis.ai refers to the US region and an authoring key retrieved from this portal will not work within a Europe deployment. 
-  - Once signed in, click on your name in the top right hand corner.
-  - Choose Settings and make a note of the Authoring Key for the next step.
+  - Once signed in, select your initials in the uppermost righthand corner of the page to view the profile menu.
+  - Select Settings and make a note of the Authoring Key for the next step.
 
 ### Time to Complete
 

diff --git a/docs/_docs/tutorials/typescript/create-assistant/5_run_your_assistant.md b/docs/_docs/tutorials/typescript/create-assistant/5_run_your_assistant.md
@@ -20,6 +20,8 @@ When deployment is complete, you can run your Virtual Assistant through the foll
 
 4. Populate the fields in the **Open a Bot** modal with your bot's configuration settings. Provide the endpoint of your running bot, e.g: `http://localhost:3978/api/messages`. Provide the AppId and Secret values. Find these in your `appsettings.json` file, under the `microsoftAppId` and `microsoftAppPassword` configuration settings.
 
+> **Note**: If you password has any JSON reserved characters (backslash, quote, etc.), they must be properly escaped to connect to your bot.
+
     ![]({{site.baseurl}}/assets/images/quickstart-virtualassistant-openbotmodal.png)
 
 5. Congratulations, you've built and run your first Virtual Assistant!

diff --git a/skills/src/csharp/automotiveskill/automotiveskill/readme.md b/skills/src/csharp/automotiveskill/automotiveskill/readme.md
@@ -1,4 +1,4 @@
 
 # Automotive Skill
 
-See the Automotive Skill [documentation page](https://github.com/microsoft/botframework-solutions/blob/master/docs/reference/skills/automotive.md) for information on how to deploy and test this Skill.
+[Learn more](https://aka.ms/bfautoskill) about how to deploy and test the Automotive Skill.
diff --git a/skills/src/csharp/calendarskill/calendarskill/readme.md b/skills/src/csharp/calendarskill/calendarskill/readme.md
@@ -1,4 +1,4 @@
 
 # Calendar Skill
 
-See the Calendar Skill [documentation page](https://github.com/microsoft/botframework-solutions/blob/master/docs/reference/skills/productivity-calendar.md) for information on how to deploy and test this Skill.
+[Learn more](https://aka.ms/bfcalendarskill) about how to deploy and test the Calendar Skill.
diff --git a/skills/src/csharp/emailskill/emailskill/readme.md b/skills/src/csharp/emailskill/emailskill/readme.md
@@ -1,4 +1,4 @@
 
 # Email Skill
 
-See the Email Skill [documentation page](https://github.com/microsoft/botframework-solutions/blob/master/docs/reference/skills/productivity-email.md) for information on how to deploy and test this Skill.
+[Learn more](https://aka.ms/bfemailskill) about how to deploy and test the Email Skill.
diff --git a/skills/src/csharp/experimental/bingsearchskill/bingsearchskill/readme.md b/skills/src/csharp/experimental/bingsearchskill/bingsearchskill/readme.md
@@ -1,3 +1,3 @@
-# Skill Deployment
+# Bing Search Skill
 
-Please refer to the [Skill Template documentation](http://aka.ms/virtualassistantdocs) for deployment and customization instructions.
+[Learn more](https://aka.ms/bfexperimentalskills) about how to deploy and test the Bing Search Skill.