Requirements

Fusion Matrix suite comprises of the Matrix ToolKit, Matrix Manager, and Matrix-UI. The Matrix Manager and Matrix-UI are web applications and are each distributed as a single Web Application Archive (war) file: FusionMatrixManager.war and FusionMatrix.war. The Matrix ToolKit is a command line application which consists of a single Java Archive File (jar) called FusionMatrixToolKit.jar and a properties file.

Java (Required)

Java Runtime Environment (JRE) 1.6 or higher is required.

Servlet Container (Required)

Matrix Manager and Matrix-UI are deployed to a Servlet Container. Apache Tomcat is a popular, open source servlet container. Download links and installation instructions can be found at the following URL.

http://tomcat.apache.org/

It is recommended to use the latest version of Apache Tomcat as it will include the latest security patches. The Fusion products will not run in any version lower than 6.0.

MySQL Database (Required)

A MySQL v1.5 or higher database is required to store data and metadata loaded into the Fusion Matrix. MySQL is a free open source database which is available for download from:

http://www.mysql.com/

We also recommend SQL YOG community edition, which is a free GUI for database view/maintenance.

https://code.google.com/p/sqlyog/

Fusion Security (Optional)

Fusion Security provides the Fusion Matrix support for Embargo data. Fusion Security configuration is documented in the Fusion Security Technical section.

Fusion Audit (Optional)

Fusion Audit captures audit information on data requests and submissions. Fusion Audit configuration is documented in the Fusion Audit Technical section.

Email Server (optional)

The Fusion Matrix makes use of an email server.The Fusion Matrix will send emails to users in the following circumstances:

  1. If Fusion Matrix is connected to external applications (Fusion Security/Fusion Audit/Fusion Matrix) and the connection is lost (or resumed).
  2. If the Fusion Matrix has been configured to automatically register data imports with the Fusion Registry and the registration fails
  3. If the Fusion Matrix has been configured to consume data registrations from the Fusion Registry, to act as a data portal, but the information at the registered URL could not be indexed
  4. When embargo decryption starts, competes, or fails
  5. If a data import fails
  6. If a data import has warnings
  7. If the Fusion Matrix is connected to the Fusion Registry and fails to process a registry update

If an email server is not configured, then Fusion Matrix will not be able to communicate the above information. Whilst an email sever is not required it is strongly recommended to use one.

Installation

Matrix Toolkit

The Matrix ToolKit is a Java jar file and does not require installation. The Matrix ToolKit application is configured via the matrix.properties file.

The default properties are shown below.


######################################################################
#     MYSQL DATABASE PROPERTIES                                      #
######################################################################
database.matrix.driver=com.mysql.jdbc.Driver
database.matrix.username=root
database.matrix.password=password
database.matrix.url=jdbc:mysql://localhost:3306
database.matrix.schema=fusion_matrix
database.matrix.dialect=org.hibernate.dialect.MySQLDialect
database.matrix.flushEvery=50000

######################################################################
#     EMAIL PROPERTIES                                               #
######################################################################
mail.recipients=
mail.security=true
mail.username=
mail.password=
mail.smtp=
mail.port=

#####################################################################
#     SWEEPER ENGINE PROPERTIES                                     #
#####################################################################
sweeper.dir=C:/Matrix/Sweeper

MySQL configuration

The username and password should be set to the database username and password. The database connection defaults to connect to a MySQL instance running on the same machine as the Matrix ToolKit on port 3306 (which is the MySQL default port). The schema references the database schema to use. Fusion Matrix will create the database tables automatically, but the database schema must exist. A schema can be created by executing the following command from within a MySQL shell:

create database fusion_matrix;

Sweeper Configuration

The sweeper.dir property states the root directory to scan when running the Sweeper Engine for data imports. This property can be left blank if not running the sweeper.

When specifying the directory to scan, it is required to use the backslash ‘/’ as opposed to the forward slash ‘\’ for the directory separator even on a Windows system. For example:

