To set up a Tetra SharePoint Online Connector v1.x, do the following.

Prerequisites

• SharePoint Online Sites and corresponding document libraries are created and ready
• Tetra Data Platform (TDP) version 3.6 or higher
• A Microsoft enterprise application with credentials that the Connector can use along with authorization permissions to access files and their metadata in SharePoint Online sites
• (Optional) Tetra Hub. Although typically unnecessary because SharePoint Online and the TDP are cloud services, it is possible to deploy the Tetra SharePoint Online Connector as a standalone service to a Tetra Hub for on-premises networking requirements. If deployed to a Tetra Hub, internal networking/firewalls rules to allow communication between the Connector and the Hub must be configured. For more information, contact your customer success manager (CSM).

Create a Microsoft Enterprise Application

Before Running the connector, a Microsoft Entra identity platform administrator needs to create an enterprise application for the Connector. For instructions, see the Demo - Create Azure AD app to submit requests to Microsoft Graph video on the Microsoft 365 Developer YouTube channel.

The Connector uses Microsoft application permissions for authorization. You must ensure that the enterprise application credentials used by the Connector have the necessary permissions to transfer data between SharePoint Online and the TDP.

To maintain a strong security stance, consider using the least-privileged permissions required to access the following endpoints:

📘

NOTE

It's recommended that you apply Sites.Read.All for SharePoint and Files.Read.All permissions to use the following, required Graph API endpoints.

• Send delta queries to a drive item
• Get driveItem info
• Get listItem info
• Download contents of a driveItem

For more information about how to make sure that your Connector supports the OAuth 2 Client Credentials flow, see Get access without a user in the Microsoft documentation.

📘

NOTE

It's recommended that you dedicate a new enterprise app for each Connector. Creating a dedicated enterprise app for the Connector simplifies troubleshooting, reduces the component's security footprint, and reduces the risk of API throttling by SharePoint Online.

Create a Tetra SharePoint Online Connector

To create a Tetra SharePoint Online Connector, do the following:

1. Sign in to the TDP. Then, in the left navigation menu, choose Data Sources and select Connectors. The Connectors page appears.
2. Follow the instructions in Create a Pluggable Connector. For CONNECTOR TYPE, make sure that you select the most recent connector version in common > SharePoint Online.

📘

NOTE

After the Connector is created, the initial MODE status is set to IDLE by default. To activate the Connector, you must configure its settings. For instructions, see the Configure the Connector section.

Configure the Connector

📘

NOTE

Connector configuration parameters can vary between connector versions. It's recommended that you refer to the Connector's README file in the TDP for specific configuration details.

On the Connectors page, select the name of the Connector that you created. Then, select the Configuration tab to configure the required settings.

For more information about the required parameters and best practices for configuring them, open the latest SharePoint Connector version’s README file in the TDP. For instructions, see View Connectors and Their Details.

Saving the Connector configuration prompts the Connector to update and re-establish a polling interval. The first poll will occur after an initial, configured polling interval is complete.

Review and Edit the Connector's Information

The Information tab on the Connector Details page displays information about the Connector, the files pending, successfully uploaded, or failed. It also provides functionality to edit a Connector’s information, metadata, and tags.

To edit the Connector's information, select the Edit button on the Connector Details page's Information tab.

For more information, see Review and Edit a Pluggable Connector's Information.

Set the Connector's Status to Running

Set the Connector's status to Running by following the instructions in Change a Pluggable Connector's Status.

The Connector will be assigned a command to switch to RUNNING mode, and it will begin by polling all folders specified in its configuration. Depending on the number and size of folders in SharePoint Online, this may take anywhere from a few seconds (in the case of a few small files in a few folders) to potentially hours (in the case of many large files in many folders). As files are uploaded from SharePoint to the TDP, the file uploads table begins to populate with file processing statuses. A file upload with a SUCCESS status indicates that it was uploaded to the TDP. An icon linking to the File Details page of each uploaded file becomes visible when you hover over the status.

