Teams Hub

About

  • Integration with the Teams application is accomplished by installing the SmartHub Teams application in your tenant or a specific Team.

  • The integration is compatible with both the web and the desktop version of Teams.

  • The SmartHub Teams app exposes 3 types of integrations:

    • Message extension
      • Enables you to run searches and embed results as part of your messages in Chat.
    • Personal Tab extension
      • Enables you to access the full functionality of the SmartHub center directly from Teams.
    • Teams Tab extension
      • Enables all the members of your team to access the full functionality of the SmartHub center directly from the Team tabs.
When upgrading from an older version to SmartHub 5.6.6 or later, you must reinstall the Teams Hub integration.

Prerequisites

  • SmartHub must be installed and accessible using HTTPS
    • This requires a trusted, valid certificate to be configured in the IIS bindings
  • Supported Authentication: Only "Azure AD" or "Federated authentication"
    • Windows Authentication is unsupported

  • If you plan to install the Hub for only someTeams then the Teams external app installation switch needs to be enabled to side-load applications - see Admin settings for apps in Microsoft Teams.



    If you do not configure the Teams Hub correctly, it is made available to the entire Organization. Any user will be able to install the Hub for himself or the Teams he is a member of.

Additional Message Extension Requirements

In Teams, the message extension functionality is based off the Microsoft Bot Framework infrastructure. As a result there are some specific requirements for this feature to work:

  • An Office 365 account with permissions to register a Bot service.
  • SmartHub needs to be accessible from the internet for the Bot Framework to reach it.
  • A bot needs to be registered and configured in the Microsoft Bot Framework Portal. For more information, see the Register the SmartHub Teams Bot section.

