Using JavaScript

About this topic

This topic explains how to use JavaScript in the VWorks software. For a full description of the JavaScript language, see the Mozilla Developer Center at https://developer.mozilla.org/en-US/docs/Web/JavaScript.

Read this topic if you have administrator or technician privileges. This topic assumes that you know how to write programs in JavaScript or have basic programming knowledge.

How JavaScript is used in the software

A comprehensive JavaScript engine is implemented in the VWorks software so that you can customize the software as follows:

•	Change the existing task parameters.

•	Skip a task if certain conditions are met.

•	Repeat a task if certain conditions are met.

The task parameters can change dynamically during a run based on conditions such as:

•	Information passed from an external source, such as a database

•	The number of times the protocol has cycled

•	Feedback on changing conditions or data values during the run

Examples of use

You can use JavaScript in the VWorks software to:

•	Print the parameters of a task to the main log.

•	Run a command that launches an external application, such as a batch file or database-updating program.

•	Reduce the length of the protocol.

Where to write JavaScript

You can write JavaScript in the Advanced Settings area of any task or in the JavaScript task in the Startup, Main, and Cleanup Protocols. JavaScript written in any task is run differently than code written in the JavaScript task:

•	Any task. During a protocol run, the software will run the JavaScript first before evaluating whether the task is possible.

•	JavaScript task. You can add the JavaScript task to run a program that is independent of any task. During a protocol run, the software will run the JavaScript as it reaches the JavaScript task.

The following example shows JavaScript written in the Advanced Settings area of the Aspirate task. Notice that the script is written directly in the text box.

 

You can add JavaScript in the following ways:

•	Directly in the text box in the Advanced Settings area (see the previous example)

•	As an external file that is called by the open( ) function in the text box

 

About JavaScript variables

By default, the values of all variables are cleared (set to undefined) before the next protocol is run. To retain the value of all variables from protocol to protocol, select the Use global context for this protocol option in the Protocol Options tab. When the option is turned on, a variable and its value assigned in one protocol can be used by other protocols that have the same variable until you exit the software. If using the global context option, the values of variables are not reset until the software is restarted.

 

CAUTION If you select the Use global context for this protocol option, variables with the same name in different protocols will overwrite each other.

Cautions

Before running a protocol containing JavaScript, compile the protocol and run it in simulation mode.

During the compiling process, the software uses values displayed in the Task Parameters area and not the values set by JavaScript. Therefore, some errors might not be detected during compilation. The values that appear in the Task Parameters area do not reflect the effects of the JavaScript.

Be aware that JavaScript does not check pipetting volumes before the run begins. Therefore, you must make sure that the pipetting steps make logical sense. For example, the software does not alert you if a JavaScript attempts to aspirate 1 µL from a microplate well that can only hold 0.5 µL.

Related information

 

For information about...	See...
JavaScript language	Mozilla Developer Center
Using script variables directly in task parameters	Using simple variables
JavaScript task	JavaScript
Using JavaScript utilities	Using JavaScript utilities
Startup and cleanup protocols	Setting up Startup and Cleanup Protocol processes