Configuring Interview Stages

Overview

An Onyx interview consists of stages. Four types of stage are possible: consent, physical measurment, sample collection, questionnaire.

Configuration Files for Interview Stages
Preparing the Stages
Defining Stage Dependencies

To view a list of Onyx variables

Defining a Conclusion Stage
Ordering the Stages
Configuring the Action Windows for Stages

Naming and invoking of action windows
Suppressing action windows
Fine-tuning action windows

Customizing the text above the comment field

Configuration Files for Interview Stages

Onyx stages are configured in different subdirectories of the WEB-INF/config directory. Each type of stage has its own subdirectory:

The Consent Stage is configured in: WEB-INF/config/marble
Physical Measurement Stages are configured in: WEB-INF/config/jade
Sample Collection Stages are configured in: WEB-INF/config/ruby
Questionnaire Stages are configured in: WEB-INF/config/quartz

Each of these subdirectories, contains the following files:

module-context.xml (contains context information for the Spring framework)
module-config.properties (contains configuration properties used by Onyx)
messages_locale.properties (contains localized strings for onscreen labels)
stages.xml (contains stage definitions)

Preparing the Stages

You prepare the stages required for your custom version of Onyx as explained in these pages:

Defining Stage Dependencies

When you add a stage to Onyx (by adding a <stage> element to the appropriate stages.xml file), you can define dependencies for the stage. In other words, you can set conditions that will be evaluated at runtime to determine the state of the stage (READY or some other state). For example: The BloodPressure stage in onyx-demo, depends on two conditions: (1) the participant signing the consent form and (2) completion of the CIPreliminaryQuestionnaire.

WEB-INF/config/jade/stages.xml

To view a list of Onyx variables

To view a list of the variables that you can use in stage dependency conditions, you must run Onyx in deployment mode and use a utility to output a zip file containing variable lists and other information.

Edit onyx-config.properties and set the application mode to development as follows:
WEB-INF/config/onyx-config.properties
Restart Tomcat.
Access onyx-demo by pointing your browser to http://localhost:8080/onyx-demo.
Enter adminstrator user name and password.
Select the Administration link in the upper right corner.
Select the Developers tab.
Click the Dump Variables & ValueSets button.

A file named magma-dump.zip will be written at the location indicated onscreen. The file Participants/variables.xml (in the zip file) lists the variables that are most useful for defining stage dependency conditions.

Defining a Conclusion Stage

Onyx requires a conclusion stage so that an interview can conclude normally and be assigned the "complete" status.

You can configure any stage to be the conclusion stage by editing the stages.xml file that contains the stage definition and adding an <interviewConclusion> element to the appropriate <stage> element. In the onyx-demo application, the conclusion stage is the ConclusionQuestionnaire which is defined in WEB-INF/config/quartz/stages.xml:

If you configure one of your custom stages to be the conclusion stage, be sure to remove the above stage element from the WEB-INF/config/quartz/stages.xml in your project.

Ordering the Stages

In the procedures for preparing the different types of stages, the last step was inserting in the stage ordering in the onyx-config.properties file as shown below. After you have prepared all the stages for your custom version of Onyx, you should probably check the order.

WEB-INF/config/onyx-config.properties

The stage names that must be used in this line are those defined in the various stages.xml files located in these directories:

Consent stage: WEB-INF/config/marble/stages.xml
Questionnaire stages: WEB-INF/config/quartz/stages.xml
Physical measurement stages: WEB-INF/config/jade/stages.xml
Sample Collection stages: WEB-INF/config/ruby/stages.xml

If no stage can be identified by a provided name, the name will be ignored.

If a stage is defined in a stages.xml file, but not included in the stage order list, Onyx will include the stage in the interview.

Configuring the Action Windows for Stages

By default, the onyx-demo application, displays an action window whenever the operator performs an action related to a stage. For example, when the operator starts or finishes a stage. These windows are configured in the WEB-INF/config/action-definitions.xml file.

The following actionDefinition element shows how a typical action window is defined. For information about the elements within an <actionDefinition>, see Fine-tuning action windows.

WEB-INF/config/action-definitions.xml

Naming and invoking of action windows

The name or <code> of an action window is composed as follows:

action.ACTION_TYPE.StageState.StageType

where,

ACTION_TYPE is the actual action. Possible values: EXECUTE, STOP, SKIP, COMPLETE.

StageState is the state of the stage on which the action was invoked. Possible values: Ready, InProgress, Interrupted, Completed.

StageType is the type of stage. Possible values:
- Marble for the consent stage
- Jade for physical measurement stages
- Quartz for questionnaire stages
- Ruby for sample collection stages

When a user takes an action in the Onyx user interface, Onyx determines which action window to display (or not) by looking for the most specific action definition that fits the action, and works its way to the least specific action definition that fits. For example, if Onyx can't find action.EXECUTE.Stop.Marble, it might end up using the action.EXECUTE.Stop definition.

Suppressing action windows

You cannot suppress the display of all action windows by making a single change in the action-definitions.xml file. You must suppress them one-by-one.

To suppress the display of a particular action window, add the following element to the appropriate <actionDefinition> element.

Notes

If you want to suppress a "start" window, look for actions with this ACTION_TYPE.StageState combination: EXECUTE.Ready
The two general <actionDefinition> elements at the top of the action-definitions.xml file, do not override the more particular <actionDefinitions> elements lower down in the file. Adding <askComment>false</askComment> to either of these two elements will not have the effect of removing action windows for all stages.

Fine-tuning action windows

The following table explains the effect of setting key elements in the action-definitions.xml file in WEB-INF/config.

Element	Default value	Description
`<askParticipantId>`	`true`	If `true`, the Participant ID field will be available, and the user must enter the correct Participant ID. If `false`, the Participant ID field will be grayed out.
`<askPassword>`	`true`	If `true`, the Password field will be available, and the user must enter their password. If `false`, the Password ID field will be grayed out.
`<commentMandatory>`	`true`	If `true`, the Comment field will be available, and the user must enter a comment. If `false`, the Comment field will be grayed out.
`<reasonMandatory>`	`false`	If `true`, the Reason drop-down list will be available and populated with the Strings in the `<reasons>` element; and the user must select a reason. If `false`, the Reason drop-down list will be grayed out.
`<askComment>`	`true`	If `true,` an Action window will be displayed. If `false`, an Action window will not be displayed. NOTE: For backward compatibility, if an `<askComment>` element is not present, it is equivalent to setting it to true (so the Action window will be displayed).

Customizing the text above the comment field

To customize the text displayed above the comment field in an action window, you add a <commentNote> element to the appropriate <actionDefinition> element in the action-definitions.xml file.

Here is an example :

Then you need to add localized strings containing the desired message in each of the message-locale.properties files in the WEB-INF/config directory. For example, for the above <commentNote>, you would add the following line to the English properties file:

WEB-INF/config/messages_en.properties
action.COMPLETE.InProgress.Jade.CommentNote=Please enter your comments below.

Each <actionDefinition> element can include its own <commentNote> element. If the configuration doesn't specify a custom message for an action, a default message will be displayed.