API ReferenceProduct Documentation
Product Documentation
Start typing to search…

Tetra Egnyte Connector User Guide (v1.0.x)

This guide shows how to use Tetra Egnyte Connector versions 1.0.x. The Connector is a containerized application that uses the Pluggable Connector Framework to monitor Egnyte software folders for new and modified files, and then upload them to the Tetra Data Platform (TDP).

Prerequisites

The Tetra Egnyte Connector requires the following:

  • Active Egnyte account
  • A valid client ID and client secret for an app defined in the Egnyte developer portal (contact your customer account leader to get help setting this up)
  • Access to an Egnyte login with sufficient permissions to ingest files

Create a Tetra Egnyte Connector

To create a Tetra Egnyte 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 Egnyte Connector.
📘

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

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

Configuration Parameters

The Tetra Egnyte Connector requires the following configuration parameters.

Base Egnyte URL

  • Parameter Name: base_egnyte_url
  • Type: String
  • Required: Yes

The base URL for your Egnyte instance, including the protocol.

Example: https://acme.egnyte.com

Client ID

  • Parameter Name: client_id
  • Type: String
  • Required: Yes

The OAuth client ID (also referred to as "API key") from the Egnyte developers portal. This is used for OAuth authentication with Egnyte.

Client Secret

  • Parameter Name: client_secret
  • Type: String (Secret)
  • Required: Yes

The client secret from the Egnyte developers portal. This is used along with the client ID for OAuth authentication.

📘

NOTE

The client secret is stored securely and will not be visible after initial configuration.

Polling Interval

  • Parameter Name: polling_interval
  • Type: Number (integer)
  • Required: No
  • Default: 5 minutes

How often the Connector checks Egnyte for new or updated files, specified in minutes. Must be between 1 and 1440 minutes (24 hours).

Destination ID

  • Parameter Name: destination_id
  • Type: String (UUID)
  • Required: No

If provided, uploaded file paths will use this ID instead of the Connector's native ID. This is useful for maintaining consistent file paths when migrating from another Connector or data source.

Scan Paths

  • Parameter Name: scan_paths
  • Type: Array of JSON objects
  • Required: No

Advanced file filtering and labeling configurations. When configured, files are matched against path configurations to determine if they should be uploaded and how they should be labeled.

Each path configuration object contains the following fields:

  • path: Folder path to scan in Egnyte (for example, "/data" or "/Shared/experiments/")
  • file_pattern: Glob pattern for file names (for example, "*.txt", "experiment_*", or "*" for all files)
  • metadata_only (optional): If true, only file metadata is uploaded to TDP instead of full file contents. Defaults to false
  • labels (optional): Custom labels to apply to matching files (each label needs name and value fields)

Matching Behavior:

  • A file's path must start with the configured path (when terminated with /) to match
  • The filename must match the glob pattern specified in file_pattern
  • Empty strings for path or file_pattern match everything
  • When multiple path configurations match a file, labels from all matching configurations are applied
  • A file is uploaded in metadata-only mode if and only if all matching path configurations have metadata_only set to true
  • Files that don't match any path configuration are not uploaded (if scan_paths is configured)
  • If scan_paths is not configured or empty, all files are uploaded with full content

Example Configuration:

{
  "base_egnyte_url": "https://acme.egnyte.com",
  "client_id": "your-client-id-here",
  "client_secret": "your-client-secret-here",
  "polling_interval": 10,
  "scan_paths": [
    {
      "path": "/Shared/data",
      "file_pattern": "*.txt",
      "metadata_only": true,
      "labels": [
        {
          "name": "experiment",
          "value": "project-123"
        }
      ]
    },
    {
      "path": "/Shared/logs/connector",
      "file_pattern": "*",
      "metadata_only": false,
      "labels": [
        {
          "name": "data_type",
          "value": "logs"
        }
      ]
    }
  ]
}

For more details on path configurations and label restrictions, see the Tetra Egnyte Connector artifact's README documentation. To access the README, see View Connectors and Their Details.

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.

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.

Access Data

Using the polling interval set in configuration, the Connector periodically queries Egnyte to discover new or modified files since the last poll. The Connector uses Egnyte's Events API to efficiently track file changes without scanning the entire file system.

