Customizing the Global Configuration

Skip to end of metadata
Go to start of metadata

Overview

To create a customized version of Onyx, you use the onyx-demo application as a starting point. You can modify various aspects of the global Onyx configuration to suit your study's needs, build one or more custom questionnaires, define custom physical measurement and sample collection stages, and then generate a war file so it can be deployed on a server.

Copying the onyx-demo Project

The first step in creating a customized version of Onyx is to copy the onyx-demo project as and rename it for your study. You will modify the configuration as explained in this guide.

Onyx Configuration

The WEB-INF/config directory (for customizers)

Most of the customization and configuration changes you will make, will be done in the following directory of your project:

                 src/main/webapp/WEB-INF/config

Throughout this guide, we refer to this directory as your WEB-INF/config directory. 

The WEB-INF/config directory (for installers)

If you are looking at this guide after installing a custom version of Onyx, your WEB-INF/config directory is under the Tomcat home directory:

                 $TOMCAT_HOME/webapps/custom-onyx/WEB-INF/config

Onyx Configuration Files

Most Onyx configuration is done in files located in the WEB-INF/config directory and its subdirectories.

Most global parameters are set in the onyx-config.properties file which is directly in WEB-INF/config.

Changing the Database Settings

The database settings are specified at the end of the onyx-config.properties file.  If necessary, you can change these settings as indicated in this table.