(Windows) C:/matrix/sweep
(UNIX) /home/ubuntu/matrix/sweep

Launching Matrix Toolkit

Once the Matrix ToolKit properties file has been configured, the Matrix ToolKit is ready for use. The Matrix ToolKit documentation describes the runnable services provided by the Matrix ToolKit.

Matrix Manager

Deploying Matrix Manager

Matrix Manager is deployed as a .war file to a servlet container. The war file is named FusionMatrixManager.war, this can be renamed if required.

To deploy to tomcat, copy the .war file into [tomcat]/webapps and start tomcat.

On server startup the .war file will unpack its contents into a folder with the same name as the .war file. So the default deployed application will be to location:

[tomcat]/webapps/FusionMatrixManager

The application will be accessible via the URL:

http(s)://[your server]:[your port]/FusionMatrixManager

If the war file, and therefore subsequent directory name were altered, this would be reflected in the URL path of the application. If the folder is named ROOT, then the application will be accessible via the root URL which is:

http(s)://[your server]:[your port]

Once the war file has been unpacked it is possible to alter the default configurations by modifying the contents of the properties file, described in the following section.

Note: If Tomcat fails to start-up properly during the initial deploy, then the war file may not have fully unpacked, and subsequent launches will fail. If you are unsure whether the war file has deployed as expected it is possible to manually unpack the application. To manually unpack the application, create a folder under [tomcat]/webapps, the name of the folder can be anything, but it will be reflected in the URL path to your application. Unzip the war file into this new folder; this can be achieved by renaming the .war file to a .zip if necessary. After unzipping the war file, it can be deleted.

Configuring Matrix Manager

The configuration details for the Matrix Manager are in a properties file, which is in the following location:

[tomcat]/webapps/FusionMatrixManager/WEB-INF/classes/matrix.properties

The default configuration is shown below.


######################################################################
#     MYSQL DATABASE PROPERTIES                                      #
######################################################################
database.matrix.driver=com.mysql.jdbc.Driver
database.matrix.username=root
database.matrix.password=password
database.matrix.url=jdbc:mysql://localhost:3306
database.matrix.schema=fusion_matrix
database.matrix.dialect=org.hibernate.dialect.MySQLDialect
database.matrix.flushEvery=50000

######################################################################
#     EMAIL PROPERTIES                                               #
######################################################################
mail.recipients=
mail.security=true
mail.username=
mail.password=
mail.smtp=
mail.port=

######################################################################
#     SECURITY PROPERTIES                                            #
######################################################################
requires.channel=any

#PORT MAPPINGS FOR AUTO REDIRECTION FROM HTTP TO HTTPS
port.http=8080
port.https=8443

default.username=root
default.password=password

server.url=http://localhost:8080/FusionMatrixManager

Database Configuration

The database connection details can be modified in the properties file. The schema must exist when tomcat launches. The database tables will be created if they do not exist.

The .flushEvery property is used when loading datasets to the Matrix, the higher this number the more observations the Matrix will hold in memory before performing a flush. If this number is too high it may result in an out of memory exception on data load. If this number is set to -1 then the Matrix will perform a flush each time the memory drops below a pre-set threshold.

Email Properties

Email properties are optional. If provided then Fusion Matrix Manager and Matrix Toolkit will be capable of sending emails. Email notifications are sent to all recipients under certain conditions listed later in this section.

The mail.recipients is a semicolon delimited list of email addresses that will receive the email notifications.

The mail.username and mail.password are the authentication credentials for the mail server. These fields are left blank if security is not enabled.

The mail.smtp and mail.port provide the connection details to the mail server.

The mail.security property should only be set to false if your mail server does not require a password.

Security Properties

The default configuration is to allow connection over the HTTP (unsecure) protocol. To enforce HTTPS (an encrypted and therefore secure protocol) the requires.channel property must be set to https. Port mappings can then be used to automatically redirect users from the unsecure HTTP port to the secure HTTPS port. To set up the redirection the port.http must be set to the HTTP port of the Tomcat Server and the port.https must be se to the HTTPS port.

