Command Service

You can communicate with on-premises Tetra Integrations programmatically by using the TetraScience Command Service. The Command Service can streamline operations and improve efficiency, because it helps scientists initiate commands to instruments without needing to manually interact with them. Instead, the Tetra Data Platform (TDP) can interface with the instrument by using a REST API call to make the request.

How the Command Service Works

The Command Service creates and sends commands to Tetra Integrations, listens for command updates from integrations, and tracks all changes and responses. It also provides the ability to search for commands and view command history either through the TDP user interface or Command Service API endpoints.

After the API request is sent, the Tetra Integration implements logic to receive commands, run them, and send the response back to the Command Service.

Activate the Command Service

For Tetra Agents

To activate an Agent’s Command Service queue, see Enable the Agent’s Queue.

For Pluggable Connectors

The Command service is activated automatically for Pluggable Connectors.

📘

NOTE

Legacy Connectors don’t support the Command Service.

Create Commands

Most commands are created automatically when a user takes an action in the TDP user interface.

To create custom Command Service commands, see Create command in the TetraScience API Documentation. For an example command, see Tetra File-Log Agent Copy File Command.

Manage Commands by Using the TDP UI

📘

NOTE

The following procedure shows how to manage Command Service commands by using the TDP user interface. To manage commands through the TetraScience API, see Command Service API Endpoints.

As an Admin, you can manage Command Service commands through the Commands page by doing the following:

For more information about TDP roles and their permissions, see Tetra Data Platform Roles and Permissions/Features Available by Role.

View the Commands Page

To open the Commands page, do the following:

  1. In the left navigation menu, select the hamburger menu icon. Then, choose Administration.
  2. Choose Commands. The Commands page opens and displays a list of all commands in the current organization.
TDP Commands page

TDP Commands page

Search for Commands

To search for commands, you can enter keywords into any of the following search fields on the Commands page.

📘

NOTE

If you apply multiple filters, only commands that match all of the chosen filters display.

Commands Page Search Fields

The following table describes the search fields that are available on the Commands page.

FieldDescription
TARGETShows the name and unique identifier of the integration that received the command
REQUEST ACTIONShows the action that the command invoked on the integration

For example: TetraScience.Agent.file-log.DropFile.CopyFile invokes the CopyFile action on a Tetra File-Log Agent
STATESShows each command’s status: Success, Failure, or Purged
COMMAND IDShows a unique identifier for each command
CREATEDShows when the command was created
EXPIREDShows when the command expires

View Command Details

To view a specific command’s details, do the following:

  1. On the Commands page, find the command that you want more information about.
  2. In the far right column of the command’s row, choose Details. A Command Details dialog appears.
TDP Command Details dialog

Command Details dialog

Command Details

The following table describes the information that’s available in the Command Details dialog.

SectionDescription
COMMAND IDShows a unique identifier for each command
TARGETShows the name and unique identifier of the integration that received the command
TIMEShows the date and time of the command’s status changes
DETAILSShows the command’s status changes
UPDATED BYShows if the TDP or target integration updated a given status
Command BodyShows the "body" of the command's API request
ResponseShows the command response

📘

NOTE

If a command has no response (for example, if the request's status is Pending), the Response section displays the following error:

"ERROR":{1 item
"message":"src property must be a valid json object"
}

When this error appears, command processing isn't affected and no action is needed. A fix for this issue is in development and testing and is scheduled for a future TDP release.

Purge Command Queues of Pending Commands

🚧

IMPORTANT

Purging an integration’s command queue deletes all pending commands from the selected integration.

To delete all of the pending commands from an integration’s command queue, do the following:

  1. On the Commands page, select the upper right Purge Queue button. The Purge Pending Commands dialog appears.
  2. From the Select Target drop-down menu, select an integration.
  3. Choose Purge.