The following procedure shows how to have the Tetra Chromeleon Agent programmatically create new sequences and append to existing sequences with sample information by using by using the eWorkflow Creation command and the Tetra Data Platform (TDP) Command Service.

Prerequisites

To run the eWorkflow Creation command, you must have the following:

• Chromeleon SDK 7.2.9 or higher.
• A running Tetra Chromeleon Agent v2.2.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 Chromeleon 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 Chromeleon Agent Installation Guide.

Step 2: Run the eWorkflow Creation Command

To run the Tetra Chromeleon Agent eWorkflow Creation command, do the following:

1. Create a valid Create Command in your code editor by using one of the following eWorkflow Creation Command Examples 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 eWorkflow Creation command, it does the following:

• Connects to Chromeleon and authenticates using the configured credentials
• Creates any new sequences
• Appends any new sample information to existing sequences
• Updates sample information, if needed

📘

NOTE

The Chromeleon Software Development Kit (SDK) used by the Agent sets the precedence of the settings on the eWorkflow definition higher than that of the command payload.

"Nevertheless, the eWorkflow definition has a higher priority than the context data (a definition in the eWorkflow overrides the definition in the context - see ISequenceCreationContext for detailed information)."

This means the Location specified in the command payload will not be used if the eWorkflow definition has a value for the Data Vault field on the Sequence General tab. To ensure the Sequence is created in the location specified in the command, set the Data Vault field to the empty value on the eWorkflow definition in Chromeleon.

Command Structure

The eWorkflow Creation command uses the following structure:

{
  "eworkflow": {
    "chromeleon_datavault_server": "SERVER_NAME",
    "chromeleon_datavault": "DATA_VAULT_NAME",
    "eworkflow": "EWORKFLOW_NAME"
  },
  "sequence": {
    "name": "SEQUENCE_NAME",
    "instrument": "INSTRUMENT_NAME",
    "location": "SEQUENCE_LOCATION",
    "starting_position": "STARTING_POSITION",
    "number_of_samples": 10,
    "custom_fields": [
      {
        "name": "CUSTOM_FIELD_NAME",
        "value": "CUSTOM_FIELD_VALUE"
      }
    ]
  },
  "sample_list": [
    {
      "condition": [
        {
          "column_name": "COLUMN_NAME",
          "value": "COLUMN_VALUE"
        }
      ],
      "all_injections": {
        "name": "SAMPLE_NAME",
        "position": "SAMPLE_POSITION",
        "injection_type": "INJECTION_TYPE",
        "custom_fields": [
          {
            "name": "CUSTOM_FIELD_NAME",
            "value": "CUSTOM_FIELD_VALUE"
          }
        ]
      },
      "injections_by_index": [
        {
          "index": 1,
          "name": "SAMPLE_NAME",
          "position": "SAMPLE_POSITION",
          "injection_type": "INJECTION_TYPE",
          "custom_fields": [
            {
              "name": "CUSTOM_FIELD_NAME",
              "value": "CUSTOM_FIELD_VALUE"
            }
          ]
        }
      ]
    }
  ]
}

Command Response

The command response returns information about the created sequence.

📘

NOTE

The appended field indicates if the command appended to an existing sequence (true) or created a new one (false).

Example Response

{
  "sequence": {
    "url": "chrom://server/datavault/folder/sequence.seq",
    "name": "sequence",
    "custom_fields": {
      "CustomField1": "Value1",
      "CustomField2": "Value2"
    },
    "injections": [
      {
        "name": "Sample1",
        "position": "P:A1",
        "injection_type": "Unknown",
        "custom_fields": {
          "CustomField1": "Value1"
        }
      }
    ]
  },
  "appended": false
}

eWorkflow Creation Command Examples

🚧

IMPORTANT

You must enter values for the following variables:

• ForPOST, 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.

Request Body Data Fields

The following fields are required in the command payload:

eWorkflow Definition

Sequence Definition

Optional Fields

The following fields are optional.

Optional Sequence Definition Fields

Optional Sample Update Fields

The sample_list array allows you to update sample (injection) properties after the sequence is created. Each entry in the array can contain any of the following.

Optional Sample Update Conditions

The condition array allows you to specify criteria for matching injections. Each condition consists of the following fields.