📘

NOTE

The connector only processes files from specific Egnyte event types: create, update, and copy. Other event types (such as move, delete, or rename) are not currently supported.

When new or modified files are detected, the Connector marks them in its internal data store as pending upload. These files become visible from the Connector's page as files with status PENDING. During each polling interval, the Connector processes pending files and uploads them to the TDP. Successfully uploaded files are marked as SUCCESS and failed uploads are marked as ERROR.

Files are uploaded to the TDP with the following metadata:

  • Original file path from Egnyte
  • File size and checksum
  • Last modified timestamp
  • Any configured labels from path configurations
  • Egnyte entry ID and group ID for tracking

After upload, you can access files through the TDP Search page or through the TetraScience API using standard file search and retrieval methods.

Checksums

As described in the Egnyte documentation, Egnyte provides checksums for its files. These are either hex encoded SHA-512 strings, or a custom format based on combining SHA-512 from individual parts of an upload. Because this formatting differs from how the TDP and Amazon S3 implement checksums, the Egnyte checksum is not directly comparable to what is in the TDP.

The Connector does perform a running verification of the Egnyte checksum while uploading to the TDP. For each file, there will be a log entry indicating that the checksum was verified. If the Connector does not match the Egnyte checksum while uploading, it will mark the file transfer as failed with an error message indicating that the checksums failed to match.

Custom Commands

The Tetra Egnyte Connector supports custom commands that can be sent through the TetraScience Command Service or through the Connector's page in the TDP user interface. These commands allow you to manage file processing programmatically.

Mark File as Skipped

Action: TetraScience.Connector.Egnyte.MarkFileSkipped.v1

The Mark File as Skipped command provides the ability to mark a specific file version as SKIPPED to prevent it from being processed by the Connector through the TetraScience Command Service.

Use Cases:

  • Skip corrupted or invalid files
  • Exclude files that should not be processed
  • Temporarily skip files pending fixes or updates

Behavior:

  • Only files with status PENDING or ERROR can be marked as SKIPPED.
  • If both full file and metadata-only entries exist for the same entry_id (due to configuration changes), both will be marked as SKIPPED.
  • Files marked as SKIPPED will not be processed during subsequent Connector runs.

Required Payload Fields

  • entry_id (string): The Egnyte entry ID (version identifier) for the file to skip. This is Egnyte's unique identifier for a specific version of a file.
  • reason (string, optional): Optional reason for skipping the file, stored in file metadata for audit trail (for example, "Corrupted file, waiting for re-upload")

How to Get the entry_id:

The entry_id is Egnyte's unique identifier for a specific version of a file. You can obtain it in two ways:

Method 1: Egnyte Web UI

  1. Navigate to the file in Egnyte.
  2. Right-click the file. Then, select Properties.
  3. Go to the Versions tab.
  4. Click "Copy version ID" for the version you want to skip.
  5. The copied value is the entry_id.

Method 2: Egnyte API

  • Call GET /pubapi/v1/fs/{path} where {path} is the file path.
  • The response includes an entry_id field.

For more information about using the Egnyte Links API, see the Egnyte Links API documentation.

Example Payload:

{
  "targetId": "your-connector-id",
  "action": "TetraScience.Connector.Egnyte.MarkFileSkipped.v1",
  "payload": {
    "entry_id": "2c8e1083-47f8-4d57-94dc-fd05429b7ec3",
    "reason": "Corrupted file, waiting for re-upload"
  }
}

Example Response:

{
  "success": true,
  "message": "File marked as SKIPPED for entry_id: 2c8e1083-47f8-4d57-94dc-fd05429b7ec3",
  "entry_id": "2c8e1083-47f8-4d57-94dc-fd05429b7ec3",
  "records_updated": 1,
  "updated_records": [
    {
      "file_id": "12345",
      "unique_external_id": "2c8e1083-47f8-4d57-94dc-fd05429b7ec3",
      "filepath": "/Shared/data/experiment.txt",
      "previous_status": "PENDING"
    }
  ],
  "new_status": "SKIPPED",
  "reason": "Corrupted file, waiting for re-upload"
}

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.

Updated about 23 hours ago