Experiments database objects
You must have an established connection to the Experiments database to use the experimentTagsDB object. For setup and connection instructions, see Using the Experiments Editor.About experimentTagsDB
The VWorks JavaScript interpreter provides an experimentTagsDB object that can be accessed by a script and used to query records from, add records to, and edit records in the Experiments database.
To handle most interactions with the Experiments database, you can use the built-in features in a VWorks form and the Step Started/Completed task in the protocol instead of the experimentTagsDB object.
experimentTagsDB has no properties.
About protocolExperimentData
Protocols run by a VWorks form
The JavaScript object protocolExperimentData is created automatically when a VWorks form that has an Experiment ID control and an Application name is used to run a protocol. When the object is created, the experimentID (string), applicationName (string), and iteration (int) properties of this object are accessible.
For details on the form design, see Configuring a form for experiment IDs and Experiments database.
Protocols run independently of a form
If your protocol contains Step Started/Completed tasks, but is designed to be run without a form, you must explicitly create your own protocolExperimentData object to add records to the Experiments database.
Properties of protocolExperimentData
protocolExperimentData has five properties:
• experimentID (string)
• applicationName (string)
• iteration (int)
• lastStartedStepName (string)
• stepCompleted (boolean)
The experiment ID, application name, and iteration number are used in combination to identify which run to associate with a given set of data in the Experiments database.
protocolExperimentData has no methods. You can use the protocolExperimentData object with the experimentTagsDB methods to make the required function calls. The following example shows how to declare your own protocolExperimentData object.
Example: Declaring protocolExperimentData object
var protocolExperimentData = {
experimentID: "expID1",
applicationName: "myApp",
iteration: 1,
lastStartedStepName: "",
stepCompleted: true
}
experimentID: "expID1",
applicationName: "myApp",
iteration: 1,
lastStartedStepName: "",
stepCompleted: true
}
Methods of experimentTagsDB
Methods are JavaScript functions invoked through an object. The experimentTagsDB object has the following methods, available on systems that have a connection to the Experiments database. Use these methods to tag experiment data to be added to the Experiments database and to generate reports from the database.
Syntax:
experimentTagsDB.method( )
Note: Because a closed experiment cannot have data added to it, any calls to the following methods will fail if the experiment ID is Closed:
experimentTagsDB.CreateIteration();
experimentTagsDB.AddTag();
experimentTagsDB.AddTagToCurrentStep();
experimentTagsDB.AddStepCompletion();
experimentTagsDB.AddNote();
Note: Script errors are reported in the main Log and prevent the rest of the script from executing, but do not result in a VWorks Error dialog.
Method | Description |
|---|---|
AddNote() | Adds a note to the specified experiment ID. Parameters: String. The text of the Note description. This method requires that a protocolExperimentData object exist in the same JavaScript context, and that protocolExperimentData contains all of the standard data members created for it when a protocol is run via a form that uses the Experiments database. If protocolExperimentData does not exist, or if any of the fields are missing or incorrect, a call to experimentTagsDB.AddNote() will result in a script error. Example: Note: If your protocol is designed to be run without a form, you must explicitly create your own protocolExperimentData object. See Example: Declaring protocolExperimentData object. var protocolExperimentData = { experimentID: "Experiment XYZ", applicationName: "Affinity Purification", iteration: 1, lastStartedStepName: "", stepCompleted: true } experimentTagsDB.AddNote("Off deck incubation"); |
AddTagToCurrentStep() | Adds an experiment tag to the Experiments database as does calling experimentTagsDB.AddTag(). Except that AddTag() always specifies an order value of 1, whereas AddTagToCurrentStep() specifies whatever order value is supplied as the third parameter. Returns a Boolean value. It returns true if successful, and false if not successful. This method requires that a protocolExperimentData object exist in the same JavaScript context and contain all of the standard data members created for it when a protocol is run via a form that uses the Experiments database. If protocolExperimentData does not exist, or if any of the fields are missing or incorrect, a call to experimentTagsDB.AddTagToCurrentStep() will result in a script error. Parameters: • String. The Field Name to be added to the database as a tag. This string must not be empty, otherwise, a script error will result. • String. The Field Value to be added with the tag. This field may be blank. • Integer. The order that the tag is to appear in its section of an experiment ID report. This value must be 1 or greater. If it is 0 or less, a script error results. Examples: Note: If your protocol is designed to be run without a form, you must explicitly create your own protocolExperimentData object. See Example: Declaring protocolExperimentData object. var iter = experimentTagsDB.CreateIteration (experimentID, "Affinity Purification"); experimentTagsDB.AddTagToCurrentStep("Volume uL", "100", 3) experimentTagsDB.AddTag(protocolExperimentData.experimentID, protocolExperimentData.applicationName, protocolExperimentData.iteration, "", "Custom Field 1", "JS inserted"); |
CreateIteration() | Returns a long integer corresponding to an iteration number. Typically, AddTag() and CreateIteration() would be called at the start of the protocol, for example, in the startup script or in a task in the Startup Protocol. AddTag() would be called once for each tag to be created in the Experiments database. CreateIteration() would only be called once per protocol. Parameters: • Text string. The experiment ID. • Text string. The application name. |
GetHighestIteration() | Returns a long integer corresponding to an iteration number. A return of zero means this application has not yet been run for this experiment ID. Parameters: • Text string. The experiment ID. • Text string. The application name. |
GenerateReport | Generates a report (.pdf) of the specified experiment ID. Parameters: • Text string. The experiment ID. • Text string. The file path to the pdf file to be created. This second parameter can be blank, or omitted entirely. In this case, when this method call executes, a Save As file dialog box opens and prompts the user to specify the file name and storage location for the report. Example: experimentTagsDB.GenerateReport (experimentID, "C:\VWorks Workspace\VWorks\ExperimentReports"); |
StartOrCompleteStep() | Indicates the start and completion of a task sequence (step) to be tagged in the protocol for inclusion in the Experiments database. Returns a Boolean value: true if successful, and false if not successful. Parameters: • String. The name of the step to mark as started or completed. • Boolean true/false. Marks the step as started (false) or completed (true). If set to false (starting a step): – If the specified step has already been marked as started in the database, a warning will be displayed in the log, no action will be taken, and the function will return false. – Otherwise, the step will be marked as started, protocolExperimentData.lastStartedStepName will be set to the step specified in the first parameter, protocolExperimentData.stepCompleted will be set to false, and the function will return true. If set to true (completing a step): – If the specified step has not yet been marked as started or has already been marked as completed in the database, a warning will be displayed in the log, no action will be taken, and the function will return false. – Otherwise, the step will be marked as started, protocolExperimentData.lastStartedStepName will be set to the step specified in the first parameter, protocolExperimentData.stepCompleted will be set to true, and the function will return true. This method requires that a protocolExperimentData object exist in the same JavaScript context and contain all of the standard data members created for it when a protocol is run via a form that uses the Experiments database. If protocolExperimentData does not exist, or if any of the fields are missing or incorrect, a call to experimentTagsDB.StartOrCompleteStep() will result in a script error. This method makes the same checks, and has the same effect, as executing a Step Started/Completed task. In the protocol, you would add a JavaScript task (  ) with a call to this method at the point just before the start of the step to be tagged. You would add a second JavaScript task just after the end of this step. The parameters would be the same for both except for the final Boolean, which would be set to true, indicating that the step had completed. (A false value means that the step had started).Examples: Note: If your protocol is designed to be run without a form, you must explicitly create your own protocolExperimentData object. See Example: Declaring protocolExperimentData object. experimentTagsDB.StartOrCompleteStep("Load Samples", false); |
Related information
For information about... | See... |
|---|---|
Establishing connection to the experiment tags database Experiment ID reports | |
Using a form to track experiment data | |
Adding the Step Started/Completed task to a protocol | |
Using JavaScript in the VWorks software | |
VWorks-defined functions | |
Using JavaScript utilities | |
JavaScript task | |
Startup and cleanup protocols |