Core LIMS Training: Velocity Templates

Course Topics What are Velocity Templates? Custom Instrument Files Custom Experiment Reports Custom Inventory Reports Custom E-mails Note: This training assumes that you have reviewed and understand Basic Administration Training 2/27/2018 Confidential

Velocity Templates for Reports Velocity Template Language (VTL) is a simplified language that can be used to define customized reports in the LIMS Four use cases currently in the LIMS Create formatted file outputs from a LIMS experiment to be loaded into an instrument Write customized experiment reports to a folder after experiment is published Create customized inventory reports to run from Containers or Samples List Functions page Custom e-mail reports that are activated by a trigger or set on a recurring alert Enables admins more flexibility to define dynamic content by referencing methods already defined in underlying Java code More documentation on VTL can be found at: http://velocity.apache.org/engine/releases/velocity-1.7/vtl-reference-guide.html 2/27/2018 Confidential

Creating a File for Instrument Input LIMS Setup By Admin: Add an association to the instrument Entity Type and the ci_InstrumentFile attribute (data type = Instrument Sequence File) on the experiment Entity Type Add the attribute ci_velocity_template (data type = Velocity Context Text Area or Text - Generic) to the instrument Entity Type Create the instrument record and fill in the ci_velocity_template with a report defined using VTL End User Process: Create new experiment record with desired instrument Associate any required samples or containers Click on Generate hyperlink on experiment record to create file Click on View hyperlink to download and save file Upload custom file to instrument and run experiment 2/27/2018 Confidential

Admin Setup – Update Experiment Entity Type Add the ci_InstrumentFile attribute to make a Generate hyperlink on the experiment record If not already there, add an association to the instrument you want to make a file for on the experiment entity type 2/27/2018 Confidential

Admin Setup – Update Instrument Entity Type If not already there, add the velocity attribute on the instrument entity type 2/27/2018 Confidential

Admin Setup – Create Instrument Record Enter a descriptive name for end users to select when creating an experiment Enter the velocity script that defines how the file is laid out in the instrument record 2/27/2018 Confidential

End User – Expt with Generate/View Hyperlinks Don’t forget to add containers or samples that you want to be in the instrument file first After it is generated, click on View to download/export the file Click on Generate to create or update the file Associated instrument record contains the file definition 2/27/2018 Confidential

End User – Generated File After it is generated, click on View hyperlink to view the file 2/27/2018 Confidential

Example Velocity Script for Instrument File First line defines column header names in output file ${tab} needed to define separators between columns #end closes the loop #foreach ($seq in $seqList) begins a loop over the experiment samples Each $seq term is calling for data for each sample in the list $seq.lot.barcode, $seq.container.barcode, $seq.cellRow, and $seq.cellCol call global variables $seq.sample.getValue(“MW”) is calling a sample attribute – MW must be spelled exactly as the attribute is spelled in the LIMS Tip: Copy/paste scripts into Wordpad or a similar text editor to view code without scrolling 2/27/2018 Confidential

Velocity Template Tips References begin with $ and are used to get something Directives begin with # and are used to do something Avoid spaces within the references (or use an underscore) Attributes that are used for Velocity reports should be in capital letters and spelled exactly as they are in the LIMS For the header lines of code, some instruments require the “${tab}” term written out to denote the start of a new header. Some instruments can just have a actual space placed there by hitting the ‘Tab’ button. 2/27/2018 Confidential

Available Global Variables for Instrument Files Entity Object Available Variables Description Assay $assay.name gets an assay name associated to the experiment $assay.barcode gets an assay barcode associated to the experiment Protocol $protocol.name gets a protocol name associated to the experiment $protocol.barcode gets a protocol barcode associated to the experiment $protocol.getValue("attribute name") gets an attribute on the protocol of the experiment Experiment $experiment.name gets an experiment name $experiment.barcode gets an experiment barcode $experiment.getValue("attribute name") gets an attribute on the experiment Instrument $instrument.name gets an instrument name associated to the experiment $instrument.barcode In addition to the above variables: any attribute from other objects that are directly associated to an experiment The variable name is in the format PREDICATE_ATTRIBUTENAME (replace all spaces, non-alphanumeric characters with ‘_’ and capitalize all characters). For example, the variable named $INSTRUMENT_METHOD_ACQUISITION_METHOD is constructed from the INSTRUMENT METHOD association to an experiment. ‘INSTRUMENT METHOD’ is the predicate and ‘Acquisition Method’ is an attribute of the Instrument Method object. seqList (List of experiment samples) 2/27/2018 Confidential

Variables Available in seqList (for Instruments) 1 Object Object Type Available Variables Description experimentSample Experiment Sample Object $seq.ExperimentSample.name gets a list of experiment sample names $seq.ExperimentSample.barcode gets a list of experiment sample barcodes $seq.ExperimentSample.getValue("attribute name") gets a list of experiment sample attribute values sampleID containerBarcode_cellPos $seq.sampleID gets the list of sample IDs in a series of container cells exptContSeq Experiment Container Sequence $seq.exptConcSeq gets the list of experiment containers linked to an experiment lot Entity Object $seq.lot.name gets a list of lot names associated to an experiment $seq.lot.barcode gets a list of lot barcodes associated to an experiment $seq.lot.getValue("attribute name") gets a list of values for a lot attribute sample $seq.sample.name gets a list of sample names  associated to an experiment $seq.sample.barcode gets a list of sample barcodes  associated to an experiment $seq.sample.getValue("attribute name") gets a list of values for a sample attribute seqList is used to loop through a list of experiment samples 2/27/2018 Confidential

Variables Available in seqList (for Instruments) 2 Object Object Type Available Variables Description container Container Object $seq.container.name gets a list of container names associated to an experiment cellPos Numeric Position $seq.cellPos gets the numeric position of a cell in a multiple well container cellCol Numeric Column $seq.cellCol gets the column number of a cell in a multiple well container cellRow Alphabetical Row $seq.cellRow gets the row number (using the common alphabetic notation) of a cell in a multiple well container deckPositionReference   $seq.deckPositionReference gets the deck position of an instrument locationPos $seq.locationPos gets the numeric position of a slot in a location with slots locationCol $seq.locationCol gets the column number of a slot in a location with slots locationRow $seq.locationRow gets the row number (using the common alphabetic notation) of a slot in a location with slots 2/27/2018 Confidential

Common Velocity Script Examples Output a tab character: ${tab} Loop through an experiment sample list and output the sample barcode: #foreach( $seq in $seqList ) $seq.sample.barcode #end Conditional for a null value: #if(!$seq.sample.getValue(“MW”))No MW found#{else}$seq.sample.getValue(“MW”)#end Output the loop counter: $foreach.count Output a date in a specified format: $date.get('yyyyMMdd') 2/27/2018 Confidential

Creating a Customized Experiment Report LIMS Setup By Admin: If missing, add an Experiment Report Entity Type under the Report Supertype with a the ci_velocity_template attribute Create a new experiment velocity report record and fill in the ci_velocity_template attribute with a report defined using VTL Add an association to the Experiment Report Entity Type on the Assay Entity Type using ON_PUBLISH_REPORT as the predicate Create or edit Assay record to link specific assay record to report record Modify or create Trigger Implementation Entity Type Create a trigger record Add trigger to experiment End User Process: Publish a completed experiment record of the specific assay defined View attached file 2/27/2018 Confidential

Admin Setup –Experiment Report Entity Type If not already there, create an Experiment Report Entity Type under a Report Super Type and add a velocity template attribute 2/27/2018 Confidential

Admin Setup – Create Experiment Report Record Define report using Velocity 2/27/2018 Confidential

Admin Setup –Associate Report To Assay Type 2/27/2018 Confidential On the Assay Entity Type add an association to the experiment report with the ON_PUBLISH_REPORT context

Admin Setup –Associate Assay To Report On the Assay Record select the experiment record with the velocity report 2/27/2018 Confidential

Admin Setup –Trigger Entity Type If one does not already exist, you may need to create or modify a Trigger Entity Type under Trigger Impl Super Type Description, action type, and Implementation Class are required; if you only need these attributes you can use the Trigger Impl Entity Type 2/27/2018 Confidential

Admin Setup – Create Trigger Record Use a descriptive name for pull down menu Define event when report created Must use this class Optional: Define folder where the file will be output on server (you will need to create the folder on server) Can optionally filter reports to a sample type 2/27/2018 Confidential

Admin Setup – Add Trigger to Experiment Select the Triggers hyperlink for your experiment type Select the trigger you created in the Event Only section under ON_PUBLISH Click the Add Triggers button at the bottom of the page 2/27/2018 Confidential

End User – Create and Publish Experiment After the publish link is selected, the report will be automatically generated and attached to the experiment Click on the View File Hyperlink to view the report 2/27/2018 Confidential

Example Template For Experiment Report Source Barcode${tab}Area${tab}Injection Volume #foreach( $seq in $seqList) $seq.lot.barcode${tab}$seq.es.getData("area")${tab}$seq.es.getData("injection_volume") #end 2/27/2018 Confidential

