task object

About the task object

The VWorks JavaScript interpreter provides the following objects that can be accessed by a script.

•	task object

•	plate object

•	plates[ ] object

•	InventoryLabware object

•	plateDB object

•	runset object

•	forms object

This topic describes the task object properties and methods.

task refers to the currently running task. It allows the properties of the task to be accessed using a standard syntax. Depending on which task is running, a different set of properties might be available.

Properties

The properties available for a task correspond to its task parameters in the Task Parameters area.

To see the properties of a task:

1	Open a protocol that contains the task.

2	Select the task in the Protocol area.

3	In the Advanced Settings area, type task. in the Script to be executed before task box. The software automatically displays the list of available properties for the task object.

In the following example, the properties for the Aspirate (Bravo) task is shown in the Advanced Settings area. Notice that they correspond to the parameters in the Task Parameters area.

 

Instead of displaying the list of task properties in the Advanced Settings area, you can also list them in the Main Log. Doing so allows you to print the log file and retain a hardcopy of the properties for reference.

To list the task properties in the Main Log:

1	Open a protocol that contains the task.

2	Select the task in the Protocol area.

3	In the Task Parameters area, click Advanced Settings.

4	Type the following in the Script to be executed before task area:

for (x in task) {

print("task.[" + x + "] =" + task[x]);

}

5	Run the protocol. The task properties appear in the Main Log.

The following example shows the properties for the Aspirate (Bravo) task.

 

Task property data types

A task property can be one of the following data types. You can use the default task parameter value to determine the data type.

 

Data type	Example task parameter
Array	Aspirate task, well selection For more information about the array data type, see Array data types.
Boolean	Aspirate task, Perform tip touch option
Float	Aspirate task, Volume parameter
Integer	Loop task, Number of times to loop parameter
String	Name of a process plate

Array data types

In JavaScript, an array is a built-in object that stores a collection of like values called elements. Each element is accessed by an index value that is enclosed in square brackets. Index values must be non-negative integers.

The following example script declares an array with three elements:

var vehicle_type = new Array(3);

vehicle_type[0] = “car”;

vehicle_type[1] = “truck”;

vehicle_type[2] = “van”;

In the VWorks software, the array data type applies to properties that specify:

•	The sides of a microplate for barcode reading or labeling

•	The well selection in liquid-handling tasks, such as the Aspirate task

Sides of a microplate

In properties that specify the sides of a microplate, the array contains four elements, each representing a side of the microplate, for example:

•	task.side[SOUTH]

•	task.side[EAST]

•	task.side[NORTH]

•	task.side[WEST]

Well selection

In properties that specify well selection, the array identifies the location of wells and quadrants in a microplate. Well locations are represented by a pair of integers that describe its row and column coordinates: [row, column].

 

 

A quadrant is an evenly spaced array of locations that are accessible by the tips on a pipette head. The following table lists the types of pipette heads and the number of accessible quadrants in various microplates.

 

Pipette head channels/pin tool pins	Microplate	Number of quadrants
96	96-well 384-well 1536-well	1 4 16
384	384-well 1536-well	1 4
1536 (pin tool only)	1536-well	1

The following diagram demonstrates the concept of quadrants. The diagram shows a portion of a 384-well microplate and highlights the four quadrants (Q1, Q2, Q3, and Q4) that are accessible by the A1 tip of a 96-channel pipette head. Notice that the green color highlights all of the quadrant 1 (Q1) wells across the microplate.

 

 

 

When specifying well selection, you provide both the well location and quadrant location. For example, the designation for the four quadrants highlighted in the previous diagram is:

[[1,1],[1,2],[2,1],[2,2]]

where the Q1 coordinates are [1,1], Q2 coordinates are [1,2], Q3 coordinates are [2,1], and Q4 coordinates are [2,2].

You can also use variables to represent the row and column coordinates, as the following example shows:

task.Wellselection = [[disp_row,disp_col]]

IMPORTANT Quadrant specifications in the Well Selection dialog box will override task.Wellselection values assigned in the Advanced Settings area.

To cycle through the quadrants in a liquid-handling task, you can use a series of if statements as the following example shows.

var Dispense_Loop;

if (Dispense_Loop == undefined) {

Dispense_Loop = 1;

}

if (isNaN(Dispense_Loop)){

Dispense_Loop = 1;

}

