Configuring Physical Measurement Stages

Skip to end of metadata
Go to start of metadata

Overview

Your organization may require one or more physical measurement stages for its custom version of Onyx. Typically, a separate Onyx stage is defined for each type of physical measurement.

The onyx-demo web application includes several physical measurement stages. You can use these stages as models for the physical stages of your custom version of Onyx.

Configuration Files for a Physical Measurement Stage

The configuration files for physical measurement stages are in the WEB-INF/config/jade/resources/instruments directory.  This directory includes a subdirectory for each physical measurement stage.   For example,  the subdirectory for the blood pressure stage in onyx-demo is:

    WEB-INF/config/jade/resources/instruments/BloodPressure

The subdirectory for a particular physical measurement stage includes a descriptor file that defines the stage (instrument attributes, input and output parameter attributes, validation, contraindications, and so on) and properties files for localizing the text that appears onscreen. The files are named as follows:

The onyx-demo application includes a couple of physical measurement stages that launch software for particular models of instrument. If an instrument has its own software that will be launched automatically by Onyx, an additional directory will be defined for the instrument in an instruments directory at the same level as WEB-INF. It is not currently possible to define a custom stage that will launch an instrument's software and capture the data automatically.

Physical Measurement Stages Copied from onyx-demo

When you copied the directory structure of the onyx-demo web application, you got a number of physical measurement stages. There should a subdirectory for the following stages in your WEB-INF/config/jade/resources/instruments directory:

To prepare a new physical measurement stage, you can use these stages as models. If you want to keep any of these stages, you can use them as is or modify them as necessary.  A couple of the stages launch proprietary software for particular instrument models. You can use these stages as is in your custom version of Onyx if you wish. 

Support has also been implemented for a number of other instruments with proprietary software.  Check the complete list of supported instruments, and contact us if you need more information.  It is not currently possible to define a custom stage for electronic instruments other than those in the supported list. 

Defining the Instrument Descriptor File

The instrument descriptor file defines how a physical measurement stage will be presented in Onyx. To prepare the instrument descriptor file for a custom physical stage, start with a descriptor file for one of the physical measurment stages in onyx-demo and edit the elements as necessary.

Example of an Instrument Descriptor File

An instrument descriptor file defines how the physical measurement stage will proceed in Onyx. The following example of an instrument descriptor file is for a sitting height measurement.

instrument-descriptor.xml

Elements of an Instrument Descriptor File

These are the elements that can be included in an instrument descriptor file.

Elements Description
<instrumentType> Top-level element for defining an instrument and its attributes.
<contraIndication> Contraindication, a condition that, if present, means the stage should not be carried out.  If one or more contraindication elements are included in the instrument descriptor file, the first page of the stage will be about contraindications.

