Create, update, and delete connections in the Microsoft Graph

Connections from external services to the Microsoft Search service are represented by the externalConnection resource in Microsoft Graph.

Important

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 Microsoft Graph connectors platform offers a simple way to add your external data into the Microsoft Graph. A connection is a logical container for your external data that an administrator can manage as a single unit.

Once a connection has been created, you can add your content from any external data source such as an on-premises content source or an external SaaS service. You can only view and manage the connections you created or were explicitly authorized to manage. A search admin can view and manage all the connections in the tenant from the Modern Admin Center.

Sample custom helpdesk system Tickets Connector Structure

Sample custom helpdesk system Tickets Connector Structure

Admin View of Connections including the custom Tickets Connector

Admin View of Connections including the custom Tickets Connector

You can model a connection anyway you want, but creating one connection for every instance of your connector is the most common model. For example, each time you set up the Microsoft Windows file share connector, a new connection is created. You can also create a single connection to add all items from your data source. For example, creating a single connection to add all the tickets and incidents across multiple teams from your helpdesk system.

States and operations

Your connection can exist in one of the following states.

State Description
Draft An empty connection is provisioned. The data source, schema, or any settings have not been configured yet.
Ready The connection is provisioned with registered schema and is ready for ingestion.
Obsolete This occurs when a dependent feature, such as an API, has been deprecated. Deleting the connection is the only valid operation.
LimitExceeded If you hit the maximum limit of a single connection or the tenant level quota across all connections, you cannot add more items until you exit the state.

The following table specifies which operations are available in each state.

Operation Draft Ready Obsolete LimitExceeded
Create connection ✔️ ✔️
Read connection ✔️ ✔️ ✔️ ✔️
Update connection ✔️ ✔️ ✔️
Delete connection ✔️ ✔️ ✔️ ✔️
Create schema ✔️
Read schema ✔️ ✔️ ✔️
Update schema
Delete schema
Create item ✔️
Read item ✔️ ✔️ ✔️
Update item ✔️ ✔️
Delete item ✔️ ✔️

A connection allows your application to define a schema for items that will be indexed, and provides an endpoint for your service to add, update, or delete items from the index. Creating a connection is the first step for an application to add items to the search index.

Create a connection

Before an application can add items to the search index, it must create and configure a connection using the following steps.

Important

After a schema has been registered, it cannot be changed for an existing connection.

Update a connection

You can change the display name or description of an existing connection by updating the connection.

Delete a connection

You can delete a connection, and remove all items that were indexed via that connection.

Next steps