To pause data upload from SharePoint, select the Set to Idle or Disable button. Setting the Connector's status to IDLE stops the Connector from polling. Disabling the Connector turns off the Connector completely and prevents the user from updating the configuration until the Connector is re-enabled as RUNNING or IDLE.

📘

NOTE

TDP reports the Connector as Offline until it registers several connector heartbeats in the platform. After a few minutes of heart beats, the TDP indicates that the Connector is Online. The Connector is Offline when disabled or experiencing network issues with the TDP. An initially created Connector starts in IDLE mode until it is configured and set to RUNNING. IDLE Connectors do not upload files from SharePoint Online to the TDP.

Monitor the Connector's Health

The Connector regularly reports its health status and provides diagnostic messages to help with troubleshooting during events, such as the following:

• Receiving a new configuration and authenticating with SharePoint Online
• Experiencing an error that interrupts a folder poll
• After assessing the outcomes of polling all folders

To check the Connector's health status, see Review and Edit a Pluggable Connector's Information. For detailed troubleshooting information related to specific diagnostic messages, see your Connector version's README file in the TDP. To access the README file, see View Connectors and Their Details.

Monitor File Uploads

The Connector uploads all new file changes returned by a Microsoft Delta Query. File uploads are displayed in the Files table on the Connector's Information tab, where a row in the table corresponds to a file version from SharePoint Online that was uploaded to the TDP.

Files can have the following statuses:

• SUCCESS: The file was uploaded to the TDP. Hovering over the status displays an icon that provides a link to the uploaded file's File Details page.
• PROCESSING: The file is being uploaded to the TDP.
• PENDING: The file has been discovered in SharePoint Online and will be uploaded by the Connector.
• ERROR: An issue prevented upload of the file version to the TDP. A descriptive message will be provided by the Connector when this status occurs. The Connector will also attempt to upload the file up to three times before leaving the file in ERROR status. Updating the file or its metadata in SharePoint Online will create a new file version for upload to the TDP.

Metrics

After a Connector instance is created and running, you can monitor the Connector’s health by selecting the Metrics tab on the Connector Details page. The Metrics tab displays the Connector's container metrics as well as aggregated states on total files scanned and uploaded as well as files that returned errors or are pending.

For more information, see Monitor a Pluggable Connector's Metrics.

Limitations

The following are known limitations of the Tetra SharePoint Online Connector v1:

• The Connector retrieves the latest file version at the time of polling. This means that multiple edits made in SharePoint between polls may be represented as a single file version in the TDP.
• If files in SharePoint Online are renamed or moved, then the file version is uploaded as a distinct file at a new file path in the TDP.
• The Connector does not support polling the root directory of a document library.
• If multiple sourcePaths in the Connector configuration have overlapping paths, files found in multiple sourcePaths may be uploaded with the sourceType and labels of an arbitrary source path.
• The Connector only supports polling the default document library of a SharePoint site.
• The Connector uploads checksums from Sharepoint's Graph API to the TDP, but does not verify the SharePoint quickXorHash hash. Customers seeking additional data integrity verification may verify the hash by using a code snippet like the one found in Code Snippets: QuickXorHash Algorithm in the Microsoft documentation.
• Syncing a large SharePoint document library may risk exceeding Microsoft Graph API limits. If the Connector reaches a daily limit, polling may be paused for up to a day because of SharePoint throttling. The Connector will broadcast throttling as a change in health status and a descriptive error. Because of this throttling risk, customers should carefully plan their Connector deployments and manage their enterprise application access credentials. For more information about SharePoint throttling, see Avoid getting throttled or blocked in SharePoint Online in the Microsoft documentation.
• The Connector will try to upload a file version from SharePoint three times before marking the upload as failed. Once a file version is marked as failed, the Connector will not attempt to re-upload it. If an upload error occurs, users can resolve the issue and perform actions like delete and restore the file, change file contents, update SharePoint document library metadata, move the file to a new directory, or rename the file to increase the file version and permit a re-upload of the file to the TDP.