• Deployment Guide
  • Prerequisites
  • Steps
    • Register AD Application
    • Deploy to Azure subscription
    • Set-up Authentication
    • Add Permissions to your app
    • Create the Teams app packages
    • Install the apps in Microsoft Teams
  • Troubleshooting

---

To begin, you will need:

• An Azure subscription where you can create the following kinds of resources:
  • App Service
  • App Service Plan
  • Bot Channels Registration
  • Azure Function
  • Azure Storage Account
  • Service Bus
  • QnA Maker cognitive service
  • Application Insights
• A team of Administrators which will be used to send ERG group registration and End-user feedback notifications. (You can add or remove team members later!)
• A copy of the Group Connect app GitHub repo
• A reasonable set of Question and Answer pairs to set up the knowledge base for the bot.

---

Register two Azure AD applications in your tenant's directory: one for End-user app, and another for the Admin app.

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

2. Click New registration to create an Azure AD application.

   • Name: Name of your Teams App - if you are following the template for a default deployment, we recommend "Group Connect".
   • Supported account types: Select "Accounts in any organizational directory" (refer image below).
   • Leave the "Redirect URI" field blank for now.

   

3. Click Register to complete the registration.

4. When the app is registered, you'll be taken to the app's "Overview" page. Copy the Application (client) ID; we will need it later. Verify that the "Supported account types" is set to Multiple organizations.

   

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 choose when the secret will expire. Click "Add".

   

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

7. Go back to “App registrations”, then repeat steps 2-6 to create another Azure AD application for the Admin app.

• Name: The name of your Admin app. We advise appending “Admin” to the name of this app; for example, “Group Connect Admin”.

• Supported account types: Select "Accounts in any organizational directory".

• Leave the "Redirect URL" field blank for now.

  At this point you should have the following 5 values:

  1. Application (client) ID for the End-user bot.
  2. Client secret for the End-user bot.
  3. Directory (tenant) ID.
  4. Application (client) ID for the Admin bot.
  5. Client secret for the Admin bot.

  We recommend that you copy the values, we will need them later.

  

1. Click on the Deploy to Azure button below.

   

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

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

   Note: Please ensure that you don't use underscore (_) or space in any of the field values otherwise the deployment may fail.

4. Select a subscription and a resource group.

   • We recommend creating a new resource group.

   • The resource group location MUST be in a datacenter that supports all the following:

     • Storage Accounts
     • Application Insights
     • Azure Functions
     • Service Bus
     • App Service
     • QnA Maker

     Note: For QnA Maker please do not change the default region of West US. The management service of QnA Maker is available only in the West US region at the moment. No customer data is stored in this service. Please refer to the official Microsoft docs here for more details.

   For an up-to-date list of datacenters that support the above, click here

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

   • The [Base Resource Name] must be available. For example, if you select groupconnect as the base name, the name groupconnect must be available (not taken); otherwise, the deployment will fail with a conflict error. Also, please ensure the name you select is not more than 19 characters.
   • Remember the base resource name that you selected. We will need it later.

6. Update the following fields in the template:

   1. User Client ID: The application (client) ID of user bot. (from Step 1)
   2. User Client Secret: The client secret of user bot. (from Step 1)
   3. Author Client ID: The application (client) ID of admin bot. (from Step 1)
   4. Author Client Secret: The client secret of admin bot. (from Step 1)
   5. Team Link: This is a link to the team of Administrators/Group Leadership to which the app will send ERG approval and End-user feedback notifications. Please ensure this is a Teams link which starts with "https://teams.microsoft.com/l/team". Navigate to a team of your choice on Teams and click on ellipsis (...), and in the resulting menu click on 'Get link to team' to copy the team link.
   6. Tenant Id: The tenant ID. (from Step 1)
   7. Proactively Install User App [Optional]: Default value is true. You may set it to false if you want to disable the feature.
   8. User App ExternalId [Optional]: Default value is 148a66bb-e83d-425a-927d-09f4299a9274. This MUST be the same id that is in the Teams app manifest for the user app.
   9. DefaultCulture, SupportedCultures [Optional]: By default the application contains en-US resources. You may add/update the resources for other locales and update this configuration if desired.

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

   Note: If your Azure subscription is in a different tenant than the tenant where you want to install the Teams App, please update the Tenant Id field with the tenant where you want to install the Teams App.

