The following procedure shows how to configure Empower project settings programmatically by using the Tetra Empower Agent and the Tetra Data Platform (TDP) Command Service.

To configure Empower project settings directly from the TDP user interface, see Configure Empower Project Settings from the TDP UI.

📘

NOTE

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

Prerequisites

The Tetra Empower Agent Project Configuration 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 Configuration Command

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

1. Create a valid Create Command in your code editor by using the following Project Configuration 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 Configuration Command, the Agent will apply the specified settings to projects currently monitored by the Empower Agent. After the Agent successfully configures the project entries stored in the Empower Agent database, the Agent then sends a SUCCESS status back to the TDP.

Project Configuration 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.ConfigureProjects",    
  "expiresAt": "2024-12-31T23:58:43.749Z",
  "payload": {
      "database_name":"wat12",
      "projects": [
       {
                "project_path": "A166078",
                "is_enabled": "false",
                "user_defined_priority": "Normal"
       }, 
       {
                "project_path": "2D_8\\2D_21",
                "is_enabled": "yes",
                "user_defined_priority" : "high",
                "sign_off_result_option": "Sign Off Level 1",
                "three_d_ms_method": "Get Spectra"
        }
      ]
    }
}

Request Body Data Fields

Including the Project Configuration Command in Task Scripts

To have the Project Configuration 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 Configuration 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 Configuration 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 Configuration Command under any of the following conditions: