In a Standard assay design, you can enable reporting of warnings in a transformation script by using the
maximumSeverity property. Ordinarily, errors will stop the execution of a script and the assay import, but if warnings are configured, you can have the import pause on warnings and allow an operator to examine the transformed results and elect to proceed or cancel the upload. Warning reporting is optional, and invisible unless you explicitly enable it. If your script does not update maximumSeverity, then no warnings will be triggered and no user interaction will be required.
Note that this feature applies only to the Standard Assay Type and is not a generic assay feature. Warnings are also not supported for assays set to Import in Background.
Enable Support for Warnings in a Transformation Script
To raise a warning from within your transformation script, set maximumSeverity to WARN within the transformedRunProperties file. To report an error, set maximumSeverity to ERROR. To display a specific message with either a warning or error, write the message to errors.html in the current directory. For example, this snippet from an R transformation script define both warning and error handlers:
# Writes the maximumSeverity level to the transformRunProperties
# file and the error/warning message to the error.html file.
# LabKey Server will read these files after execution to determine
# if an error or warning occurred and handle it appropriately.
handleErrorsAndWarnings <- function()
{
if(run.error.level > 0)
{
fileConn<-file(trans.output.file);
if(run.error.level == 1)
{
writeLines(c(paste("maximumSeverity","WARN",sep="t")), fileConn);
}
else
{
writeLines(c(paste("maximumSeverity","ERROR",sep="t")), fileConn);
}
close(fileConn);
# This file gets read and displayed directly as warnings or
# errors, depending on maximumSeverity level.
if(!is.null(run.error.msg))
{
fileConn<-file("errors.html");
writeLines(run.error.msg, fileConn);
close(fileConn);
}
quit();
}
}
Download an example transformation script including this handler and other configuration required for warning reporting, including how to decide what message to print for the user and a commented out example of how a message on error could be triggered:
Workflow for Warnings
When a warning is triggered during assay import, the user will see a
Transform Warnings panel.
Any
Output Files can be examined (click the link to download) with the option to
Proceed or
Cancel the import based on the contents.
If the user clicks
Proceed the transform script will be rerun and no warnings will be raised the on second pass. Quieting warnings on the approved import is handled using the value of an internal property called severityLevel in the run properties file. Errors will still be raised if necessary even after proceeding past warnings.
Priority of Errors and Warnings
- 1. Script error (syntax, runtime, etc...) <- Error
- 2. Script returns a non-zero value <- Error
- 3. Script writes ERROR to maximumSeverity in the transformedRunProperties file <- Error
- If the script also writes a message to errors.html, it will be displayed, otherwise a server generated message will be shown.
- 4. Script writes WARN to maximumSeverity in the transformedRunProperties file <- Warning
- If the script also writes a message to errors.html, it will be displayed, otherwise a server generated message will be shown.
- The Proceed and Cancel buttons are shown, requiring a user selection to continue.
- 5. Script does not write a value to maximumSeverity in transformedRunProperties but does write a message to errors.html. This will be interpreted as an error.
Related Topics
