The following procedure shows how to create or update a Sample Set Method in Waters Empower programmatically by using the Tetra Empower Agent and the Tetra Data Platform (TDP) Command Service.

A Sample Set Method is an ordered list of sample information and corresponding functions that define data acquisition. This command allows you to create a new Sample Set Method or create a new version of an existing Sample Set Method in Empower.

Prerequisites

The Tetra Empower Agent Create Sample Set Method Command requires the following:

• A running Tetra Empower Agent v5.1.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.

Empower Requirements

Before running the command, verify the following Empower requirements:

Empower Version

The current solution is compatible with Empower 3 Feature Release 2 through Empower 3.6.1.

Empower Options

The command supports all Empower options except the following:

• Dissolution system is not supported. According to Empower documentation, to create a Sample Set Method for Dissolution, you must use the Sample Set Method Wizard instead of Empower Toolkit.

Empower Project

• The project must exist in Empower. The command will not create a new project if the specified project doesn't exist.
• The project must not be locked.
• The project must not have the Confirm Identity option enabled for method changes. If enabled, the Agent will hang because it cannot handle the password prompt popup.

Empower User Account

• The Agent Empower User Account must have permission to access the specified project.
• The Empower User Account must have the Save Sample Set Method permission enabled.

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 Create Sample Set Method Command

To run the Tetra Empower Agent Create Sample Set Method Command, do the following:

1. Create a valid Create Command in your code editor by using the following Create Sample Set Method 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 Create Sample Set Method Command, the Agent will create the Sample Set Method in the specified Empower project. If a Sample Set Method with the same name already exists, Empower creates a new version of that method. After the Agent successfully creates the Sample Set Method, the Agent then sends a SUCCESS status back to the TDP.

🚧

IMPORTANT

Because Empower has various versions and options in production, the Sample Set Method payload can vary. We recommend that you run the Fetch Sample Set Method Command to fetch an existing method as a template, instead of creating the method payload from scratch.

Create Sample Set Method 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.CreateSampleSetMethod",
  "expiresAt": "YYYY-MM-DDTHH:MM:SSZ",
  "payload": {
    "project_name": "MyProject",
    "sample_set_method_name": "MySampleSetMethod",
    "lines": [
      {
        "vial": "1",
        "inj_vol": "10",
        "num_of_injs": "1",
        "sample_name": "Sample1",
        "function": "Inject Samples",
        "method_set_or_report_method": "MyMethodSet",
        "processing": "Normal",
        "dilution": "1",
        "run_time": "30",
        "sample_weight": "1",
        "blank": false,
        "custom_fields": [
          {
            "key": "ColumnName",
            "value": "MyColumn",
            "value_data_type": "string"
          }
        ],
        "components": [
          {
            "component": "Component1",
            "value": "1.0",
            "purity": "99.5",
            "units": "mg/mL"
          }
        ]
      }
    ]
  }
}

Request Body Data Fields

Sample Set Method Line Fields

The following table describes the fields available for each line in the lines array:

Custom Fields

The custom_fields array allows you to include project-specific custom fields that are not defined as top-level properties. Each custom field requires the following properties:

Example:

"custom_fields": [
  {
    "key": "ColumnID",
    "value": "10677193",
    "value_data_type": "string"
  },
  {
    "key": "PrepType",
    "value": "In-Needle Auto Additions",
    "value_data_type": "string"
  }
]

📘

NOTE

Valid boolean values include: true, false, True, and False. The values null, "", -1, 0, and 1 are not supported for boolean fields.

Component Fields

The components array defines chemical components for each Sample Set Method line:

Valid Empower Functions

The function field must contain one of the following valid Empower functions:

• Inject Standards
• Inject Samples
• Inject Controls
• Inject RF Internal Standards
• Inject Immediate Standards
• Inject Immediate Samples
• Clear Calibration
• Equilibrate
• Report
• Quantitate
• Calibrate
• Condition Column
• Purge Inj
• Purge Det
• Refresh Syringe
• Wash Needle
• Wet Prime
• Sys Prep
• Summarize Custom Fields
• Pause
• Summarize Custom Fields (Exclude Faulted)
• Summarize Custom Fields Incrementally
• Summarize Custom Fields Incrementally (Exclude Faulted)
• Export
• Inject Narrow Standards
• Inject Broad Standards
• Inject Narrow Unknowns
• Inject Broad Unknowns
• Dissolution Wait
• Compute Dissolution

Valid Processing Options

The processing field must contain one of the following values:

• Normal
• Don't Process or Report
• Don't Report
• Ignore Faults
• No Sys Suit

Data Validation and Null Values

Data Type

All data types are either string or boolean. Empower Toolkit can handle integer, float, and double values from their string representation.

Null Values Handling

The following Empower-defined null values are not allowed in the payload:

• -2147483648 (mtkNullLong)
• -50000 (mtkNullDouble, mtkNullSingle)
• -32768 (mtkNullInteger)

For optional fields, either omit the field or set it to null.

Non-English Locale Handling

If the Tetra Empower Agent is hosted on an Empower client that has a non-English (United States) locale, the string values in the JSON payload should reflect this setting.

For example, if the locale is English (Germany), Windows uses , (comma) instead of . (dot) as the decimal separator:

{
  "sample_weight": "1,00000",
  "target_mass_1": "365,10"
}

Notes for Empower v3.6.0 and Higher

Waters modified the Auto Addition options in Sample Set Method for Empower v3.6.0 and above. Auto Addition options are handled by two additional fields that can be configured in the custom_fields section:

• PrepType - for example: "In-Needle Auto Additions"
• SamplePrep - for example: "2,5.1"

Empower Audit Trail

When the Sample Set Method is created successfully, an entry is written into the Project Audit Trail. If the method is updated, the Project Audit Trail includes the version number.

If the payload is invalid, no entry is written to any Empower Audit Trails.

Including the Create Sample Set Method Command in Task Scripts

You can use the Tetra Empower Agent Create Sample Set Method Command in task scripts to automate Sample Set Method creation.

Troubleshooting

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.