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.

  1. Enable the queue for the Tetra Chromeleon Agent's connector in the cloud. For instructions on how to do this, see this topic.
  2. 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.
  3. You must send a SequenceCreation Command, it must be properly formatted and must not have expired.
  4. 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.
  5. 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:

  1. Create a JSON-formatted version of the Sequence Creation Command File (Worklist).
  2. 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.

  1. 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 FieldDescriptionCommentsValidation
versionSchema versionThe value is 1.0Required
sequenceSequence sectionRequired
sequence.nameName of the sequence to be generated.Required
sequence.urlLocation of the folder where the sequence should be generatedThe structure is <data_vault>/folder_path e.g.chrom://localhost/ ChromeleonLocal/ImportTest/localhost/ChromeleonLocal is the Data Vault UrlAn 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 ViewSettingsView settings to be used when opening an injection in the sequence.Optional
sequence.preferred ReportTemplateReport template to be used when opening an injection in the sequence.Optional
sequence.preferredChannelChannel shown by default in the injection listOptional
sequence.submitSignatureIf set to true, an authorized user can electronically sign the sequence and submit it.Optional
sequence.reviewSignatureIf set to true, an authorized user can electronically review the sequence.Optional
sequence.approveSignatureIf set to true, an authorized user can electronically approve the sequence.Optional
sequence.customVariable. nameName of the sequence custom variable.Optional
sequence.customVariable. valueThe value of sequence custom variableOptional
sequence.instrument. nameName of the instrumentOptional
sequence.instrument. hostHost of the instrumentOptional
sequence.option. allowAppendInjectionsBy default, sequence creation is aborted if the sequence already exists. Set this attribute to true to append the injections to the existing sequenceOptional
injectionInjection SectionRequired
injection.nameInjection NameRequired
injection.typeInjection TypeOptional. If it is provided, it should be one of the following values: Unknown, Blank, Check Standard, Validation, Calibration Standard, Standard, Matrix, Spiked, Unspiked
injection.levelLevel (Calibration Level)Optional
injection.positionInjection 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.volumeInject Volume in µLOptional
injection.instrumentMethodName of the instrument method to be used for processing the injection. A warning is issued if the specified method does not exist.Optional
injection.processingMethodName 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.weightWeight (Weight Factor)Optional
injection.dilutionDilution (Factor)Optional
injection.intStdInternal Standard AmountOptional
injection.replicateIdReplicate IDOptional
injection.commentCommentOptional
injection.spikeGroupSpike GroupOptional
templatesTemplates SectionLocation of the associated items (instrument method, processing method, layout, report templates, documents, and so on)Required
templates.associatedItem. nameName of the associated itemDescribes the name and url of an associated item (instrument method, processing method, view settings, report templates, or documents) to be copied to the specified sequenceOptional
templates.associatedItem. urlChromeleon url of the associated itemOptional
templates.customVariable. nameName 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 variableOptional
templates.customVariable. urlChromeleon url of the custom variableOptional
optionsOptions SectionGeneral parameters for the worklist importRequired
options.allowAppendInjectionsBy 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.deleteWorklistIf set to true, the worklist will be deleted when the sequence is created successfully.Optional
options.renameOnErrorIf 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.

  1. 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.

  2. 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>
    }
}'
  1. 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"
      }
    ]
  }
}
  1. 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>