task object
The VWorks JavaScript interpreter provides a task object that can be accessed by a script. 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 (Agilent 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 (Agilent 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]]
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 in the VWorks software | |
VWorks-defined functions | |
Other VWorks-defined objects | |
Using JavaScript utilities | |
JavaScript task | |
Startup and cleanup protocols | |
Specifying a quadrant pattern in the Well Selection dialog box |