To custom your own onyx application, use as a starting point the project onyx-example by copying it as a new project. This is what is done for each cohort under svn source control.
The WEB-INF/config/onyx-config.properties file has properties that control the general behavior of Onyx.
Database Configuration
The database configuration properties in onyx-config.properties must be edited to fit your environment. Currently there are examples of HSQL and MySQL. Comment out and uncomment the appropriate lines for your configuration. Edit the variables to what is configured for your system. For example the username and password properties have to be changed for your environment.
validationQuery and testOnBorrow are used to test stale connections to the database. If used make sure that the validationQuery actually works in the chosen RDBMS by connecting to the database and executing the query.
For more information on how to configure the dataSource, follow this link.
Other aspects Onyx's database usage can be tweaked by overriding the configuration file WEB-INF/spring/datasource.xml. Doing so requires very good knowledge of database and Hibernate setup. Normally, these files do not need to be modified.
Privileges
The user for connecting to the database should have all privileges on that database. It is recommended not to restrict the privileges on the onyx database. Obviously, the user does not require any privilege on other databases.
MYSQL
The required MySQL JAR files are already deployed within the .war package. All you need to do to use MySQL is to make the configuration changes as described above.
At the time of writing this document, MySQL 5.1.x is recommended.
HSQL
HSQL is a Java implementation of an RDBMS. It has the ability to be embedded inside another application: it does not require a server running an previously installed instance. As such, it is a great candidate for testing a deployment. It is not recommended for production environments.
The required HSQL JAR files are already deployed within the downloaded package. All you need to do to use HSQL is to configure the settings as described above.
For information on hibernate.dialect: follow this link for a list of available Hibernate dialects.
HSQL jdbc url's are described here.
Other Databases
It is possible to configure other databases such as Oracle but because they have not been tested they will not be discussed here until the need arises.
Participant Configuration
Enrolled vs. Volunteers
Onyx supports both enrolled participants (through an Appointment Unit) and volunteers (walk-in). Onyx can be configured to support either or both. This is done through the onyx-config.properties file.
| Value | Description |
|---|---|
| ENROLLED | Allows loading a list of appointments obtained from an Appointment Unit. |
| VOLUNTEER | Allows registering participants without an appointment. Supports the use-case of accepting walk-ins. |
Participant Identification Field Configuration
Built-in Participant Attributes
Some participants attributes are predefined, and are also configurable:
| Attribute | Description |
|---|---|
| Enrollment ID | |
| Participant ID | ID pattern is configurable using Java Pattern. |
| First Name | |
| Last Name | |
| Birth Date | |
| Gender | Possible values are: M,F |
| Assessment Center ID | |
| Appointment Time |
Configuration of Participant ID:
Custom Participant Attributes
The expected participant attributes can be configured in the file WEB-INF/config/participant-attributes.xml. Built-in attributes can be redefined, new attributes can be declared using the following schema:
| Property | Values | Description |
|---|---|---|
| name | Localizable attribute name | |
| assignableAtEnrollment | true, false | |
| mandatoryAtEnrollment | true, false | On error, if mandatory the update is aborted, else the content of the field is replaced by blanks. |
| mandatoryAtReception | true, false | |
| editableAtReception | true, false | |
| editableAfterReception | true, false | |
| 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 |
The localization of some attribute properties is done in the files WEB-INF/config/messages_*.properties.
The pattern validator allows to perform the validation based on a regular expression as specified by the Java Pattern.
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 z
Examples of range validators configuration:
Example of participant attributes configuration:
Appointment List Configuration
The expected file format for an appointment list from an Appointment Unit is Excel. The actual structure of the workbook is configurable. We explain here how to configure this structure.
This is done in the onyx-config.properties file.
| Attribute | Description |
|---|---|
| org.obiba.onyx.participantReader.sheetNumber | Excel workbooks can have multiple worksheets. This attribute identifies which worksheet within the workbook to read. |
| org.obiba.onyx.participantReader.headerRowNumber | This indicates which row contains the names of each column. These names mapped to participant attributes. For example, a column named 'Street' will be mapped to a configured participant attribute with the same name (if any). |
| org.obiba.onyx.participantReader.firstDataRowNumber | Indicates the first row within the sheet that contains participant data |
| org.obiba.onyx.participantReader.columnToAttribute | Considering that column names are mapped to participant attributes, this configuration property allows mapping a column name to a different participant attribute. For example, a 'Sex' column can be mapped to a 'Gender' attribute through this configuration property. |
Installing and Configuring Modules
Onyx Modules are configured through the file structure found under WEB-INF/config directory. Each module has its own subdirectory:
- WEB-INF/config/jade
- WEB-INF/config/quartz
Within the module's configuration directory WEB-INF/config/<module>/ the following filename conventions are used:
- Module Spring Context: module-context.xml
- Configuration properties file: module-config.properties
- Resource bundles: messages_locale.properties
- Module stages: stages.xml
Together, these files configure and deploy a module and its stage(s) within Onyx at runtime. Example files are available under the WEB-INF/config directory.
The following sections describe how to "install" and configure the available modules:
- Marble - The Electronic Consent Module
- Ruby - The Sample Collection Module
- Mica - The Conclusion and Participant Report Module
- Quartz - The Questionnaire Module
- Jade - The Physical Measurements Module
Stage Configuration
At this point, Onyx should be configured with all the required stages, but they are in no particular order and have no relation with one-another. This section shows how to configure these aspects.
Stage Ordering
Stage ordering is configurable, but also pluggable. In other words, Onyx provides a way to order stages within an interview, but this basic functionality could be replaced by a more sophisticated custom mechanism.
The basic stage ordering is specified by an entry in Onyx's WEB-INF/config/onyx-config.properties file:
Stage Dependency
This aspect is important as some stages must absolutely be executed before others. For example, the Standing Height stage must be completed before the Bioimpedence stage. Some stages not only depend on a previous stage's completion, but also on that stage's data. For example, all stages depend on the consent stage completion, but also acceptance.
Stage dependency is defined at the stage level using stageDependencyConditions. Here are the some predefined conditions:
| Name | Description |
|---|---|
| stageCondition | A stage waits for another's completion |
| variableCondition | A stage wait's for another completion and captured variable boolean value |
| moduleCondition | A stage waits for all the stages contributed by a module (useful for the conclusion stage) |
| inverseCondition | A condition that reverses another (useful for exclusive stages) |
| multipleCondition | Given a boolean operator (and, or) this condition combines multiple ones |
An example use within Jade's stages.xml file:
Variable Configuration
Variable Exportation Configuration
Data can be exported to several destinations. Destinations are configured through the export-destinations.xml file under the configuration directory.
Variables to be exported is specified per destination. There are two strategies for defining which of the variables will be exported to a given destination:
- include all, eventually filter out some variables, eventually re-include some previously filtered out variables.
- include none, include some variables, eventually filter out some previously included variables.
The variables to include or to filter are expressed by a path which is compared ("starts with" comparison) to each variable path.
You need also to specify where on the file system the data is be exported to:
Configurable Variables
Since Onyx 1.3.2
To add configurable variables in the system, declare them in the configuration file:
The configurable variables file allows new variables to be created that are based on existing variables. In the above example a new variable named "PostalCodePrefix" is created. The "PostalCodePrefix" variable is based on the existing variable "Onyx.Admin.Participant.Postal_Code". The "regexDataSource" dataSource is used to take the first three characters from the existing variable and use them for the newly created variable. So if "Postal_Code" contained the value "T5G 2B1" then "PostalCodePrefix" would contain the value "T5G".
The new variable name must not include '.', ' ' or non ascii chars. For example "Admin.PostalPostFix" is NOT permitted.
The parent tag contains the path to the parent variable to which the variable will be attached to. If needed variables will be created to build this path. The root name must be the one defined in the application: 'Onyx'.
When adding new configurable variables you may need to also modify the "export-destinations.xml" file in order to adjust the filters so that the new variable is exported.