Home›Workplace Search›SharePoint native connector

SharePoint native connector

Discover and synchronise SharePoint content into Interact's search index with permissions applied.

Overview

The SharePoint native connector can automatically discover and synchronise content from the common SharePoint areas:

  • Site collections
  • Sites
  • Site drives (document libraries)
  • Site drive items (files and folders)
  • Lists
  • List items
  • List item attachments

The configuration gives you granular control over what is synchronised, so you can filter what reaches the search index and is therefore discoverable by users in search. By default, permissions are applied to all synchronised content (users, groups, and so on).

You can also display synchronised content in content widgets and Content Listing Blocks. An advanced filter lets you filter the content further for display purposes, including directory-level filters. All content remains discoverable via search if users have permission to see it.

For details on how to configure the connector, see Config.

Security

What is synchronised

Content is synchronised to the search index for search discoverability only. This ensures that a search can run across the relevant fields of synchronised documents (title, description, content).

The connector synchronises only the SharePoint sites specified in the config. You can also select which lists or document libraries to include from each configured site. The connector does not synchronise personal OneDrives.

What is viewable

Only the basic synchronised information, such as title and summary, is shown in search results within search, content widgets, and Content Listing Blocks. Users cannot load the entire document content within the intranet. When a user selects a result, they are directed to the external system, which performs its own security checks before any document is accessed.

SharePoint permissions (groups, shares)

Users cannot see synchronised documents in search, content widgets, or Content Listing Blocks that they do not have access to in SharePoint.

Permissions are applied to synchronised SharePoint content so that it behaves the same way as when the content is accessed directly in SharePoint. Within the intranet quick search, general search, content widgets, and Content Listing Blocks, users see only the content they could see and open in SharePoint. This includes content shared explicitly with them or with a group they belong to.

Microsoft APIs

Most of the HTTP requests use the Graph API. Not all required functionality is available through the Graph API alone, so the connector also makes REST requests to the SharePoint API to:

  • Identify whether a site has unique role assignments or inherits them, and fetch the role assignments (groups, users) for each synchronised site.
  • Identify whether a site list has unique role assignments or inherits them, and fetch the role assignments for each synchronised list.
  • Identify whether a site list item has unique role assignments or inherits them, and fetch the role assignments for each synchronised list item.
  • Identify whether a site page has unique role assignments or inherits them, and fetch the role assignments for each synchronised page.
  • Fetch a list of site list item attachments.
  • Download site list item attachments.
  • Fetch a list of site pages.
  • Identify which users are part of a site group role assignment.

Encrypted credentials

The credentials of a connector are encrypted on save using current recommended encryption algorithms and best practices. Once saved and encrypted, the credentials (encrypted or unencrypted) cannot be retrieved by any end user, Power User, or administrator. For more details, see Credentials.

Specifying which content to synchronise

A SharePoint native connector has many configuration options that let you fine-tune which content is synchronised.

For sites, you can synchronise All sites or a list of Specific sites only. If you choose All, you can also explicitly exclude specific sites.

For any synchronised site, you can also choose which drives (document libraries) or lists to synchronise. As with sites, you can synchronise All (with a specific set to exclude) or Specific drives or lists.

You can configure the drive (document library) filters and the list filters at a global level, so they apply to all sites automatically. You can also combine global filters with overrides for specific sites.

You cannot currently filter which files from a drive (document library) or list items from lists are synchronised. If a drive or list is configured to synchronise, all of its items are synchronised. This additional level of filtering is planned for a future release.

General search filters and taxonomy

For synchronised content, a set of default taxonomy values is recorded automatically. When configured, these allow additional filters in general search, and let you use the taxonomy values in the advanced filter in the content widget and Content Listing Block.

For lists and their list items, you can also synchronise data from custom columns into taxonomy values, so they can be used in the general search filter and the advanced filter of the content widget and Content Listing Block.

Taxonomy values

Content type

By default, synchronised entities have one of the following content type taxonomy values set, depending on their type:

  • Site Collection
  • Site
  • Site Drive
  • Site Drive File
  • Site Drive Folder
  • Site List
  • Site List Item
  • Site List Item Attachment
  • Site Page

You can customise the text labels for these types using the SharePoint connector config.

Additional taxonomy

For synchronised content, the following additional taxonomy values are also stored where relevant:

  • Site Collection
  • Site
  • Site Drive
  • Site List
  • File Extension
  • Directory

You can customise the text labels for these additional taxonomy values using the SharePoint connector config.

Icons

Default SharePoint-style icons are used for synchronised content:

  • Site Collection
  • Site
  • Site Drive
  • Site Drive File (can be customised per extension)
  • Site Drive Folder
  • Site List
  • Site List Item
  • Site List Item Attachment (can be customised per extension)

All files use the same icon by default, but you can override this and define custom icons for different file extensions in the SharePoint connector config.

Sync mechanisms for different types

Different entity types are synchronised in different ways, as supported by Microsoft Graph and the SharePoint REST API.

Drive items are synchronised using a delta URL, which reports any changes since the last synchronisation session. The delta URL is stored in the synchronised state of the associated drive.

Note: It is also possible to synchronise list items by delta, but that feature is only in beta for Microsoft Graph, so it is not yet implemented for the Workplace Search SharePoint connector.

Delta considerations

When you perform a delta request (either an initial or a follow-up delta), the response can include the same content multiple times. This is documented behaviour in the Graph API spec, so the synchronisation process handles it by taking only the last document as the most recent one.

Delta synchronisation is in production mode for drive items and has been in beta mode for list items for some time. For list items, there is the added complexity of handling attachments, so these considerations would need to be investigated and verified before implementing deltas for list items.

Handling invalidated delta URLs

The Graph API docs indicate that an existing delta URL could become invalid at any time, returning a 410 Gone response. If this happens, a full resync of all child drive items is required.

To do this, a connector can forcibly update all of its children (using the materialised path) to use Session deletion mode rather than Explicit. This bypasses the usual mechanism for updating synchronisation state and allows synchronisation to continue from where it failed.

After a full resync of the drive items, any synchronised drive items automatically have their deletion mode set back to Explicit. Any that were not synchronised remain in Session deletion mode and are correctly deleted at the end of the synchronisation session.

Features

  • Handling of 410 error responses
  • Handling of throttling, appropriate delays (from the header) and retries, for both the Graph and REST clients
  • Diagnostic counters that track how many times API methods are called
  • Extensive logging
  • Highly configurable
  • Both basic and advanced (delta) synchronisation
  • List item taxonomy
  • List item avatar URL path builder (configuration)
  • Customisation of behaviours for sites and lists
  • Default population of avatar asset IDs based on file extensions

Creating an Azure OAuth app and SharePoint

The SharePoint native connector uses both the Microsoft Graph API and the SharePoint REST API. For more information, see Azure OAuth app and SharePoint.

Domain mapping

If your SharePoint is configured with a different domain than the one associated with your intranet and users, you can configure a domain replacement. During user synchronisation, when a SharePoint user is matched with a user in the intranet, the email address is altered, only for the purpose of user lookups, based on this configured domain replacement.

Next steps

Section: Workplace Search