Opal Configuration Guide

Contents of this Guide

Prerequisites

• Opal is installed, following the instructions described in Opal Installation Guide: the configuration will take place in Opal main configuration file: OPAL_HOME/conf/opal-config.xml
• Having the user rights for Launching Opal Server, because Opal needs to be restarted after changing its configuration.

Functional Units Configuration

For more information about what are the Functional Units, see functional units general description.

The functional units configuration takes place in the conf/opal-config.xml file, functionalUnits section.

Unit Name

The unit name is required and is the one to be provided with the --unit option of some commands: import and keystore.

Participant Identifier Variables

When importing participant's data, two kinds of participant's unique identifiers are to be handled:

• each imported participant is identified by a key that is the shared key between the unit and Opal. This shared key is to be stored in the Opal key database. This follows the Participant Key Separation process.
• some of the imported variable values are participant identifiers (for instance a personal information returned by an instrument). To protect participant's privacy, these variables are also to be stored in the Opal key database and not in the Opal data database.

Then the unit's configuration will specify:

• keyVariableName (required): is the variable name under which the imported participant key will be stored in the Opal key database.
• select statement (optional): this statement selects the variables which values are participant identifiers. When importing data from Onyx, some variables have a 'identifier' boolean attribute that tells they are participant's identifier. The default behaviour of the import process is to handle that attribute. For other identifier variables, use the select clause to override this default behaviour. This is to be specified using the Magma Javascript API.

Keystore Configuration

For each functional unit there is a keystore containing the encryption key pairs (private key and certificate). The unit's keystore configuration is done by running some specific commands. See keystore command for more details.

In the case of assessment centres collecting data using Onyx, define only one functional unit for all sites and use the --alias option of the keystore command to store each site encryption key pairs.

Datasources Configuration

The datasources configuration takes place in the conf/opal-config.xml file. The datasources need to be declared before performing a copy for instance. Depending on your needs, the datasources will be persisted in different type of schema, the currently supported ones being:

• EAV,
• Flat SQL,
• Excel.

EAV Datasource

Default Opal datasource (opal-data) is persisted in a EAV based schema. This schema is able to persist several datasources. So if you want to add a new datasource persisted this way, simply declare the additional bloc:

JDBC Datasource

Opal can be connected to an external database schema (SQL) using a JDBC datasource. In other words, it gives read/write access to external data within Opal.

Configuring a JDBC datasource takes place in the file conf/opal-config.xml. The following is an example of a basic configuration (within the factories node).

Example

name

The name which will be used in Opal to refer to this datasource.

jdbcProperties

This configuration is specific to the external database instance to which the Opal will connect to.

driverClassName : The JDBC driver supplied by the database vendor.
url : The path to the database schema.
username : Username to access the database instance.
password : Password associated with the username provided.

settings

These optional settings are specific to the JDBC datasource, they allow more control over its behavior. More specifically, they allow the specification of the mapping between the SQL database tables with the Opal entities.

tableSettings

In certain cases, it may be necessary to configure how the JDBC Datasource maps a specific table. This is possible to do using the tableSettings node. In the example above, table settings are defined for the SQL table named "nonstandard_table". For any table, it is possible to specify the following mapping details:

Note that the tableSettings node is optional; if no table-specific mappings are necessary, the node may be omitted.

Variable Views Configuration

The definition of a view is expressed in terms of:

• select ... from ... where ... statements for defining a subset of existing tables.
• variables ... from ... where statements for enumerating derived variables.

View definition uses extensively the Magma Javascript API.

The configuration takes place in the file conf/opal-config.xml.

select

Select the variables that will be part of the view. In the current version, the variable selection is done using a javascript. The return value of the javascript is a boolean telling whether or not the currently evaluated variable is part of the view.

If this statement is omitted, all the variables of the from statement are part of the view.

This statement is exclusive to the variables statement.

Use the copy command to get the variables catalogue of the tables.

Example

Select the variables which name starts with Participant or contains DO_YOU_SMOKE:

variables

Enumerates the derived variables that are part of the view. The from statement needs to be specified so that the derived variables scripts are resolved.

the variable script attribute is used to specify how to resolve the values for the derived variable. The script syntax is based on Magma Javascript API.

This statement is exclusive to the select statement.

Example

from

In the current version, a view is a subset of one table or of joined tables. Each table is identified by its fully qualified name.

This statement is required.

Use the show command to get the list of the tables available in the system.

Examples

From one table:

From joined tables:

where

Select the value sets that will be part of the view. In the current version, the value set selection is done using a javascript. The return value of the javascript is a boolean telling whether or not the currently evaluated value set is part of the view.

If this statement is omitted, all the value sets of the table are part of the view.

Use the copy command to get the variables catalogue of the table.

Example

Select the value sets for which the answer to the question DO_YOU_SMOKE is neither DNK nor PNA.

Attaching a View to a Datasource

Once defined using the select / variables / from / where statements, the view can be attached to any datasource: it can be the same datasource as the one the table belongs to, or a dedicated datasource.

Example

Search Opal Documentation