Summary
Opal consists of a command line tool, opal that allows sub-commands in a console to perform different tasks.
This guide provides a description of the opal command.
Prerequisites
A properly configured Opal distribution. See Opal Configuration Guide 1.0 for details about 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 |
| JAVA_OPTS | An optional variable. It's value is used when launching java. For example: -Xmx2G -XX:MaxPermSize=256M |
Using Command Line Tools
Scripts for running the command line tools are in the OPAL_HOME/bin directory.
Two types of scripts are provided:
- opal (shell script for Linux/Unix users)
- opal.bat (batch file for Windows users)
Running opal command line opens a console that allows the execution of sub-commands. The command line syntax is the following:
opal <options>
where
- opal is the Opal command line tool
- options are switches, with or without values; every option has a long form (e.g., "--help") and a short form (e.g., "-h")
Getting Help
Typing:
opal --help
prints the general syntax and options.
Starting Opal Console
You have to be authenticated to perform commands on Opal. Starting Opal command requires a user name and a password. See with your administrator to get these information.
The user name and password can be provided as options. If not you will be prompt for them.
| Options | Description |
|---|---|
| --username -u NAME | User name for authentication on the command line. If not provided opal will prompt you for it. |
| --password -p TEXT | User password for authentication on the command line, useful for scripting. If not provided opal will prompt you for it. |
Once in the console, the command syntax is the following:
<command> <options> <arguments>
where
- command is an action to be performed.
- options are switches, with or without values; every option has a long form (e.g., "--help") and a short form (e.g., "-h"). Every command supports the help option.
- arguments are (unnamed) arguments applied to the action (e.g., a list of files).
The commands available are:
| Command | Description |
|---|---|
| certificate | Export the public key certificate for the specified key pair alias. |
| copy | Copy tables to an existing destination datasource or to a specified Excel file. The tables can be explicitly named and/or be the ones from a specified source datasource. The variables can be optionally processed: dispatched in another table and/or renamed. |
| decrypt | Decrypts a list of Onyx data files into a directory. |
| help | Display the list of available commands. |
| import | Imports a list of Onyx data files to a destination datasource. |
| keystore | Encryption key pairs creation, import or deletion. |
| quit | Quit the Opal console. |
| show | Display the names of the available datasources and tables in the system. |
| split | Splits one or more ZIP files into multiple pieces. |
| version | Print the version number of Opal. |
Commands
The following commands are available from the Opal console.
certificate
Description
Export the public key certificate for the specified key pair alias. The certificate is in pem format, written on standard output or in a file.
To know how to create a key pair, see keystore command.
Syntax
certificate --alias NAME [--out FILE]
Options
| Option | Description |
|---|---|
| --alias -a NAME | The alias name of the encryption key pair. |
| [--out -o FILE] | Export the certificate to the specified file, in pem format. |
copy
Description
Copy tables to an existing destination datasource or to a specified Excel file. The tables can be explicitly named and/or be the ones from a specified source datasource. The variables can be optionally processed: dispatched in another table and/or renamed.
Use show command to get the list of datasources and tables declared in the system.
Syntax
copy [--source NAME] (--destination NAME | --out FILE) [--multiplex SCRIPT] [--transform SCRIPT] [--nonIncremental] [--catalogue] [TABLE_NAME...]
Arguments
- None, and then requires the source option.
- One or more fully qualified table names, that can be used in combination with the source option.
Options
| Option | Description |
|---|---|
| [--source NAME] | The name of the source datasource. This is used to resolve table names when they are not fully qualified. |
| [--destination -d NAME] | The name of the datasource destination in which export the data. This datasource must be declared in the system. This option is exclusive to the out option. |
| [--out -o FILE] | The datasource destination is an Excel file. See note below. This option is exclusive to the destination option. |
| [--multiplex SCRIPT] | Executes the specified SCRIPT to determine the destination table name. This is used to copy variables from one table to multiple tables. If this option is not used, default behaviour is to copy to a table with name of the original table. See Magma Javascript API 1.0 for more details about how to write the script. |
| [--transform SCRIPT] | Executes the specified SCRIPT to determine the resulting variable's name. If this option is not used, default behaviour is to copy the variable with its original name. See Magma Javascript API 1.0 for more details about how to write the script. |
| [--nonIncremental] | Copies all value sets from the source tables without regard to prior copy operations. |
| [--catalogue] | Copies the variables only (as opposed to variables and data). |
decrypt
Description
Decrypts a list of Onyx data files into a directory.
Syntax
decrypt [--out FILE] FILE [FILE...]
Arguments
The list of .zip files to be decrypted.
Options
| Option | Description |
|---|---|
| [--out -o FILE] | The directory into which the decrypted files are written. Default is current directory. |
import
Description
Imports a list of Onyx data files into a destination datasource. If a directory is provided, all .zip files inside of it are assumed to be imported. After import, the files are moved to the archive directory (if specified).
The zip file's content can be encrypted using a public key. When this is the case, Opal will lookup the corresponding key-pair in it's keystore (see the keystore command). If the key-pair is not present, import will fail.
Syntax
import --datasource NAME --owner NAME FILE...
Arguments
A list of files that can be either .zip files or directories that contains .zip files.
Options
| Option | Description |
|---|---|
| --datasource -d NAME | The destination datasource into which the variable catalogue and the participants data will be imported. |
| --owner -o NAME | The name under which the participants identifiers that will be stored in the participants key database. |
keystore
Description
Encryption key pairs creation, import or deletion.
A key pair can be:
- created from scratch, providing the algorithm information,
- imported, providing the pem file of the private key. Then the corresponding certificate can be:
- created from scratch,
- imported from a pem file.
Once a key pair is in the keystore, you can extract the public certificate using the certificate command.
Syntax
keystore --alias NAME (--delete | --algo NAME --size INT | --private FILE [--certificate FILE])
Options
| Option | Description |
|---|---|
| --alias -a NAME | The alias name of the encryption key pair. |
| [--algo -g NAME] | The algorithm for creating the key pair. RSA is recommended. |
| [--size -s INT] | The key size for creating the key pair. |
| [--private -p FILE] | Provides the private key file in pem format. |
| [--certificate -c FILE] | Provides the certified public key file in pem format that matches the private key file. If omitted the user is prompt for creating one. |
| [--delete -d] | Delete a key pair from the keystore. |
show
Description
Display the fully qualified names of the available datasources and tables in the system. These names are the ones to be used when a datasource or a table name is to be provided on other command lines.
Syntax
show [--datasources] [--tables]
Options
| Option | Description |
|---|---|
| [--datasources -d] | List the datasources names. |
| [--tables -t] | List the tables fully qualified names. |
split
Description
Splits one or more ZIP files into multiple pieces.
Syntax
split --out DIR [--size size] _FILE_...
Arguments
One or more fully file names (must be Onyx export ZIP files)
Options
| Option | Description |
|---|---|
| --out -o DIR | The output directory where the parts |
| [--size -s value] | Maximum number of entities to write per file. Default is 500. |
Excel Files
Note that Opal supports both Excel 97 and Excel 2007 formats. When specifying an output file, Opal will choose which format to use through the extension of the filename specified:
| Extension | Format used | Limits |
|---|---|---|
| .xls | Excel 97 | 256 columns and 64K lines (more details) |
| .xlsx | Excel 2007 | 16K columns and 1M lines (more details) |
Be aware that the Excel 97 format only supports 256 columns. This limits the size of the tables that can be written to these files. Simply specify an .xlsx to support writing large tables (up to 16 000 columns).
Reporting with BIRT
Using a tool like BIRT, simple and complex reports may be created on top of marts.
BIRT connects to a data source (e.g., the mart database). One or more data sets may be defined in terms of the mart data (i.e., by specifying SQL queries). It is also possible to define "computed data", using built-in BIRT functions or even JavaScript.
Data sets are associated with ("wired into") reports. Reports are constructed from a palette of components. BIRT provides a visual, drag-and-drop interface for building reports, which may include tables and many types of charts.
Further details, tutorials and other resources on BIRT may be found online.