Skip to content

Deployment guide

Jump to bottom
Pranav Krishnamurthy edited this page Aug 15, 2019 · 24 revisions

Prerequisites

To begin, you will need:

  • An Azure subscription where you can create the following kinds of resources:
    • An app service
    • An app service plan
    • Bot channels registration
    • Azure storage account
    • Azure search
    • QnAMaker cognitive service
    • Application Insights
    • Valid UPN's list of the individuals who will need access to configuration web app.
  • A copy of the FAQ++ app GitHub repo (https://github.com/OfficeDev/microsoft-teams-faqplusplus-app)

Step 1: Register FAQ++ Configuration Microsoft Azure AD application

Register two Azure AD applications in your tenant's directory: one for the FAQ++ Bot, and another for the configuration app. Prior to having any apps registered, ensure to have a resource group properly created.

  1. Log in to the Azure Portal for your subscription, and go to the "App registrations" blade here.

  2. Click on "New registration" and create an Azure AD application.

    1. Name: The name of your configuration application (i.e. "Configuration App")
    2. Supported account types: Select "Account in this organizational directory only"

    image1

    1. Copy the Client ID and Tenant ID values which will be used in the deployment. It is recommended that you copy these values into a text file, using an application like Notepad. The ClientID is the application ID of the configuration web app. The TenantID is the tenant ID of your Azure subscription.

    image2

    1. Ensure that the for the Configuration Web App, the id_tokens authorization is enabled. To do so, after you have registered the configuration web app through app registrations, navigate to the tab that reads "Authentication" and in the middle pane scroll down to the point where the text reads "To enable the implicit grant flow, select the tokens you would like to be issued by the authorization endpoint:". Click on the check box that reads "ID tokens".

    image3

    1. Repeat steps 1 through 4 to register the bot application. However, there are a few differences that are to be noted here:
      1. The application should be registered to "Accounts in any organizational directory", which means that the bot application supports multiple tenants.
      2. No authorization is required for the bot application (i.e. no need for using the id_tokens)

At this point you have 4 unique values:

  • Application (client) ID for the bot
  • Client secret for the bot
  • Application (client) ID for the configuration
  • Tenant ID, which is the same for both apps

Step 2: Deploy to your Azure subscription

  1. Click on the "Deploy to Azure" button below.

Deploy to Azure

  1. When prompted, log in to your Azure subscription.

  2. Azure will create a "Custom deployment" based on the ARM template and ask you to fill in the template parameters.

  3. Select a subscription and resource group.

    • We recommend creating a new resource group.
    • The resource group location MUST be in a datacenter that supports: Application Insights; Azure Search; and QnA Maker. For an up-to-date list, click here, and select a region where the following services are available:
      • Application Insights
      • QnA Maker
      • Azure Search

  4. Enter a "Base Resource Name", which the template uses to generate names for the other resources.

    • The app service names [Base Resource Name] and [Base Resource Name]-config must be available. For example, if you select contosofaqplusplus as the base name, the names contosofaqplusplus and contosofaqplusplus-config must be free; otherwise, the deployment will fail with a Conflict error.
    • Remember the base resource name that you selected. We will need it later.

  5. Fill in the various IDs in the template:

    1. Bot Client ID: The application (client) ID of the Microsoft Teams Bot app
    2. Bot Client Secret: The client secret of the Microsoft Teams Bot app
    3. Config App Client Id: The application (client) ID of the configuration app
    4. Tenant Id: The tenant ID above

    Make sure that the values are copied as-is, with no extra spaces. The template checks that GUIDs are exactly 36 characters.

  6. Fill in the "Config Admin UPN List", which is a semicolon-delimited list of users who will be allowed to access the configuration app.

  1. Agree to the Azure terms and conditions by clicking on the check box "I agree to the terms and conditions stated above" located at the bottom of the page.
  2. Click on "Purchase" to start the deployment.
  3. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal. It can take more than 10 minutes for the deployment to finish.
  4. Once the deployment has finished, you would be directed to a page that has the following fields:
    1. botId - This is the Microsoft Application ID for the FAQ Plus bot.
    2. appDomain - This is the base domain for the FAQ Plus Bot.
    3. configurationAppUrl - This is the URL for the configuration web application.

Step 3: Finish setting up the configuration app

  1. Note the location of the configuration app that you deployed, which is https://[BaseResourceName]-config.azurewebsites.net. For example, if you chose "contosofaqplusplus" as the base name, the configuration app will be at https://contosofaqplusplus-config.azurewebsites.net
  2. Go back to the "App Registrations" page here.
  3. Click on the application under the application list. Under "Manage", click on "Authentication" to bring up authentication settings.
  4. Add a new entry to "Redirect URIs":
    • Type: Web
    • Redirect URI: Location (URL) of your configuration app. This is the URL from Step 3.1.
  5. Under "Implicit grant", check "ID tokens".
  6. Click "Save" to commit your changes. Remember that this should be done once for the configuration app only.

Step 4: Configure the bot application settings

  1. Once the configuration app has been correctly configured, navigate to the URL.
  2. You will be prompted to login with your credentials (assuming that your email address is one among the valid UPN list)
  3. After logging in, you would be presented with the following screenshot below: image4
  4. To configure the Team ID, you would need to get the link to a Team from the Teams client. To do so, open Microsoft Teams, and navigate to the Team to be configured for receiving notifications from the bot. Your screen should resemble something like the below screenshot: image5 Once you click on the text that reads "Get link to team", you would be given another prompt which resembles as follows: image6
  5. You then proceed to paste the copied Team link into the configuration app near the field that reads "Team Id". Your screen on the configuration app should look like below: image7
  6. Proceed to obtain a Knowledge Base ID (or, KbId) from the QnAMaker resource. To create a knowledge base, please go here. If you have not logged in to QnAMaker previously, you may be prompted to login.
  7. Once you have created, and trained your knowledge base, you would need to publish it. Once the knowledge base has been published you would end up with a screenshot similar to the one below: image8
  8. The highlighted GUID in the above screenshot is the knowledge base Id. That value should be copied and pasted into the configuration app.
  9. Provide the values for the help tab text, and the welcome message text. After all of the information has been provided, your screen would resemble something similar to below: image9

Notes

While configuring your FAQ Plus bot through configuration web app, there is a button that reads OK next to each input field. By clicking the button that reads OK, the information stored in each of those input fields is being saved in a database.

Step 5: Create the Teams app packages

The following steps would need to be repeated twice. One package would be sideloaded for a Team and the other Teams app package would be used in a personal scope.

  1. Open then Manifest\manifest.json file in a text editor.
  2. Change the placeholder fields in the manifest to values appropriate for your organization.
    • developer.name (What's this?)
    • developer.websiteUrl
    • developer.privacyUrl
    • developer.termsOfUseUrl
  3. Change the <<botId>> placeholder to your Azure AD application's ID from above. This is the same GUID that you entered in the template under "Bot Client ID".
  4. In the "validDomains" section, replace the <<appDomain>> with your Bot App Service's domain. This will be [BaseResourceName].azurewebsites.net. For example if you chose "contosofaqplusplus" as the base name, change the placeholder to contosofaqplusplus.azurewebsites.net.
  5. Create a ZIP package with the manifest.json,color.png, and outline.png. The two image files are the icons for your app in Teams.
    • Make sure that the 3 files are the top level of the ZIP package, with no nested folders.

TODO: Have the screenshot here

Step 6: Run the apps in Microsoft Teams

  1. If your tenant has sideloading apps enabled, you can install your apps personally by following the instructions below:
    • Upload the custom app package using the Store. Documentation can be found here
  2. You can also upload it to your tenant's app catalog, so that it can be available for everyone in your tenant to install. Reference on how to do that can be found here
  3. Run your messaging extension. Documentation is located here

Troubleshooting

Please see our Troubleshooting page.

Clone this wiki locally