For the Dashboard to work it must be connected to an ICAT version of 4.7.0 or greater, TopCat 2.0.0 or greater and requires ids.server 1.6.0 or greater.


  • The dashboard distribution:
  • A database as described in Database installation instructions installed on the server
  • A suitable deployed container (here assumed to be glassfish though tomcat should be sufficient) to support a web application. Testing has been carried out with Glassfish 4.0 and above. Glassfish installation instructions are available.
  • Python (version 2.4 to 2.7) installed on the server.
  • Python module lxml.
  • The IDS must have its logging level set to READ WRITE PREPARE.
  • If the IDS and ICAT are on Linux machines the Dashboard machine must have access to the ephemeral port ranges. For example Linux Kernel 2.4 has a default range of 32768 to 61000

Summary of steps

  1. Please follow the generic installation instructions
  2. If it is the first time you are installing the Dashboard you will need to run the import script.
  3. Check that it works.

ICAT transfer script

This is a python script that will perform an initial database transfer of data from the ICAT to the dashboard.

To run the script:

icat_transfer --vendor

The vendor option is currently either --oracle or --mysql


  • The database for the dashboard must be empty to prevent data clashes.
  • IFF Oracle Databases: Python package cx_Oracle is installed.
  • IFF MySql Databases: Python package pymysql is installed.

The icat_transfer.ini file

There will be [Options] for the ICAT and Dashboard Database

The username used to login into the Oracle database.
The password used to login into the Oracle database.
The URL of the Oracle database.
The username used to login into the MySql database.
The port of the MySql database.
The password used to login into the MySql database.
The schema name of the MySql database.

The file

May be either glassfish or wildfly - though only glassfish is working properly at the moment.
is the top level of the container installation. For glasssfish it must contain "glassfish/domains" and for wildfly it must contain jboss-modules.jar.
is the administration port of the container which is typically 4848 for glassfish and 9990 for wildfly.
must be set to true or false. If true then only https and not http connections will be allowed.
is the name of the jdbc driver and must match the jar file for your database that you stored in the previous step.
url to connect to your database. For example: jdbc:mysql://localhost:3306/icat
username to connect to your database.
password to connect to your database.
the url of the IDS server that will send JMS messages to the dashboard. For example: Please note no prefix.
the url of the ICAT server that will send JMS messages to the dashboard.For example: Please note no prefix.
This is optional and may be used to control the SQL generated by the JPA. Values must be chosen from: TargetDatabase
This is optional and if set to one of the values in Eclipse Link logging.level controls the logging of JPA generated SQL statements.

The file

The url of the machine hosting the icat service. It should normally just have the scheme, the hostname and the port. For example:
The authenticator mnemonic for the ICAT reader account for the dashboard.
Username of the ICAT reader account for the dashboard.
Password of the ICAT reader account for the dashboard.
List of accounts in the format mnemonic/name to be allowed access to the dashboard.
The hour that the Dashboard should do its daily collection of data from the ICAT. (24 Hour Clock)
The URL of the TopCat to gather download statistics.

Check that the dashboard works

Enter a url of the form into a web browse and it should respond: The Dashboard is doing fine!

Post-installation work

Fresh Install

For the Dashboard to start collecting daily information on the ICAT use and to collect meta information on the ICAT from its inception then you will need to run the ICAT transfer python script.

In all cases


To improve performance:
  • Consider creating the indices defined in indices.sql. Indices can make a huge difference to the database performance but there is also a small cost for each index.