For example, to match injections with a specific position, you could use the following condition array:

"condition": [
  {
    "column_name": "Position",
    "value": "P:A4"
  }
]

You can specify multiple conditions, and all conditions must match for an injection to be updated.

Supported Field Types

The eWorkflow Creation command supports updating various field types for injections. The command supports the following field types.

Standard Injection Properties

These are built-in properties of Chromeleon injections:

Common injection properties include the following:

• name: The name of the injection (String)
• position: The position of the injection (String)
• injection_type: The type of injection (Enum - can be specified as a string or integer)
• injection_volume: The injection volume (Numeric)
• weight: The sample weight (Numeric)
• dilution_factor: The dilution factor (Numeric)
• istd_amount: The internal standard amount (Numeric)
• comment: A comment for the injection (String)

Custom Fields

Custom fields can be updated by using the custom_fields array. The command supports the following custom field types.

📝

NOTE

For DateTime custom fields, the value must include a timezone offset (Z for UTC, or +/-HH:MM). For example, "2025-03-19T20:43:07Z" or "2025-03-19T16:43:07-04:00".

Updating All Matching Injections

The all_injections object allows you to specify updates that should be applied to all injections that match the conditions.

The following is an example of the all_injections object:

"all_injections": {
  "name": "Standard",
  "injection_type": "CalibrationStandard",
  "injection_volume": 10.5,
  "custom_fields": [
    {
      "name": "CustomDateField",
      "value": "2025-03-19T20:43:07Z"
    }
  ]
}

Updating Specific Injections by Index

The injections_by_index array allows you to update specific injections by their index. The index is 1-based, meaning the first injection has an index of 1.

The following is an example of the injections_by_index array:

"injections_by_index": [
  {
    "index": 1,
    "name": "Blank",
    "injection_type": "Blank",
    "injection_volume": 5.0
  },
  {
    "index": 2,
    "name": "Standard",
    "injection_type": "CalibrationStandard",
    "custom_fields": [
      {
        "name": "CustomNumericField",
        "value": 42.5
      }
    ]
  }
]

Append Sample Information to an existing Sequence

The eWorkflow Creation command supports the ability to append additional injections and associated sample information to a sequence that is already generated from the same eWorkflow. To append to an existing sequence, use the same command structure as creating a new sequence. When the Sequence name already exists in the Data Vault, the Agent will automatically append the sample information as additional injections to the sequence.

📝

NOTE

Append injection(s) if sequence already exists must be enabled for the eWorkflow in the eWorkflow Creation command by using the Chromeleon eWorkflow Editor.

Command Response

The command response returns information about the created sequence:

{
  "sequence": {
    "url": "chrom://server/datavault/folder/sequence.seq",
    "name": "sequence",
    "custom_fields": {
      "CustomField1": "Value1",
      "CustomField2": "Value2"
    },
    "injections": [
      {
        "name": "Sample1",
        "position": "P:A1",
        "injection_type": "Unknown",
        "custom_fields": {
          "CustomField1": "Value1"
        }
      }
    ]
  },
  "appended": false
}

The appended field indicates whether the command appended to an existing sequence or created a new one.

Example: Creating a Simple Sequence

Here's an example of creating a simple sequence with three samples:

{
  "eworkflow": {
    "chromeleon_datavault_server": "CHROMELEON4",
    "chromeleon_datavault": "Test",
    "eworkflow": "test_eWorkflow"
  },
  "sequence": {
    "name": "test_sequence",
    "instrument": "Instrument A",
    "location": "chrom://CHROMELEON4/Test/ImportTest",
    "starting_position": "P:A4",
    "number_of_samples": 3
  }
}

Example: Creating a Sequence with Sample Updates

Here's an example of creating a sequence and updating sample information with various field types:

