The following procedure shows how to programmatically notify the Tetra OpenLab Agent to configure a project by using the Configure Project command and the Tetra Data Platform (TDP) Command Service.

Prerequisites

To run the Project Configuration command, you must have the following:

• A running Tetra OpenLab Agent v1.0.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 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 OpenLab 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).

For more information, see Enter TDP Connection Settings in the Tetra OpenLab Agent Installation Guide.

Step 2: Run the Project Configuration Command

To run the Tetra OpenLab 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.

After the Agent receives the Configure Project command, it does the following:

• Connects to OpenLab and authenticates by using the configured credentials
• For each project in the payload, the Agent does the following:
  • Retrieves the project information from OpenLab
  • Updates the project configuration in the Agent's database and triggers any necessary actions
  • Raises events for successful or failed project configuration updates

For an example response, see the Command Response section.

Command Structure

The Project Configuration command uses the following structure:

{
  "targetId": "7659ef3a-95e9-4e4c-9742-eaf18e4a8af8",
  "action": "TetraScience.Agent.openLab.ConfigureOpenLabProjects",
  "expiresAt": "2025-12-31T23:58:43.749Z",
  "payload": {
     "projects": [
            {
                "project_name": "241023_1207_clean",
                "is_enabled": true
            },
            {
                "project_name": "tetra project group 1\\test project jason 4",
                "is_enabled": false
            },
            {
                "project_name": "tetra project group 2\\openlab sample project",
                "is_enabled": false
            }
        ]
  }
}

Project Configuration Command Example

🚧

IMPORTANT

You must enter values for the following variables:

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

curl --location --request POST 'https://api.tetrascience.com/v1/commands' \
--header 'ts-auth-token: <JWT Token>' \
--header 'x-org-slug: <Your Org Slug>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "targetId": "<Agent ID>",
  "action": "TetraScience.Agent.openLab.ConfigureOpenLabProjects",
  "expiresAt": "2025-12-31T23:58:43.749Z",
  "payload": {
    "projects": [
       {
                "project_name": "241023_1207_clean",
                "is_enabled": true
            },
            {
                "project_name": "tetra project group 1\\test project jason 4",
                "is_enabled": false
            },
            {
                "project_name": "tetra project group 2\\openlab sample project",
                "is_enabled": false
            }
    ]
  }
}'

Request Body Data Fields

Command Response

When the command runs successfully, it returns a Success status with the following message:

{
  "message": "TetraScience.Agent.openLab.ConfigureOpenLabProjects is executed successfully."
}

If the command runs successfully, but some of the projects can't be found, it returns a Success status with the following message:

{
  "message": "TetraScience.Agent.openLab.ConfigureOpenLabProjects is executed successfully: openlab test project is not found in the Agent."
}

If the command fails, it returns a Failure status with the following error message:

{
  "message": "Total 1 error occurred",
  "validationErrors": [
    {
      "key": "projects[0]",
      "error": "Required properties are missing from object: project_name",
      "value": "Required",
      "errorCode": "CommandSchemaValidationError"
    }
  ]
}

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.