Property Key Description
org.obiba.onyx.datasource.driver the JDBC driver to use (note that the driver's JAR file must be placed in WEB-INF/lib)
org.obiba.onyx.datasource.url the JDBC url for connecting to the database
org.obiba.onyx.datasource.username the username to use for connecting
org.obiba.onyx.datasource.password the password to use for connecting
org.obiba.onyx.datasource.dialect the Hibernate dialect to use (more info here)
org.obiba.onyx.datasource.validationQuery a valid SQL query to issue for testing JDBC connections
org.obiba.onyx.datasource.testOnBorrow whether to test pooled connections before providing them

Configuring Participant Recuitment

Onyx supports two ways of recruiting participants: ENROLLED  (participants who have appointments) and VOLUNTEER (participants without appointments, also known as "walk-ins"). Onyx can be configured to accept either recruitment type or both. This is set near the top of the onyx-config.properties file.

WEB-INF/config/onyx-config.properties

Configuring Participant Attributes

Onyx collects data about people who agree to participate in a study. These people are called "participants".

Built-in participant attributes

Onyx includes the following attributes for all participants.  These attributes can be customized as explained below:

Attribute Description
Enrollment ID An identifier for the participant that was assigned at enrollment time. Typically, this value is read from the appointment list.
Participant ID The unique identifier used in Onyx. You can define a format for the Participant ID as explained below. 
First Name  
Last Name  
Birth Date  
Gender Possible values are: M,F
Assessment Center ID Also
Appointment Time  

Defining the format of the Participant ID (optional)

You can define a validation pattern for the Participant ID attribute in the following section of the onyx-config.properties file.

WEB-INF/config/onyx-config.properties

The default pattern (.*) means any value would be accepted. For detailed information about the defining a validation pattern, see JavaPattern. 

Customizing participant attributes

Participant attributes can be customized in the participant-attributes.xml file in WEB-INF/config. In this file, you can redefine the built-in attributes and declare new attributes.

A new attribute can be declared using the following schema:

Attribute Possible Values Description
name   Localizable attribute name
assignableAtEnrollment true, false true means this attribute must be present in the appointment list.  A value may be set at enrollment time, but it is not required.
mandatoryAtEnrollment true, false true means a value must be set for this attribute at enrollment time.
If this is set to true and there is no value when the appointment is being updated, an error will resut.
If this is set to false, this property does not need to be set at enrollment time.
mandatoryAtReception true, false true means this attribute must be set when the participant is received through the Onyx user interface.
editableAtReception true, false true means the value of this attribute can be changed when the participant is received through the Onyx user interface. 
editableAfterReception true, false true means the value of this attribute can be changed at any time during the participant interview.
type TEXT, INTEGER, DECIMAL, BOOLEAN, DATE The type of the attribute value
allowedValues list of strings Localizable allowed values for the attribute
validators patternValidator, rangeValidator Validation rules of the attribute value

For example, these are the custom attributes of participants defined for the onyx-demo application:

WEB-INF/config/participant-attributes.xml

To localize the names of participant attributes

The names of participant attributes can be localized in the{{ messages_*.properties }}files in  }}{{ WEB-INF/config.  For onyx-demo, English and French properties files are provided.

To validate participant attributes

You can define patternValidator which will validate the value entered based on a regular expression as specified in JavaPattern.

The range validator is able to check that the participant value is in a range of numerical values (INTEGER, DECIMAL), dates (DATE) or text length (TEXT). Upper and lower bound can be provided individually or both.

Allowed date formats for date bounds are:

  • yyyy-MM-dd
  • yyyy-MM-dd HH:mm:ss.S

Here are some examples of how to configure range validators:

Defining Custom Variables

You can define custom variables in a file called custom-variables.xml file in WEB-INF/config. Here are some reasons you might want to define a custom variable:

  • for export purposes (see the variable PostalCodePrefix in the example below)
  • to use in a condition when defining stage dependencies (see Defining Stage Dependencies)
  • to use in a condition used to determine whether or not to display a particular question in a questionnaire

For information on how to define a script, see Magma Javascript API.

WEB-INF/config/custom-variables.xml

Configuring the Appointment list

Onyx imports participant appointments from a file (generated by some other programme). The file can be in Excel or XML format. 

Defining input and output directories for the appointment list

You must define the input directory where Onyx will look for the appointment list file. Defining an output directory is optional. When updating the appointment list, the user can select a file.  If they don't, Onyx will process whatever XML or Excel (.XSL) file it finds in the input directory.

WEB-INF/config/onyx-config.properties

Configuring the appointment list reader

The appointment list file is read by a ParticipantReader class. You set a number of lines in the onyx-config.properties file to define what the reader class should look for in the appointment file. See the table below for an explanation of the attributes related to the participant reader. See also the Excel example and the XML example.

Attribute Needed for
Description
org.obiba.onyx.participantReader.sheetNumber Excel appointment lists
Excel workbooks can have multiple worksheets. This attribute identifies which worksheet to read.
org.obiba.onyx.participantReader.headerRowNumber Excel appointment lists This indicates which row contains the names of columns. The column names are mapped to participant attributes (in the columnToAttribute attribute which is explained below in this table). 
org.obiba.onyx.participantReader.firstDataRowNumber Excel appointment lists Indicates the first row in the sheet that contains participant data.
org.obiba.onyx.participantReader.columnToAttribute Excel  and XML appointment lists For Excel format appointment lists: 
Maps the name of columns in the Excel file onto Onyx participant attributes. In the example below, the column labelled "Sex" is mapped onto the participant attribute "Gender".  If the name of the column and the participant attribute are the same, they don't need to be included in the mapping.
For XML format appointment lists: 
Maps the name of elements in the XML file onto Onyx participant attributes. In the example below, the attribute with the key "Sexe" is mapped onto the participant attribute "Gender".  If the name of the column and the participant attribute are the same, they don't need to be included in the mapping.

Example Excel appointment list

For an Excel format appointment list that looks like this (click on the thumbnail below)...

...the participant reader attributes would be set as follows in onyx-config.properties:

WEB-INF/config/onyx-config.properties (Excel format appointment list)

Example XML appointment list

For an XML format appointment list that looks like this...

...the participant reader attributes would be set as follows in onyx-config.properties:

WEB-INF/config/onyx-config.properties (XML format appointment list)

Scheduling automatic updates of the appointment list

Edit the following line in the  onyx-config.properties file:

WEB-INF/config/onyx-config.properties

The above configuration ("0 0 4 * * ?") means that the appointment list will be updated every day at 4:00 a.m. To disable automatic updates, simply leave the property blank, as follows:

For details of the syntax to use, see http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html.

Modifying Date and Time Formats

You can edit the data and time formats that will be used throughout Onyx by editing these lines in the onyx-config.properties file:

WEB-INF/config/onyx-config.properties

Modifying the Printer

On startup, Onyx decides which printer to use for printing reports for participants. Onyx will try to find a printer with a particular name. If that printer does not exist, or does not support PS printing, then it will fallback to using the system's default printer. If that printer does not support PS printing, then printing reports from Onyx will not be possible.

You can change the printer to look up at startup:

Property Key Description
org.obiba.onyx.pdfPrinterName Name of printer to try before trying the system default printer
Search Onyx Documentation
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.