How to Register the SmartHub Teams Bot

  1. Navigate to the Bot Framework Portal.
  2. Click on the Create button.
  3. You are redirected to the Azure portal Bot Service Blade.
  4. Enter a Bot handle.
  5. Choose the Subscription.
  6. Select a Resource Group (or create a new one).
  7. Select a Pricing Tier.
  8. On the Microsoft App ID field, do the following:
    1. If you do not own an application, create a new Microsoft App ID.
    2. If you already have a registered application, use an existing app registration
      1. In this scenario, the Existing app ID and Existing app password must be provided. 
        1. The App ID can be obtained from an existing registered application. To locate the App ID, click Overview and note the value in the Application (client) ID field. You should also note the Directory ID on this page for later use in the configuration.
        2. The App password can be obtained by clicking the Certificates & secrets on the left side panel.

          The existing app should be multi-tenant.
  9. Click Review + Create then Create.
  10. Wait until the deployment is finished, then click Go to resource.
  11. Click Configuration and enter the Messaging endpoint in the following format: https://smartHubAddress:port/_bai/MSTeams. For example, https://smarthub.contoso.com/_bai/MSTeams.


  12. Check Enable Streaming Endpoint.
  13. Take note of the Microsoft App ID and Client Secret values which is required later on.
  14. Click on the Channels section and choose the Microsoft Teams from the Available Channels section.
  15. Agree to the terms of Service, select Microsoft Teams Commercial (most common) then click Save.
  16. Configure the bot for Single Sign-on (SSO):
    1. Navigate to the newly created bot.
    2. Adjacent to Microsoft App ID:
      1. Select Manage.
      2. From the left pane of your bot resource, Select Authentication.
    3. If the Web Platform has not been created, choose Add a platform > Web.
    4. Enter the following Redirect URI: https://token.botframework.com/.auth/web/redirect.
    5. Check the Access tokens and ID tokens checkboxes.
    6. Click Configure.
    7. If the web platform is already created, add the above URI and select those checkboxes.
  17. The current application should be registered as multi-tenant, otherwise the bot framework is not allowed to access the exposed API that will e created in the following steps.

    1. If the Microsoft App ID was created at the same time with the Azure Bot, the app registration is already set to multi-tenant.

    2. If you used an existing app registration, the following changes should be made:

      1. Navigate to the Manifest section.

      2. Change the property for signInAudeince to AzureADandPersonalMicrosoftAccount.

        A multi-tenant application does not allow custom Application ID URI. For example:
        • https://localhost:1234, https://my-app-id-URI
        • The property must use a verified domain of the organization or its sub-domain.

      3. Ensure the config item is set to "accessTokenAcceptedVersion": 2. If not, change it's value to 2.

      4. Click Save.

  18. Select Expose an API from the left pane and select Set for the Application ID URI.

    1. If the newly created application was used, use the Application ID URI shown and append api://botid- at the beginning of the URI.

    2. If an existing app was used, set the Application ID URI as follows: api://botid-<MicrosoftAppId>.


      3. You must use the exact Application ID URI template as described above, otherwise the SSO process will fail.

  19. Click Save. Take a note of Application ID URI value which are required later on.
  20. On the Scopes defined by this API section, create a new scope with the following configuration:
    1. Scope name: Enter a scope name.
    2. Who can consent?: Select Admins and users.
    3. Admin consent display name: Enter a consent display name.
    4. Admin consent description: Enter a description for the Admin consent.
    5. State: Select Enabled.

  21. Save the newly created scope.
  22. Add the following IDs as Authorized client applications and select the checkbox for Authorized scopes:

    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile or desktop application)

    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)

    • Your MicrosoftAppId. If you have been following these steps, you would have noted this in step 13.'

  23. Select Token configuration from the left-side panel and do the following:
    1. Click Add optional claim. Select Access as *Token type.
    2. Select upn under Claim and click Add.
    3. Click Add optional claim. Select ID as *Token type.
    4. Select upn under Claim and click Add.
  24. Navigate to API Permissions > Add a permission > Microsoft Graph > Delegated permissions and select all OpenId permissions:
    • email
    • offline_access
    • openid
    • profile
  25. Navigate to API Permissions > Add a permission > My APIs > Select your app that you use for authentication in SmartHub > Select the scope that your configured in step 20. In this example, we set up a scope named SH.ALL.
  26. Open the Azure Bot and go to Configuration > Add OAuth Connection Settings.
    1. In the New Connection Setting, enter the following details:
      • Name: Enter a name for the new connection string. Take a note of the connection name.
      • Service Provider: Select Azure Active Directory V2 from the drop-down list.
      • Client id: Enter the Microsoft App Id that you noted in step 13.
      • Client secret: Enter the Client Secret value that you noted in step 13.
      • Token Exchange URL: Enter the Application ID URI that you noted in step 19.
      • Tenant ID: Enter the Tenant ID that you noted in step 8.
      • Scopes: enter email offline_access openid profile smarthub-auth-app-scope/SH.ALL.


  27. Click Save.
  28. After the OAuth connection is saved, select it and click Test Connection.
  29. On the permissions pop-up, click Approve.
  30. If the configuration is correct, a token will be generated. You can close this tab.

How to Configure the App

To install the app you must first update the manifest with your own configuration details:

  1. Navigate to the installation directory of your SmartHub website.
  2. Open the integrations\msteams\SmartHubApp folder.
  3. Edit the manifest.json, SmartHub Security Settings and web.config files as instructed in the following sections.
    You must change the version from "version": "1.0.0.0" to "version": "1.0.0".

Personal Tab Settings

This is used for configuring what page the Personal tab of the users that install the Hub will display.

  • To fully disable this functionality remove the entire staticTabs node and its children from the manifest.
  • Look for staticTabs property and change the contentUrl and websiteUrl to point to your SmartHub address

For Example:
Copy 
"contentUrl": "https://smartHubAddress:port/Index.html#pn=msteams"
"websiteUrl": "https://smartHubAddress:port/Index.html#pn=msteams"

 

Messaging Extension Settings

This is used for configuring what bot the Messaging extension communicates with. To fully disable this functionality, remove the entire composeExtensions node and its children from the manifest.

  1. Look for composeExtensions and change the botId property by replacing it with Microsoft App ID that you noted down during the Bot Service creation.
  2. Look for webApplicationInfo and do the following:
    • Replace the id property with the Microsoft App ID.
    • Replace the resource property with the Application ID URI.
  3. From your SmartHub rooot folder, open the web.config file for editing.
  4. Change the following keys:

    • TeamsBotConnectionName with connection name that you noted.

    • TeamsBotSiteURL with the smarthub address in the following format: https://smartHubAddress:port.

    • TeamsBotClientId with the Client ID that you noted.

  5. Navigate to the SmartHub Admin page > Security Settings > Trusted app registration and expand the section.
    • Add Trusted App Registrations.
    • Add the Client ID of the Azure bot app.
    • Add the Client Secret of the Azure bot app.
    • Click OK.

