Content

Overview Form Maintenance Purpose Form Options Specialized Buttons   Form Processing Form Processing Overview Variables Exposed during Form Processing Methods Exposed during Form Processing Form Processing Output Form Processing Example

 

Overview	Top

"Form Definitions" lets you create and edit Forms. To create a Form, begin by opening the Form List page (Lab Admin → eForms → Form Definitions). This is a standard List page, so click "Add" to open the Form Maintenance page and create a new Form.

 

Form Maintenance	Top

Purpose

The Form Maintenance page provides options that determine how the Form behaves in a Document.

Form Options

The Form tab includes options to define the Form's Business Rules. These describe the use and operation of the Form when presented to the user, such as:

•	Operations available.
•	Requirement for valid data at various stages in Form operation.
•	Data approval requirements.
•	Indication that the Form data requires Double Data Entry (DDE), with options for DDE scenarios.

Field	Description
Form	Form information: • Identifier. • Version Number. • Version Status. • Description.
Version
Version Status
Description
title	Text that identified the Form when you search for it in the eForm Manager page. For example, if the FormId is F-001, you might want to make the title "Study Form 001" for easy identification.
Document Description Rule	When you save the Document, the Groovy script you specify here generates a dynamic description of the Document that is based on things such as the Fields in the Document.
Transient Form	Indicates that this is a Transient Form: • A Transient Form does not save data in the database. Submitted data are checked against any defined validation rules, then the Form is sent to the Form processing module. This lets you use the Form to do things such as create custom Maintenance pages, e.g., create Samples with associated Tests. • Form processing options (except "Checkable") and processing rules are not available with Transient Forms. Additionally, Transient Forms have no life cycle, no states, and exhibit no status transitions. The Form is simply Submitted and processed, i.e., "validate-to-process". • The Submit option is implicit, meaning that the "Submittable" option need not be enabled. • The "Copy" button is removed from the eForm Manager for Transient Forms.
Virtual Form	Virtual Users can access this Form only if this option is enabled.
Translate	Makes the Form translatable (see Translations).
Form Type	Defines the type of Form: Form Type Lets you create... Form (default) A Form that does not require Worksheet capabilities. Worksheet A Worksheet Form. Choosing Worksheet enables the "Worksheet Type", "Items/Worksheet", and "Versionable" fields. See eForm Worksheet Principles for more information.
Worksheet Type	Defines the type of Worksheet (Workitem, Dataset, SDI, or QCBatch) and creates a protected Datasource in the Form Builder. See eForm Worksheet Principles for more information.
Items/Worksheet	Maximum number of items that are passed to the Worksheet during creation. See eForm Worksheet Principles for more information.
Draftable	• Saves changes made to the Form thus far, but does not Submit it to the next state. • If the Form is "Draftable", the next two options are available.
Validate Data when Drafting	Performs field-level validation when working with Draftable Forms. Unchecking this allows validation to be disabled when it is deemed inconvenient or unnecessary (such as in a Draft Document).
Save Invalid Data	Allows data that does not meet validation criteria to be saved as a result of the Draft.
Checkable	Displays the "Check" button on the eForm Manager page: • "Check" detects mistakes made in all fields on the Form, including Group validation rules you have setup. For example, if a value must be a Reference Type and you enter something that is not a valid Reference Type, the check shows the error in the Review pane. • Note that there is "on-the-fly checking" each time you exit a field. However, that is done on a field-by-field basis. • Also note that Group validations are not (by default) checked on-the-fly.
Submitable	Displays the "Submit" button on the eForm Manager page: • The "Submit" operation saves entered data to the database and moves the Document to the next state in the Document life cycle (for that specific document). • If the Form is "Submitable", the next option is available.
Submit Invalid Data	• Allows any data to be Submitted, whether or not it meets validation criteria. • This is for doing things like database transcription, where you just want to save whatever is entered. Another application might be if you are adamant about all entered values being accepted, and you will want to allow invalid data (and possibly find it later by DDE reconciliation). However, the invalid data will still be flagged in the Review pane of the eForm Manager page.
Approval Type	See Conditions for Document Approval in the eForms Document Reference.
Approve Invalid Data	Allows the approver to approve invalid data, which will be used throughout processing of the Form.
Double Data Entry (DDE)	• Indicates that Double Data Entry (DDE) will be used to enter data for the Form. The implications of Double Data Entry are described in the eForm Data Entry Examples and the eForm Document Reference. • If "Double Data Entry" is enabled, the next option is available.
DDE User2 Receives Discrepancy Alerts	• When enabled, both DDE User2 and the Reconciler will be alerted to discrepancies. • When disabled, DDE User2 will not be alerted to discrepancies. However, the Reconciler will be alerted. If this option is enabled, the next option is available.
DDE User2 Can Reconcile Data	When checked, DDE User2 can see DDE User1's entered data and can reconcile it. Relevant Fields must be marked as "Reconcilable" (using the Form Builder's "Reconcile" property).
Reconciliation Role	Role to which the DDE Reconciler belongs. This is required for Reconciling DDE.
Document Manager Role	Role to which the Document Manager belongs.
Lock Document When Done	• When enabled, only the Document Manager can change the Document after its status has tranistioned to "Done". • When disabled, the Document can be edited after its status has transitioned to "Done". See Document Manager Operations in the eForm Manager.
User Training Required	When checked, a user can open the Form only if he has a training certification for the Form. See Worksheet Assignment and Analyst Certification.
User Training Overrides	When checked, a user can can open the Form whether or not he has a training certification for the Form. See Worksheet Assignment and Analyst Certification. The Document retains a record of the override.
Versionable	When checked, enables Versioning for Documents created from Worksheet Forms. See Creating a Worksheet Form.

 

