Upgrading to Onyx 1.7.0

Overview

To upgrade to Version 1.7.0 of Onyx for a particular study, you must do some or all of the following tasks depending on how Onyx has been configured for the study:

Replace any references to "active" variables within your stage.xml configuration files

In Onyx configuration (stage.xml), dependencies between stages are usually expressed the following way:

In this example configuration, there are three conditions to be satisfied before the StandingHeight stage is made available:

1. The Consent stage must be completed and the participant must consent (Consent.accepted variable must be true);
2. The CIPreliminaryQuestionnaire stage must be completed, cannot be skipped;
3. The StandingHeight stage is not contra-indicated by the CIPreliminaryQuestionnaire.

The third condition is refering to an "active" variable within the CIPreliminaryQuestionnaire to implement a contra-indication. The value of this variable will be true if the contra-indication message (boiler-plate question) have been shown to the user (which mean that the corresponding measure should be contra-indicated) when answering the CIPreliminaryQuestionnaire. In the previous version of Onyx, most (if not all) users have implemented those conditions based on this particular strategy.

This cannot be done this way any more. The solution for migrating this configuration is to design the corresponding derived variables in the custom-variables.xml file, and use these derived variables for resolving the stage dependencies.

Step 1 : Make a list of all conditions referring to an "active" variable

For each of your deployed Onyx modules (Jade, Marble, Quartz, Ruby), look at the stage.xml configuration file. Identify each of the conditions that refers to an "active" variable. These are example :

Step 2 : Locate the boiler-plate question definition that corresponds to each "active" variable

In your Questionnaire Builder program you should find a boiler-plate question that corresponds to each of the variable that you have identified in the previous step. These should like (based on the previous example):

Step 3 : Create a new derived variable in custom-variables.xml corresponding to each contra-indication

For each boiler-plate question, create a custom variable in custom-variables.xml which is equivalent to the boiler-plate question condition. Doing this with the examples from step 2 should give:

Value Tables for Interview Stages

In previous versions of Onyx, variables for interview stages were all located in a single Magma value table, Participants.

Onyx 1.7.0 creates a value table per interview stage. Variables for a given stage are located in the table for that stage. Consent stage variables are located in the Consents table; variables for the contra-indication questionnaire stage are in the CIPreliminaryQuestionnaire table; and so forth.

Note that the variable naming scheme has changed. Previously, variable names began with the name of the variable's related stage (e.g., Consent.accepted where Consent is the stage and accept is the variable). Since (participant) variables are now located in separate tables, either in the Participants table or in one of the stage tables (Consent, CIPreliminaryQuestionnaire, StandingHeight, etc.}}, references to variables must be updated in various configuration files. In some cases, the stage name prefix should simply be dropped (Consent.accepted becomes accepted); in other cases the fully-qualified variable must be specified (Consent.accepted becomes Consent:accepted, where the ":" separates the table name from variable name);

The following configuration files may be affected:

• .../WEB-INF/config/export-destinations.xml
• .../WEB-INF/config/purge.xml
• .../WEB-INF/config/*/stages.xml
• .../WEB-INF/config/marble/ConsentForm-condition.xml
• .../WEB-INF/config/jade/resources/instruments/*/instrument-descriptor.xml
• .../WEB-INF/config/jade/module-config.properties

These files should be carefully reviewed. No changes are required if a file does not contain any variable references.

Export destinations

In the case of export-destinations.xml, valueset nodes (which are a way of filtering exported data) may need to be modified and/or additional nodes may need to be added.

Previously, for each export destination a valueset node was defined per entity type (Participant, Instrument, Workstation) to be exported to that destination. But participant variables are now spread over multiple tables (the Participants table plus all the new stage tables). A given export destination might require variables from only some of these tables. In addition, data filters might need to be applied per table, not per entity type. Consequently, a "valueTable" attribute has been added to the valueset node to support table-level filtering.

Purge

In the case of purge.xml, the valueset node now requires the new "valueTable" attribute. This attribute should have the value "Participants". Note that it is not necessary to add any additional valueset nodes.

In other words,

should be changed to

This works as follows:

• If an export destination requires variables from a specific participant table, a valueset must be included with the "valueTable" attribute set to the name of that table.
• Filters defined by a valueset node with a "valueTable" attribute are applied to the specified table only.
• Filters defined by a valueset node with an "entityType" attribute but without a "valueTable" attribute are applied to all tables with the specified entity type.

Another modification required concerns the "EXCLUDE" scripts in valueset nodes. These scripts are used to prevent the same valueset from being exported more than once to the same destination. They should now specify not just a datasource but also a table. For example, the following script in valueset node for the Consent table

should be changed to

Any valueset nodes for workstations should have the "valueTable" attribute set to Workstations. Similarly, valueset nodes for instruments should have the "valueTable" attribute set fo Instruments. Failure to add this attribute will cause workstations and instruments not to be exported.

Participant Registry

In previous versions of Onyx there were two ways to add new Participants to the system, either by updating the appointment list (ENROLLED) or by signing up a single participant at a time (VOLUNTEER). With Onyx 1.7.0 a new way to add Participants is available making it possible to retrieve Participant information from an external system via a RESTful web service call.

Controlling How Participants are Added to Onyx

The following configuration is part of the onyx-config.properties file and controls which buttons are available to add Participants to Onyx.

Configuring Essential Participant Attributes

Up until now it has been possible to modify non-essential Participant attributes by modifying the contents of the WEB-INF/config/participant-attributes.xml file. Starting with this version of Onyx it will also be possible to modify essential Participant attributes. Essential attributes are attributes that are required by Onyx and include the following:

1. Enrollment ID
2. Participant ID
3. First Name
4. Last Name
5. Birth Date
6. Gender
7. Assessment Center ID
8. Appointment Time

Retrieving the Essential Participant Attributes File

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.

Editing the Essential Participant Attributes File

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.

Participant Registry Configuration

To use the RESTful Participant Registry modify the oynx-config.properties configuration file to contain the following.

To test the Participant Registry modify the oynx-config.properties configuration file to contain the following. This will configure a "fixed" Participant Registry that returns canned values.

The test participant registry behaves the following way:

XML Response Expected by the RestfulParticipantRegistry

The expected content type of the response is text/xml.

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. 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 RestfulParticipantRegistry will interpret any other HTTP code sent as a participant registry lookup failure.

Upgrading Existing Database Schema

Note that existing Onyx schemas will be updated automatically when the new version of Onyx is deployed.