Specifying Custom Fields

Each custom field is specified by using one of the data collection entity names (see Data Collection Entities), followed by a dot separator, followed by the field name enclosed in :: characters.

For example:

Rules and Constraints

• The expression is evaluated and the target field value set for each input/output pair in the step.

• Where there are replicates or pooling this may mean that a particular input or output item is evaluated multiple times.

• Lab Logic Toolkit can write to read-only fields.

• Lab Logic Toolkit can write to all hidden fields.

The evaluateDynamicExpression script evaluates the expression and sets the target field value for each input/output pair in the step.

• Where there are replicates or pooling this may mean that a particular input or output item will be evaluated multiple times.

• The output data collection is treated specially. The script performs the following actions:

  • Searches the per-input output sample and the per-input output result file/measurement (if they exist) for any output field names found in the expression.

  • Returns any values found.

• In the event of a name collision (ie, the same field name exists on both sample output and result file / measurement output) the sample value is used.

Example Expressions

Example 1

-exp 'output.::DNA Concentration:: = (step.::Ideal Volume:: * step.::Ideal Concentration::) / input.::Volume::

In this example expression, the sample output DNA Concentration field is assigned the value resulting from the following calculation:

1. Multiplying the value of the step Ideal Volume by the value of its Ideal Concentration.

2. Dividing that result by the Volume defined on the sample input.

Note the following:

• step.::Ideal Volume:: is the value of a UDF/custom field. The period between step and Ideal Volume signifies that Ideal Volume is associated with the step.

• The part of the expression to the left of the = sign is always the destination or result of the expression, that is:

  -exp 'destination = (step.::Ideal Volume:: * step.::Ideal Concentration::) / input.::Volume::'
• The part of the expression to the right of the = sign is always the source of the value to be stored in the destination, that is:

  -exp 'destination = source value'
• In this case, multiplying the value of the protocol step Ideal Volume by the value of its Ideal Concentration, and then dividing the result by the Volume defined on the sample input.

Example 2

Copy a step or analyte / derived sample field value to a field configured on the step output - for use in downstream steps:

-exp 'output.::PCR Cycles:: = step.::PCR Cycles::'

This expression will be evaluated one time for each output.

Example 3

Copy a result file or measurement field value to the output analyte / derived field for use in downstream step:

-exp 'output.::Concentration:: = input.::Concentration::'

Example 4

Automatically set a text-string field value:

-exp 'output.::Conc. Units:: = ::nM::'

Handling Non-Existent UDFs/Custom Fields

In the API, fields that do not exist and fields that do not have a value set are considered the same and are handled in the same way.

Attempting to access a nonexistent UDF / custom field will usually result in an error. Sometimes this may not be the desired behavior.

Before attempting to access a field, you can use the hasValue function to check if it exists.

The hasValue function:

• May be used on any item.

• Takes one parameter - the name of the field.

• Returns true if the field exists and has a non-null value.

Example Expressions:

The following expression checks that the Concentration field has a non-null value, and then checks that this value is greater than 1:

-exp 'input.::QC:: = input.hasValue( ::Concentration:: ) && input.::Concentration:: > 1'

The following expression checks that a toggle switch field has a non-null value - ie, that it is set to true or false, and then checks that the value is set to true:

-exp 'if (step.hasValue(::Toggle UDF::) && step.::Toggle UDF::)'