Configuring Workbook
Overview
The Workbook interface can be configured to customer needs.
Process
Workbook configuration is managed by setting various application preferences. Application preferences are managed using the CCPREF—Preferences application.
Linking Workbook Sessions to Menus
Set the WORKBOOK_CMD_MENU application preference
Set the WORKBOOK_RCLICK_MENU application preference
When a workbook session is launched, then the main and right-click menus are built using the XML code in the scripts contained in the WORKBOOK_CMD_MENU and WORKBOOK_RCLICK_MENU application preferences, respectively. This allows individual operators to have workbook menus tailored to their requirements.
The Scope for these preferences is usually set at laboratory, role or user level.
These application preferences need to be set to the comma-separated list of codes of the scripts containing the XML code used to build the workbook main and right-click menus, respectively.
Author the workbook script using a script authoring tool. For example:
- WORKBOOK_CMD_MENU.xml
- WORKBOOK_STATUS_MENU.xml
- WORBOOK_APP_MENU.xml
- WORKBOOK_EDIT_MENU.xml
- WORKBOOK_INST_MENU.xml
Use the CCSCRT—Script application to create or update a script with the following codes and upload the workbook menu script, ensuring that the script's Script Type is set to 018—Workbook. For example:
- WORKBOOK_CMD_MENU and upload the WORKBOOK_CMD_MENU.xml file
- WORKBOOK_STATUS_MENU and upload the WORKBOOK_STATUS_MENU.xml file
- WORKBOOK_APP_MENU and upload the WORKBOOK_APP_MENU.xml file
- WORKBOOK_EDIT_MENU and upload the WORKBOOK_EDIT_MENU.xml file
- WORKBOOK_INST_MENU and upload the WORKBOOK_INST_MENU.xml file
Configuring the Workbook Interface
Headers
Set the WKBK_TRANSPOSED_GRID_SAMPLE_HEADER application preference
The WKBK_TRANSPOSED_GRID_SAMPLE_HEADER application preference defines the sample attributes used to create the column header text for sample columns for a workbook opened in transposed mode.
The Scope for this preference is usually set at laboratory or user level.
Any multi-lined sample headers truncate or grow, as required.
Example: If a workbook is opened in transposed mode and the WKBK_TRANSPOSED_GRID_SAMPLE_HEADER application preference is set to "SampleName,SampleDescription,SampleID", such that the column header has three lines:
SampleName
SampleDescription
SampleID
if the column is made too narrow, then each line is individually truncated to:
SampleNa...
SampleDe...
SampleID
Column Widths
Set the WKBK_TRANSPOSED_GRID_COLUMN_WIDTH application preference
The WKBK_TRANSPOSED_GRID_COLUMN_WIDTH application preference defines the width of the sample column for a workbook opened in transposed mode.
The Scope for this preference is usually set at laboratory level.
Font
Set the WKBK_FONT_SETTING application
The WKBK_FONT_SETTING application preference defines the font used to display workbook content.
The Scope for this preference is usually set at laboratory level.
Sample Biofields
Set the WORKBOOK_SAMPLE_LIST_BIOFIELDS application preference
Sample biofields can be displayed for each sample on the workbook's Sample Details grid in the CCWKOP—Open Workbook application or Sample Details grid in the CCWKOPTRAN—Open Transposed Workbook application.
Where the WORKBOOK_SAMPLE_LIST_BIOFIELDS application preference is defined and contains a comma-separated list of Biofield:ColumnWidths entries, when a workbook is opened, then the Sample grid displays a column for each valid biofield that has a Use Scope of Sample, after the normal sample and custom attribute columns, where the column heading is the biofield name, and the column width is that as specified in the preference. Where the biofield exists on the sample, then the workbook's cell contains the value of the sample biofield. Where the biofield does not exist on the sample, then the workbook's cell displays empty.
In this example of biofield code and column width for each sample biofield:
HAZ_STATUS:10, TRAY_NO:10, CONT_TYPE:15
the workbook sample panel would show something like:
SampleName|Std01|HazSt|Tray#|Container Type | ...<workbook cells>
The sample-scope biofields are displayed after the existing standard and custom attribute columns (as determined by personalisation).
The Scope for this preference is usually set at instance, organisation or laboratory level.
Customising Workbook Functionality
Where configured, preference-based workbook scripts and scheme-based workbook scripts are used to perform custom functionality.
Scripts are applied via preferences either on a laboratory or use basis (depending on the level at which preferences are set), or scheme-based functions related to display, formula handling or report handling.
Scripts run on workbook open, workbook save, on workbook cell select, before workbook cell change and after workbook cell changed.
For example, scripts can be can used to:
- Hide or display columns, and to control the width of columns in the workbook grids.
- Change job owner and change sample owner within a workbook.
- Incorporate a scripted function in cell formulas. Some cells may have scripts that execute pre-set input or alert dialog boxes to guide you in your data entry, for example, by clicking the OK or Cancel button on the dialog box, to confirm or cancel the data entry.
- Re-calculate highlighted cells by accessing menu items that run custom scripts using the Workbook API.
- Perform rounding and unit conversion on data, and view the outcome in a dialog before adjusting values in the workbook.
- Generate an internal report, then download and open the report.
- Receive or enter multiple readings from the instrument, select a sub-set of those readings and apply a calculation script that can for example, determine the average of the selected readings and update the final value with the result or de-activate particular readings.
Interactive instrument connection scripts are used to:
- Customise instrument connections so that results can be captured or decoded from COM ports, instruments and equipment data files.
- Automatically advance to the next row (same selected column) after a result is captured so that the most common use case is covered by default.
- Override the automatic advance behaviour and have control over which cell is selected after a result is captured.
Customising Workbook using a Script
Set the WORKBOOK_SCRIPT application preference
The WORKBOOK_SCRIPT application preference to the code of the script used to apply custom logic on workbook events.
A workbook script can customise various events, including onLoad and onLoadNextPage to modify the workbook interface, initial data on display, or to run functionality like formula evaluations, and onCellSelected, onCellBeforeChange, onCellAfterChange and onCellParamValueAfterChange to customise data entry and beforeSave and afterSave to customise the submit.
The Scope for this preference is usually set at laboratory, role or user level.
Note that a scheme can link to a workbook script as well. Refer to Maintaining Schemes to configure a workbook script for a sample preparation, analytical preparation or analytical scheme. The code in a workbook script is executed first, followed by the code in a scheme script, for the respective workbook event.
Refer to the Customising Workbook Events in the CCLAS 6 Customisation Guide.
Paging of Samples Loaded into the Workbook
The WORKBOOK_IS_LOAD_ALL_SAMPLES application preference configures whether all samples are loaded into a workbook when a workbook is opened in normal mode or loaded upon a page-down action.
The Scope for this preference is usually set at laboratory level.
Set the WORKBOOK_IS_LOAD_ALL_SAMPLES application preference
Calculating Formulas Automatically on Load
The WKBK_AUTO_CALCULATE_ONLOAD application preference configures automatic calculation of workbook formulas for sample scheme analytes loaded into a workbook.
The Scope for this preference is usually set at laboratory level.
Set the WKBK_AUTO_CALCULATE_ONLOAD application preference
Block Recalculating Formulas Based on Workflow Status
The BLOCK_FORMULA_UPDATE application preference blocks the automatic calculation of workbook formulas for sample scheme analytes loaded into a workbook if the workflow status of the cell matches the ones defined in the preference. The Scope for this preference is usually set at laboratory level.
If not present in the workbook load groovy script, then to show the "Blocked" status in the workbook status bar, insert the line
if(ana.isBlocked){ message = message + "Blocked" }
just before the statusBar2Text is set in the onCellSelected() method.
The snippet is shown as an example.
}
if(ana.isBlocked){message = message + "Blocked"
}
if (ana.locked ) {message = message + " locked"
}
if (ana.hasChanged()) {message = message + " changed"
}
The Detail Panel (CCWKOPPANE) usually launched from the Workbook Menu (CCWKOP - Update Open Workbook), has a new checkbox property called Blocked. If the preference BLOCK_FORMULA_UPDATE Setting Value is set to COMPLETED (as an example) and a result has a workflow status of COMPLETED, then this Blocked attribute will display as checked. If the workflow status of the result does not match the preference or that preference does not exist, then this attribute is unchecked.
Note: If a user needs to run Force Recalculate to re-execute a formula on a cell that is Blocked, then the user has to first reset that cell's workflow status to a value that was not defined in the BLOCK_FORMULA_UPDATE preference (usually COMPLETED and/or RELEASED).
Set the BLOCK_FORMULA_UPDATE application preference
Calculating Results from Multiple Readings
The CALCULATE_FROM_READINGS application preference specifies the script that is used to calculate a new reading from selected readings in the readings grid in the lower panel in the CCWKOP—Open Workbook application, which then becomes the result of the sample scheme analyte.
The Scope for this preference is usually set at laboratory level.
Set the CALCULATE_FROM_READINGS application preference
Setting the Workbook Lock Interval
The WORKBOOK_LOCK_REFRESH_INTERVAL application preference configures the interval, in minutes, at which a heartbeat is sent to the server from a workbook, to keep job scheme locks active.
The Scope for this preference is usually set at laboratory level.
Set the WORKBOOK_LOCK_REFRESH_INTERVAL application preference
Configuring whether Properties for Workbook Logic come from Org or Enabled Scope
When the system assesses results in a workbook:
-
The WORKBOOK_OVERRIDE_SCHEME_LIST application preference defines which scheme attributes are taken from the lab-enabled scheme, and which attributes sre taken from the org-scope scheme, when assessing results in workbook.
-
The WORKBOOK_OVERRIDE_SCHEME_VERSION_LIST application preference defines which scheme version attributes are taken from the lab-enabled scheme version, and which attributes are taken from the org-scope scheme version.
-
The WORKBOOK_OVERRIDE_SCHEME_VERSION_ANALYTE_LIST application preference defines which scheme version analyte attributes are taken from the lab-enabled scheme version analyte, and which attributes are taken from the org-scope scheme version analyte.
The Scope for these preferences is usually set at laboratory level.
Set the WORKBOOK_OVERRIDE_SCHEME_LIST application preference
Set the WORKBOOK_OVERRIDE_SCHEME_VERSION_LIST application preference
Set the WORKBOOK_OVERRIDE_SCHEME_VERSION_ANALYTE_LIST application preference
Related processes...
- Locating Workbooks
- Opening a Workbook Session
- Managing the Workbook Sample List
- Using the Workbook Grid
- Workbook Cell Locks and and Unlocking Workbook Cells
- Entering Results into Workbook Cells
- Using Formulas to Calculate Results
- Understanding System Processes that follow Result Entry
- Generating an Internal Report of Results
- Configuring Analysis
- Configuring Worklist
- Configuring the Quality Results Viewer