Available Global Variables for Expt Reports Entity Object Available Variables Description Assay $assay.name gets an assay name associated to the experiment $assay.barcode gets an assay barcode associated to the experiment Protocol $protocol.name gets a protocol name associated to the experiment $protocol.barcode gets a protocol barcode associated to the experiment $protocol.getValue("attribute name") gets an attribute on the protocol of the experiment Experiment $experiment.name gets an experiment name $experiment.barcode gets an experiment barcode $experiment.getCreationDate() gets the date an experiment record was created $experiment.getPublishDate() gets the date an experiment was published $experiment.getValue("attribute name") gets an attribute on the experiment In addition to the above variables: any attribute from other objects that are directly associated to an experiment The variable name is in the format PREDICATE_ATTRIBUTENAME (replace all spaces, non-alphanumeric characters with ‘_’ and capitalize all characters). For example, the variable named $INSTRUMENT_METHOD_ACQUISITION_METHOD is constructed from the INSTRUMENT METHOD association to an experiment. ‘INSTRUMENT METHOD’ is the predicate and ‘Acquisition Method’ is an attribute of the Instrument Method object. seqList (List of experiment samples) 2/27/2018 Confidential

Variables Available in seqList (for Experiments) 1 Object Object Type Available Variables Description es Experiment Sample Object $seq.es.name gets a list of experiment sample names $seq.es.barcode gets a list of experiment sample barcodes $seq.es.getValue("attribute name") gets a list of experiment sample attribute values $seq.es.getData("attribute name") gets the experimental data for an assay attribute for each experiment sample sampleID containerBarcode_cellPos $seq.sampleID gets the list of sample IDs in a series of container cells exptContSeq Experiment Container Sequence $seq.exptConcSeq gets the list of experiment containers linked to an experiment lot Entity Object $seq.lot.name gets a list of lot names associated to an experiment $seq.lot.barcode gets a list of lot barcodes associated to an experiment $seq.lot.getValue("attribute name") gets a list of values for a lot attribute sample $seq.sample.name gets a list of sample names  associated to an experiment $seq.sample.barcode gets a list of sample barcodes  associated to an experiment $seq.sample.getValue("attribute name") gets a list of values for a sample attribute seqList is used to loop through a list of experiment samples 2/27/2018 Confidential

Variables Available in seqList (for Experiments) 2 Object Object Type Available Variables Description cell   $seq.cell.cell container Container Object seq.container.name gets a list of container names associated to an experiment $seq.container.barcode $seq.container.getValue("attribute name") gets a list of values for a container attribute Inventory Details $seq.amount gets the numerical amount of material in the container $seq.amountUnit gets the unit for the amount of material in the container $seq.conc gets the numerical concentration in the container $seq.concUnit gets the unit for the concentration in the container $seq.parentCell.cell $seq.parentContainer.barcode 2/27/2018 Confidential

Creating a Customized Inventory Report LIMS Setup By Admin: If missing, add the Inventory Velocity Report Supertype and the Container Inventory Velocity Report/Sample Inventory Velocity Report Entity Types Create a new container or sample inventory velocity report record and fill in the ci_velocity_template attribute with a report defined using VTL End User Process: Transfer or paste in a list of containers or samples into a list functions page Select the report from the Inventory Report option and Submit 2/27/2018 Confidential

Admin Setup – Check Velocity Entity Types Exist You will need Inventory Velocity Report Supertype with the 2 Entity Types below 2/27/2018 Confidential

Admin Setup – Create Velocity Report Record Report Name will appear in pull down menu on List Functions page Enter the velocity script that defines how the inventory report is displayed 2/27/2018 Confidential

End User – Call Report From List Functions Page Select the custom report with velocity script 2/27/2018 Confidential

End User – Report Will Be a Txt File This allows admins to expose other columns of data not available in the default Inventory Report Useful for creating reports with sample, lot, and container info together 2/27/2018 Confidential

Example Velocity Script for Inventory Report This velocity template creates the report shown on the previous slide 2/27/2018 Confidential

Available Global Variables for Inventory Reports cellList (List of container cells /wells) 2/27/2018 Confidential

Variables Available in cellList Object Object Type Available Variables Description cellContent Cell Contents Objects $cell.cellContent.contentration Gets the concentration of a cell cell Cell Object cell.cell.cell Gets the cell number $cell.cell.amount Gets the numerical amount (without units) $cell.cell.unit Gets the amount unit $cell.cell.getColumnMajor("Container Format")   lot Entity Object cell.lot.name Gets the name of the lot in the container cell $cell.lot.barcode Gets the barcode of the lot in the container cell $cell.lot.getValue("attribute name") Gets the value of an attribute on the lot stored in the container cell $cell.lot.sample. name Gets the name of the sample in the container cell $cell.lot.sample.barcode Gets the barcode of the sample in the container cell $cell.lot.sample.getValue("attribute name") Gets the value of an attribute on the sample stored in the container cell container Container Object $cell.container.name Gets the name of the container $cell.container.barcode Gets the barcode of the container $cell.container.getValue("attribute name") Gets the value of an attribute of the container cellList is used to loop through a list of container cells 2/27/2018 Confidential