7. If you wish to change the app name, description, and icon from the defaults, modify the corresponding template parameters.

8. Click on "Review + create" to start the deployment.

9. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal. It may take up to an hour for the deployment to finish.

   If the deployment fails, see this section of the Troubleshooting guide.

10. Once the deployment is successfully completed, go to the deployment's "Outputs" tab, and note down the following values. We will need them later.

    • authorBotId: This is the Microsoft Application ID for the Author's app. It can be found in the "AzureAd:ClientId" field of your configuration e.g. 5630f8a2-c2a0-4cda-bdfa-c2fa87654321. For the following steps, it will be referred to as %authorBotId%.

    • userBotId: This is the Microsoft Application ID for end user app. It can be found in the "UserAppId" field of your configuration e.g. 1240f8a2-c2a0-4cda-bdfa-c2fa87659876. For the following steps, it will be referred to as %userBotId%.

    • appDomain: This is the base domain for the Group Connect app. It is the value in the "AzureAd:ApplicationIdURI" field of your configuration without the "api://" e.g. appName.azurewebsites.net. For the following steps, it will be referred to as %appDomain%.

1. Note that you have the %appDomain% values from the previous step (Step 2).

   If do not have these values, refer this section of the Troubleshooting guide for steps to get these values.

2. Go to App Registrations page here and open the Admin app you created (in Step 1) from the application list.

3. Under Manage, click on Authentication to bring up authentication settings.

   1. Add a new entry to Redirect URIs:

      • Type: Web
      • Redirect URI: Enter https://%appDomain%/signin-simple-end for the URL e.g. https://[BaseResourceName].azurewebsites.net/signin-simple-end
      • Front-channel logout URL: Keep it blank

   2. Under Implicit grant, check ID tokens.

   3. Click Save to commit your changes.

4. Back under Manage, click on Expose an API.

   1. Click on the Set link next to Application ID URI, and change the value to api://%appDomain% e.g. api://[BaseResourceName].azurewebsites.net.

   2. Click Save to commit your changes.

   3. Click on Add a scope, under Scopes defined by this API. In the flyout that appears, enter the following values:

      • Scope name: access_as_user
      • Who can consent?: Admins and users
      • Admin consent display name: Access the API as the current logged-in user
      • Admin consent description: Allows Teams to call the app’s web APIs as the current user
      • User consent display name: Access the API as the current logged-in user
      • User consent description: Allows Teams to call the app’s web APIs as the current user

   4. Click Add scope to commit your changes.

   5. Click Add a client application, under Authorized client applications. In the flyout that appears, enter the following values:

      • Client ID: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
      • Authorized scopes: Select the scope that ends with access_as_user. (There should only be 1 scope in this list.)

   6. Click Add application to commit your changes.

   7. Repeat the previous two steps, but with client ID = 1fec8e78-bce4-4aaf-ab1b-5451cc387264. After this step you should have two client applications (5e3ce6c0-2b1f-4285-8d4b-75ee78787346 and 1fec8e78-bce4-4aaf-ab1b-5451cc387264) listed under Authorized client applications.

5. Back under Manage, click on Manifest.

   1. In the editor that appears, find the optionalClaims property in the JSON Azure AD application manifest, and replace it with the following block:

       "optionalClaims": {
           "idToken": [],
           "accessToken": [
               {
                   "name": "upn",
                   "source": null,
                   "essential": false,
                   "additionalProperties": []
               }
           ],
           "saml2Token": []
       },
   

6. Click Save to commit your changes.

Continuing from the Azure AD app registration page where we ended Step 3.

1. Select API Permissions blade from the left hand side.

