1. Core LIMS Training: CoreScripts

2. Course Topics Definitions Traversal CoreScripts Update CoreScripts
Configuring CoreScripts Triggers
Examples
Note: This training assumes that you have reviewed and understand Basic Administration Training and the Triggers Training
4/15/2018
Confidential

3. What are CoreScripts?
CoreScripts are ways to quickly add modular pieces of code without compiling a new build
CoreScripts can be used to automatically push or pull data from one LIMS record to another; it is useful for automating redundant data entry
Core Scripts can also be used to automatically transform data in a record
CoreScripts use a simple, proprietary coding language
CoreScripts are called by a trigger
CORESCRIPTS is an entity type under super type TRIGGER IMPL; these trigger records store the code
4/15/2018
Confidential

4. Parts of a CoreScript There are 2 main parts of a CoreScript
Traversal - part that retrieves the entities the script will act on (conceptually similar to declaring variables)
Update - part that operates on one or more entities
Each section of the script is stored in a separate attribute on the CoreScripts Tigger Impl record
You are not required to have traversal part for every CoreScript
Scripts are read left to right
Left side generally contains commands to retrieve entities
Middle may contain commands to traverse or other manipulations
Right side of script gives temporary key or final location to store results
4/15/2018
Confidential

5. CoreScript Syntax
Each script part will be enclosed in square brackets []
COMMANDS and KEYS are prefixed with a dollar sign $
Values and key names will be enclosed in curly brackets {}
Periods are used to separate commands and keys within a script
Commas are used to separate scripts from each other or to separate retrieval (get) functions from storing (set) functions
You can space a script across multiple lines to make it easier to read
4/15/2018
Confidential

6. Relative Entity Traversal
A traversal script has the general format:
[ ${ENTITY }.$COMMAND{VALUE}.$COMMAND{VALUE}….. , ${KEY} ]
which can also be written: [
${ENTITY }.$COMMAND{VALUE}.$COMMAND{VALUE}….. ,
${KEY} ]
4/15/2018
Confidential

7. Traversal Commands Command Description Value ATN
Get an entity by name stored in an attribute
Name of attribute
ATB
Get an entity by barcode stored in an attribute
ASC
Get entities by association context
Context
AST
Get entities by association type
Associated type
ASTP
Get parent entities by association type
CELL
Get cells in a container / experiment container
Cell number or blank = all cells
EXC
Get experiment containers in experiment
EXDB
Get entity by barcode stored in experiment data in experiment samples
Name of experiment data attribute
EXDID
Get entity by ID stored in experiment data in experiment samples
EXDN
Get entity by name stored in experiment data in experiment samples
EXS
Get experiment samples in experiment / experiment container
Sample type or blank = all experiment samples
4/15/2018
Confidential

8. Keys
You can name keys anything you want (but it is a good idea to name keys by what data they are holding to make it easier to troubleshoot later)
Keys are transiently stored – they cannot be called directly after a CoreScript is completed or shared between trigger records (trigger level scope)
Most key values are assumed to be numeric (or a string with a barcode)
Best practice is to enclose all string values used in the get part of an update script in double quotes “”around the {key}.Tip: You can put quotes around a number if you are not going to use it in math expressions
There is one special pre-named key
${this} – it represents the entity that the trigger is running on
4/15/2018
Confidential

9. Example Simple Entity Traversal
CoreScript: [ ${this}.$ATB{ci_uptest_atb}, ${ATB_TEST} ] Description: Traverse from the entity with the trigger to the barcode that is stored in the attribute named “ci_uptest_atb”. Store the resulting entity in the key ${ATB_TEST}.
4/15/2018
Confidential

10. Example Entity Traversal Across Multiple Levels
CoreScript: [ ${this}.$ATB{ci_uptest_atb}.$ASC{SUPER SCRIPT} , ${SCRIPTS} ] Description: Traverse from the entity with the trigger to the barcode that is stored in the attribute named “ci_uptest_atb”. Now traverse from here to all associations with the context “SUPER SCRIPT”. Store these entities in the key ${SCRIPTS}.
4/15/2018
Confidential

11. Example Multiple Entity Traversals (Sample)
CoreScript: [
${this},
${SAMPLE_LOT} ],
${SAMPLE_LOT}. $ATB{ci_parent_lot},
${PARENT_LOT}
${SAMPLE_LOT}. $ASC{CHILDREN},
${CHILD_LOTS} ]
Description:
Store the entity in ${this} in a new key called ${SAMPLE_LOT}. Traverse from the SAMPLE_LOT entity to the barcode that is stored in the attribute named “ci_parent_lot”, and store that entity in the key ${PARENT_LOT}. Now traverse from the SAMPLE_LOT entity to all associations with the context “CHILDREN”, and store these entities in the key ${CHILD_LOTS}.
Tip: Best practice is to name keys to clearly indicate what data they are holding
4/15/2018
Confidential