Specialized Buttons	Top

In addition to the standard Maintenance page toolbar buttons, the Form Maintenance page also provides these specialized buttons:

Button	Description
Approve Version	Lets you Approve the Form. A confirmation dialog asks if you want to Approve the Form. After you confirm the Approval, Version Status transitions from "Provisional" to "Current". The Form Builder (below) and Form Processing tab are disabled except on Provisional versions.
Form Builder	Opens a full-screen Form Builder.

 

Form Processing	Top

Overview

When the user "Submits" the Form, Action Blocks defined by Form Processing (and built using the Action Block Editor) describe processing required on the data entered into (or generated from) the Form. This "processing" transposes data defined by Fields to LabVantage objects (such as Samples and Tests).

Variables Exposed during Form Processing

These variables are exposed when evaluating Form Processing rules.

Variable	Description
fields	Map containing the Fields of the Form. The value of the Map entry is a Field object that has its own API. However, for most cases, the syntax will be one of these: fields.fielda
groups	Map containing the Groups of the Form. The value of the Map entry is a Group object.
document	Map containing the values from the Document table for the current Document, e.g., document.documentid .
user	Map containing string values of the connection details. For example, user.sysuserid is the current user.
logger	Logger object for logging to sapphire.log.
database	DBRead object that provides readonly access to the database.
output	Empty Map that allows values to be returned to the eForm Manager page after processing.
actionProcessor queryProcessor sdcProcessor	Standard LabVantage Java Public API Accessors in sapphire.accessor. Example: DataSet projects = queryProcessor.getSqlDataSet( "select * from s_project " ) There are shorthands for a number of the common methods, e.g., • actionProcessor.processAction( actionid, version, props ) can be written as just processAction( actionid, props ) • queryProcessor.getSqlDataSet( sql ) can be written as getSqlDataSet( sql )

Methods Exposed during Form Processing

These methods are exposed when evaluating Form Processing rules:

•	void info( message )
•	void debug( message )
•	void error( message )
•	void error( message, throwable )

Example: logger.info( "project exists" )

Form Processing Output

Using Groovy, you can populate an output map to send data and directive back to the eForm Manager. There are currently two directives:

Directive	Description	Example
REDIRECT	• Tells the eForm Manager where to go next. • Requires a nextpage property to be returned. • All other properties in the output object will be submitted to the nextpage.	This returns a newly created sampleid and displays it in the SampleList page: output.action = 'redirect' output.nextpage = 'SampleList' output.keyid1 = sampleprops.newkeyid1 The value of output.nextpage can be simply the Page Id, or it can be a full Request Controller expression such as rc?command=page&page=SampleList.
EVAL	• Tells the eForm Manager which JavaScript to execute. • Only the action and script property of the output map are used. All other fields are ignored.	This displays a newly created sampleid in an alert dialog: output.action = 'eval' output.script = "alert( 'New sampleid: ${sampleprops.newkeyid1}')" Or, to call your included JavaScript function to perform client-side post-processing code: output.action = 'eval' output.script = quot;postProcess( '${sampleprops.newkeyid1}' )"

Form Processing Example

This example shows how a Groovy script might be used in Form Processing to create a Sample and associate Tests with it:

logger.info( "Start" )

def sampleprops = [

sdcid: "Sample",

sampledesc: fields.subject,

projectid: fields.project,

batchid: fields.batch,

collectiondt: fields.formdate

]

logger.info( "Calling AddSDI with properties: " + sampleprops.toString() )

processAction( AddSDI.ID, sampleprops )

def testprops = [

sdcid: "Sample",

keyid1: sampleprops.newkeyid1,

workitemid: groups.tests.attributeList( "workitemid" )

]

logger.info( "Calling AddSDIWorkItem with properties: " + testprops.toString() )

processAction( AddSDIWorkItem.ID, testprops )

output.action = 'redirect'

output.nextpage = 'SampleList'

output.keyid1 = sampleprops.newkeyid1

logger.info( "Done" )