2. Click on Add a permission button to add permission to your app.

3. In Microsoft APIs under Select an API label, select the particular service and give the following permissions,

   • Under Commonly used Microsoft APIs,

   • Select “Microsoft Graph”, then select Delegated permissions and check the following permissions,

     1. Group.Read.All
     2. AppCatalog.Read.All

   • then select Application permissions and check the following permissions,

     1. Group.Read.All
     2. TeamsAppInstallation.ReadWriteSelfForUser.All
     3. User.Read.All

   • Click on Add Permissions to commit your changes.

   

   

   Please refer to Solution overview for more details about the above permissions.

4. If you are logged in as the Global Administrator, click on the “Grant admin consent for %tenant-name%” button to grant admin consent, else inform your Admin to do the same through the portal.

   Alternatively you may follow the steps below:

   • Prepare link - https://login.microsoftonline.com/common/adminconsent?client_id=%appId%. Replace the %appId% with the Application (client) ID of Microsoft Teams bot app (from above).
   • Global Administrator can grant consent using the link above.

1. Create a knowledge base, following the instructions in the QnA Maker documentation.

2. Once you have signed-in to QnaMakerAI, click on 'Create a knowledge base' at the top.

3. In the resulting screen, Skip the step, "Create a QnA service in Microsoft Azure", because the ARM template that you deployed in Step 2 "Deploy to your Azure subscription" already created the QnA service. Proceed directly to the next step, "Connect your QnA service to your KB".

Use the following values when connecting to the QnA service:

• Microsoft Azure Directory ID: The tenant associated with the Azure subscription selected in Step 2.1.
• Azure subscription name: The Azure subscription to which the ARM template was deployed.
• Azure QnA service: The QnA service created during the deployment. This is the same as the "Base resource name"; for example, if you chose "contosoconnectfaq" as the base name, the QnA Maker service will be named contosoconnectfaq.

4. Add a Name to your Knowledge base.

With the new updates, the knowledge base can now support multi-turn conversations. To understand the basics of multi-turn conversations, navigate to the QnA Maker documentation to understand about multi-turn conversations. To enable multi-turn on the newly created knowledge base, go to this link to enable multi-turn extraction on the knowledge base.

• Note: For best practices with regards to formatting and document structure, please follow these guidelines.

5. Click on 'Create your KB'. In the next screen you will be prompted to add QnA pairs to the KB.

6. Once you are done adding QnA pairs, click on 'Save and train' and once it is saved, click on 'Publish'.

7. The page will show a success message once the service has been deployed. Note down the KB Id, you will need it in the next step. The KB Id is a GUID and it will be displayed on the screen in the following format POST /knowledgebases/{KB_Id}/generateAnswer.

For more details on publishing the knowledge see here.

Save the knowledge base ID. We will need it in the next step.

Group Connect app comes with 2 applications – Admin, End-user. The Admin application is intended for employees who create and send messages in the organization and manage the list of Groups and Resources. The End-user application is intended for employees who discover the Groups and Resources and receive the messages sent by Admins.

Create two Teams app packages: one to be installed to an Admin team and other for End-users to install in their personal scope.

1. Make sure you have cloned the app repository locally.

2. Open the Manifest\manifest_admin.json file in a text editor.

3. Change the placeholder fields in the manifest to values appropriate for your organization. For more information on this fields you can refer this link

   Name	Maximum size (in characters)
   name	32
   websiteUrl	2048
   privacyUrl	2048
   termsOfUseUrl	2048

4. Change the <<appDomain>> placeholder in the configurationUrl setting to be the %appDomain% value e.g. "https://[BaseResourceName].azurewebsites.net/configtab". The maximum length of the URL should not exceed more than 2048 characters in length.

5. Change the <<appDomain>> placeholder in the validDomains setting to be the %appDomain% value e.g. "[BaseResourceName].azurewebsites.net".