Team Tab Extension Settings

This is used for configuring what page should be opened when users navigate to the SmartHub tab in their Team. To fully disable this functionality, remove the entire configurableTabs node and its children from the manifest.

  1. Look for configurableTab and modify the configurationUrl to point to your SmartHub address - make sure you leave the following relative path in the URL:
       /integrations/msteams/ConfigPage.html

  2. If you want to point the Team Tab to a custom page that is based on the default Index and Results pages from Teams, you must append the following to the end of the URL:
       ?address=<address to the page that should be opened by the tab>
  • By default, it automatically opens the built-in /integrations/msteams pages.
For proper operation, the value of the ?address parameter must be encoded.

After Settings Are Complete

  1. Save the changes and go to the parent directory: integrations\msteams.
  2. Go to SmartHubApp directory and select all (CTRL + A) files inside.
    1. Right-click the files and choose the option Send To → Compressed (zipped) folder.

  3. After the archive is created, copy it to the environment where you have the Teams desktop client installed.

How to Install the SmartHub Teams App

The SmartHub Teams App can be installed at 3 levels:

  • Me or My Teams → Personal (Add for you)
    • The Messaging extension is installed only for you
    • The Personal Tab extension is installed to your account
    • The Team Tab extension is not installed
  • Me or My Teams → Team (Add to a team)
    • The Messaging extension is installed for all of your team members
    • The Personal tab extension is only installed to your account
    • The Team Tab extension is installed for the Teams you select
  • Organization
    • The app is uploaded and made available for all of your users but is not automatically installed to any user or team.

The app needs to be installed individually for each team that is planing to use it.

How to Install the Teams App for a Specific User or Team

Navigate to the Store and click on Upload a custom app > Upload for me or my teams and select the ZIP file created in step 2 in After Settings Are Complete.

How to Make the Teams App Available to Your Organization

Navigate to the Store and click on Upload a custom app > Upload for [OrganizationName] and select the ZIP file created in step 2 in After Settings Are Complete.

This does not install the application but makes it available under the Store → [Organization Name] subsection.



Now you and everyone from your organization can select the Teams app and install it personally or to any Team the user owns.

How to Uninstall the SmartHub Teams App

The SmartHub Teams App must be uninstalled from 4 sections, or tabs, listed here:

  • Personal tab
  • Team tab
  • Conversations tab
  • <Your Custom Named> SmartHub tab

Personal Tab

  1. Select Teams from the right side menu.
  2. From the menu, select SmartHub.
  3. Click the dots icon "..." and select Uninstall.


Team Tab

  1. Click the icon More options.
  2. Click Manage team.

  3. On the top, horizontal menu, select Apps.
  4. Click the trash can icon to delete your (custom) Smart Hub app.

How to Change the Results Icon from the Bot

  1. Navigate to the installation directory of your SmartHub website.
  2. Open the integrations\msteams\image folder.
  3. Add your custom icons, using as name of the file the expected extension.
    • Example: for results with a PDF extension, the icon name is "pdf.png"
The icon.png file represents the default icon.

How to Use Open In Tab

TheOpen in tabbutton allows to user to open a Smart Hub teams tab directly from the messaging extension.

The button can be found by clicking on theActionsbutton and selectingOpen in tab.

How to Track Queries from Bot in SmartAnalytics

To see reports about queries from Bot, go to http://ReportingPageAddress/Pages/QueryAnalytics/QueriesBySource.aspx

Conversations Tab

  1. Go to your team's General page.
  2. Go to the Conversations tab.
  3. Click on the Messagingextensions icon.
  4. Go to the Smart Hub App and click "Uninstall."


Remove <YourCustomNamed> SmartHub

Remove "SmartHub Enterprise Search" (or the name of your SmartHub) Tab:

  1. Go to your team's General page.
  2. Select your SmartHub from the top horizontal menu.
  3. Click Remove.