Skip to content
Recipes
/
Start a protocol run
Last updated

Start a protocol run

This page provides step-by-step instructions for running a protocol using the Prep API.

Retrieve protocol list

Before running a protocol, review the protocols in the system to obtain the protocol ID of the desired protocol to run.

Go to Retrieve the list of protocols for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocols' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
[
  {
    "id": 0,
    "name": "string",
    "favorite": true,
    "dateModified": "2019-08-24T14:15:22Z",
    "dateRun": "2019-08-24T14:15:22Z"
  }
]

Create a protocol run

Creating a protocol run prepares the system for protocol execution and loads the deck. Use a protocol ID found in the protocol list to send this request.

Creating a protocol run requires the protocol ID, a simulation flag, and a recompile flag.

The ProtocolId field is the numeric id assigned when the protocol was first created.

Use the Simulation field to trigger a simulation of the protocol associated with the ProtocolId field. All devices associated with the protocol are also simulated.

The Recompile field forces the protocol to be recompiled even if it was already verified.

The instrument may need to initialize if this is not a simulation. Close the door during this step.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "protocolId": 0,
  "runDatalId": "string",
  "isRunInProgress": true,
  "isSimulation": true,
  "protocolRunState": "Idle",
  "startTime": "2019-08-24T14:15:22Z",
  "estimatedEndTime": "2019-08-24T14:15:22Z",
  "endPauseTime": "2019-08-24T14:15:22Z",
  "protocolName": "string",
  "currentStep": 0,
  "preLoadThermalDeviceUsed": "Hhs",
  "preLoadHepaFiltration": true
}

Load deck

Get load instructions

Retrieve the load instructions to verify the labware the protocol is expecting.

The PositionName field is the name assigned to the position for this run.

The DeckPosition field is the ID of the deck position where the labware is placed. The positions are ordered from 1 to 8, where the rear left is 1, front left is 4, rear right is 5, and front right is 8.

The LabwarePosition field is the labware site used for this run.

The LabwareClassification field describes the labware type (e.g., Plate, Tiprack).

Go to Retrieve the load instructions for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "protocolId": 0,
  "runDatalId": "string",
  "isRunInProgress": true,
  "isSimulation": true,
  "protocolRunState": "Idle",
  "startTime": "2019-08-24T14:15:22Z",
  "estimatedEndTime": "2019-08-24T14:15:22Z",
  "endPauseTime": "2019-08-24T14:15:22Z",
  "protocolName": "string",
  "currentStep": 0,
  "preLoadThermalDeviceUsed": "Hhs",
  "preLoadHepaFiltration": true
}

Complete protocol loading

After the labware has been placed on the deck, close the door and start the protocol run using Put load complete.

The ProtocolId field is the numeric ID assigned when the protocol was first created.

The Simulate field triggers a simulation of the protocol associated with the ProtocolId field.

The LoadCompleteAction field is the action to perform after the LoadComplete has been sent.

The ResidualTips field is where the tips are placed in the labware when the tip rack isn't full.

The Barcodes field is a list of barcodes for each deck or labware position.

The LiquidVolumes field is a list of liquids, volumes, and deck and labware positions used primarily for reagents and diluents.

Go to Complete the loading for the run for more information.

curl -i -X PUT \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/load-complete' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "protocolId": 0,
    "simulate": true,
    "loadCompleteAction": "Run",
    "residualTips": [
      {
        "deckPosition": 0,
        "residualTipData": {
          "useAllAddresses": true,
          "addresses": [
            {
              "row": 1,
              "column": 1
            }
          ]
        }
      }
    ],
    "barcodes": [
      {
        "deckPosition": 0,
        "address": {
          "row": 0,
          "column": 0
        },
        "barcodeValue": "string"
      }
    ],
    "liquidVolumes": [
      {
        "deckPosition": 0,
        "positionOnSite": 0,
        "row": 0,
        "column": 0,
        "volume": 0.1
      }
    ]
  }'
Response
No content

Poll protocol status until completion

After all steps have been followed, wait for protocol execution to complete. Poll for the protocolRunState to be 0 (idle), or until isRunInProgress is false.

A more advanced and efficient approach for this would be listening for events to determine when the correct state is reached.

The ProtocolId field is the ID of the protocol currently running.

The RunDataId field is the ID of the run data of the current.

The IsRunInProgress field indicates whether the run is currently running or if it has completed or been aborted.

The IsSimulation field indicates whether the run is being simulated or if it is running on an instrument.

The StartTime field is the time the run started.

The EstimatedEndTime field is the time the run is expected to complete.

The EndPauseTime field is the total time of the pause step if it has a fixed duration.

The ProtocolName field is the name of the protocol being used in the current run.

The CurrentStep field is the step ID that the run is currently processing.

The PreLoadThermalDeviceUsed field indicates the thermal device (if any) installed for the run.

The PreLoadHepaFiltration field indicates whether the instrument is using a HEPA filtration system.

Go to Get the current run status for more information.

curl -i -X GET \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "protocolId": 0,
  "runDatalId": "string",
  "isRunInProgress": true,
  "isSimulation": true,
  "protocolRunState": "Idle",
  "startTime": "2019-08-24T14:15:22Z",
  "estimatedEndTime": "2019-08-24T14:15:22Z",
  "endPauseTime": "2019-08-24T14:15:22Z",
  "protocolName": "string",
  "currentStep": 0,
  "preLoadThermalDeviceUsed": "Hhs",
  "preLoadHepaFiltration": true
}

Execute protocol operations

This section describes the available operations for protocol execution: pausing, resuming, and aborting a protocol. Each operation requires the instrument to be in a specific state before executing.

Available operations

Pause a protocol

To pause a protocol, the instrument must be in a Running state.

curl -i -X PUT \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/pause' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "hasError": true,
  "error": "string"
}

Resume a protocol

To resume a protocol, the instrument must be in a Paused state.

Never use the Resume endpoint to start a protocol.

curl -i -X PUT \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/resume' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "hasError": true,
  "error": "string"
}

Abort a protocol

This option is available when the instrument is in a Running or Paused state.

curl -i -X PUT \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/abort' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "hasError": true,
  "error": "string"
}

Unload a protocol

This option is available when the instrument is in an Aborted, Initialized, or Terminated state.

curl -i -X PUT \
  'http://{{your_prep_ip_address}}/api/v1/protocol-run/cleanup-unloading' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response
application/json
{
  "hasError": true,
  "error": "string"
}
Previous page
Next page