12. Example Multiple Entity Traversals (Expt)
CoreScript: [
${this},
${EXPERIMENT} ],
${EXPERIMENT}. $EXS{},
${EX_SAMPLES}
${EX_SAMPLES}. $EXDB{ci_minted_lot},
${MINTED_LOTS} ]
Description:
Store the entity in ${this} in a new key called ${EXPERIMENT}. Traverse from the EXPERIMENT entity to all of its experiment samples, and store those entities in the key ${EX_SAMPLES}. Now traverse from the EX_SAMPLES entities to the barcode that is stored in the experiment data attribute named “ci_minted_lot”. Store these entities in the key ${MINTED_LOTS}.
4/15/2018
Confidential

13. Update Script An update script has the general format:
[ Value , Destination ]
which can also be written: [
${SOURCE KEY}.$COMMAND{VALUE},
${DESTINATION KEY}.$COMMAND{VALUE} ]
4/15/2018
Confidential

14. Update Get Value Commands
Description
Value AT
Get the value of an attribute
Name of attribute
ASC
Get comma delimited IDs by association context
Association context
EXD
Get the value of experiment data by attribute name
Attribute name
JEP
Get the value of a stored result by variable name
Variable name
UNIQ
Get the value of a unique attribute (like name, barcode, sequence, ID) by unique attribute name
Unique attribute name
UNIQC
Get the value of an unique attribute (like ID, unit, amount) by unique attribute name for a cell
4/15/2018
Confidential

15. Update Destination Commands
Description
Value AT
Store result in the attribute by name
Name of attribute
ASC
Store IDs as an association with context
Association context
JEP
Store result in a JEP key
Variable name
UNIQ
Store result in a unique attribute (like name, barcode, sequence, ID)
Unique attribute name
4/15/2018
Confidential

16. Example Copy Attribute Script
Tip: String attributes of the get part of statement should be contained in double quotes
CoreScript: [ “${source}.$AT{ci_source_value}”, ${destination}.$AT{ci_destination_value} ] Description: Retrieve the value contained in the attribute named “ci_source_value” on the entities contained in the key ${source} and store them in the attribute named “ci_destination_value” on the entities stored in the ${destination} key.
4/15/2018
Confidential

17. Example Copy Association Script
CoreScript: [ “${source}.$ASC{SUPER SCRIPT}”, ${destination}.$ASC{REALLY SUPER SCRIPT} ] Description: Retrieve the associations with the context “SUPER SCRIPT” on the entities contained in the key ${source} and copy them to the entities stored in the destination key ${destination} with the context “REALLY SUPER SCRIPT”.
4/15/2018
Confidential

18. Example Copy Association Script of Parents
CoreScript: [ “${source}.$ASTP{EMPLOYEE}”, ${destination}.$ASC{NAME} ] Description: Retrieve the parent associations with the context “EMPLOYEE” on the entities contained in the key ${source}. Copy them to the entities stored in the destination key ${destination} with the context “NAME”.
4/15/2018
Confidential

19. Unique Attributes and Associations
LIMS objects have some special built-in attributes that are not like ordinary LIMS attributes
Examples are barcode or name of an entity
These attributes are required to be on all entity types by default
Admins can not modify or remove these attributes
Similarly there are implicit associations that are hard-coded that you may need to access
An example is the association between a sample and a lot
CoreScripts can access unique attributes and associations with the UNIQ command
Unique attributes are named:
ci_Bean_name
Bean (or class name) is the LIMS Object
name is the name of the attribute
4/15/2018
Confidential

20. Available Beans and Attribute Names
Description
Entity id
Samples and most other objects in the LIMS will use “Entity” as the Bean; id is the system entity id (typically a unique 7 digit number)
name
The name of the entity
barcode
The barcode of the entity
active
Boolean to determine if an entity is currently available for public viewing/querying or not
locationID
Barcode of a location where entity is currently stored
sequence
Numeric position of record in the database for the entity type
hasSignatureEvent
If track signatures is enforced, then this is a Boolean to indicate whether a record has been signed (typically used in ELN)
likedBy
Indicates which employees have clicked on the “Like” icon on a specific LIMS record (all records except employee)
followedBy
Indicates which employees have clicked on the “Follow” icon of a specific employee record
json
Returns the json representation of the entity
4/15/2018
Confidential

