Tags | Microsoft Search | Microsoft Graph | Integrations |

ADMIN PRIVILEGES REQUIRED

This documentation is for Stack Overflow for Teams Enterprise. Free, Basic, and Business users can access their documentation here. Find your plan.

Overview

Many organizations use the search capabilities found in such Microsoft tools as Office, Bing, and SharePoint. With a Microsoft Graph Search Connector, you can add your Stack Overflow for Teams Enterprise (SOE) data to the search results of any Microsoft 365 service.

When signed into Windows Search with a work account, your users will be able to search by title for questions, answers, and articles on your SOE site. Clicking on any title link will take them to the full post or article on your SOE site.

NOTE: The Microsoft Graph Connector is not a "live" connection to your SOE site. Instead, you'll upload question, answer, and article data to the search database. To keep this cached SOE data current and accurate, you'll need to update it regularly.

Here are some considerations relating to the Microsoft search tools:

Microsoft Search uses insights from Microsoft Graph to show results tailored to each user. Different users may see different results, even if they search for the same words.
Microsoft Search will only return results the user already has access to, per Microsoft admin settings. It will not change permissions.
With Microsoft Bing, users will see results from within their organization, their SOE site, and the internet.

NOTE: We offer these scripts and instructions with no technical support. You are responsible for modifying, testing, and implementing these scripts for your own use.

The Microsoft Graph Connector

In this example, we'll show how to use the Microsoft Graph API to build and customize a connection between Microsoft Search and SOE. Your Microsoft organization will manage the connection, which will appear as "Search" under "Connected Experiences". The Graph Connector counts toward your Microsoft search connection quota. For more information, see your Microsoft Admin Portal.

You can find all API calls used in this example in this Postman collection. Here's a video of the Microsoft Graph Connector setup process.

Build a custom Microsoft Graph Search Connector

NOTE: The following steps demonstrate one way to create a Microsoft Graph Connector. There may be others. Because of the many variables involved, Stack Overflow does not offer additional support for connecting your SOE site to Microsoft Search.

To build a Microsoft Graph Search Connector:

Get an authentication and authorization token (more info).
Create and Register your app.
Get access with or without a user by requesting an access token.
Create a new externalConnection by posting to the connections collection. This will allow you to bring content from external services into Microsoft Graph.

Your Connection should reflect the integration you are building. We recommend setting the following body for the Graph API request:
```
{
"id": "soe",
"name": "SO Enterprise",
"description": "SOE Search Connector"
}
```
Create a schema for your new connection. The schema determines how Microsoft Search will use your external content. It lists all the properties you plan to add to the connection, along with their attributes, labels, and aliases. You must register the schema before adding items to the connection. Microsoft provides a list of all available properties and their definitions.

In this step, you define what content Microsoft Search can access, and how it can search it. Limit the externalItem properties to those that anyone in your organization should be able to see in the Microsoft Search results. We recommend Title and Post URL only. Anyone in your organization would then be able to see the post title, but only those with login credentials to your SOE site would be able to follow the link and read the full body of the post.

IMPORTANT: In this step, you also set the naming for the data you would like to upload later on. To make the data upload as easy as possible, use property names that match the Stack Overflow API output ("title" and "share_link" in this example).
```
"properties": [
    {
    "name": "title",
    "type": "string",
    "isSearchable": "true",
    "isRetrievable": "true",
    "isQueryable": "true",
    "labels": [
        "Title"
    }
    {
    "name": "share_link",
    "type": "string",
    "isRetrievable": "true",
    "labels": [
        "url"
    ]
    }etc.
```
After you create the connection and its schema, upload your data by creating an externalItem for each post or article from your SOE site (the data source). Each externalItem must have a unique ID. SOE make this easy, as each question, answer, and article on your site already has a unique ID.

The items you upload must match the schema properties created in the previous step. For example:
```
"id": "73",
"properties": {
"title": "Test question to find for Microsoft Search Connector",
"share_link": "https://support-test.stackenterprise.co/questions/73"},
}
etc.
```

The Stack Overflow API

Accessing the Stack Overflow API is the simplest way to retrieve your SOE data for import into your Microsoft Search Connector. If you want to limit the posts you include, consider adding a tag to those posts then filtering by the tag in your API query.

With API v2.3 (https://[your_site]/api/docs), you can filter the return data to include only the properties you wish to upload. This example returns only ID, title, and URL:

We recommend a script or service to automate the process of updating your Microsoft Search Connector data. This automation would query the Stack Overflow API, convert the data into the correct schema, create each externalItem, and post the data to the Microsoft search API in JSON format.

Final steps

Check that the connection is working correctly, and give Microsoft Search the necessary permissions to display the properties.
Create the Result Type to control how Microsoft Search displays the results. By default, search results display in a layout that you can choose from a template. You can also fully customize and configure the search results display.
Confirm that your SOE data appears in the search results at https://www.office.com/search. If you want to see SOE data in Bing search results as well, enable Microsoft Search in Bing for your organization.

To update or delete a Microsoft Graph Connector, follow these instructions.

Limitations

To learn more about Microsoft Graph connector limitations (number of connections, number of externalItem resources, etc.), read Microsoft's Use the Microsoft Graph connectors API article. Learn more about the limitations of Graph API in the Microsoft Graph connectors API limits article.

Additionally, consider these factors when building a Microsoft Graph connector:

You'll be sharing your SOE data with your Microsoft Office organization, but outside of your SOE site and with no SOE login required. Make sure to limit the data you provide to the Microsoft Search Connector to avoid privacy breaches (for example: include post titles but not body text).
You'll need to regularly update the search data so it accurately reflects new, edited, and deleted content. We recommend a script or service to automate data updates.
Microsoft Search will not sort results.