if ((Dispense_Loop < 1)||(Dispense_Loop > 4)){

Dispense_Loop = 1;

}

 

if (Dispense_Loop == 1){

task.Wellselection = [[1,1]];

}

if (Dispense_Loop == 2){

task.Wellselection = [[1,2]];

}

if (Dispense_Loop == 3){

task.Wellselection = [[2,1]];

}

if (Dispense_Loop == 4){

task.Wellselection = [[2,2]];

}

Dispense_Loop++;

print("Dispensing to quadrant "+task.Wellselection+" of Destination plate.");

}

Methods

The task object methods, and the properties of the methods, are specific to the selected task. The following table lists some of the shared methods:

 

Method	Description
task.skip()	Skips the current task. Use this function to conditionally run a task, such as in this example which skips the task if the simulator is not running: if (!task.isSimulatorRunning()) { task.skip(); }
task.pause()	Pauses the protocol and opens a dialog box that asks you whether you want to continue or abort the run. Use this function if you need to pause the protocol to, for example, replenish the fluid in a static reservoir. You could use the print() function to add a note to the log toolbar describing the action to take when the VWorks software has paused.
task.isSimulatorRunning()	Returns true if this is a simulated run. Has no arguments.
task.repeat()	Schedules another instance of this task, including its script, to be repeated immediately after this task finishes execution. Subsequent calls to task.repeat() within the same script instance are ignored.
task.repeatDelay(int timeseconds)	Requests the task to wait the specified time (in seconds), and then repeats. The clock starts running the moment this call is made, but the subsequent instance of this task will not start executing before the current instance finishes execution. If task.repeatDelay() is called more than once within the same script instance, the final call's specified number of seconds will be used. In no case will task.repeatDelay() cause more than one additional instance of this task to be scheduled.
task.setGlobalData(string name, string value)	Stores value in name in the Global database.
task.getGlobalData(string name)	Returns the value stored earlier using task.setGlobalData for the given name.
task.getProtocolName()	Retrieves the full protocol path (string).

task.Headmode method

Available only for SubProcess (Bravo). The following method enables selection of a subset of the barrels in the pipette head:

task.Headmode(string args)

The string parameter must contain a comma-separated list of the following four interger values:

 

string args	Values
1	Specifies the barrel selection as follows: 0 = all_barrels 1 = column 2 = row 3 = partial_column_row 4 = single_barrel
2	Specifies the region of the barrel selection, where, 0 = front_right 1 = back_right 2 = back_left 3 = front_left
3	Specifies the number of rows for the barrel selection, for example, • 96-barrel head, the maximum row value is 8, and the maximum column value is 12. • 384-barrel head, the maximum row value is 16, the maximum column value is 24.
4	Specifies the number of columns for the barrel selection, for example, • 96-barrel head, the maximum row value is 8, and the maximum column value is 12. • 384-barrel head, the maximum row value is 16, the maximum column value is 24.

The following examples show how to use task.Headmode.

 

Barrel selection options	Example task.Headmode script and comparable view in the Head Mode Selector dialog box
Select partial row/column	Selecting 35 barrels (7-by-5 region) task.Headmode = “3,1,7,5”
Select column or columns	Selecting 5 columns Note: Row specified is ignored. task.Headmode = “1,2,1,5”
Select row or rows	Selecting 4 rows Note: Column specified is ignored. task.HeadMode = “2,3,4,1”
Select single barrel	Selecting single barrel in the back left Note: Row and column specified are ignored; region is always 1-by-1. task.HeadMode = “4,2,1,1”

Related information

 

For information about...	See...
Writing JavaScript for the Print and Apply task	Using JavaScript with the CentrifugeAuto task
Using JavaScript in the VWorks software	Using JavaScript
VWorks-defined functions	VWorks-defined functions
Other VWorks-defined objects	• InventoryLabware object • plate object • plates[ ] object • plateDB object • runset object • forms object
Using JavaScript utilities	Using JavaScript utilities
JavaScript task	JavaScript
Startup and cleanup protocols	Setting up Startup and Cleanup Protocol processes
Specifying a quadrant pattern in the Well Selection dialog box	• Aspirate (Bravo, Vertical Pipetting Station) • Dispense (Bravo, Vertical Pipetting Station) • Mix (Bravo, Vertical Pipetting Station)