Microsoft Teams Integration Setup

Integrating ThoughtFarmer with Microsoft Teams allows users to:

• Search the intranet directly from Teams.
• See intranet link previews within Teams conversations.
• Receive notifications about intranet activity in Teams channels.

Setup Overview

To enable Microsoft Teams integration, complete the following steps:

1. Create a Microsoft Teams app
2. Configure Microsoft Teams settings in ThoughtFarmer
3. Publish the app to your organization
4. Add the ThoughtFarmer app to individual Teams

Creating a Microsoft Teams App for ThoughtFarmer

Step 1: Create the App

1. Go to Microsoft Teams Developer Portal and login.
2. Navigate to Apps.
3. Click New app at the top.
4. Enter a name for the app and click Add.

Step 2: Configure Basic Information

1. On the new app screen, under Basic information, fill in the required fields
   • Short name
   • Short and long description
   • Developer or company name
   • Website
   • Privacy policy
   • Terms of use
2. Click Save.
3. (Optional) Under Branding you can:
   • Upload custom icons
   • Choose an accent color

Creating a Bot for ThoughtFarmer in Microsoft Teams

Step 1: Create the Bot

1. In the Microsoft Teams Developer Portal, click Tools (pencil icon) on the left, then select Bot Management.
2. Click New bot.
3. Enter a name for your bot and click Add.
   

Step 2: Configure the Bot

1. Under Configure, set the Endpoint address as

   1. https://your-thoughtfarmer-url.com/msteams/bot

      1. (Replace "your-thoughtfarmer-url.com" with your actual ThoughtFarmer site URL.)
         
         
         
         
2. Click Save.

Step 3: Generate and Store a Client Secret

1. Click Client secrets on the left.
2. Click Add a client secret for your bot.
3. Copy the auto-generated client secret and store it securely. (You will need this for the ThoughtFarmer integration.)
4. Click Ok

Step 4: Link the Bot to your App

1. Click Apps on the left-hand menu and select the app you created earlier.
2. Under Configure, click on App features and select Bot.
3. Select your newly created bot from the Select an existing bot dropdown menu.
4. In the Select an existing bot dropdown, choose your newly created bot.
5. Under Select the scopes where people can use your bot, select:
   1. Personal
   2. Teams
6. Click Save.

Enable Link Unfurls and Search in Microsoft Teams

These steps will enable intranet search within Microsoft Teams and allow links pasted into a Microsoft Teams channel to unfurl, displaying details about the linked ThoughtFarmer page.

Step 1: Enable Message Extension

1. Navigate to Configure > App Features.
2. Select Message extension. 
3. When prompted, select your newly created bot from the Select an existing bot dropdown menu.
4. Click Save.

Step 2: Set up Intranet Search in Microsoft Teams

1. Under Command, click Add a command.
2. In the Add a Command modal, ensure Search is selected as the command type.
3. In the Command ID field, enter search. (This ID is used internally and is not visible to users.)
4. Enter a Command title and description to help users understand the search functionality.
   
   
   
5. Under Parameter name, enter: query. (This parameter name is used for linking Microsoft Teams with your intranet.)
6. Provide a Parameter title and description to guide users when they use the search function.
7. Set the input type to Text.
8. Click Save.

Step 3: Enable Link Unfurling

1. Under Link unfurling, click Add domain.
2. In the Add domain window, enter your ThoughtFarmer intranet's URL. (eg. myintranet.thoughtfarmer.com
3. Click Add.
4. Click Save.

Once these steps are complete, Microsoft Teams users will be able to search the ThoughtFarmer intranet directly from Teams and see previews of links when they are pasted in a channel.

Command title and description fields: Show in command menu when you @mention the intranet bot

Parameter description field: Shows in the search field when you open the intranet app from ... menu

Add Your URL as a Trusted Domain

Adding your ThoughtFarmer URL as a trusted domain ensures that Microsoft Teams can load your intranet’s pages in pop-up windows during authentication and account linking.

1. Navigate to Configure > Domains.
2. Click Create your first domain.
3. In the Add Domain window, enter your ThoughtFarmer intranet URL, e.g.: myintranet.thoughtfarmer.com
4. Click Add.

Publish the App to Your Organization