default.username and default.password are the login credentials that will be used for authentication to Fusion Matrix Manager. Note that once logged into Fusion Matrix Manager it is possible to set Fusion Security as the authentication service. Once Fusion Security has been configured the default username and password may no longer be used for access to the Fusion Matrix Manager and the credentials must come from Fusion Security

Email Conditions

The Fusion Matrix will send email notifications in the following conditions.

Condition

Description

Contact with Fusion Product lost

If Fusion Matrix Manager has been configured to use Fusion Registry, Fusion Audit, or Fusion Security, then these services will be polled periodically. If any of the services cannot be contacted, or if an unexpected reply is received, then an email will be issued.

Contact with Fusion Product resumed

If Fusion Matrix Manager has previously lost contact with a fusion product, but contact becomes re-established, then an email will be issued.

Auto Registration Failed

If Fusion Matrix Manager has been set up to automatically submit a Registration to the Fusion Registry on data submission, and the Registration has failed, then an email will be issued.

Registry Registration Failed

If the Fusion Matrix Manager is linked to a Fusion Registry and a Registration has been submitted to the Fusion Registry which cannot be processed by the Fusion Matrix Manager then an email will be issued.

Structure Update Failed

If the Fusion Matrix Manager is linked to a Fusion Registry then it will update its structure definitions as they are updated in the Fusion Registry. If the Fusion Matrix is unable to process an update then an email is issued.

An example is if dimensions are added to a Data Structure Definition for which the Fusion Matrix already has data imported against. The Fusion Matrix cannot process this update as it will make an existing dataset invalid.

Data Import Failed

If a data import fails an email will be issued.

Data Import Warnings

If a data import completes, but has warning, then an email is issued.

Embargo Updates

When Fusion Matrix Manager starts the decryption process for an embargo dataset an email is sent. Another email is sent on completion. In the unlikely event of a failure, an email will also be sent.

Once the application has been configured, start-up tomcat and navigate to the following URL in a web browser.

http(s)://server:port/FusionMatrixManager

The login page shown in the following image should be displayed.

Showing the login page to Fusion Matrix Manager

Matrix UI

Deploying Matrix-UI

Matrix-UI is deployed as a .war file to a servlet container. The war file is named FusionMatrix.war, this can be renamed if required.

To deploy to tomcat, copy the .war file into [tomcat]/webapps and start tomcat.

On server startup the .war file will unpack its contents into a folder with the same name as the .war file. So the default deployed application will be to location:

[tomcat]/webapps/FusionMatrix

The application will be accessible via the URL:

http(s)://[your server]:[your port]/FusionMatrix

If the war file, and therefore subsequent directory name were altered, this would be reflected in the URL path of the application. If the folder is named ROOT, then the application will be accessible via the root URL which is:

http(s)://[your server]:[your port]

Once the war file has been unpacked it is possible to alter the default configurations by modifying the contents of the properties file, described in the following section.

Note: If Tomcat fails to start-up properly during the initial deploy, then the war file may not have fully unpacked, and subsequent launches will fail. If you are unsure if the war file has deployed as expected it is possible to manually unpack the application. To manually unpack the application, create a folder under [tomcat]/webapps, the name of the folder can be anything, but it will be reflected in the URL path to your application. Unzip the war file into this new folder; this can be achieved by renaming the .war file to a .zip if necessary. After unzipping the war file, it can be deleted.

Configuring Matrix-UI

The configuration details for the Matrix are in the following file:

[tomcat]/webapps/FusionMatrix/WEB-INF/classes/matrix.properties

The default contents of the matrix.properties file are shown below:

######################################################################
#     MYSQL DATABASE PROPERTIES                                      #
######################################################################
database.matrix.driver=com.mysql.jdbc.Driver
database.matrix.username=root
database.matrix.password=password
database.matrix.url=jdbc:mysql://localhost:3306
database.matrix.schema=fusion_matrix
database.matrix.dialect=org.hibernate.dialect.MySQLDialect
database.matrix.readonly=false