6. Change the <<appDomain>> placeholder in the resource setting of the webApplicationInfo section to be the %appDomain% value e.g. "api://[BaseResourceName].azurewebsites.net"

7. Change the <<botId>> placeholder in the botId setting to be the %botId% value - this is your Azure AD application's ID from above. This is the Client Id of the app and it should not exceed more than 64 characters in length. Please note that there are two places in the manifest (for admins) where you will need to update Bot ID.

8. Change the <<botId>> placeholder in the id setting of the webApplicationInfo section to be the %botId% value of the Admin app.

9. Copy the manifest_admin.json file to a file named manifest.json.

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

    • Name this package group-connect-admin.zip, so you know that this is the app for the admin team.
    • Make sure that the 3 files are the top level of the ZIP package, with no nested folders.

    

11. Delete the manifest.json file.

Repeat the steps above for the End-user app with the file Manifest\manifest_users.json.

Note:

• Please be careful while repeating the Step 8 from above for the End-user app. In the webApplicationInfo section, you need to update the Client Id of the Admin app in place of the <<botId>> placeholder.
• You will not need to change anything for the configurationUrl section because the end-user app does not have any configurable tab associated with it.

Name the resulting package group-connect-users.zip, so you know that this is the app for the End-users.

1. Install the admin app (the group-connect-admin.zip package) to your team of Administrators.
   • If your tenant has sideloading apps enabled, you can install your app by following the instructions here.

IMPORTANT: We recommend installing the 'Group Connect (Comms)' app in the team whose ID was provided during the app installation as a custom (sideloaded) app. Do NOT use app permission policies to restrict access to this app to the members of the admin team. Otherwise, members of the admin team may not receive messages sent from Group Connect app.

1. Upload the 'Group Connect' app to your tenant's app catalog so that it is available for everyone in your tenant to install.

IMPORTANT: Proactive app installation will work only if you upload the User app to your tenant's app catalog.

1. Navigate to the team in which the app is installed and select the appropriate channel.

2. Click on the ‘+’ icon at the top of the channel. It will show you a list of Apps that are available for you to pin as a tab.

3. Select 'Group Connect (Comms)' from the list and click on 'Add'.

4. In the resulting step you will the see the option to select the type of the configurable tab. Select the option for Comms tab.

5. You will be able to broadcast messages to all the users using this tab.

1. Navigate to the team in which the app is installed and select the appropriate channel.

2. Click on the ‘+’ icon at the top of the channel. It will show you a list of Apps that are available for you to pin as a tab.

3. Select 'Group Connect (Comms)' from the list and click on 'Add'.

4. In the resulting step, you will the see the option to select the type of the configurable tab. Select 'Add a Manage groups tab'.

5. You will be able to see and manage all the groups registered in the app.

1. Navigate to the Group management tab

2. Click on 'Configure' button at the top of the tab which will open a task module that will display all the configurable properties.

The configuration screen is divided into two categories

• Chat bot (QnA Maker) configuration This section contains all the properties related to setting up the chat bot in the app

  • Enable/Disable responses from the chat bot : Enable this feature setting if you want the chat bot to respond to user questions. If the setting is disabled, the app will not answer user questions or inputs and respond with a generic message.
  • QnA Maker Knowledge base Id : This is the Id (GUID) of the Knowledge Base that the app refers to answer user questions. Please ensure you specify the Azure QnA Maker service you set up during installation if you have enabled the above setting and want the app to respond to user questions.

• Group registration configuration This section contains all the properties related to setting up of the Group registration feature

  • Enable/Disable the button for app users to register new groups : Enable this feature setting if you want to enable End-users/Employees to register a new group. When this feature is enabled, End-users will see a button to add a new group in the Discover Groups tab in the personal scope. The usual approval workflow will be initiated and the new group will be visible in the Discover Groups tab only if approved by the Admins.
  • Configure text of the button to register new groups: Admins will be able to configure the button text to register new groups through this field

Once you have completed these steps, please refer to Getting started page for guidance on how to use the app.

Please see our Troubleshooting page.

---