Advanced Topics: Sending a Sequence Creation Command from TDP to Chromeleon

Suggest Edits

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
version	Schema version	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 structure is <data_vault>/folder_path e.g.chrom://localhost/ ChromeleonLocal/ImportTest/localhost/ChromeleonLocal is the Data Vault Url	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.preferred ViewSettings	View settings to be used when opening an injection in the sequence.		Optional
sequence.preferred ReportTemplate	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, and so on)	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:
Consider using a JSON validation tool [can we also reference the JSON schema here so that customers can validate their JSON payload against that schema?] to ensure that your JSON file is properly formatted in addition to reviewing your file for the correct content.

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.

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>

Updated about 1 year ago

Prerequisites

Ways to Send the Sequence Creation Command

Sending a Sequence Creation Command using the Command API Endpoint

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

📘NOTE:

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

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

📘
NOTE: