Configure an external connection and deploy schema

  • 3 minutes

In this unit, you learn how to configure a Microsoft Entra app registration for use with a custom Graph connector. You also learn how to create an external connection and configure a schema for importing external content.

Configure Microsoft Entra app registration

To import external content to Microsoft 365, a Graph connector needs an external connection and a schema. A custom Graph connector uses Microsoft Graph APIs to create the external connection and deploy the schema. To communicate with Graph APIs, it authenticates with Microsoft 365 using a Microsoft Entra app registration. Typically, Graph connectors are apps that run without user interaction. To let connectors create the connection, deploy the schema, and ingest external content, you grant them the following application permissions:

  • ExternalConnection.ReadWrite.OwnedBy – which allows the connector to create the connection and deploy the schema,
  • ExternalItem.ReadWrite.OwnedBy – which allows the connector to ingest external items

Both permissions allow the connector to only access the connection and items it owns, which is the recommended security practice.

Create an external connection

A custom Graph connector creates an external connection using the External connection Microsoft Graph endpoint. When creating a connection, you need to specify its ID, name, and description. The ID must be unique in your Microsoft 365 tenant and be between 3 and 32 characters long. The following code snippet shows how to create an external connection:

using Microsoft.Graph.Models.ExternalConnectors;

var requestBody = new ExternalConnection
{
  Id = "msgraphdocs",
  Name = "Microsoft Graph documentation",
  Description = "Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.",
};

await graphClient.External.Connections.PostAsync(requestBody);

Deploy the schema

After you create an external connection, the next step is to deploy the schema. The schema consists of one or more properties. For each property, you need to specify its name and type of data that it stores. You can also define whether its data should be used for full-text search and sorting. Finally, you can add one or more semantic labels, that help Microsoft 365 understand what information the property represents. Copilot for Microsoft 365 requires an external connection to define in its schema at least the title, url, and iconUrl semantic labels. The following code snippet shows how to deploy a schema:

using Microsoft.Graph.Models.ExternalConnectors;

var schema = new Schema
{
  BaseType = "microsoft.graph.externalItem",
  Properties = new()
  {
    new Property
    {
      Name = "title",
      Type = PropertyType.String,
      IsQueryable = true,
      IsSearchable = true,
      IsRetrievable = true,
      Labels = new() { Label.Title }
    },
    new Property
    {
      Name = "iconUrl",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.IconUrl }
    },
    new Property
    {
      Name = "url",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.Url }
    },
  }
};

await graphClient.External
  .Connections["{externalConnection-id}"]
  .Schema
  .PatchAsync(schema);

Deploying an external connection schema is a long-running operation that takes anywhere between 5 and 15 minutes. To know when the provisioning is finished and the connection is ready to use, retrieve information about the connection and check its status. If the connection isn't ready yet, wait 1 minute before checking its status again.

do {
  var externalConnection = await GraphService.Client.External
    .Connections["{externalConnection-id}"]
    .GetAsync();

  if (externalConnection?.State != ConnectionState.Draft)
  {
    break;
  }

  await Task.Delay(60_000);
}
while (true);