Script Parameters and Usage

The following table defines the parameters used by the evaluateDynamicExpression script.

Automation Command Line

Using Special Characters—Rules and Constraints

Joining Multiple Evaluations

Use the following special syntax to join multiple evaluations within an expression:

• AND = &&

• OR = ||

• NOT = !

Boolean expressions should evaluate to true or false.

Troubleshooting

For debugging errors, run through the following steps to determine the cause.

1. Check custom field format (eg, step.::UDF Name::).

2. Make sure that the custom fields have been created for the correct entity type.

3. Check the mapping of the field type (see section) — if doing Math they need to be numeric.

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.

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.

Example Expressions

Example 1

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:

• 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:

Example 2

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

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:

Example 4

Automatically set a text-string field value:

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:

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:

When working with the Lab Logic Toolkit evaluateDynamicExpression script, custom field values can originate from the following data collection entities (these will differ, depending on the step from which the script is being run):

• input (analyte/derived sample)

• output (analyte/derived sample or per-input result file, measurement, or file placeholder)¹

The container entity makes the input, output, or submittedSample container available to the scripting engine.

• The container can be queried for its name, for example:

  Copy

  input.::container::.::name::

• Container name, UDFs / fields, and entity information can be read or written, for example:

  Copy

  output.::container::.::example udf1:: = input.::container::.::example udf1::

Example basic expressions:

-exp 'output.container.::containerUDF:: = ::This is a string::'
-exp 'input.::container::.::containerUDF:: = ::This is a string::'
-exp 'submittedSample.container.::containerUDF:: = ::This is a string::'

For a pooled derived sample consisting of several submitted samples, Lab Logic Toolkit exposes a submittedSamples property that is a collection of the submitted samples represented in the well.

• submittedSamples returns a list of submitted samples.

• If it is not a pooled sample, it will return a list of 1.

• submittedSample returns an error if sample is pooled.

Use this collection to read and/or update all related submitted samples.

For example:

• To set the sample level UDF/custom field for each of the related submitted samples:

• To sum the Volume UDF/custom field on all the related submitted samples into a single value written to the input analyte / derived sample:

For information on Groovy syntax and closures, see .

The following tables summarize the mapping of UDF/custom field types.

Working with Toggle Switches

The LIMS and API treat the toggle switch field type as boolean when its value is set to true or false. However, it is possible to configure a toggle switch to not have to set a boolean true / false value. In this case, the value of the field is None Set and the field is treated as a 'nonexistent' field. To make sure that a toggle switch value has been set, you can use the hasValue function. For details, see .

Use the fail() method to halt the script and display an error message. If the script is used on a step transition, this method also prevents the step from proceeding to the next screen.

Example expression:

Note that this example also uses the hasValue function (see ).

In QC steps, some items have a QC flag associated with them. This flag can be read and set from script expressions. The value may be set to true or false.

Example expressions:

-exp 'input.QC = input.::Concentration:: >= step.::minConcentration:: && input.::Concentration:: <= step.::maxConcentration::' -exp 'output.QC = input.QC'-exp 'if(Step.::Concentration:: >= 1) { input.QC = true } else { input.QC = false }'

The nextStep property is similar to the input, output, submittedSample, container, and step entities. However, nextStep can only be used on the left side of a dynamic expression; it cannot be used in the calculation on the right side of the expression.

The basic syntax is as follows:

Depending on how the step is configured, a nextStep expression may set the next action for the step inputs or the step outputs. For example, in steps that do not produce output samples — such as QC steps, it is the step inputs that proceed (provided they pass QC) to the next step in the workflow.

When creating an expression that calls the nextStep property, there is no need to differentiate between step inputs and step outputs. The LIMS is able to determine this from how the API represents the entities that are available to set next actions on.

The following table summarizes the non-UDF/custom field properties available for each entity type. Column headers are the types available. The bold row entries are the properties available.

name

The name read-only property makes the name of the entity available to the scripting engine.

Example basic expression:

workflowName

The workflowName read-only property makes the workflow name of input samples available to the scripting engine.

This property contains a string representing the current IN_PROGRESS workflow names. The string is formatted as a comma-delimited list, with a space inserted before each new item.

Example basic expressions:

replicateCount

The replicateCount read-only property is available for input samples.

This property contains an integer value representing the number of output replicates (samples or result files / measurements or files / file placeholders) generated from the input sample in the current step.

Example basic expressions:

pooledInputsCount

The number of input analytes/derived samples that contributed to this analyte / derived sample.

• For pooled analytes / derived samples, this is > 1.

• For non-pooled analytes this is 1.

• Replicated samples that are then pooled are still counted separately in pooledInputsCount.

Example basic expression:

When working with the pooledInputsCount property, the script looks at the step that created the derived sample or result file / measurement, and doesnot look upstream for a pooling step.

Example scenario:

Step 1: Pooling step that creates pooled samples.

Step 2: Nonpooling step that takes in the pooled samples and creates new derived samples (that are themselves still pools).

Step 3: Nonpooling step with expression that calls input.pooledInputsCount.

The expression in step 3 returns '1' because it onlys look at the previous step (step 2)—the step that created the current derived samples.

limsid

You can access the limsid field with some knowledge of Groovy and the LLTK. Use the following examples with any supported entity:

Example basic expressions:

well

The well read-only property makes the well location of input, output, or submittedSample available to dynamic expressions. Result file / measurement outputs are supported if they have placement information (eg, on QC steps).

Example basic expression: