Configuring Sample Collection Stages

Overview

Onyx can include stages for collecting biological samples (blood, urine, and so on). This page explains how to configure a sample collection stage.

Configuration Files for Sample Collection Stages

The configuration files for the sample stage are found in the $custom-onyx/WEB-INF/config/ruby directory.  SInce you copied the onyx-demo application, the directory should contain these standard configuration files:

• messages_en.properties   (contains English strings for all messages in all sample collection stage)
• messages_fr.properties   (contains French strings for all messages in all sample collection stage)
• module-context.xml   (contains tube registration configurations for all sample collection stages)
• remarks.xml  (contains codes for a set of remarks that will be displayed in a drop-down list)
• stages.xml  (contains definitions of all sample collection stages)

and these files specific to the onyx-demo application which includes two sample collection stages (Blood and Urine, and Urine only):

• info-messages.bloodUrine.xml   (contains codes for custom messages in the Blood and Urine stage)
• info-messages.urine.xml   (contains codes for custom messages in the Urine stage)

Screenshot of a Sample Collection Stage

The screenshot below shows the main page of a typical sample collection stage. The page includes a table of registered tubes. When the user scans the barcoce on a sample tube, the barcode is validated and if it passes validation, the tube is added to the table. Columns can be added to the table when you define the barcode structure.

What's Involved in Configuring a Sample Collection Stage

Configuring a sample collection stage involves the following:

• Defining the number of samples that the user is expected to collect
• Defining the structure of the barcode on sample labels and barcode validation
• Defining predefined remarks that the user choose from to describe the sample
• Defining custom information messages for the user (optional)
• Adding the stage to the stages.xml file
• Setting the stage order in Onyx

Preparing a Bean for Your Sample Collection Stage

The module-context.xml  file  that you copied from the onyx-demo application includes two bean definitions: one for each of the two sample collection stages defined in onyx-demo. You should copy one of these beans and modify its identifiers to fit your sample collection stage.  For example, if your stage only for collecting blood, its identifiers would look like this:

Naming the Stage

The string you use for key here is the name you will enter for the stage in the stages.xml file. See Adding the Stage to stages.xml.

Defining the Number of Samples Expected

To define the number of samples (tubes) that the user is expected to collect during the stage, edit this property in the bean for your stage in WEB-INF/config/ruby/module-context.xml:

    <property name="expectedTubeCount" value="15" />

Defining the Barcode Structure

The barcode structure for the stage is defined in this property of the bean for your stage in WEB-INF/config/ruby/module-context.xml:

    <property name="barcodeStructure">

A structured barcode is validated by an ordered list of barcode part parsers. Each part parser is responsible for validating a certain number of characters within the barcode. When valid, this portion is removed from the barcode and the remaining sequence of characters is passed on to the next part parser.

A barcode part parser can do the following:

• Notify the user with a specific message when a validation error occurs
• Validate the part based on any type of criteria, even data from within the database
• Optionally display a column (with localized labels) in the table of registered tubes that is displayed in Onyx. See the column labelled Tube Type in the Screenshot of a Sample Collection Stage.

Using Predefined Barcode Parsers

You can use these predefined parsers.

Example Using Predefined Parsers

For this barcode structure...

...the validation for the different parts of the barcode would be:

Here is how the above barcode structure would be validated:

This configuration would result in two columns being displayed in the table of registered tubes in Onyx.

Localizing Labels for Columns and Tube Types

The labels for columns and tube types must be added to the properties files in WEB-INF/config/ruby. 

The labels associated with the values of barcode parts are looked up using a key composed of the part's value and the parser's column title, like this: columnTitle.partValue.  If no label is found for a particular part value, the part's value itself becomes the label. 

In the above example,  the needed English labels would be defined by adding these lines to the English properties file:

Defining Custom Parsers

Part parsers classes must implement the IBarcodePartParser interface. As such, creating a custom parser is very straightforward.

Defining Remarks for Drop-down List

When a tube is added to the table of registered tubes (see screenshot), an Edit link is available. This Edit link leads opens a dialog that includes a drop-down list of remarks that the user can choose from to describe the sample. To populate this file, you must:

1. Define the codes for the strings that will populate the drop-down list in the remarks.xml file.
2. Define the corresponding localized strings in the message_locale.properties files.

Here are the codes for the remarks from the onyx-demo application:

Here are the English strings for the remarks in the onyx-demo application:

Adding Custom Messages

As shown in the screenshot, a sample collection stage can display a number of messages near the top of the main page of a sample collection stage. 

Defining Custom Messages for One Sample Collection Stage

To set up custom messages for a particular sample collection stage, you must:

1. Create a file containing the codes for the stage's messages . For example, the onyx-demo application, has two such files: one for each of its sample collection stages (info-messages.bloodUrine.xml and info-messages.urine.xml). Put the file in the WEB-INF/config/ruby directory.
2. Add localized strings for the custom messages to the messages_locale.properties files in WEB-INF/config/ruby directory.
3. Edit the WEB-INF/config/ruby/module-context.xml file  and add a <property name="infoMessagesFile"> element  to the bean definition for the stage.  Set the value to the    appropriate filename. For example:

Using the Same Messages for All Sample Collection Stages

1. Create a file named info-messages.xml that contains the codes for the messages.
2. Add localized strings for the messages to the messages_locale.properties files in WEB-INF/config/ruby directory.

      NOTE:  Do not add any  <property name="infoMessagesFile"> elements to the module-context.xml file. 

Adding a Sample Collection Stage to Onyx

To add a sample collection stage to your custom version of Onyx, you must:

1. Add the stage to the list of sample collection stages.
2. Localize the name of the stage.
3. Set the position of the stage in the global stage ordering.

Adding the Stage to stages.xml

To add a sample collection to your version of Onyx, you need to add a <stage> element to the WEB-INF/config/ruby/stages.xml file.
You can define any dependency conditions by using the <stage> elements for the onyx-demo stages as a model. See also Defining Stage Dependencies.

The <name> of the stage must be the name used in the module_context file.  See Naming the Stage.

Localizing the Name of the Stage

To localize the name of the physical measurement in each available interface language, you edit each of the properties files in the WEB-INF/config/ruby  directory .

For example, to localize the name of the BloodPressure stage:

• Add a line to the English properties file:

• And a line to the French properties file:

Setting the Position of the Stage in the Interview

To establish where a stage fits in the interview, you add the stage name (for example: BloodSamplesCollection) to this line in the global Onyx configuration file :

Removing Traces of onyx-demo Stages

When you have finished defining your custom sample collection stages, be sure to remove all traces of the stages copied from onyx-demo.

1. Remove onyx-demo  <stage> elements from the WEB-INF/config/ruby/stages.xml file.
2. Remove onyx-demo <entry> and <bean> elements from the WEB-INF/config/ruby/module-context.xml file.
3. Remove the localized strings for the onyx-demo stages from the properties files in WEB-INF/config/ruby. Check these sections:
      Stage Descriptions
      Info Messages for BloodUrine
      Info Messages for Urine
4. Remove files for onyx-demo custom messages from the WEB-INF/config/ruby directory:
      info-messages.bloodUrine.xml
      info-messages.urine.xml

Search Onyx Documentation