Once you've configured your ThoughtFarmer integration in Microsoft Teams, the final step is to publish the app so that your organization can access it.

Step 1: Validate the app

1. In the Microsoft Developer Portal, go to App validation under Publish.
2. Click Get Started, then check all the Validation Acknowledgement checkboxes.
3. Click Start Validation.
4. Review the validation results and ensure there are no errors in your app configuration.

Step 2: Prepare and Submit the App for Approval

1. In Microsoft Developer Portal, go to Apps and select the app you created.
2. Navigate to the Publishing section and go to Publish to org.
3. Click Publish to submit the app for approval.
4. The app will now require approval from a Teams administrator within your organization.

Step 3: Approve the App (Admin Action Required)

An organization admin must complete the following steps to approve the app:

1. In Microsoft Teams Admin Center, go to Teams apps > Manage apps.
2. Locate the Pending approval section.
3. Find the submitted app in the list and click on it.
4. Click Allow the app, then Publish it to make it available to the entire organization.

Once published, users in your organization will be able to find and install the app in Microsoft Teams.

Register App with Entra ID

Following these instructions allows admins to log in to their Microsoft Teams accounts within ThoughtFarmer, so that they can select teams and channels when setting up activity messages.

1. Go to Entra ID > App registrations > select the Bot you created (An auto-registration will have been created for the Bot you created) > Authentication tab.
2. Click Add a platform.
3. Under Configure platforms, click Single-page application.
4. In the Redirect URIs field, enter your Thoughtfarmer URL plus /msteams/auth/complete/graphapi , eg. https://myintranet.thoughtfarmer.com/msteams/auth/complete/graphapi
   
   
   
   
5. Select the checkboxes:
   • Access tokens (used for implicit flows)
   • ID tokens (used for implicit and hybrid flows)
6. Click Save.
7. Click on the API permissions tab.
8. Follow these steps to add three permissions:
   1. Click Add a permission.
   2. Click Microsoft Graph.
   3. Click Delegated permissions.
   4. Find the permissions (you can use the search field to help locate the permissions) and select the checkboxes for:
      • Under User > User.Read
      • Under Channel > Channel.ReadBasic.All
      • Under Team > Team.ReadBasic.All
   5. Click Add permissions. 
   6. Click Grant Admin consent.

Configure Microsoft Teams in ThoughtFarmer's admin panel

Before you can complete these steps, you must Create a Microsoft Teams app.

1. Go to the ThoughtFarmer Admin panel: Integrations section > Microsoft Teams page.
2. Under the App configuration tab, enter your organization's Microsoft Tenant ID.
   • The Tenant ID is your organization's ID in Microsoft Entra ID. One way to find this is to click this URL: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Properties
     This will take you to your Microsoft Entra ID, where you can see and copy your Microsoft Tenant ID.
     
3. Enter your Bot ID.
   • To find your Bot ID, go to the Microsoft Developer Portal, Tools section. Click on Bot management. Copy the Bot ID beside the Microsoft Teams App Bot you created. (If you haven't generated a bot secret for the bot already, see the Create a bot heading.) Paste the Bot ID into ThoughtFarmer.
4. Enter your Bot secret.
   • This is the Bot secret that you created and saved during the steps under the Create a bot heading.
5. Enter your Client ID. (For more information, see Client ID heading below.)
6. Click Save.
7. Under the Link previews and search tab, enter Search. (This is the command ID that you entered when you were enabling search for the Microsoft Teams app in the Microsoft Developer Portal).
8. Click Save.

Client ID

The client ID is the ID for an Azure app that is configured to allow users to log in and ask for information about teams and channels. It can be the same as your Bot ID, your existing Microsoft Cloud Drive client ID, or a new client ID that you create. The easiest setup is generally to have the Client ID be the same as the Bot ID. Client ID is the value that makes it possible to log in to your Microsoft Teams account and select a Team and Channel when setting up an activity message.

Enable the Microsoft Teams integration

Once you have set up the Microsoft Teams integration, you may wish to set up activity messages or add security groups for link unfurls and search results before you enable the integration on your intranet. To learn more about these configuration options, see Microsoft Teams integration configuration.

Once you are ready to enable the integration, go to the ThoughtFarmer Admin panel: Integrations section > Microsoft Teams page, and turn the Enable toggle to ON.