Customizing the Consent Stage

Overview

The onyx-demo application that you are using as a basis for your customization, includes a consent stage. You can modify the configuration of the consent stage for your customized version of Onyx in these ways:

Configuration Files for the Consent Stage

The configuration files for the consent stage are found in the WEB-INF/config/marble directory.

The consent stage is included in Onyx by means of a <stage> element in the stages.xml file in this directory.  The name of the consent stage is defined in this file. In the onyx-demo application, the name of the consent stage is Consent.

Configuring Consent Modes (electronic and manual)

The consent stage in the onyx-demo application is configured to accept the participant's consent in electronic and manual (paper) forms.  Manual mode is always possible (it cannot be disabled). Electronic mode can be disabled.

If your organization will obtain consent electronically, you will need create custom consent forms as explained in Creating Custom Electronic Consent Forms (PDF).

If your organization will only obtain consent manually (on paper forms), you must disable electronic consent by setting the allowElectronicMode property to false in the marble/module-config.properties file as follows:

Configuring the Locales for Manual Consent

Your organization may provide its manual consent forms in several languages.  The Onyx consent stage allows the user to select the language of the manual consent form given to the participant.  The list of available languages is confugured by editing the following line in the WEB-INF/config/marble/module-config.properties file.  

As shown above, the onyx-demo application accepts manual consent in English and French.  If your organization requires other languages, add the appropriate two-letter language codes to this line.  For possible language codes, see http://www.loc.gov/standards/iso639-2/php/code_list.php.

Creating Custom Electronic Consent Forms (PDF)

If your custom version of Onyx will accept consent electronically, you must create a consent form in each language that is required for your version of Onyx.

This procedure requires a single license for Acrobat Professional. Onyx uses Acrobat Reader (which is free) to display the consent form at runtime.

To create a PDF consent form

Repeat this procedure to create a PDF consent form for each language that you need to support.

1. Create a consent form in one of your supported languages, using Microsoft Word or any tool of your choice.
2. Convert the form to PDF using a PDF converter.
3. Save the PDF using a name that includes the appropriate language code (and optionally, a country code). For example: ConsentForm_en.pdf for the English version. See How to name consent form files below.
4. Edit the PDF using Adobe Acrobat Professional to include the necessary fields and buttons:
   1. Add a text field wherever you want information to be supplied automatically by Onyx (for example, participant and interviewer information--see the table below).
      1. Set each field to read-only.
      2. Rename each field so it can be automatically completed by Onyx (see the table below).
      3. Apply formatting to all fields that require it (using Acrobat field formatting; for example: date formatting).
   2. Add signature fields where signatures are required. If the signature is required, append "_mandatoryField" to the end of the signature field name.
   3. If the interviewer must enter more information manually, add as many fields as necessary (for example: radio buttons and text fields). If the field is required, append "_mandatoryField" to the end of a field name.
   4. Add one or more form submit buttons.
      1. Add a button to accept the consent. Set the button name to "AcceptURL".
      2. Add a button to refuse the consent. Set the button name to "RefuseURL".
      3. Set each button so they are invisible if the form is printed.
   5. Select ADVANCED -> ENABLE USAGE RIGHTS IN ACROBAT READER in the top menu.
   6. Save the PDF file.

How to name consent form files

The filenames of PDF consent forms must conform to this configurable naming scheme:

     basename_language_country.pdf

where,

• basename is a configurable prefix for the filename (ConsentForm by default). It can be configured in the WEB-INF/config/marble/module-config.properties file.
• language is the two-letter ISO Language Code (ISO-639-1) code for the form's language (example: en for English, fr for French). See language codes.
• country (optional) is a two-letter ISO Country Code (ISO-3166).  See country codes.

Examples of valid consent form names:

• ConsentForm_en.pdf

• ConsentForm_fr.pdf

• ConsentForm_fr_CA.pdf

Where to put consent form files

By default, PDF consent forms should be located in the WEB-INF/config/marble/resources directory. Based on the consent form files in the resources directory, Onyx "discovers" the available languages and displays them at runtime. No further configuration is required.

You can change the resources directory by modifying this line in the WEB-INF/config/marble/module-config.properties file:

How to name fields in PDF forms

At runtime, Onyx can complete certain fields in your consent forms automatically. The mapping between Onyx variables and fields in the PDF form is defined in WEB-INF/config/marble/module-config.properties.  For a list of the Onyx variables that you can use in your consent form, see To view a list of Onyx variables.

Here is the variable-to-field mapping for the consent form in the onyx-demo application:

The table below indicates information that Onyx can supply and how you should name the fields in your consent form, if you want Onyx to complete the fields.

Customizing Consent Stage Messages

You can modify various texts displayed onscreen during the consent stage by editing the messages_language.properties files located in the WEB-INF/config/marble directory. The directory contains a messages file for each user interface language supported by Onyx.  By default, there are messages files for English and French.

For example, if you want to change the English name for the stage to be displayed onscreen, you would edit Consent.description line in this file:

Disabling the Consent Stage

If your study does not require that participants sign a consent form, you can disable the consent stage as follows:

      1.  Remove the <stage> element from the marble/stages.xml file. The element to remove looks like this:

      2. Remove all the <variableCondition> elements related to the consent stage from the stages.xml files in the jade and ruby directories. The elements to remove look like this:

      3.  Remove all the <stageDependencyCondition> elements from the stages.xml file in the quartz directory. The elements to remove look like this:

      4.  Remove the word Consent from the staticStageOrder property line in the onyx-config.properties file:

Search Onyx Documentation