Microsoft Teams integration setup

Integration with Microsoft Teams allows you to connect your intranet with your Microsoft Teams app and see intranet activity from within Microsoft Teams. Once the two are connected, you can search the intranet, see intranet link previews, and get notified of new activity on the intranet from inside a Microsoft Teams channel.

There are three larger steps involved in setting up a Microsoft Teams integration for your ThoughtFarmer intranet:

• Create a Microsoft Teams app
• Configure Microsoft Teams in your intranet's admin panel
• Publish the app to your organization

Once the Microsoft Teams integration is successfully set up, you need to add the application to individual teams in Microsoft Teams.

• Enable the ThoughtFarmer intranet integration on specific teams.

Create a Microsoft Teams app

Create the app

1. Go to https://dev.teams.microsoft.com/ and login.
2. Go to Apps
3. Click New app at the top.
4. Give the app a name for your reference in the Microsoft Developer Portal and click Add.

Edit general information settings for the app

You have to fill out some basic information before you can publish the app.

1. On the new app screen, under Basic information on the left, fill out any required information (short name, short and long description, developer or company name, website, privacy policy, terms of use). It is not necessary to fill in an Application (client) ID in order to save (though it appears to have an asterisk indicating it is required).
2. Click Save.
3. Under Branding on the left, you have the option to upload custom icons and choose an accent color. These settings affect the appearance of the app in Teams, and are optional.

Create a bot

1. In the MS Developer Portal, click Tools (pencil icon) on the left, then Bot management.
2. Click New bot.
   
   
   
   
3. Enter a name for your bot, and click Add.
4. Under Configure, to configure your bot Endpoint address, enter your ThoughtFarmer site URL plus "/msteams/bot". eg. https://myintranet.thoughtfarmer.com/msteams/bot
   
   
   
   
5. Click Save.
6. Click Client secrets on the left.
7. Click Add a client secret for your bot.
8. A client secret for your bot will be auto-generated. Copy the client secret and save it somewhere for later use. (Important: You will need to enter the client secret for the bot in ThoughtFarmer as part of the Microsoft Teams integration.) Click OK.
9. Click on Apps on the left. Click on the app you created earlier.
10. Under Configure, click on App features. Select Bot.
11. Select your newly created bot from the Select an existing bot dropdown menu.
12. Under Select the scopes... check Personal and Team.
13. Click Save.

Note: In steps 7 and 8 above, you generate a new client secret for your bot. You will need this secret later when you are configuring Microsoft Teams in your intranet's admin panel.

Enable link unfurls and search

These steps will enable intranet search from Microsoft Teams, and will allow links pasted into a Microsoft Teams channel to unfurl and display more details about the intranet page.

1. In the Microsoft Developer Portal section for your Microsoft Teams app, go to Configure > App features.
2. Select Message extension. You will be asked to select a bot to use for messaging. Select your newly created bot from the Select an existing bot dropdown menu.
3. Click Save.
4. To set up intranet search functionality in Microsoft Teams:
   1. Under Command, click Add a command.
   2. In the Add a command modal, make sure the command type Search is selected.
   3. In the Command ID field, enter Search. (The command ID is not shown to the user, but is important for the connection between Microsoft Teams and your intranet.)
   4. Enter the desired Command title and description in the corresponding fields. (These values are information for users that displays when a user enters the search command in Microsoft Teams.)
      
      
      
      
   5. For the Parameter name, type in query. (The parameter name is not shown to the user, but it is important for the connection between Microsoft Teams and your intranet.
   6. For the Parameter title and description, type in something describing the action (searching the intranet) and what you need to enter (your search term). (The parameter description shows in the search field when the intranet app is opened from the more options menu.)
   7. Select the text type of input.
   8. Click Save.
      
      
      
      
5. Under Preview links, click Add domain.
6. In the Add domain window, enter your intranet site's URL. eg. myintranet.thoughtfarmer.com (This will allow links to unfurl and display link previews.)
7. Click Add.
8. Click Save.

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 URL as a trusted domain allows Microsoft Teams to load URLs from your site into a pop-up window during the authentication/account link process.

1. In the Microsoft Developer Portal section for your Microsoft Teams app, go to Configure > Domains.
2. Click Create your first domain.
3. In the Add domain window, type your ThoughtFarmer URL eg. myintranet.thoughtfarmer.com.
4. Click Add.

Publish the app to your organization

Validate the app

1. Go to https://dev.teams.microsoft.com/ 
2. Go to Apps and select the App you created.
3. Go to App validation under Publish.
4. Click +New Validation amd click the checkboxes under Validation Acknowledgement. 
5. Click Start Validation
6. Validate and ensure that there are no errors on your app.

Prepare the app and submit for approval

1. Go to Apps and select the App you created.
2. In the Publishing section, go to the page Publish to org.
3. Click Publish. This submits the application for approval. An admin within the organization needs to approve it for the organization.

Approve the app

An organization admin must complete these steps.

1. Go to the page Teams apps, and click on Manage apps.
2. The app submitted using the steps above should show in the Pending approval section.
3. Find the app in the list and click on it.
4. Allow the app and Publish it. This makes it available to the organization.

Register app with Azure AD

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 Microsoft Azure > 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. 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 Configure.
7. Click on the API permissions tab.
8. Follow these steps to add three permissions, one at a time:
   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. (Repeat for each permission.)
   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.