The following procedure describes how to notify the Tetra File-Log Agent of file changes when the Agent is unable to automatically detect modifications on file systems such as Dell EMC Isilon or other NAS solution.

📘

NOTE

The File Change Command is available for Tetra File-Log Agent versions 4.5.0 and higher only.

Prerequisites

The Tetra File-Log Agent File Change Command requires the following:

• A running Tetra File-Log Agent v4.5.0 or higher installed and configured with its queue enabled.
• A valid JSON Web Token (JWT) for the service user running the command. To create a JWT, see Generate a JWT for a Service User.
• Your Tetra Data Platform (TDP) organization's slug (ORG SLUG). To find your org slug, see View Organization Details.
• Access to a tool that will allow you to run REST API calls, such as curl or Postman.

Step 1: Verify That the Agent Can Receive Commands

To allow the Agent to securely receive and run commands from the TDP, do the following:

1. From the Tetra File-Log Agent Management Console, in the left navigation menu, under Menu, choose Configuration.
2. Verify that the Receive Commands toggle is set to Yes (the default value is set to No).

For more information, see Set Up the Agent Configuration in the Tetra File-Log Agent Installation Guide.

Step 2: Run the File Changed Command

To run the Tetra File-Log Agent File Changed Command, do the following:

1. Create a valid Create Command in your code editor by using the following File Changed Command Example code snippet.
2. Copy and run the updated command by using a tool that will allow you to run REST API calls, such as curl or Postman.

when the Agent receives the File Changed Command, it will start to scan the specified file paths and identify any new or modified files for upload. After the Agent successfully completes the file change action, it then sends a SUCCESS status back to the TDP.

For more information, see Command Validation.

File Changed Command Example

🚧

IMPORTANT

You must enter values for the following variables:

• ForPOST, enter https://api.tetrascience.com/v1/commands
• For x-org-slug, enter your organization's slug.
• For ts-auth-token, enter your service user's JWT.
• Make sure that you enter a valid Request body that includes all of the Required fields listed in the Request Body Data Fields table.

// POST https://api.tetrascience.com/v1/commands

// Headers:
x-org-slug: <your-org-slug>
ts-auth-token: <your-auth-token>
  
// Request body:
{
  "targetId": "<agent-id>",
  "action": "TetraScience.Agent.file-log.FileChanged",
  "expiresAt": "<command expiration datetimeoffset in ISO-8601 format, e.g. 2025-12-31T23:58:43.749Z>",
  "payload": {
    "events": [
     {
      "path": "C:\\data\\experiment1\\results.txt",
      "type": "created"
     },
     {
      "path": "C:\\data\\experiment2\\analysis",
      "type": "changed"
     }
   ]
 }  
}

Request Body Data Fields

File Changed Command Payload JSON Schema

{
  "$schema": "https://json-schema.org/2020-12/schema",
  "$id": "https://tetrascience.com/command.schema.json/v1",
  "title": "TetraScience.Agent.FileLog.FileChangedCommand body schema",
  "description": "JSON schema to send file changed events",
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "type": { "enum": [ "", "unspecified", "created", "deleted", "changed", "renamed" ] }
        },
        "required": [ "path" ]
      }
    }
  },
  "required": [ "events" ]
}

Successful Request Responses

If both schemas are valid, the TDP returns a response that contains the new generated command Id, such as the following:

{
    "id": "<new_command_id>",
    "orgSlug": "<org_slug>",
    "targetId": "<agent_id>",
    "action": "TetraScience.Agent.file-log.FileChanged",
    "expiresAt": "2025-12-31T23:58:43.749Z",   
    "status": "PENDING",
    "requestBody": {
      ...
    }
}

Failed Request Responses

If either of the schemas aren't valid, the TDP returns the following response:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Invalid request payload input"
}

To resolve common 400 errors, see the Troubleshooting section.

Including the File Changed Command in Task Scripts

To have the File Changed Command interact with task scripts you will need to use the context object. The context object provides functions for you to read files, write files, update metadata, get pipeline configuration information, and more.

The ts-sdk library provides two Context API functions that simplify creating and sending File Changed commands in task scripts:

• context.get_presigned_url: Returns a time-limited HTTPS URL that can be used to access a file.

• context.run_command: Invokes the remote command on the Agent and returns its response.

Common Usage Scenarios and Behaviors

• It can be used to notify the Agent about file changes that occurred outside of the Agent's detection mechanism, such as when files are modified by a third-party application or service.
• The Administrator can manually trigger file processing by sending the File Change Command.
• The command allows to send multiple file change events in a single command to efficiently notify the Agent about batch file changes.
• The folder path and files specified to be processed should match the glob pattern and file age criteria defined in the Agent configuration, ensuring consistent behavior between the direct monitoring and command-driven events
• If the folder path or files specified in the command cannot be found or not matching the glob pattern and file age criteria, the Agent still will return SUCCESS status back to the TDP.

Troubleshooting

The Tetra File-Log Agent will send a FAILURE status back to the TDP under any of the following conditions:

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.