21. Available Beans and Attribute Names - 2
Description
Employee
firstName
First name of an employee
lastName
Last name of an employee
userName
Name a user uses to log into the Core LIMS
address of employee
Event
protocolId
Enitity ID of a protocol associated with the action
employeeId
Entity ID of employee who performed the action
instrumentId
Entity ID of instrument that performed the action
signed
Boolean to indicate if event was confirmed with a signature
4/15/2018
Confidential

22. Available Beans and Attribute Names - 3
Description
Experiment
hasRawData
Boolean to indicate if an experiment has raw, unprocessed data or not
hasIntermediateData
Boolean to indicate if an experiment has data calculated from raw data values or not
Experiment Container id
Entity ID of the experiment container
experimentId
Entity ID of the experiment
containerId
Entity ID of the container
sequence
Numeric position of record in the database for experiment container
accept
Boolean to indicate if user accepted the container as valid data
4/15/2018
Confidential

23. Available Beans and Attribute Names - 4
Description
Experiment
Sample
experimentId
Entity ID of the experiment
sampleEntityId
Entity ID of the sample
concentrationNanoMolar
Concentration of sample (stored in nM)
experimentContainerId
Entity ID of the experiment container
cell
Numeric position in a multiple well container
sequence
Numeric position of record in the database for experiment sample
accept
Boolean to indicate if user accepted the sample as valid data
grouping
Indicates how data should be aggregated
concUnit
Unit for the sample concentration (used when users input data or for displays; data will be converted to nM for storage)
4/15/2018
Confidential

24. Available Beans and Attribute Names - 5
Description
Location
parentLocationId
Entity ID of the parent location
capacity
Total amount of items a location can hold
count
Current amount of items a location is holding
LocationFormat id
Entity ID of the location format
name
Name of the location format
description
Description of the location format
cellCount
Total number of cell positions in the location matrix
Lot
lot
Entity ID of the lot
sampleId
Entity ID of the sample
4/15/2018
Confidential

25. Available Beans and Attribute Names - 6
Description
Printer
isOpen
Boolean to indicate whether printer is available for printing
lableTypeId
Entity ID of the label
writerType
Indicates whether to write to a file or a printer; options are FileWriter or PrintWriter
filePath
Describes the location a file will be written to if output is a file
Container
locationID
Barcode of a location where the container is currently stored
Container Format id
Entity ID of the location format
name
Name of the location format
description
Description of the location format
cellCount
Total number of cell positions in the location matrix
Molecules
smiles
Simple line notation to describe chemical structures
formula
Chemical formula which describes the numbers of each atom in a molecule
molecularWeight
The mass of a molecule
mdlNumber
Registration number of a structure in the MDL database
sampleID
Entity ID of a sample molecule
4/15/2018
Confidential

26. Available Beans and Attribute Names - 7
Description
Cell id
Entity ID of the specific cell
containerID
Entity ID of the parent container
cell
Numeric sequence of the specific cell
amount
Physical amount of the sample lot in the cell
unit
Unit for the amount of sample lot
movedAmount
Amount of material transferred between container cells
movedAmountUnit
Unit for the amount of transferred
solventAmount
Amount of solvent in the cell
eventId
Entity ID of the transfer event
4/15/2018
Confidential

27. Example Script With Unique Attributes
CoreScript: [
“${PRIMER_LOT}.$UNIQ{ci_Lot_barcode}”,
${DESTINATION}.$AT{ci_primer_lot} ],
“${EXPERIMENT_SAMPLE}.$EXD{ci_primer_name}”,
${SAMPLE}.$UNIQ{ci_Entity_name} ]
Description:
Retrieve the barcode from the Lot entity inside the ${PRIMER_LOT} key and store that barcode in the attribute “ci_primer_lot” on the entity inside the ${DESTINATION} key. Next, retrieve the value from the experiment data “ci_primer_name” that is on the experiment sample inside ${EXPERIMENT_SAMPLE}. Store this value as the name of the entity contained in the ${SAMPLE} key.
4/15/2018
Confidential

28. Mathematical Expressions
CoreScripts use JEP (Java Expression Parser) functions to manipulate values
All common arithmetic operators and mathematical functions are supported
For complete documentation on all supported commands, see:
Use parenthesis () to enclose expressions that need to be operated on by a JEP function
JEP functions are also used in user-defined equations in the LIMS
4/15/2018
Confidential

