The following procedure shows how to initiate scan requests for Empower projects programmatically by using the Tetra Empower Agent and the Tetra Data Platform (TDP) Command Service.

To initiate scan requests for Empower projects directly from the TDP user interface, see Initiate Scan Requests for Empower Projects from the TDP UI.

📘

NOTE

The Project Scan Command is available for Tetra Empower Agent versions 5.3.0 and higher only.

Prerequisites

The Tetra Empower Agent Project Scan Command requires the following:

• A running Tetra Empower Agent v5.3.x 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 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 Empower 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 Verify Connector Settings in the Tetra Empower Agent Installation Guide.

Step 2: Run the Project Scan Command

To run the Tetra Empower Agent Project Scan Command, do the following:

1. Create a valid Create Command in your code editor by using the following Project Scan 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.

Upon receiving the Project Scan Command, the Agent will launch a dedicated process to scan that specified project. If the Agent receives multiple commands, it will process one command at a time. After the Agent successfully completes the project scan, it then sends a SUCCESS status back to the TDP.

Project Scan 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": "caed8e22-d100-49a3-a00d-2dc0345e174b",
  "action": "TetraScience.Agent.empower.ScanProject",    
  "expiresAt": "2024-12-31T23:58:43.749Z",
  "payload": {
      "database_name":"wat12",
      "project_path": "Tetra\\A166078"      
    }
}

Request Body Data Fields

Including the Project Scan Command in Task Scripts

To have the Project Scan 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 greatly simplify creating and sending Project Scan 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.

With the pre-signed URL, you can construct the payload as described in the Project Scan Command Example and use the run_command function to send it to the Agent.

Troubleshooting

The Tetra Empower Agent will send a FAILURE status back to the TDP after it receives a Project Scan Command under any of the following conditions: