Installation and Execution Environment
Opal is distributed as a zip file. To install Opal, proceed as follows:
- Unzip the Opal distribution. Note that the zip file contains a root directory named opal-cli-1.0. This is the Opal "home" directory (i.e., the installation directory). You can copy it wherever you want. You can also rename it.
- Configure the following environment variables:
Environment variable Description JAVA_HOME Path to the Java installation directory.
For example:
C:\Program Files\Java\jdk1.6.0_07%OPAL_HOME% Path to the Opal "home" (installation) directory.
For example:
C:\opal-cli-1.0 - Edit the Opal configuration file (%OPAL_HOME%\conf\opal-config.properties). See instructions that follow.
The machine that is running Opal must have CPUs with a frequency rating of at least 2Ghz (per core if it's multi-core). Also, when on Linux, you can check the "bogomips" rating of the CPU (cat /proc/cpuinfo | grep bogomips), it should be above 4K.
Users Directories Configuration
The security framework that is used by Opal for authentication, authorization etc. is Shiro. The configuration of Shiro for Opal is done via the file %OPAL_HOME%\conf\shiro.ini.
More information about how to configure Shiro using the INI file can be found here. Support of LDAP, although announced by Shiro, is not yet implemented.
Default configuration is a static user 'administrator' with password 'password'.
Database Configuration
Opal is made of two distinct databases: one for the holding the participants identification keys and another one for holding the variable catalogue and participant data.
Configuration file edition
The database configuration properties in %OPAL_HOME%\conf\opal-config.properties must be edited to fit your environment. Currently there are examples for MySQL. Comment out and uncomment the appropriate lines for your configuration. Edit the properties to what is configured for your system. For example the username and password properties have to be changed for your environment.
For more information on how to configure the datasource, follow this link.
Database creation
Create the necessary Opal schemas (opal and opal_key) on your database system. If you are using MySQL, this can be done this way:
create schema opal;
create schema opal_key;
%OPAL_HOME%\bin\opal.bat --upgrade
 | There is not yet support for encrypting the database passwords in the configuration file. |
MYSQL
The required MySQL JAR files are already deployed within the .zip file. 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.
It has been seen sometimes that by default the MySQL database server configuration was capped at 128M. Obviously, this is insufficient. Not all MySQL configurations are capped this way. Check your my.ini or my.cnf files to make sure your database doesn't have an upper limit: the 'innodb_data_file_path' parameter controls this. If the parameter is not
present then your OS will be the limiting factor. Please refer to the MySQL manual of configuration for more details:
http://dev.mysql.com/doc/refman/5.1/en/innodb-configuration.html
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.
Archive Directory Configuration
After data files were imported there are moved to an archive directory. This is to be specified in the file %OPAL_HOME%\conf\opal-config.properties.
Set the path (that can be relative) to the archive directory under the org.obiba.opal.import.archiveDirectory property.
Keystore Configuration
Keystore configuration is done by running some specific commands. See keystore command for more details.
Variable Views Configuration
Opal deals with variables and values in tables. Views are here to define a subset of a table, both in terms of variables and values. These virtual tables are then manipulated just like standard tables (for instance they can be exported to a mart datasource).
Given one table:
| Table1 | |||
|---|---|---|---|
| entity | Var1 | Var2 | Var3 |
| 1 | Value1.1 | Value2.1 | Value 3.1 |
| 2 | Value1.2 | Value2.2 | Value 3.2 |
| 3 | Value1.3 | Value2.3 | Value 3.3 |
A view can be defined so that the resulting 'table' may be:
| View1 | ||
|---|---|---|
| entity | Var1 | Var3 |
| 1 | Value1.1 | Value 3.1 |
| 3 | Value1.3 | Value 3.3 |
The definition of a view is expressed in terms of select ... from ... where ... statements. View definition uses extensively the Magma Javascript API 1.0.
The configuration takes place in the file %OPAL_HOME%\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 table are part of the view.
Use the list command to get the variables catalogue of the tables.
Example
Select the variables which name starts with Participant or contains DO_YOU_SMOKE:
from
In the current version, a view is a subset of one table only (join of tables is not supported yet). The 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.
Example
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 list 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 / 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
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 %OPAL_HOME%\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.
defaultEntityType : The default Opal entity which will be used for mapping a SQL table (if none has been specified, see tableSettings below).
useMetadataTables : Whether or not metadata tables should be used when reading from and writing to the SQL schema. The default value is false.
mappedTables : Table names to be mapped in Opal. If not specified, all tables with at least one primary key column will be mapped.
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:
sqlTableName : The table name in the SQL schema.
magmaTableName : The name of the table as seen from Opal. When null, the magma-transformed SQL name is used.
entityType : The type of Opal entity this table contains.
entityIdentifierColumns : A list of SQL column names which should be used as the unique identifier for the Opal entity.
Note that the tableSettings node is optional; if no table-specific mappings are necessary, the node may be omitted.