Tetra Chromeleon Agent Sequence Creation Command

The Tetra Chromeleon Agent not only generates and uploads RAW files, but can also receive a Sequence Creation Request from the Tetra Data Platform that can be used to send a Sequence Creation command to Chromeleon.

Prerequisites

Before you send the Sequence Creation Command, do the following.

Enable the queue for the Tetra Chromeleon Agent's connector in the cloud. For instructions on how to do this, see this topic.
Enable the queue in the Tetra Chromeleon Agent, on prem, in the Agent's management console. For instructions on how to do this, see this topic.
You must send a SequenceCreation Command, it must be properly formatted and must not have expired.
Ensure that you have a valid, active JSON Web Token (JWT). You'll need it for authentication. For information on how to generate one, see this topic.
Your Tetra Chromeleon Agent should be installed, configured, and started.

Ways to Send the Sequence Creation Command

There are a few ways that you can send a Sequence Creation command:

Use the Command API endpoint to send the Sequence Creation Command, including a JSON payload of the command.
Create a Self-Service Pipeline that contains a task script that calls the Command API endpoint for you.

Sending a Sequence Creation Command using the Command API Endpoint

To send a Sequence Creation Command using the Command API Endpoint, you'll need to:

Create a JSON-formatted version of the Sequence Creation Command File (Worklist).
Use the Command API to issue a command that sends the Sequence Creation Command File to the Tetra Command Agent.

Details for each of these steps appear below.

Create a JSON-formatted version of the Sequence Creation Command File.

To create a JSON Sequence Creation Command File, complete the following steps.

Create a JSON Sequence Creation Command File. An example appears below. A detailed description of each field is described in the table that follows the example.

{
    "targetId": "7659ef3a-95e9-4e4c-9742-eaf18e4a8af8",
    "action": "TetraScience.Agent.chromeleon.SequenceCreation",
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    },
    "expiresAt": "2021-12-31T23:58:43.749Z",
    "payload": {
        "version": "1.0",
        "sequence": {
            "name": "JasonSequence30",
            "url": "chrom://localhost/ChromeleonLocal/ImportTest/",
            "injection": [{
                    "name": "Standard2"
                },
                {
                    "name": "Injection3"
                }
            ]
        },
        "options": {
        },
        "templates": {
        }
    }
}

{
  "version":  "1.0",
  "sequence": {
    "name": "Sequence04",
    "url": "chrom://localhost/ChromeleonLocal/ImportTest/",
    "comment": "PAH hair analytic",
    "preferredViewSettings": "Default",
    "preferredReportTemplate": "PAK_TEST",
    "preferredChannel": "UV_VIS_1",
    "reviewSignature": true,
    "submitSignature": true,
    "approveSignature": true,
    "instrument": {
      "name": "HPLC1",
      "host": "localhost"
    },
    "customVariable": [
      {
        "name": "Comment",
        "value": "To test a comment"
      }
    ],
    "injection": [
      {
        "name": "Standard1",
        "type": "Standard",
        "level": "01",
        "position": "1",
        "volume": 25.1,
        "instrumentMethod": "PAK_TEST",
        "processingMethod": "PAK_TEST",
        "weight": 1.0,
        "dilution": 1.0,
        "intStd": 1.0,
        "replicateId": "",
        "comment": "Check PAK-Standard-1",
        "customVariable": [
          {
            "name": "LimsSampleID",
            "value": "ID96-895-675"
          }
        ]
      },
      {
        "name": "Injection1",
        "type": "Unknown",
        "level": "",
        "position": "26",
        "volume": 20.0,
        "instrumentMethod": "PAK_TEST",
        "processingMethod": "PAK_TEST",
        "weight": 1.0,
        "dilution": 1.0,
        "intStd": 1.0,
        "replicateId": "",
        "comment": "PAK hair sample, ID96-895-675",
        "customVariable": [
          {
            "name": "LimsSampleID",
            "value": "ID96-895-676"
          },
          {
            "name": "CalculatedResult",
            "value": "Test"
          }

        ]
      }
    ]

  },
  "options": {
    "allowAppendInjections": false,
    "deleteWorklist": true,
    "renameOnError": false
  },
  "templates": {
    "associatedItem": [
      {
        "name": "PAK_TEST",
        "url": "chrom://localhost/ChromeleonLocal/Templates/PAH340.instmeth"
      },
      {
        "name": "PAK_TEST",
        "url": "chrom://localhost/ChromeleonLocal/Templates/PAH340.procmeth"
      }

    ],
    "customVariable": [
      {
        "name": "LimsSampleID",
        "url": "chrom://desktop-h58p0pp/ChromeleonLocal"
      },
      {
        "name": "Comment",
        "url": "chrom://desktop-h58p0pp/ChromeleonLocal"
      },
      {
        "name": "CalculatedResult",
        "url": "chrom://desktop-h58p0pp/ChromeleonLocal"
      }
    ]
  }
}

