Release 'live' 09-05-2019 (#1713)

articles/bot-service-channel-connect-facebook.md

@@ -126,14 +126,31 @@ Ensure that the Facebook Page associated with this bot is published. Status appe
 
 ## Connect a bot to Facebook Workplace
 
+Facebook Workplace is a business-oriented version of Facebook, which allows employees to easily connect and collaborate. It contains live videos, news feeds, groups, messenger, reactions, search, and trending posts. It also supports:
+
+- Analytics and integrations. A dashboard with analytics, integration, single sign-on, and identity providers that companies use to integrate Workplace with their existing IT systems.
+- Multi-company groups. Shared spaces in which employees from different organizations can work together and collaborate.
+
 See the [Workplace Help Center](https://workplace.facebook.com/help/work/) to learn more about Facebook Workplace and [Workplace Developer Documentation](https://developers.facebook.com/docs/workplace) for guidelines about developing for Facebook Workplace.
 
-To configure a bot to communicate using Facebook Workplace, create a custom integration and connect the bot to it.
+To use Facebook Workplace with your bot, you must create a Workplace account and a custom integration to connect the bot.
+
+### Create a Workplace Premium account
 
+1. Submit an application to [workplace](https://www.facebook.com/workplace) on  behalf of your company.
+1. Once your application has been approved, you will receive an email inviting you to join. The response may take a while.
+1. From the e-mail invitation, click **Get Started**.
+1. Enter your profile information.
+    > [!TIP]
+    > Set yourself as the system administrator. Remember that only system administrators can create custom integrations.
+1. Click **Preview Profile** and verify the information is correct.
+1. Access *Free Trial*.
+1. Create **password**.
+1. Click **Invite Coworkers** to invite employees to sign-in. The employees you invited will become members as soon as they sign. They will go through a similar sign-in process as described in these steps.
 
-1. Create a Facebook Workplace Premium account. Follow the instructions [here](https://www.facebook.com/workplace) to create a Facebook Workplace Premium account and set yourself as the system administrator. Please keep in mind that only system administrator of a Workplace can create custom integrations.
+### Create a custom integration
 
-1. Create a [custom integration](https://developers.facebook.com/docs/workplace/custom-integrations-new) for your Workplace following the steps described next. When you create a custom integration, an app with defined permissions and a page of type 'Bot' only visible within your Workplace community are created.
+Create a [custom integration](https://developers.facebook.com/docs/workplace/custom-integrations-new) for your Workplace following the steps described below. When you create a custom integration, an app with defined permissions and a page of type 'Bot' only visible within your Workplace community are created.
 
 1. In the **Admin Panel**, open the **Integrations** tab.
 1. Click on the **Create your own custom App** button.

articles/bot-service-channel-connect-telegram.md

@@ -47,9 +47,17 @@ Copy the Telegram bot's access token.
 
 ## Enter the Telegram bot's access token
 
-Paste the token you copied previously into the **Access Token** field and click **Submit**.
+Go to your bot's **Channels** section in the Azure portal and click the **Telegram** button. 
 
-## Enable the bot
-Check **Enable this bot on Telegram**. Then click **I'm done configuring Telegram**.
+> [!NOTE]
+>  The Azure portal UI will look slightly different if you have already connected your bot to Telegram. 
 
-When you have completed these steps, your bot will be successfully configured to communicate with users in Telegram.
+![Select Telegram in channels](~/media/channels/tg-connectBot-Azure.png)
+
+Paste the token you copied previously into the **Access Token** field and click **Save**.
+
+![Telegram access token](~/media/channels/tg-accessToken-Azure.png)
+
+Your bot is now successfully configured to communicate with users in Telegram. 
+
+![Telegram bot enabled](~/media/channels/tg-botEnabled-Azure.png)

articles/includes/deploy/snippet-ARM-existing-resource-group.md

@@ -0,0 +1,28 @@
+When using an existing resource group, you can either use an existing App Service Plan or create a new one. Steps for both options are listed below. 
+
+**Option 1: Existing App Service Plan** 
+
+In this case, we are using an existing App Service Plan, but creating new a Web App and Bot Channels Registration. 
+
+> [!NOTE]
+> This command sets the bot's ID and display name. The `botId` parameter should be globally unique and is used as the immutable bot ID. The bot's display name is mutable.
+
+```cmd
+az group deployment create --name "<name-of-deployment>" --resource-group "<name-of-resource-group>" --template-file "template-with-preexisting-rg.json" --parameters appId="<msa-app-guid>" appSecret="<msa-app-password>" botId="<id-or-name-of-bot>" newWebAppName="<name-of-web-app>" existingAppServicePlan="<name-of-app-service-plan>" appServicePlanLocation="<location>"
+```
+
+**Option 2: New App Service Plan**
+
+In this case, we are creating App Service Plan, Web App, and Bot Channels Registration. 
+
+```cmd
+az group deployment create --name "<name-of-deployment>" --resource-group "<name-of-resource-group>" --template-file "template-with-preexisting-rg.json" --parameters appId="<msa-app-guid>" appSecret="<msa-app-password>" botId="<id-or-name-of-bot>" newWebAppName="<name-of-web-app>" newAppServicePlanName="<name-of-app-service-plan>" appServicePlanLocation="<location>"
+```
+
+| Option   | Description |
+|:---------|:------------|
+| name | Friendly name for the deployment. |
+| resource-group | Name of the azure resource group. |
+| template-file | The path to the ARM template. You can use `template-with-preexisting-rg.json` file provided in the `deploymentTemplates` folder of the project. |
+| location |Location. Values from: `az account list-locations`. You can configure the default location using `az configure --defaults location=<location>`. |
+| parameters | Provide deployment parameter values. `appId` value you got from running the `az ad app create` command. `appSecret` is the password you provided in the previous step. The `botId` parameter should be globally unique and is used as the immutable bot ID. It is also used to configure the display name of the bot, which is mutable. `newWebAppName` is the name of the Web App you are creating. `newAppServicePlanName` is the name of App Service Plan. `newAppServicePlanLocation` is the location of the App Service Plan. |

articles/includes/deploy/snippet-ARM-new-resource-group.md

@@ -0,0 +1,12 @@
+You'll create a new resource group in Azure and then use the ARM template to create the resources specified in it. In this case, we are providing App Service Plan, Web App, and Bot Channels Registration.
+
+```cmd
+az deployment create --name "<name-of-deployment>" --template-file "template-with-new-rg.json" --location "location-name" --parameters appId="<msa-app-guid>" appSecret="<msa-app-password>" botId="<id-or-name-of-bot>" botSku=F0 newAppServicePlanName="<name-of-app-service-plan>" newWebAppName="<name-of-web-app>" groupName="<new-group-name>" groupLocation="<location>" newAppServicePlanLocation="<location>"
+```
+
+| Option   | Description |
+|:---------|:------------|
+| name | Friendly name for the deployment. |
+| template-file | The path to the ARM template. You can use the `template-with-new-rg.json` file provided in the `deploymentTemplates` folder of the project. |
+| location |Location. Values from: `az account list-locations`. You can configure the default location using `az configure --defaults location=<location>`. |
+| parameters | Provide deployment parameter values. `appId` value you got from running the `az ad app create` command. `appSecret` is the password you provided in the previous step. The `botId` parameter should be globally unique and is used as the immutable bot ID. It is also used to configure the display name of the bot, which is mutable. `botSku` is the pricing tier and can be F0 (Free) or S1 (Standard). `newAppServicePlanName` is the name of App Service Plan. `newWebAppName` is the name of the Web App you are creating. `groupName` is the name of the Azure resource group you are creating. `groupLocation` is the location of the Azure resource group. `newAppServicePlanLocation` is the location of the App Service Plan. |

articles/includes/deploy/snippet-IIS-Kudu-files.md

@@ -0,0 +1,32 @@
+You need to prepare your project files before you can deploy your bot. 
+<!-- **C# bots** -->
+##### [C#](#tab/csharp)
+
+```cmd
+az bot prepare-deploy --lang Csharp --code-dir "." --proj-file-path "MyBot.csproj"
+```
+
+You must provide the path to the .csproj file relative to --code-dir. This can be performed via the --proj-file-path argument. The command would resolve --code-dir and --proj-file-path to "./MyBot.csproj"
+
+<!-- **JavaScript bots** -->
+##### [JavaScript](#tab/javascript)
+
+```cmd
+az bot prepare-deploy --code-dir "." --lang Javascript
+```
+
+This command will fetch a web.config which is needed for Node.js apps to work with IIS on Azure App Services. Make sure web.config is saved to the root of your bot.
+
+<!-- **TypeScript bots** -->
+##### [TypeScript](#tab/typescript)
+
+```cmd
+az bot prepare-deploy --code-dir "." --lang Typescript
+```
+
+This command works similarly to JavaScript above, but for a Typescript bot.
+
+---
+
+> [!NOTE]
+> The `az bot prepare-depoloy` command should generate a `.deployment` file in your bot project folder.

articles/includes/deploy/snippet-az-login.md

@@ -1,23 +1,9 @@
-Open a command prompt to log in to the Azure portal.
+Once you've created and tested a bot locally, you can deploy it to Azure. Open a command prompt to log in to the Azure portal.
 
 ```cmd
 az login
 ```
-
 A browser window will open, allowing you to sign in.
 
-### Set the subscription
-
-Set the default subscription to use.
-
-```cmd
-az account set --subscription "<azure-subscription>"
-```
-
-If you are not sure which subscription to use for deploying the bot, you can view the list of `subscriptions` for your account by using `az account list` command.
-
-Navigate to the bot folder.
-
-```cmd
-cd <local-bot-folder>
-```
+> [!NOTE]
+> If you deploy your bot to a non-Azure cloud such as US Gov, you need to run `az cloud set --name <name-of-cloud>` before `az login`, where &lt;name-of-cloud> is the name of a registered cloud, such as `AzureUSGovernment`. If you want to go back to public cloud, you can run `az cloud set --name AzureCloud`. 

articles/includes/deploy/snippet-az-set-subscription.md

@@ -0,0 +1,7 @@
+Set the default subscription to use.
+
+```cmd
+az account set --subscription "<azure-subscription>"
+```
+
+If you are not sure which subscription to use for deploying the bot, you can view the list of subscriptions for your account by using `az account list` command. 

articles/includes/deploy/snippet-create-app-registration.md

@@ -0,0 +1,19 @@
+Registering the application means that you can use Azure AD to authenticate users and request access to user resources. Your bot requires a Registered app in Azure that provides the bot access to the Bot Framework Service for sending and receiving authenticated messages. To create register an app via the Azure CLI, perform the following command:
+
+```cmd
+az ad app create --display-name "displayName" --password "AtLeastSixteenCharacters_0" --available-to-other-tenants
+```
+
+| Option   | Description |
+|:---------|:------------|
+| display-name | The display name of the application. |
+| password | App password, aka 'client secret'. The password must be at least 16 characters long, contain at least 1 upper or lower case alphabetical character, and contain at least 1 special character.|
+| available-to-other-tenants| Indicates whether the application can be used from any Azure AD tenant. Set to `true` to enable your bot to work with the Azure Bot Service channels.|
+
+The above command outputs JSON with the key `appId`, save the value of this key for the ARM deployment, where it will be used for the `appId` parameter. The password provided will be used for the `appSecret` parameter.
+
+> [!NOTE] 
+> If you would like to use an existing App registration you can use the command:
+> ``` cmd
+> az bot create --kind webapp --resource-group "<name-of-resource-group>" --name "<name-of-web-app>" --appid "<existing-app-id>" --password "<existing-app-password>" --lang <Javascript|Csharp>
+> ```

articles/includes/deploy/snippet-deploy-code-to-az.md

@@ -0,0 +1,11 @@
+At this point we are ready to deploy the code to the Azure Web App. Run the following command from the command line to perform deployment using the kudu zip push deployment for a web app.
+
+```cmd
+az webapp deployment source config-zip --resource-group "<resource-group-name>" --name "<name-of-web-app>" --src "code.zip" 
+```
+
+| Option   | Description |
+|:---------|:------------|
+| resource-group | The name of the Azure resource group that contains your bot. (This will be the resource group you used or created when creating the app registration for your bot.) |
+| name | Name of the Web App you used earlier. |
+| src  | The path to the zipped file you created. |

articles/includes/deploy/snippet-prepare-deploy-intro.md

@@ -0,0 +1,4 @@
+When you create a bot using the [Visual Studio template](https://docs.microsoft.com/azure/bot-service/dotnet/bot-builder-dotnet-sdk-quickstart?view=azure-bot-service-4.0) or [Yeoman template](https://docs.microsoft.com/azure/bot-service/javascript/bot-builder-javascript-quickstart?view=azure-bot-service-4.0), the source code generated includes a `deploymentTemplates` folder that contains ARM templates. The deployment process documented here uses one of the ARM templates to provision required resources for the bot in Azure by using the Azure CLI. 
+
+> [!NOTE]
+> With the release of Bot Framework SDK 4.3, we have _deprecated_ the use of a .bot file. Instead, we use an appsettings.json or .env file to manage bot resources. For information on migrating settings from the .bot file to appsettings.json or .env file, see [managing bot resources](https://docs.microsoft.com/azure/bot-service/bot-file-basics?view=azure-bot-service-4.0).

articles/includes/deploy/snippet-prerequisite.md

@@ -1,4 +1,9 @@
-- If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/) before you begin.
+- A subscription to [Microsoft Azure](https://azure.microsoft.com/free/)
+- A C#, JavaScript, or TypeScript bot that you have developed on your local machine
+- Latest version of the [Azure CLI](https://docs.microsoft.com/cli/azure/?view=azure-cli-latest)
+- Familiarity with [Azure CLI and ARM templates](https://docs.microsoft.com/azure/azure-resource-manager/resource-group-overview)
+
+<!-- - If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/) before you begin.
 - Install the latest version of the [Azure cli tool](https://docs.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest).
 - Install latest version of the [MSBot](https://github.com/Microsoft/botbuilder-tools/tree/master/packages/MSBot) tool.
 - Install latest released version of the [Bot Framework Emulator](https://aka.ms/Emulator-wiki-getting-started).
@@ -9,4 +14,4 @@ With msbot 4.3.2 and later, you need Azure CLI version 2.0.54 or later. If you i
 
 ```cmd
 az extension remove --name botservice
-```
+``` -->

articles/includes/deploy/snippet-test-in-web-chat.md

@@ -0,0 +1,9 @@
+1. In your browser, navigate to the [Azure portal](https://ms.portal.azure.com).
+2. In the left panel, click **Resource groups**.
+3. In the right panel, search for your group.
+4. Click on your group name.
+5. Click the link of your Bot Channel Registration.
+6. In the **Bot Channel Registration** panel, click **Test in Web Chat**.
+Alternatively, in the right panel, click the **Test** box.
+
+For more information about channel registration, see [Register a bot with Bot Service](https://docs.microsoft.com/azure/bot-service/bot-service-quickstart-registration?view=azure-bot-service-3.0).

articles/includes/deploy/snippet-zip-code.md

@@ -0,0 +1,14 @@
+When using the non-configured [zip deploy API](https://github.com/projectkudu/kudu/wiki/Deploying-from-a-zip-file-or-url) to deploy your bot's code, Web App/Kudu's behavior is as follows:
+
+_Kudu assumes by default that deployments from zip files are ready to run and do not require additional build steps during deployment, such as npm install or dotnet restore/dotnet publish._
+
+As such, it is important to include your built code and with all necessary dependencies in the zip file being deployed to the Web App, otherwise your bot will not work as intended.
+
+> [!IMPORTANT]
+> Before zipping your project files, make sure that you are _in_ the project folder. 
+> - For C# bots, it is the folder that has the .csproj file. 
+> - For JS bots, it is the folder that has the app.js or index.js file. 
+>
+>**Within** the project folder, select all the files and zip them up, then run the command while still in the folder. 
+>
+> If your root folder location is incorrect, the **bot will fail to run in the Azure portal**.