Configuring the On-line Application

Forms See also
SAMANA—CriteriaInstrument Form

SAMANA—SamanaEdit Form

Capturing Data using On-line Data Capture Sessions

Overview

A workbook comprises scheme and analytes for a selected production or laboratory batch job, presenting the CUID scheme analyte results in a spreadsheet, allowing for result entry, capture and calculation from formula, as well as the use of commands to manipulate the data within the spreadsheet.

Various aspects of the workbook environment can be configured by the LIMS administrator to limit access, fix the type of data expected, and to customise the spreadsheet.

This process is pertinent to LIMS and laboratory managers who configure the LIMS, and workbook sessions in particular.

Process

Configuring Access to the On-line Application

Ensure the Samana.exe file is located in the folder defined by the ExeDirectory GLOBAL setting. Give users, or users with specific roles, access to the application by setting the AccessLevel SAMANA program setting. Once a user has sufficient access rights, they can run the On-line application either from the On-line node on the CCLAS menu or directly from the CCLAS Exe folder.

Enable the ShowTipOfTheDay SAMANA program setting to display tips to users upon start up of the On-line application, and enter the tips, with one tip per line, in a file, place the file in a folder under the CCLAS root folder defined by the CCLASRootDirectory GLOBAL setting, then set the TipofTheDayFile SAMANA program setting to the folder and file name, for example %CCLASRootDirectory%TIPS\ONLINE.TIP.

Set the DataCaptureErrorLog SAMANA program setting to the name of the error log file.

Set the AutoRefreshDelay SAMANA program setting.The data displayed in the On-line grid is automatically refreshed at an interval defined by the AutoRefreshDelay SAMANA program setting.

Adding Custom Start-up Forms to On-line Data Capture

On-line data capture often requires custom forms that are tailored to a laboratory's requirements to automatically load and execute upon application start up. If auto-start-up forms are not defined, then the main screen of the On-line module displays on application start up.

Set the AutoRunn SAMANA program settings to the custom forms to be run automatically on start up of the On-line application.

Configuring Access to Data in an On-line Data Capture Session

Non-level 3 users can be limited to which data they can modify based upon the status of the data.

Set the AnalyteLockedStatuses SAMANA program setting to the comma-separated list of statuses to lock cells containing data with one of the statuses, to prohibit the user making changes. For example, to ensure non-level 3 users cannot modify validated, IGN, NA, IS or LNR sample analytes, set the program setting to CPL,IGN,NA,IS,LNR.

Configuring On-line Run List

The application starts up with an empty instrument run list to which users add samples by finding the first sample scheme, then adding the rest of the samples in the job scheme or the rest of the sample's schemes, or by adding different sample schemes, or by adding a pre-configured run list, or by creating a dynamic run-list for an instrument scheme. Set the MainListViewColumnn SAMANA program settings to specify which columns from the SAMPLE table are presented in the grid.

To filter the instrument run list based on field criteria:

  • Set the Criterian SAMANA program setting to specify the column filtering properties using the PROFJOBCUID table, and set the CurrentCriteria SAMANA program setting to default the current criteria.
  • To enable the Properties main menu option to allow users to update the criteria, enable the AllowProperties SAMANA program setting.

Enable the AddFirstSample SAMANA program setting to append an empty sample as the first sample in the instrument run list.

To help performance of finding and loading samples in the instrument run list:

  • Set the GridComboMaxItems SAMANA program setting to the maximum number of jobs that appear in the Job drop-down list.

  • Set the GridMaxItems SAMANA program setting to the maximum number of schemes that appear in the Scheme, Cuid, Type and Ident drop-down lists.

  • Set the InitialRecords SAMANA program setting to the number of samples from a job that are initially loaded into the instrument run list, when adding the rest of the samples for a job.

On-line data capture often requires custom forms which are tailored to a laboratory's requirements, typically used to populate the instrument run list using custom criteria. To add the name of a custom form to the Add main menu option in the On-line application:

Note: Contact your CCLAS support representative for coded forms.

Enable the AllowSampleNavigation SAMANA program setting to allow the user to move to samples in the instrument run list. If the setting is disabled, then the IFF controls the movement to the next sample.

Set the SelectedRowColour SAMANA program setting to the background colour of the selected row.

Enable the FindNextUnanalysedQC SAMANA program setting so that when results for a QC sample are captured, if the sample type and sample ident are used to find the next QC sample, but there are multiple QC samples with the same type and ident, then the next non-analysed QC sample is located and receives the result.

Configuring the Collection of Data from Instruments

Defining the source of the data, the protocol (if any) used to interact with the instrument, and how the data is decoded, is managed by an Instrument Format File (IFF) located in the IFFScripts folder. The instrument format files contain VBScript language.

  • The Instrumentn SAMANA program settings for the current user's staff account contains the IFFs and hence the available instruments.

  • If no such program settings exist for the user's staff account, then the same settings for the CCLASMGR staff account contains the IFFs and hence the available instruments.

  • If no such program settings exist for the CCLASMGR staff account, then the list of IFFs in the IFFScripts folder is used.

The mode of the data from the instrument defaults to Final unless overridden in the IFF.

The weight-to-volume correction mode defaults to Off unless overridden in the IFF.

Where a decoded sample scheme is not yet registered in CCLAS, the registration mode defaults to Never unless overridden in the IFF.