Data Field	Description	Comments	Validation
Schemaversion	The value is 1.0		Required
sequence	Sequence section		Required
sequence.name	Name of the sequence to be generated.		Required
sequence.url	Location of the folder where the sequence should be generated	The Data Vault URL in the following format: `\<data_vault>/folder_path <br>e.g.chrom://localhost/ChromeleonLocal/ImportTest/<br>localhost/ChromeleonLocal`	An already existing sequence at the specified location is never overwritten; sequence creation is either aborted or, if the `allowAppendInjections` attribute is set to `true`, the injections specified in the worklist are appended to the existing sequence
sequence.preferredViewSettings	View settings to be used when opening an injection in the sequence.		Optional
sequence.preferredReportTemplate	Report template to be used when opening an injection in the sequence.		Optional
sequence.preferredChannel	Channel shown by default in the injection list.		Optional
sequence.submitSignature	If set to `true`, an authorized user can electronically sign the sequence and submit it.		Optional
sequence.reviewSignature	If set to `true`, an authorized user can electronically review the sequence.		Optional
sequence.approveSignature	If set to `true`, an authorized user can electronically approve the sequence.		Optional
sequence.customVariable.name	Name of the sequence custom variable.		Optional
sequence.customVariable.value	The value of sequence custom variable.		Optional
sequence.instrument.name	Name of the instrument.		Optional
sequence.instrument.host	Host of the instrument.		Optional
sequence.option.allowAppendInjections	By default, sequence creation is aborted if the sequence already exists. Set this attribute to `true` to append the injections to the existing sequence.		Optional
injection	Injection Section		Required
injection.name	Injection Name		Required
injection.type	Injection Type		Optional. If it is provided, it should be one of the following values: `Unknown`, `Blank`, `Check Standard`, `Validation`, `Calibration Standard`, `Standard`, `Matrix`, `Spiked`, `Unspiked`
injection.level	Level (Calibration Level)		Optional
injection.position	Injection Position. The correct position format depends on the autosampler used. This attribute may be empty to allow users to set the position manually after the sequence is created. Nevertheless, a warning is generated if no position is specified.		Optional
injection.volume	Inject Volume in µL.		Optional
injection.instrumentMethod	Name of the instrument method to be used for processing the injection. A warning is issued if the specified method does not exist.		Optional
injection.processingMethod	Name of the processing method to be used for processing the chromatographic data. A warning is issued if the specified method does not exist.		Optional
injection.weight	Weight (Weight Factor)		Optional
injection.dilution	Dilution (Factor)		Optional
injection.intStd	Internal Standard Amount		Optional
injection.replicateId	Replicate ID		Optional
injection.comment	Comment		Optional
injection.spikeGroup	Spike Group		Optional
templates	Templates Section	Location of the associated items (`instrument method`, `processing method`, `layout`, `report templates`, `documents`, etc.)	Required
templates.associatedItem.name	Name of the associated item.	Describes the name and url of an associated item (`instrument method`, `processing method`, `view settings`, `report templates`, or `documents`) to be copied to the specified sequence	Optional
templates.associatedItem.url	Chromeleon url of the associated item.		Optional
templates.customVariable.name	Name of custom variable.	Describes the short name of a custom variable to be used in the sequence or injection specification. The URL references the data vault whose global custom variables list specifies the desired. custom variable	Optional
templates.customVariable.url	Chromeleon URL of the custom variable.		Optional
options	Options Section	General parameters for the worklist import.	Required
options.allowAppendInjections		By default, sequence creation is aborted if the sequence already exists. Set this attribute to `true` to append the injections to the existing sequence.	Optional
options.deleteWorklist		If set to `true`, the worklist will be deleted when the sequence is created successfully.	Optional
options.renameOnError		If set to `true`, a worklist that causes any error during sequence creation is renamed; the file extension is changed to wlex.failed.	Optional

📘
NOTE:
In addition to reviewing your file for the correct content, consider using a JSON validation tool to make sure that your JSON file is properly formatted.

Use the Command API to send the Sequence Creation Command to the Tetra Chromeleon Agent

You can use the tool of your choice to create a command that will be sent to the agent. The command is being sent using the Command API, which is part of the Tetra Data Platform. In this example, we will use curl.

