microsoft · darrenj · May 29, 2019 · May 28, 2019 · May 28, 2019 · May 28, 2019
diff --git a/docs/reference/skills/productivity-calendar.md b/docs/reference/skills/productivity-calendar.md
@@ -9,6 +9,10 @@ The most common scenarios have been implemented in this beta release, with addit
 - [Language Model](#language-model)
 - [Configuration](#configuration)
 
+## Supported Sources
+
+> Office 365 and Outlook.com through the Microsoft Graph is supported along with support for Google accounts.
+
 ## Supported Scenarios
 
 The following scenarios are currently supported by the Skill:
@@ -57,7 +61,7 @@ The following scenarios are currently supported by the Skill:
   - *How long until my next meeting?*
   - *How many days are there until Thanksgiving?*
 
-### Skill Deployment
+## Skill Deployment
 
 The Calendar Skill require the following dependencies for end to end operation which are created through an ARM deployment script which you can modify as required.
 
@@ -73,11 +77,54 @@ The Calendar Skill require the following dependencies for end to end operation w
 
 ### Authentication Connection Settings
 
-Your Authentication Connection and corresponding Application Registration should have the following Scopes added, these will be added automatically as part of Skill configuration where possible.
-
-- `User.Read`
+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:
+- `User.ReadBasic.All`  
 - `Calendars.ReadWrite`
-- `People.Read`
+- `People.Read`    
+- `Contacts.Read`
+
+> Only required if you wish to use the Skill directly and not as part of a Virtual Assistant.
+
+**However**, if you wish to use the Skill directly without using a Virtual Assistant please use the following steps to manually configure Authentication for the Calendar Skill. This is **not** required when using the Skill with a Virtual Assistant.
+
+If you wish to make use of the Calendar, Email and Task Skills you need to configure an Authentication Connection enabling uses of your Assistant to authenticate against services such as Office 365 and securely store a token which can be retrieved by your assistant when a user asks a question such as *"What does my day look like today"* to then use against an API like Microsoft Graph.
+
+The [Add Authentication to your bot](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-authentication?view=azure-bot-service-3.0) section in the Azure Bot Service documentation covers more detail on how to configure Authentication. However in this scenario, the automated deployment step has already created the **Azure AD v2 Application** for your Bot and you instead need to follow these instructions:
+
+- Navigate to the Azure Portal, Click Azure Active Directory and then `App Registrations`
+- Find the Application that's been created for your Bot as part of the deployment. You can search for the application by name or ApplicationID as part of the experience but note that search only works across applications currently shown and the one you need may be on a separate page.
+- Click API permissions on the left-hand navigation
+  - Select Add Permission to show the permissions pane
+  - Select `Microsoft Graph`
+  - Select Delegated Permissions and then add each of the following permissions required for the Productivity Skills:
+    -  `User.ReadBasic.All`  
+    -  `Calendars.ReadWrite`
+    -  `People.Read`    
+    -  `Contacts.Read`
+ -  Click Add Permissions at the bottom to apply the changes.
+
+Next you need to create the Authentication Connection for your Bot. Within the Azure Portal, find the `Web App Bot` resource created when your deployed your Bot and choose `Settings`. 
+
+- Scroll down to the oAuth Connection settings section.
+- Click `Add Setting`
+- Type in the name of your Connection Setting - e.g. `Outlook`
+- Choose `Azure Active Directory v2` from the Service Provider drop-down
+- Open the `appSettings.config` file for your Skill
+    - Copy/Paste the value of `microsoftAppId` into the ClientId setting
+    - Copy/Paste the value of `microsoftAppPassword` into the Client Secret setting
+    - Set Tenant Id to common
+    - Set scopes to `User.ReadBasic.All, Calendars.ReadWrite, People.Read, Contacts.Read`
+
+Finally, open the  `appSettings.config` file for your Calendar Skill and update the connection name to match the one provided in the previous step.
+
+```
+"oauthConnections": [
+    {
+      "name": "Outlook",
+      "provider": "Azure Active Directory v2"
+    }
+  ],
+```
 
 ## Language Model
 
@@ -138,15 +185,3 @@ LUIS models for the Skill are provided in .LU file format as part of the Skill.
 |datetimeV2| Prebuilt entity|
 |number| Prebuilt entity|
 |ordinal| Prebuilt entity|
-
-## Configuration
-
-### Supported Sources
-
-> Office 365 and Outlook.com through the Microsoft Graph is supported along with support for Google accounts.
-
-### Example Skill Manifest
-
-```
-TBC
-```
diff --git a/docs/reference/skills/productivity-email.md b/docs/reference/skills/productivity-email.md
@@ -9,6 +9,10 @@ The most common scenarios have been implemented in this beta release, with addit
 - [Language Model](#language-model)
 - [Configuration](#configuration)
 
+## Supported Sources
+
+> Office 365 and Outlook.com through the Microsoft Graph is supported along with support for Google accounts.
+
 ## Supported Scenarios
 
 The following scenarios are currently supported by the Skill:
@@ -44,6 +48,73 @@ The following scenarios are currently supported by the Skill:
   - *The third search result please*
   - *Open this one*
 
+## Skill Deployment
+
+The Email Skill require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
+
+- Azure Web App
+- Azure Storage Account (Transcripts)
+- Azure Application Insights (Telemetry)
+- Azure CosmosDb (State)
+- Azure Cognitive Services - Language Understanding
+
+> Review the pricing and terms for the services and adjust to suit your scenario.
+
+To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/tutorials/assistantandskilldeploymentsteps.md) from the folder where your have cloned the GitHub repo.
+
+### 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:
+- `User.ReadBasic.All`
+- `Mail.ReadWrite`
+- `Mail.Send`
+- `People.Read`
+- `Contacts.Read`
+
+> Only required if you wish to use the Skill directly and not as part of a Virtual Assistant.
+
+**However**, if you wish to use the Skill directly without using a Virtual Assistant please use the following steps to manually configure Authentication for the Email Skill. This is **not** required when using the Skill with a Virtual Assistant.
+
+If you wish to make use of the Calendar, Email and Task Skills you need to configure an Authentication Connection enabling uses of your Assistant to authenticate against services such as Office 365 and securely store a token which can be retrieved by your assistant when a user asks a question such as *"What does my day look like today"* to then use against an API like Microsoft Graph.
+
+The [Add Authentication to your bot](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-authentication?view=azure-bot-service-3.0) section in the Azure Bot Service documentation covers more detail on how to configure Authentication. However in this scenario, the automated deployment step has already created the **Azure AD v2 Application** for your Bot and you instead need to follow these instructions:
+
+- Navigate to the Azure Portal, Click Azure Active Directory and then `App Registrations`
+- Find the Application that's been created for your Bot as part of the deployment. You can search for the application by name or ApplicationID as part of the experience but note that search only works across applications currently shown and the one you need may be on a separate page.
+- Click API permissions on the left-hand navigation
+  - Select Add Permission to show the permissions pane
+  - Select `Microsoft Graph`
+  - Select Delegated Permissions and then add each of the following permissions required for the Productivity Skills:
+    - `User.ReadBasic.All`
+    - `Mail.ReadWrite`
+    - `Mail.Send`
+    - `People.Read`
+    - `Contacts.Read`
+ -  Click Add Permissions at the bottom to apply the changes.
+
+Next you need to create the Authentication Connection for your Bot. Within the Azure Portal, find the `Web App Bot` resource created when your deployed your Bot and choose `Settings`. 
+
+- Scroll down to the oAuth Connection settings section.
+- Click `Add Setting`
+- Type in the name of your Connection Setting - e.g. `Outlook`
+- Choose `Azure Active Directory v2` from the Service Provider drop-down
+- Open the `appSettings.config` file for your Skill
+    - Copy/Paste the value of `microsoftAppId` into the ClientId setting
+    - Copy/Paste the value of `microsoftAppPassword` into the Client Secret setting
+    - Set Tenant Id to common
+    - Set scopes to `User.ReadBasic.All Mail.ReadWrite Mail.Send People.Read Contacts.Read`
+
+Finally, open the  `appSettings.config` file for your Email Skill and update the connection name to match the one provided in the previous step.
+
+```
+"oauthConnections": [
+    {
+      "name": "Outlook",
+      "provider": "Azure Active Directory v2"
+    }
+  ],
+```
+
 ## Language Model
 
 LUIS models for the Skill are provided in .LU file format as part of the Skill. Further languages are being prioritized.
@@ -96,35 +167,6 @@ LUIS models for the Skill are provided in .LU file format as part of the Skill.
 |number| Prebuilt entity|
 |ordinal| Prebuilt entity|
 
-## Configuration
-
-### Supported Sources
-
-> Office 365 and Outlook.com through the Microsoft Graph is supported along with support for Google accounts.
-
-### Skill Deployment
-
-The Email Skill require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
-
-- Azure Web App
-- Azure Storage Account (Transcripts)
-- Azure Application Insights (Telemetry)
-- Azure CosmosDb (State)
-- Azure Cognitive Services - Language Understanding
-
-> Review the pricing and terms for the services and adjust to suit your scenario.
-
-To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/tutorials/assistantandskilldeploymentsteps.md) from the folder where your have cloned the GitHub repo.
-
-### Authentication Connection Settings
-
-Your Authentication Connection and corresponding Application Registration should have the following Scopes added, these will be added automatically as part of Skill configuration where possible.
-
-- `User.Read`
-- `Mail.Read`
-- `Mail.Send`
-- `People.Read`
-
 ### Example Skill Manifest
 
 ```

diff --git a/docs/reference/skills/productivity-todo.md b/docs/reference/skills/productivity-todo.md
@@ -3,11 +3,9 @@
 The ToDo Skill provides ToDo related capabilities to a Virtual Assistant.
 The most common scenarios have been implemented in this beta release, with additional scenarios in development.
 
-## Table of Contents
+### Supported Sources
 
-- [Supported Scenarios](#supported-scenarios)
-- [Language Model](#language-model)
-- [Configuration](#configuration)
+> Office 365 and Outlook.com through the Microsoft Graph is supported at this time. Additional sources will be coming in a future release.
 
 ## Supported Scenarios
 
@@ -30,6 +28,68 @@ The following scenarios are currently supported by the Skill:
   - *Task completed "reserve a restaurant for anniversary"*
   - *Check off "bananas" on my grocery list*
 
+## Skill Deployment
+
+The ToDo Skill require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
+
+- Azure Web App
+- Azure Storage Account (Transcripts)
+- Azure Application Insights (Telemetry)
+- Azure CosmosDb (State)
+- Azure Cognitive Services - Language Understanding
+
+> Review the pricing and terms for the services and adjust to suit your scenario.
+
+To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/tutorials/assistantandskilldeploymentsteps.md) from the folder where your have cloned the GitHub repo.
+
+### 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` 
+- `User.ReadBasic.All`
+- `Tasks.ReadWrite`
+
+**However**, if you wish to use the Skill directly without using a Virtual Assistant please use the following steps to manually configure Authentication for the ToDo Skill. This is **not** required when using the Skill with a Virtual Assistant.
+
+If you wish to make use of the Calendar, Email and Task Skills you need to configure an Authentication Connection enabling uses of your Assistant to authenticate against services such as Office 365 and securely store a token which can be retrieved by your assistant when a user asks a question such as *"What does my day look like today"* to then use against an API like Microsoft Graph.
+
+The [Add Authentication to your bot](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-authentication?view=azure-bot-service-3.0) section in the Azure Bot Service documentation covers more detail on how to configure Authentication. However in this scenario, the automated deployment step has already created the **Azure AD v2 Application** for your Bot and you instead need to follow these instructions:
+
+- Navigate to the Azure Portal, Click Azure Active Directory and then `App Registrations`
+- Find the Application that's been created for your Bot as part of the deployment. You can search for the application by name or ApplicationID as part of the experience but note that search only works across applications currently shown and the one you need may be on a separate page.
+- Click API permissions on the left-hand navigation
+  - Select Add Permission to show the permissions pane
+  - Select `Microsoft Graph`
+  - Select Delegated Permissions and then add each of the following permissions required for the Productivity Skills:
+    - `Notes.ReadWrite` 
+    - `User.ReadBasic.All`
+    - `Tasks.ReadWrite`
+ -  Click Add Permissions at the bottom to apply the changes.
+
+Next you need to create the Authentication Connection for your Bot. Within the Azure Portal, find the `Web App Bot` resource created when your deployed your Bot and choose `Settings`. 
+
+- Scroll down to the oAuth Connection settings section.
+- Click `Add Setting`
+- Type in the name of your Connection Setting - e.g. `Outlook`
+- Choose `Azure Active Directory v2` from the Service Provider drop-down
+- Open the `appSettings.config` file for your Skill
+    - Copy/Paste the value of `microsoftAppId` into the ClientId setting
+    - Copy/Paste the value of `microsoftAppPassword` into the Client Secret setting
+    - Set Tenant Id to common
+    - Set scopes to `Notes.ReadWrite, User.ReadBasic.All, Tasks.ReadWrite`
+
+Finally, open the  `appSettings.config` file for your ToDo Skill and update the connection name to match the one provided in the previous step.
+
+```
+"oauthConnections": [
+    {
+      "name": "Outlook",
+      "provider": "Azure Active Directory v2"
+    }
+  ],
+```
+
+
 ## Language Model
 
 LUIS models for the Skill are provided in .LU file format as part of the Skill. Further languages are being prioritized.
@@ -65,35 +125,3 @@ LUIS models for the Skill are provided in .LU file format as part of the Skill.
 |TaskContentPattern| Pattern.any |
 |number| Prebuilt entity|
 |ordinal| Prebuilt entity|
-
-## Configuration
-
-### Supported Sources
-
-> Office 365 and Outlook.com through the Microsoft Graph is supported at this time. Additional sources will be coming in a future release.
-
-### Skill Deployment
-
-The ToDo Skill require the following dependencies for end to end operation which are created through an ARM script which you can modify as required.
-
-- Azure Web App
-- Azure Storage Account (Transcripts)
-- Azure Application Insights (Telemetry)
-- Azure CosmosDb (State)
-- Azure Cognitive Services - Language Understanding
-
-> Review the pricing and terms for the services and adjust to suit your scenario.
-
-To deploy your services using the default configuration, follow the steps in this common [deployment documentation page](/docs/tutorials/assistantandskilldeploymentsteps.md) from the folder where your have cloned the GitHub repo.
-
-### Authentication Connection Settings
-
-Your Authentication Connection and corresponding Application Registration should have the following Scopes added, these will be added automatically as part of Skill configuration where possible.
-
-- `Notes.ReadWrite`
-
-### Example Skill Manifest
-
-```
-TBC
-```