Advanced Topics: Sending a Sequence Creation Command from TDP to Chromeleon
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:
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.
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 7 months ago