#####################################################################
#    GENERAL PROPERTIES        		                          	  #
#####################################################################
max.keys=300
server.url=http://localhost:8080/FusionMatrix

login.enabled=true
default.username=root
default.password=password

Database Configuration

The database connection details can be modified in the properties file. The schema must exist on tomcat launch the database tables will be created if they do not exist. The database.matrix.readonly can be set to true if required, this will prevent the Matrix from performing any database modifications (note, this includes table creation, so ensure the tables exist before setting this property to true.)

General Properties

This max.keys property is used to restrict the number of series keys that are sent back to the HTML GUI in Fusion Matrix. This restriction is imposed so that the web browser is not overloaded with data from the server. The default is 300 series but this value can be modified as required.

The server.url should be set to the external URL to the Fusion Matrix. This is used by the Matrix when writing datasets which contain links back to Reference Metadata Sets.

The login.enabled property can be set to true or false. If true, then a user will be allowed to login to the Matrix-UI in order to publish pre-defied queries, or to author metadata. If the Fusion Matrix Manager has been used to create a connection to Fusion Security then this will be the service which authenticates the login, otherwise the default.username and default.password will be used.

Launching Matrix-UI

Once the Matrix-UI is configured, it can be launched. In tomcat this is achieved by running the file [tomcat]/bin/startup.sh (or startup.bat for Windows). Once the servlet container has started, the web UI can be viewed from the following URL:

http://server:port/FusionMatrix

NOTE: If the folder under [tomcat]/webapps is not FusionMatrix, then the URL should replace ‘FusionMatrix’ with whatever the folder was called. The resulting page should look like the following image. Note that this will differ depending on the data and structure content that has been loaded into the Fusion Matrix:

showing the home page of the Fusion Matrix web interface

Browser 4 Excel

The Fusion Browser for Excel consists of a single .xlam file which is placed into a directory provided by Excel to add plugins.

On adding the file, Excel will contain a new Tab on the Ribbon which provides the user with the ability to browse and query for data. The Fusion Browser has a default connection to the demo Fusion Matrix hosted by Metadata Technology.

To add additional data sources, see the Browser 4 Excel documentation.

Enabling the Plugin

There are two methods to enable the plugin in Excel. Both include copying the file to a plugin directory in your file system. In both cases the file is placed in a subfolder of ‘AppData’ which is a hidden folder, therefore you will first need to enable your windows explorer to be able to view hidden files and folders.

Both plugin options are discussed below.

XLSTART

The first option is to place the plugin into the XLSTART directory then plugin will be available the next time you launch Excel. To do this, place the tsabrowser.xlam file into the following directory (note that the path may vary on different Operating Systems).

C:\Users\[your user name]\AppData\Roaming\Microsoft\Excel\XLSTART

Once Excel Starts the Fusion Browser tab will now be available.

AddIns

The second option is to place the tsabrowser.xlam plugin into the AddIns folder. This folder allows for plugins to be provided to a single location, but they can be separately enabled or disabled from within the application. Using the AddIns folder requires two steps:

1. Copying the file into the AddIns folder

2. Enabling the Fusion Browser add-in from within Excel.

First, you will need to locate your AddIns folder. On Windows 7, this is located under your home folder in the following location:

C:\Users\[your user name]\AppData\Roaming\Microsoft\AddIns

Note: this folder may be in a different location on different versions of Windows and in non-standard installations. Please check with your system administrator if you cannot find this folder.

Copy the file: tsabrowser.xlam file into this directory and then launch Excel. From within Excel, open the Excel Options menu, and select Add-Ins.

After clicking 'Go' an Add-Ins window will pop-up which will contain the Tsabrowser as an available add-in. Select this add-in and click 'OK'.

After clicking 'OK' The Add-Ins window will close and the 'Fusion Browser' tab will be added to the Excel Ribbon. This tab will be available on all subsequent launches of Excel from this computer, unless the add-in is disabled from the add-ins menu (or the .xlam file is deleted from the file system).