The Main subroutine in the IFF runs upon instrument selection to load the instrument string decoding details.

  • Enable the UseShortname SAMANA program setting to locate a result for an analyte in the instrument data string by matching on the analyte's short name.

  • Enable the FindNextUnanalysedQC SAMANA program setting to locate the next non-analysed QC sample where the sample type and sample ident are used to find the next QC sample but there are multiple QC samples with the same type and ident.

Customising the Collection of Data from Instruments

Where the SamanaKeys.VBS VBScript file is located in the folder defined by the ConfigDirectory GLOBAL setting, then the Main subroutine within it is triggered before data is captured, to allow for the pre-programming of the F6-F12 function keys so that they can be used in the main On-line form to control the data capture or manipulate the form.

Testing the IFF for Data Capture

Use the On-line application to test the IFF for data capture. Where required, the IFF can be edited directly from an instrument data capture session in the On-line application.

Edit the IFF from an instrument data capture session

Configuring the Display and Entry of Data into the Spreadsheet

The colour of an on-line grid cell indicates the state of the underlying data. The various colours are configurable with program settings.

Description Cell background colour
A sample/scheme/analyte requires a check when the result is over the upper limit for the scheme, or below the detection limit for the scheme and CheckLDL GLOBAL setting is enabled. Defined by the DetLimitFailureColour SAMANA program setting.
A sample/scheme/analyte quality control warning can be raised if it is a quality control sample out of range of acceptable limits, but within warning limits, or an unknown sample out of product specification warning limits. Defined by the QCWarningColour SAMANA program setting.
A sample/scheme/analyte quality control failure can be raised if it is a quality control sample out of range of acceptable warning limits, or an unknown sample out of product specification limits. QC failure colouring has precedence over formula colouring. Defined by the QCFailureColour SAMANA program setting
Cell contains a formula used to calculate the displayed result. Defined by the FormulaBackgroundColour SAMANA program setting.
The sample is not profiled for the scheme and analyte, that is, the PROFJOB_CUID_SCHEME_ANALYTE record does not exist. Blue
Calculating Results

Formulas are used to calculate results from entered data and parameters. The default formula for a cell is set by the scheme analyte's Formula.

Defined names are used to assist with formula definition. Where the spreadsheet is not opened in read-only mode, defined names can be added, deleted or modified.

When a sheet is initially loaded, the list of defined names contains the following definitions:

  • CUID
  • EXTERNALIDENT
  • SAMPLEIDENT
  • SAMPLETYPE
  • Analyte1
  • Analyte2
  • etc...
  • Scheme1.Analyte1
  • Scheme1.Analyte1
  • etc...

Logical and error values are usually the result of a formula, although entering these values can be useful for testing formulas. The logical values that can be entered are TRUE and FALSE. The error values that can be entered are #N/A, #VALUE!, #REF!, #NULL!, #DIV/0!, #NUM!, and #NAME?.

  • Enable the AllowAutoOverwriteFormula SAMANA program setting to overwrite an analyte's stored formula with a result captured from the instrument. If this setting is disabled, then formula cells are not overwritten with captured results.

  • Enable the SupportOldFormulaNames SAMANA program setting to support old-style formulas.

  • Enable the RecalculateFormulae SAMANA program setting to evaluate the formula in schemes that are not loaded for the current session, when sample data is saved.

  • Enable the SpawnInvertedxMDE SAMANA program setting to spawn the Data Entry inverted spreadsheet functionality in the background to perform inter-scheme calculations, since the On-line application functionality only allows for intra-scheme calculations.

Configuring the Assessment of Results

During detection limit assessment of results for unknown samples, results are always assessed against the upper detection limit, however, enable the CheckLDL GLOBAL setting to assess the result against the lower detection limit as well.

Products can have product rule scripts created for a scheme. The script is run to perform custom logic upon product assessment against the limits for the scheme.

Customising the Assessment of Results

Set the AutoProductCheck attribute to true in the IFF to automatically check samples against product limits as results are captured.

Configuring the Saving of Results

Enable the AutoStoreFormattedValue GLOBAL setting to automatically calculate and store the formatted value of CUID scheme analytes when the final values are saved.

Customising the Saving of Results

Where the IFF VBScript contains the AfterStoreSample subroutine, this is run when the analytical results are saved for the sample.

Where the SamUDF.VBS VBScript file is located in the folder defined by the ConfigDirectory GLOBAL setting and:

  • The AfterSave subroutine exists within the script file, after sample results are saved, then the script is run to perform custom logic.

Configuring the Saving and Closing of Data Capture Sessions

Prior to CCLAS 2.40.0, when capturing data using On-line data capture sessions with the Samana.exe application, where the AutoStatusUpdate SAMANA program setting was enabled, then the status of jobs associated with the analysed samples was updated at the end of the On-line session. However, in situations in which the On-line data capture session ran over several weeks, then this list of jobs became very long and caused the shut down of the Samana.exe application to take an immense amount of time.

From CCLAS 2.40.0, this setting is made obsolete. This means that the user is required to go into the MDE.exe or xMDE.exe application when the data capture session is closed, and for each associated job, to manually update the start and completion dates and status flags for the analytes, schemes, samples and job, for the job to cascade to completed.