Inventory Report Example With Association Container Type${tab}Container Barcode${tab}Location${tab}Cell${tab}Well${tab}Amount${tab}Sample${tab}Lot${tab}Number of Compounds${tab}Includes Lots #foreach( $container in $containerList) #set( $containerFormat = ${container.getValue("Container Format")} ) #set( $cellMap = ${formatToCellMap.get($containerFormat)} ) #foreach( $cell in $container.getCellList()) #set( $cellNum = ${cell.getCell()} ) #foreach( $content in $cell.getContents()) ${container.getEntityTypeName()}${tab}${container.getBarcode()}${tab}${container.getFullLocation()}${tab}${cell.getCell()}${tab}${cellMap.get("$cellNum")}${tab}${cell.getAmountString()}${tab}${content.getLot().getSample().getBarcode()}${tab}${content.getLot().getBarcode()}${tab}${content.getLot().getSample().getValue("Number of Compounds")}${tab}#foreach( $smallMol in $content.getLot().getChildAssociations("SMALL MOLECULE LOT")) ${smallMol.getBarcode()},#end${tab} #end This container inventory example calls an association 2/27/2018 Confidential

Sample Inventory Report Example Container Type${tab}Container Barcode${tab}Location${tab}Cell${tab}Amount${tab}Sample${tab}Lot${tab}Concentration #foreach( $infoMap in $cellList)${infoMap.container.getEntityTypeName()}${tab}${infoMap.container.getBarcode()}${tab}${infoMap.container.getFullLocation()}${tab}${infoMap.cell.getCell()}${tab}${infoMap.cell.getAmountString()}${tab}${infoMap.lot.getSample().getBarcode()}${tab}${infoMap.lot.getBarcode()}${tab}${infoMap.cellContent.getConcentrationDisplay()} #end 2/27/2018 Confidential

Creating Customized E-mails Multiple ways that formatted e-mails can be sent Option 1: Velocity Template on a Trigger Define the custom message on trigger record Option 2: Velocity Template on a Message Linked to an Alert Define the custom message on a message record and execute on a recurring schedule 2/27/2018 Confidential

Velocity Templates on Triggers LIMS Setup By Admin: If missing, add the ci_velocity_template attribute and an association to a message on the trigger entity Create message record with distribution list only Create trigger record with association to message and velocity template filled out Define trigger on the entity that will invoke the trigger End User Process: User performs action defined by trigger Users on distribution list receive e-mail report 2/27/2018 Confidential

Setup for Option 1 (VT on Trigger Entity) Add the ci_velocity_template attribute to a trigger entity type if not already there 2/27/2018 Confidential Also need an association to the message entity type

Setup for Option 1 (Create Message Record) If you have a Velocity Template defined on the trigger, leave the Implementation Class blank (any hardcoded messages in the Implementation Class will take precedent over the velocity template) Create a new message record Add any user accounts that need to receive the message automatically 2/27/2018 Confidential

Setup for Option 1 (Create Trigger Record) Create a new trigger record Enter when trigger can occur – this will add the trigger to trigger pull down menus for entities Enter message written with Velocity/standard HTML Select an association to message record you just created Message record will also display the association now 2/27/2018 Confidential

Setup for Option 1 (Define Trigger on Entity) Select Triggers hyperlink on Entity Type you want to trigger a message from Select the trigger records you created earlier to define triggers on the entity type Only Action Types that are listed on the trigger record will be selectable 2/27/2018 Confidential

End User Performs Action This example a user can create a new QA Sample record to trigger a message 2/27/2018 Confidential

End User Gets E-mail 2/27/2018 Confidential

Velocity Templates on Messages With Alerts LIMS Setup By Admin: Add the ci_velocity_template attribute to a message Create message record with distribution list and velocity template filled out Create alert record and associate to message Set the alert time End User Process: Users on distribution list receive e-mail report 2/27/2018 Confidential

Setup for Option 2 (VT on Message Entity) Add the ci_velocity_template attribute to a message entity type if not already there 2/27/2018 Confidential

Setup for Option 2 (Create Message Record) Required to have some SQL select statement for the Custom Data Message, but the velocity template is not required to use the results returned from the query Create a new message record Enter Velocity Template If VT is null, then you will get an unformatted table of all data from the SQL query Add any user accounts that need to receive the message automatically 2/27/2018 Confidential

Setup for Option 2 (Create Alert Record) Enter when alert will occur Default = daily Weekly enter day of the week as number (Monday=1) Monthly enter day of the month as number Create a new alert record Select an association to message record you just created Message record will also display the association now 2/27/2018 Confidential

Setup for Option 2 (Set Alert Time) If desired, you can modify the time the alert is sent by editing the LIMS configuration page Note: You will need to restart the Project Daemon to update the change 2/27/2018 Confidential

End User E-mail 2/27/2018 Confidential