Working with Lab Logic Toolkit

Script Parameters and Usage

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

Parameter	Description
-u {username}	(Required) LIMS login username
-p {password}	(Required) LIMS login password
-i {URI}	(Required) LIMS step URI Provides context to resolve all token values.
-t {true/false}	(Optional) Test mode The script may be executed automatically on step transition, or manually — by selecting the button on the Record Details screen. For automatic script execution—set test mode to false. For manual script execution—set test mode to true. Defaults to false if not specified.
-h {true/false}	(Optional) Halt on any error. By default, if the expression fails to evaluate, or evaluates to a non-numeric/non-sensical value, the script logs the problem and continue. A warning message advises the user to review the generated log file. Supplying the optional -h parameter with a value of true will cause the script to fail, preventing a step transition from proceeding, if any nonfatal errors arise.
-exp {expression}	(Required) The expression to be evaluated. The expression must be enclosed in single quotes, eg, -exp 'expression'. See Using Special Characters - Rules and Constraints section.
-log {logFileLIMSID} -logFileName {logFileLIMSID}	(Required) The LIMS ID of the log file placeholder
-excludeControls {true/false} (Cannot be used withonlyControls; these two parameters are mutually exclusive)	(Optional) Control sample handling Set this parameter to true to make sure that: The nextStep (if used) is set to REMOVE for control samples. Controls are excluded from any calculations in the expression. See Setting Next Actions and Handling Control Samples.
-onlyControls {true/false} -onlyControlSamples {true/false} (Cannot be used withexcludeControls; these two parameters are mutually exclusive)	(Optional) Control sample handling Set this parameter to true to make sure that calculations are performed on control samples only.
-s {true/false} -stopwatch {true/false}	(Optional) Tool logging Set this parameter to true to record the time needed to run the tool as an entry in the log file.

Automation Command Line

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar \
-i {stepURI:v2:http} \
-u {username} \
-p {password} \
script:evaluateDynamicExpression \
-t <false/true> \
-h <false/true> \
-exp 'INSERT EXPRESSION HERE' \
-log {logFileLIMSID}"

Using Special Characters—Rules and Constraints

Special Character	Symbol	Rules and Constraints
Single quote	'	As the ‘exp’ argument supplied to the script must be enclosed in single quotes, the single quote character cannot be used anywhere in the expression—including as part of any custom field that contains the single quote in its name.
Double quote	"	The entire command line must be enclosed in double quotes. Therefore, the double quote character cannot be used anywhere in the expression — including as part of any custom field that contains the double quote in its name.
Double colon	::	This two character string is used to delimit strings and custom field names. This character may not appear inside a custom field or string.

Joining Multiple Evaluations

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

• AND = &&

• OR = ||

• NOT = !

Example	Description
A; B	Run A and then B, regardless of success of A.
A && B	Run B if A succeeded.
A || B	Run B if A failed.
if (!A) {B}	If A condition is not met, run B.

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.

4. Check that the step has a log file placeholder configured.

   • The 'unexpanded placeholders in string' error often refers to the last -log parameter — where the step has not been configured to produce one.

   • If no log file is created, find additional error logging from the command line of the instance. This often shows the location of a syntax error. Find the log file at /opt/gls/clarity/ai/logs/automatedinformatics.log.

5. Set -t parameter to false if an automatic trigger is used.