You will be using the commands endpoint, which is part of the Command Service API. The commands endpoint is documented here: <https://developers.tetrascience.com/reference#create-command>.
Using curl, specify the request endpoint, ts-auth-token, x-org-slug, content type, target id, action, metadata (if any), and when the command should expire.

request - Should be POST <https://api.tetrascience.com/v1/commands>
ts-auth-token - Use a JSON Web Token. You can generate one with the instructions that are here
x-org-slug - Indicate your Organization Slug.
Content-Type - The content-type should be application/json.
targetId - Use the agent ID.
action - use this action: "TetraScience.Agent.chromeleon.SequenceCreation"
metadata - specify metadata if you have any. If not, simply that it is an empty array by placing nothing in between the two brackets "metadata":
expiresAt - a command expiration date: command state will change to EXPIRED and will not be eligible for execution anymore if the target agent doesn't retrieve it from the queue by the specified date/time. Here is an example.

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 Here>",
    "action": "TetraScience.Agent.chromeleon.SequenceCreation",
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    },
    "expiresAt": "2021-12-31T23:58:43.749Z",
"payload": {
        <YOUR SEQUENCE CREATION JSON FILE HERE>
    }
}'

Here is a finished example.

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": "<Your Agent ID>",
    "action": "TetraScience.Agent.chromeleon.SequenceCreation",
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    },
    "expiresAt": "2021-12-31T23:58:43.749Z",
    "payload": {
  "version":  "1.0",
  "sequence": {
    "name": "Sequence04",
    "url": "chrom://localhost/ChromeleonLocal/ImportTest/",
    "comment": "PAH hair analytic",
    "preferredViewSettings": "Default",
    "preferredReportTemplate": "PAK_TEST",
    "preferredChannel": "UV_VIS_1",
    "reviewSignature": true,
    "submitSignature": true,
    "approveSignature": true,
    "instrument": {
      "name": "HPLC1",
      "host": "localhost"
    },
    "customVariable": [
      {
        "name": "Comment",
        "value": "To test a comment"
      }
    ],
    "injection": [
      {
        "name": "Standard1",
        "type": "Standard",
        "level": "01",
        "position": "1",
        "volume": 25.1,
        "instrumentMethod": "PAK_TEST",
        "processingMethod": "PAK_TEST",
        "weight": 1.0,
        "dilution": 1.0,
        "intStd": 1.0,
        "replicateId": "",
        "comment": "Check PAK-Standard-1",
        "customVariable": [
          {
            "name": "LimsSampleID",
            "value": "ID96-895-675"
          }
        ]
      },
      {
        "name": "Injection1",
        "type": "Unknown",
        "level": "",
        "position": "26",
        "volume": 20.0,
        "instrumentMethod": "PAK_TEST",
        "processingMethod": "PAK_TEST",
        "weight": 1.0,
        "dilution": 1.0,
        "intStd": 1.0,
        "replicateId": "",
        "comment": "PAK hair sample, ID96-895-675",
        "customVariable": [
          {
            "name": "LimsSampleID",
            "value": "ID96-895-676"
          },
          {
            "name": "CalculatedResult",
            "value": "Test"
          }

        ]
      }
    ]

  },
  "options": {
    "allowAppendInjections": false,
    "deleteWorklist": true,
    "renameOnError": false
  },
  "templates": {
    "associatedItem": [
      {
        "name": "PAK_TEST",
        "url": "chrom://localhost/ChromeleonLocal/Templates/PAH340.instmeth"
      },
      {
        "name": "PAK_TEST",
        "url": "chrom://localhost/ChromeleonLocal/Templates/PAH340.procmeth"
      }

    ],
    "customVariable": [
      {
        "name": "LimsSampleID",
        "url": "chrom://desktop-h58p0pp/ChromeleonLocal"
      },
      {
        "name": "Comment",
        "url": "chrom://desktop-h58p0pp/ChromeleonLocal"
      },
      {
        "name": "CalculatedResult",
        "url": "chrom://desktop-h58p0pp/ChromeleonLocal"
      }
    ]
  }
}

When complete, save the file and run it.

Success Response Payload

When the Sequence Creation command is executed successfully, the Tetra Chromeleon Agent returns a response payload that includes the details of the created or updated sequence. This response contains the same sequence information that was specified in the command request, along with additional metadata about the operation.

Response Payload Structure

{
  "sequence": {
    "url": "chrom://localhost/ChromeleonLocal/ImportTest/Sequence04.seq",
    "name": "Sequence04",
    "custom_fields": {
      "Comment": "To test a comment"
    },
    "injections": [
      {
        "name": "Standard1",
        "position": "1",
        "injection_type": "Standard",
        "custom_fields": {
          "LimsSampleID": "ID96-895-675"
        }
      },
      {
        "name": "Injection1",
        "position": "26",
        "injection_type": "Unknown",
        "custom_fields": {
          "LimsSampleID": "ID96-895-676",
          "CalculatedResult": "Test"
        }
      }
    ]
  }
}

