Skip to content
This repository has been archived by the owner on Oct 17, 2024. It is now read-only.

Deployment guide

Jump to bottom
Adrian Solis edited this page Aug 19, 2019 · 10 revisions

Prerequisites

To begin, you will need:

  • An Azure subscription where you can create the following kinds of resources:
    • Azure Logic App
    • App service
    • App service plan
    • Bot channels registration
    • Azure storage account
    • Azure search
    • QnAMaker cognitive service
    • Application Insights
  • A copy of the List Search app GitHub repo (https://github.com/officedev/microsoft-teams-list-search-app)
  • A service account user that List Search will use to access SharePoint
    • We strongly recommend creating a new user specifically for List Search, and grant that user access to only those lists that you want to be searchable with this app.

*Not a pre-requisite, but here is a complete video walk-through of the deployment created by our community member in case you want to follow along.

Step 1: Register List Search Microsoft Azure AD application

Register two Azure AD applications in your tenant’s directory: one for the messaging extension, and another for the configuration app.

  1. Log in to the Azure Portal for your subscription, and go to the “App registrations” blade at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps.

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

    1. Name: The name of your Teams app. For example, "List Search"
    2. Supported account types: Select "Account in this organizational directory only"
    3. Leave the "Redirect URI" field blank for now.

    Azure AD app registration page

  3. Click on the "Register" button.

  4. When the app is registered, you'll be taken to the app's "Overview" page. Copy the Application (client) ID and the Directory (tenant) ID; we will need them later.

    Azure AD app overview page

  5. On the side rail in the Manage section, navigate to the "Certificates & secrets" section. In the Client secrets section, click on "+ New client secret". Add a description for the secret, and set an expiration time if you wish. Click "Add".

    Azure AD app overview page

  6. Once the client secret is created, copy its Value; we will need it later.

  7. On the side rail in the Manage section, navigate to the "API permissions" section.

    1. Click on the "+ Add a permission" button.
    2. Select "Microsoft Graph".
    3. Select "Delegated permissions".
    4. Select the following permissions:
      • offline_access
      • Sites.Read.All (in the "Sites" section)

    These scopes will give the List Search app the ability to read the same SharePoint lists as the service account user.

    Azure AD app API permissions page

  8. Go back to “App registrations”, then repeat steps 2-4 to create another Azure AD application for the configuration app. We advise appending “Configuration” to the name of this app; for example, “List Search Configuration”.

At this point you have 4 unique values:

  • Application (client) ID for the messaging extension
  • Client secret for the messaging extension
  • Application (client) ID for the configuration app
  • 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

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

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

    Custom deployment page

  4. Select a subscription and resource group.

  5. 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 contosolistsearch as the base name, the names contosolistsearch and contosolistsearch-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.

  6. Fill in the various IDs in the template:

    1. Messaging Extension Client Id: The application (client) ID of the messaging extension app
    2. Messaging Extension Client Secret: The client secret of the messaging extension 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.

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

    • For example, to allow Megan Bowen (meganb@contoso.com) and Adele Vance (adelev@contoso.com) to access the configuration app, set this parameter to meganb@contoso.com;adelev@contoso.com.
    • You can change this list later by going to the configuration app service's "Configuration" blade.

  8. 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.

  9. Click on “Purchase” to start the deployment.

  10. 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 deployment to finish.

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 “contosolistsearch” as the base name, the configuration app will be at https://contosolistsearch-config.azurewebsites.net.

  2. Go back to the “App registrations” page at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredAppsPreview. Repeat the steps below for each of the two apps that you created.

  3. Click on the application in the application list. Under “Manage”, click on “Authentication” to bring up authentication settings.

  4. Add a new entry to “Redirect URIs”:

    1. Type: Web
    2. Redirect URI: Location (URL) of your configuration app. This is the URL from Step 3.1.

    Redirect URIs section of app registration page

  5. Under "Implicit grant", check "ID tokens".

    Implicit grant section of app registration page

  6. Click “Save” to commit your changes.

Remember to do this for both the messaging extension and the configuration Azure AD apps.

Step 4: Add your SharePoint lists

  1. Go to the configuration app, which is at https://[BaseResourceName]-config.azurewebsites.net. For example, if you chose “contosolistsearch” as the base name, the configuration app will be at https://contosolistsearch-config.azurewebsites.net.

  2. When prompted, log in as one of the users that you specified in “Config Admin UPN List”.

  3. The List Search app is initially not able to access SharePoint, until it gets an access token. To begin setting the user, click on the "Set SharePoint user" button.

    Set SharePoint user button

  4. You will be presented with a login prompt. Log in as the user that List Search will use to access SharePoint.

  5. Click on "Add a new SharePoint list". (The button will be disabled until the SharePoint user is set.)

    Add a new SharePoint list button

  6. Enter the URL of the SharePoint list that you want to index, then click "Enter". The rest of the input fields on the page will be populated with information from the given SharePoint list.

    Entering list URL

  7. Configure the list by selecting:

    • Display name for the list
    • The column that should be searchable
    • Up to 4 additional columns that will be included inthe result
    • How often the list data should be refreshed

    List configuration

  8. Click on "Submit". The application will fetch the list data and index it. This can take several minutes, especially if the list is large. Do NOT navigate away from the page.

  9. When it's done indexing the list, the app will navigate back to the home page. You can repeat the process and configure up to 4 other SharePoint lists to search.

    Configuration app with added list

Step 5: Create the Teams app package

  1. Open the 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 App ID”.

  4. In the "validDomains" section, replace the placeholder with your Messaging App Service's domain. This will be [BaseResourceName].azurewebsites.net. For example, if you chose “contosolistsearch” as the base name, change the placeholder to contosolistsearch.azurewebsites.net.

  5. Create a ZIP package with 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. Teams app package ZIP file

Step 6: Run the app in Microsoft Teams

  1. If your tenant has sideloading apps enabled, you can install your app personally by following the instructions below.

  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: https://docs.microsoft.com/en-us/microsoftteams/tenant-apps-catalog-teams

  3. Run your messaging extension: https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/apps/apps-upload#accessing-your-uploaded-messaging-extension

Troubleshooting

Please see our Troubleshooting page.

Clone this wiki locally