Customizing the Global Configuration

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.

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.

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:

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.

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 modify existing attributes and declare new ones. Modifying built-in attributes is explained below.

A new attribute can be declared using the following schema:

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

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:

Customizing essential participant attributes

To modify the essential participant attributes the file essential-participant-attributes.xml must be present in the WEB-INF/config directory. If essential-participant-attributes.xml is not part of the configuration there are two methods for obtaining it.

1. Download essential-participant-attributes.xml from this page. The essential attributes are stable and not regularly modified so downloading them is relatively safe.
2. Extract the file from Onyx. This option is more complicated, but will guarantee that the correct essential-participant-attributes.xml file is used. The steps to extract the file are detailed below.

In order to modify the essential Participant attributes, first extract the essential-participant-attributes.xml file from the onyx-core*.jar file and add it to the existing cohort configuration alongside the existing participant-attributes.xml file.

Once the essential-participant-attributes.xml file has been made part of the configuration it may be modified. It is not possible to add new essential attributes or remove essential attributes, but it is possible to modify the definition of these attributes in various ways. For example, attributes that are not editable at the time of reception may be made so by modifying the value of <editableAtReception> from false to true.

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.

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.

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.

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:

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:

Scheduling automatic updates of the appointment list

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

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:

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:

Configuring Participant ID Generator

By default, Onyx does not generate participant identifiers. It is the Onyx operator that assigns a unique identifier to each participant manually when receiving them at the collection site. In this case, your organization defines the rules for generating these identifiers and Onyx will not be aware of them.

However, if you prefer to let Onyx takes care of this matter, it is possible to configure it so that it generates identifiers based on a pre-configured set of rules:

Based on the configuration described above, Onyx will generate a random number between 1 and maxIncrement which will be added to the last generated identifier sequence. The first identifier (the starting point for all this) and the Identifier Prefix (a list of characters be added before the random number) are specified when [Deploying Onyx].

Example configuration

With the following configuration:

The resulting identifiers should look like this:

DEMO + 2 (first identifier) + 3 (generated increment) = DEMO5
DEMO + 5 (previous identifier) + 4 (generated increment) = DEMO9
DEMO + 9 (previous identifier) + 2 (generated increment) = DEMO11
and so on...

Configuring the Participant Registry

The Participant Registry makes it possible to enroll new participants by retrieving participant information from an external system via a RESTful web service call. The Participant Registry is off by default and can be turned on and configured using the following properties.

The Fixed Participant Registry

Configuring the fixed participant registry will provide a demonstration of the Participant Registry User Interface by returning canned participants for known participant id values. Developers also use this registry when testing and developing the Participant Registry user interface. The behaviour of the fixed participant registry is described below.

The RESTful Participant Registry

The RESTful participant registry expects a specific response from a third party web service. It is up to third parties to build the RESTful web service that will supply Onyx with participant information. Here are the specific details about what can be included in the response.

• The expected content type of the response is text/xml.
• The service should send the HTTP code 200 (ok) when returning participant XML.
• To indicate that a participant was not found the service should return HTTP code 404 (not found).
• The Restful Participant Registry will interpret any other HTTP code sent as a participant registry lookup failure.

The expected body of the response is XML representing a single Participant. The example below shows the names of the XML elements Onyx requires in order to de-serialize the participant.

Search Onyx Documentation