API ReferenceDocumentation
Documentation

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 Tetra.

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 Tetra. 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 Tetra 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.

Include Move Events

  • Parameter Name: include_move_events
  • Type: Boolean
  • Required: No (defaults to true)

If this variable is unset or true, then the Connector will treat move as a valid action in an Egnyte event. This covers renaming and moving. Files that are moved or renamed have the path matching filters applied to both the source and destination paths, and will be ingested if any match. Similarly, decisions about labels or metadata-only status are based on all matching paths.

Authorize the Connector

Once the Connector has been configured and is online, you must authorize the connector using Egnyte's OAuth flow. The Connector provides an Egnyte Authorization tab to initiate authorization. Clicking the Connect to Egnyte button will bring up an Egnyte login. After login, you will be asked if you wish to give Egnyte access to the Connector, where the name presented for the connector will be the name of the associated app in the Egnyte portal. After agreeing, you will be redirected back to the connector page.

In version v1.0.0 of the Connector, the authorization token from Egnyte is not automatically refreshed. The token lasts for 30 days, and beginning two days from expiry the Connector will have a WARNING health status indicating that you should re-authorize. From version 1.1.0 of the Connector, the Connector features automated refresh of the token when the main access token is within 24 hours of expiry. Note: when upgrading from a previous version without automated refresh support, you will need to perform manual authentication one time to get an initial refresh token.

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. As of version v1.1.0, move (which also covers renames) is supported by default, but can be disabled. Other event types (such as delete) 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 Tetra. Successfully uploaded files are marked as SUCCESS and failed uploads are marked as ERROR.

Files are uploaded to Tetra with the following labels:

  • any labels set in the Connector page are applied to all files
  • egnyte_group_id, corresponding to a unique identifier in Egnyte for a file
  • egnyte_entry_id, corresponding to a unique identifier in Egnyte for a file version
  • egnyte_last_modified_at, a timestamp from Egnyte of when the file contents were last modified
  • egnyte_event_id, the integer identifier of the Egnyte event the Connector received corresponding to the given file version
  • any additional labels set by path configurations in the Connector configuration. All matching paths will contribute labels

After upload, you can access files through the Tetra 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 Tetra and Amazon S3 implement checksums, the Egnyte checksum is not directly comparable to what is in Tetra.

The Connector does perform a running verification of the Egnyte checksum while uploading to Tetra. 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 Tetra user interface. These commands allow you to manage file processing programmatically.

Mark File as Skipped

Action: TetraScience.Connector.Egnyte.MarkFileSkipped.v2 (from version v1.1.0)

📘

NOTE

In version v1.1.0, TetraScience.Connector.Egnyte.MarkFileSkipped.v1 will invoke the v2 command

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 8 days ago

Did this page help you?