Response Payload Fields

Field	Description
`sequence`	An object containing the details of the created or updated sequence.
`sequence.url`	The full path of the created or updated sequence in Chromeleon. This includes the complete sequence file path (e.g., `chrom://localhost/ChromeleonLocal/ImportTest/Sequence04.seq`), not just the folder path specified in the request.
`sequence.name`	The name of the sequence as created or updated in Chromeleon.
`sequence.custom_fields`	An object containing the custom variables that were set on the sequence. Each key-value pair represents a custom variable name and its value.
`sequence.injections`	An array of injection objects that were created or appended to the sequence. Each injection includes its name, position, type, and any custom variables associated with it.
`sequence.injections[].name`	The name of the injection.
`sequence.injections[].position`	The position of the injection in the sequence (e.g., autosampler position).
`sequence.injections[].injection_type`	The type of injection (e.g., Standard, Unknown, Blank, Validation, etc.).
`sequence.injections[].custom_fields`	An object containing custom variables that were set on the injection.

Important Notes

The sequence.url field in the response contains the full path to the sequence file, including the sequence filename. This is different from the sequence.url in the request, which specifies only the folder path where the sequence should be created.
All fields in the response payload should contain actual values, not empty strings or null values. This ensures that you can verify the sequence was created or updated correctly.
The custom_fields objects will only be present if custom variables were specified in the request. If no custom variables were set, these objects may be empty or omitted.

Create a Self-Service Pipeline to Send the Sequence Creation Command

As an alternative to the method above, you can create a self-service pipeline and configure that pipeline to run. The basic procedures for creating a self-service pipeline and configuring a pipeline appear in these topics:

If you create a Self-Service Pipeline for this task, you will need to do a couple of things:

Create a JSON payload for the sequence creation command in the format described below (e.g. convert XML worklist input to the JSON format if you are using XML as an input. Using an XML file as an input is optional.)
Use the context.run_command function to put the sequence creation command to the command queue of the target agent.

A sample XML worklist appears below:

<?xml version="1.0" encoding="utf-8"?>
<Worklist xmlns="www.thermofisher.com/namespaces/Chromeleon/LIMS-worklist" version="1.0">
 <Options allowAppendInjections="false" deleteWorklist="true" renameOnError="true"/>
<Templates>
  <AssociatedItem name="PAK_TEST" url="chrom://localhost/ChromeleonLocal/Templates/PAK_TEST.instmeth"/>
  <AssociatedItem name="PAK_TEST" url="chrom://localhost/ChromeleonLocal/Templates/PAK_TEST.procmeth"/>
  <AssociatedItem name="Default" url="chrom://localhost/ChromeleonLocal/Templates/Default.layout"/>
  <AssociatedItem name="PAK_TEST" url="chrom://localhost/ChromeleonLocal/Templates/PAK_TEST.report"/>
  <AssociatedItem name="LimsFormat.pdf" url="chrom://localhost/ChromeleonLocal/DEMO340.seq/LimsFormat.pdf.file"/>
  <CustomVariable name="LimsSampleID" url="chrom://localhost/ChromeleonLocal"/>
  <CustomVariable name="Comment" url="chrom://localhost/ChromeleonLocal"/>
</Templates>
<Sequence name="Sequence" url="chrom://localhost/ChromeleonLocal/ImportTest/"
                          comment="PAH hair analytic" preferredViewSettings="Default"
preferredReportTemplate="PAK_TEST" preferredChannel="UV_VIS_1" submitSignature="true" approveSignature="true">
  <Instrument name="HPLC1" host="localhost"/>
  <CustomVariable name="Comment" value="SEQ-ID96-895-675"/>
  <Injection name="Standard1" type="Standard" level="01" position="1" volume="20" instrumentMethod="PAK_TEST" processingMethod="PAK_TEST"
    weight="1.0" dilution="1.0" intStd="1.0" replicateId="" comment="Check PAK-Standard-1">
  </Injection>
  <Injection name="Injection1" type="Unknown" level="" position="26" volume="20" instrumentMethod="PAK_TEST" processingMethod="PAK_TEST" weight="1.0" dilution="1.0" intStd="1.0" replicateId=""
     comment="PAK hair sample, ID96-895-675">
    <CustomVariable name="LimsSampleID" value="ID96-895-675"/>
  </Injection>
</Sequence>
</Worklist>

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.

Updated 7 days ago