Register schema for the Microsoft Graph connection
The connection schema determines how your content will be used in various Microsoft Graph experiences. Schema is a flat list of all the properties that you plan to add to the connection along with their attributes, labels, and aliases. You must register the schema before adding items into the connection.
Microsoft Graph connectors are currently in public preview status. To gain access to connectors functionality, you must turn on the Targeted release option in your tenant. See more details on the connectors preview program.
The following table represents an example of a possible schema for a work ticket system connector.
If a property is searchable, its value is added to the full text index. When a user performs a search, we return results if there is a search hit in one of the searchable fields or its content.
A search for "design" displaying results for hits against properties (
tags) and content
If a property is queryable, you can query against it using knowledge query language (KQL). KQL consists of 1 or more free text keywords (words or phrases) or property restrictions. The property name must be included in the query, either specified in the query itself or included in the query programmatically. You can use prefix matching with the wildcard operator(*).
Suffix matching is not supported.
A search for "search ba" displaying results that match this prefix*
A search for "tags:design" scoping down results to items with "design" in the tags property
If a property is retrievable, its value can be returned in search results. Any property that you want to add in the display template or be returned from the query and be relevant in search results must be retrievable. Marking large properties, such as
editHistory, or too many properties as retrievable will increase search latency. Be selective and choose relevant properties.
A set of retrievable properties (
lastEditedBy etc.) rendered as a result
If a property is refinable, an admin can configure it as a custom filter in the Microsoft Search results page.
Refine results by
tags, a refinable property
A label is a well known tag published by Microsoft that you can add against a property in your schema. Adding a label helps various Microsoft products understand the property and provide a better experience.
|title||The title of the item that you want shown in search & other experiences|
|url||The target URL of the item in the data source|
|createdBy||Name of the person who created the item in the data source|
|lastModifiedBy||Name of the person who most recently edited the item in the data source|
|authors||Name of all the people who participated/collaborated on the item in the data source|
|createdDateTime||Date & time that the item was created in the data source|
|lastModifiedDateTime||Date & time the item was last modified in the data source|
|fileName||In case of a file, the name of the file in the data source|
|fileExtension||In case of a file, the extension of the file in the data source|
For example, the connection property lastEditedBy has the same meaning as the Microsoft label lastModifiedBy.
Add as many labels as you can, but ensure that they are accurately mapped to properties. Do not add a label to a property if it doesn't make sense. Incorrect mappings will deteriorate the experience.
All properties that you map to labels must be retrievable.
By applying as many accurately mapped labels as possible, you can also improve the discovery of your content through search. We highly recommend defining as many of the below labels as possible, listed by potential impact on discovery in descending order:
For discovery, i.e. search scenarios, please note:
- Ensure that your mappings are accurate.
- When you use a property as label that contains large content, you might increase search latency and have to wait longer for search to return results.
- Especially in the scenario where you configure a custom vertical that allows search over more than one connection, the search outcomes greatly benefit from appointing as many labels as possible.
Default result types
Labels also affect how default result types are generated. Adding the title and content labels at a minimum will ensure that a result type is created for your connection.
A default result type with
title and a result snippet
Your default result type will provide a better experience when you define these labels, when applicable, listed by ascending order:
Finally, when assigning labels, ensure the following:
- The properties that you select to function as labels need to be marked retrievable.
- The properties and their assigned labels must have the same datatype.
- You can map exactly one label to exactly one property.
Aliases are friendly names for properties that you assign. These will be used in queries and selections in refinable property filters.