The <type> can be:
  • ASKED - The interviewer will be prompted to ask the participant a question about this contraindication, and will have to select a radio button (Yes, No, or Doesn't Know) to register the participant's response.
  •  OBSERVED - The interviewer will be prompted to observe whether or not a contraindication exists and will have to select the type from a drop-down list.
    If several contraindications are included, they may as well all be of the same type.
<interpretative> Creates an interpretative variables used to capture information about the measurement. Like <contraIndication> elements,  <interpretative> elements require a <type>  (observed or asked). If one or more <interpretative> elements are included in the instrument descriptor file, a page about these variables will be included in the stage.
<expectedMeasureCount> Optional. A data source can be used to set the minimum number of measurements required to validate the measurement. Can only be defined for instruments whose <captureMethod> is AUTOMATIC. Available since Onyx 1.3.0. If this element is not included, at least one measurement will be expected. See Allow Multiple Measures for details.
<input> Defines an Input Parameter. An input parameter is a value that needs to be fed to the instrument in order to take the measurement. For example, height is an input parameter for a bioimpedence instrument.  Input parameters are only required for electronic instruments with which Onyx will interface.  
<output> Defines an Output Parameter. An output parameter is a value that is captured from the instrument. These may be typed in by the operator or read directly from the instrument.
<code> The code name of an instrument parameter. Must be unique within <instrumentType>. Serves as the key for the key-value pairs defined in the properties files for the stage.  See Localizing a Physical Measurement Stage.
<captureMethod> Defines how an output parameter is captured. MANUAL indicates that the operator is expected to provide the value. AUTOMATIC indicates that the value will be obtained by programmatic means. COMPUTED indicates that the value will be computed based on other values.
<measurementUnit> Required for unit conversion when one parameter is used as input to another. All SI units (abbreviations) are supported.
<dataType> Describes the type of data that is captured. Possible values for <dataType> are: BOOLEAN, DATA (DATA could be used to capture an image), DATE, DECIMAL, INTEGER, TEXT 
<mimeType>
 Describes the file type of output data. Should be defined for <output> whose <dataType> is DATA.  Possible values for <mimeType> are:
  • application/vnd.ms-excel
  • text/xml
  • application/pdf
  • image/bmp
  • image/jpeg
<dataSource> Instrument runtime value can be automatically obtained from an external Connect Jade, Quartz and Mica to Variable Provider#Data Source Modeldata source.
<condition> Optional. Can only be defined for output parameters. Depending on how this condition is resolved, the operator may or may not be prompted to take another measurement.  See RES_THIRD_SITTING_HEIGHT in instrument-descriptor.xml above.

Using Data Sources in an Instrument Descriptor File

Instrument descriptor files can use a <dataSource> element for various purposes. One of the attributes of a <dataSource> element is class.  See data source for more information about data sources and the possible values of the class attribute. 

  • Input parameters can specify a <dataSource> element. For example, when an instrument requires the participant's gender, an input parameter can use a participantPropertyDataSource to fetch the value automatically:
  • A data source can be used to compute values (see CALC_AVG_SITTING_HEIGHT in instrument-descriptor.xml above).
  • A data source can be used to define a condition for an output parameter (see RES_THIRD_SITTING_HEIGHT in instrument-descriptor.xml above).

Using Integrity Checks in an Instrument Descriptor File

Output parameter values can be checked for validity/integrity by using predefined integrityChecks:

Integrity Check Description
equalsValueCheck The output value must match a fixed value.
equalsParameterCheck The output value must match another parameter's value. Useful for checking output parameter values against input parameter values.
rangeCheck The output value must be within a certain male/female range of values. (see examples in instrument-descriptor.xml above)
parameterSpreadCheck Checks that two parameter values are within a specified range; either absolute range (example: +/-1cm) or relative (example: +/-5%)

All integrity checks can be configured to produce a warning instead of an error by specifying its type element as WARNING.

Localizing a Physical Measurement Stage

After you have prepared the instrument-descriptor.xml file for a physical measurement stage, you must prepare properties files that contain localized strings for all the labels that will appear in the user interface.  All elements in the instrument descriptor file that include a <code> element need to be localized. The <code> elements are the keys in the key-value pairs in the properties files.  Here is a snippet from the English properties file for the blood pressure stage.

Adding a Physical Measurement Stage to Onyx

To add a physical measurement stage to your custom version of Onyx, you must:

  1. Add the stage to the list of physical measurement 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 physical measurement stage in your version of Onyx, you need to add a <stage> element to the WEB-INF/config/jade/stages.xml file.

You can define dependency conditions by using the <stage> elements for the onyx-demo stages as a model. See also Defining Stage Dependencies.

WEB-INF/config/jade/stages.xml

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/jade directory .

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

  • Add a line to the English properties file :
messages_en.properties
  • And a line to the French properties file:
messages_fr.properties

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: BloodPressure) to this line in the global Onyx configuration file :

WEB-INF/config/onyx-config.properties

Removing Traces of onyx-demo Stages

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

  1. Remove unrequired  <stage> elements from the WEB-INF/config/jade/stages.xml file.
  2. Remove localized strings for the names of the unrequired stages from the properties files in WEB-INF/config/jade
  3. Remove directories for unrequired stages from the WEB-INF/config/jade/resources/instruments directory.
  4. Remove directories for unrequired stages from the instruments directory.
Search Onyx Documentation
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.