29. Example Simple Expression
CoreScript: [
max( ${sources}.$AT{ci_source_value} ) + 10,
${destinations}.$AT{ci_destination_value} ]
Description:
Retrieve the value contained in the attribute named “ci_source_value” on the entities contained in the key ${sources}. Take the max of those values and add 10 to it. Now store the result of this expression in the attribute named “ci_destination_value” on the entities stored in the ${destinations} key.
4/15/2018
Confidential

30. Example Conditional Expression
CoreScript: [
if( ${source1}.$AT{ci_source_value} > ${source2}.$AT{ci_source_value}, “TRUE”,”FALSE”),
${destination}.$AT{ci_destination_value} ]
Description:
Retrieve the value contained in the attribute named “ci_source_value” on the entity contained in the key ${source1} and retrieve the value contained in the attribute named “ci_source_value” on the entity contained in the key ${source2}. If ${source1} is greater than ${source2} then return “TRUE” , else return “FALSE”. Now store the result of this expression in the attribute named “ci_destination_value” on the entity stored in the ${destination} key.
4/15/2018
Confidential

31. Storing in Variables
You can store expressions within variables for later use without storing it more permanently in an entity in the LIMS
To call or store these variables, you use the CoreScripts JEP command (Note: these are NOT the JEP mathematical functions)
The format of these expressions is still [Value, Destination]
Value is typically is some complicated expression using JEP functions
Destination is the variable name which uses the format:
$JEP{RESULT}.${variable name}
You can name variable name anything you want
4/15/2018
Confidential

32. Example Script Using Variables
CoreScript: [
1000 * 1000 , $JEP{RESULT}.${MATH} ],
$JEP{RESULT}.${MATH} * 2,
${destination}.$AT{ci_destination_value} ]
Description:
Take the result of 1000 * 1000 and store that in the variable $JEP{RESULT}.${MATH}. Now multiply the value in the variable $JEP{RESULT}.${MATH} by 2, and put that result in the attribute named “ci_destination_value” on the entity stored in the ${destination} key.
4/15/2018
Confidential

33. Automatic Variables
If you stored results in a destination key, a JEP variable is automatically created behind the scenes
It is automatically named using the format:
$JEP{RESULT}.${number}
where number is the number of scripts that are executed so far
You can call either the destination key or the automatic JEP variable
Can be useful if you are reusing a variable and the value in the destination key has been updated to a different value
Also useful if you don’t want to repeat complicated expression
4/15/2018
Confidential

34. Example Script Using Auto-Named Variables
CoreScript: [
1000 * 1000,
${destination}.$AT{ci_destination_value}
] ,
$JEP{RESULT}.${1} * 2,
${destination2}.$AT{ci_destination_value} ]
Description:
Take the result of 1000 * 1000 and store that in the attribute named “ci_destination_value” on the entity stored in the ${destination} key and by default the convenience key $JEP{RESULT}.${1}. Now multiply the value in the automatic variable $JEP{RESULT}.${1} by 2 and put that result in the attribute named “ci_destination_value” on the entity stored in the ${destination2} key.
4/15/2018
Confidential

35. Trigger Implementation Details
CoreScripts will be stored in records under the TRIGGER IMPL super type in the Main Admin Panel
The entity type will be called either CORESCRIPTS or UNIVERSAL_UPDATE_TRIGGER
Tip: See Triggers slide deck for more details on how to configure triggers
4/15/2018
Confidential

36. CoreScripts Attributes
ci_relative_entities - textbox to enter traversal part of script
ci_trigger_action_type - this allows you to select which events fire the trigger
ci_update_script – textbox to enter update part of script
Implementation Class - code the trigger uses (com.coreinformatics.core.trigger.impl.UniversalUpdateTriggerImpl)
ci_trigger_description - the description is important so others can reuse the same trigger correctly – always fill out this detail!
4/15/2018
Confidential

37. Text Editor Tip
Tip: To simplify troubleshooting, it is recommended to write/edit scripts in a text editor first and then copy/paste into the LIMS text box
The LIMS will remove all carriage returns and display the script in one line in the Details record
4/15/2018
Confidential

38. Copying Boat Attributes Example
An example CoreScript record
The Trigger will be set on the Boat Entity on create and update
4/15/2018
Confidential

39. Boat Record Pre-Populated From Trigger
ci_boat_color was selected during record creation
ci_boat_text was populated automatically from trigger
ci_boat_num was populated automatically from trigger from ENG2 association
4/15/2018
Confidential

40. Troubleshooting? Check the Tomcat logs (sdout file) for errors
4/15/2018
Confidential