{
  "eworkflow": {
    "chromeleon_datavault_server": "CHROMELEON4",
    "chromeleon_datavault": "Test",
    "eworkflow": "test_eWorkflow"
  },
  "sequence": {
    "name": "test_sequence",
    "instrument": "Instrument A",
    "location": "chrom://CHROMELEON4/Test/ImportTest",
    "starting_position": "P:A4",
    "number_of_samples": 3,
    "custom_fields": [
      {
        "name": "SequenceCustomField",
        "value": "Sequence Value"
      }
    ]
  },
  "sample_list": [
    {
      "condition": [],
      "all_injections": {
        "name": "Standard",
        "injection_volume": 10.5,
        "weight": 1.5,
        "dilution_factor": 3.0,
        "istd_amount": 3.5,
        "custom_fields": [
          {
            "name": "CustomStringField",
            "value": "All Samples Value"
          }
        ]
      }
    },
    {
      "injections_by_index": [
        {
          "index": 1,
          "name": "Blank",
          "injection_type": "Blank",
          "injection_volume": 5.0
        }
      ]
    }
  ]
}

This example creates a sequence with three samples while also doing the following:

• Sets a custom field on the sequence itself
• Sets all sample names to "Standard" with various numeric properties
• Sets a custom string field value on all samples
• Updates the first sample to be a "Blank" with injection type "Blank" and a different injection volume

Example: Updating Samples Based on Conditions

The following is an example of updating samples based on conditions with different field types:

{
  "eworkflow": {
    "chromeleon_datavault_server": "CHROMELEON4",
    "chromeleon_datavault": "Test",
    "eworkflow": "test_eWorkflow"
  },
  "sequence": {
    "name": "test_sequence",
    "instrument": "Instrument A",
    "location": "chrom://CHROMELEON4/Test/ImportTest",
    "starting_position": "P:A4",
    "number_of_samples": 5
  },
  "sample_list": [
    {
      "condition": [
        {
          "column_name": "Position",
          "value": "P:A4"
        }
      ],
      "all_injections": {
        "name": "First Sample",
        "injection_type": "Unknown",
        "injection_volume": 5.0
      }
    },
    {
      "condition": [
        {
          "column_name": "Position",
          "value": "P:A5"
        }
      ],
      "all_injections": {
        "name": "Standard",
        "injection_type": "CalibrationStandard",
        "injection_volume": 10.0
      }
    },
    {
      "condition": [
        {
          "column_name": "CustomStringField",
          "value": "Special Sample"
        }
      ],
      "all_injections": {
        "comment": "This is a special sample",
        "custom_fields": [
          {
            "name": "CustomDateField",
            "value": "2025-03-19T20:43:07Z"
          }
        ]
      }
    }
  ]
}

This example creates a sequence with five examples while also doing the following:

• Updates any sample with position "P:A4" to have the name "First Sample", injection type "Unknown", and injection volume 5.0
• Updates any sample with position "P:A5" to have the name "Standard", injection type "CalibrationStandard", and injection volume 10.0
• Updates any sample with a custom field "CustomStringField" equal to "Special Sample" to have a comment and a custom date field

Example: Using Different Field Types

The following is an example that demonstrates using different field types for updates:

{
  "eworkflow": {
    "chromeleon_datavault_server": "CHROMELEON4",
    "chromeleon_datavault": "Test",
    "eworkflow": "test_eWorkflow"
  },
  "sequence": {
    "name": "field_types_test",
    "instrument": "Instrument A",
    "location": "chrom://CHROMELEON4/Test/ImportTest",
    "starting_position": "P:A4",
    "number_of_samples": 3
  },
  "sample_list": [
    {
      "injections_by_index": [
        {
          "index": 1,
          "name": "String Example",
          "position": "P:A4",
          "injection_type": "Unknown",
          "comment": "This is a string value"
        },
        {
          "index": 2,
          "name": "Numeric Example",
          "position": "P:A5",
          "injection_type": 3,
          "injection_volume": 10.5,
          "weight": 1.5,
          "dilution_factor": 3.0,
          "istd_amount": 3.5
        },
        {
          "index": 3,
          "name": "Custom Fields Example",
          "position": "P:A6",
          "custom_fields": [
            {
              "name": "CustomStringField",
              "value": "String value"
            },
            {
              "name": "CustomNumericField",
              "value": 42.5
            },
            {
              "name": "CustomDateField",
              "value": "2025-03-19T20:43:07Z"
            }
          ]
        }
      ]
    }
  ]
}

This example creates a sequence with three samples while including the following:

1. String values (name, position, comment)
2. Numeric values (injection_volume, weight, dilution_factor, istd_amount)
3. Enum values as both string ("Unknown") and integer (three for "CalibrationStandard")
4. Custom fields of different types (string, numeric, and datetime)