How to download, install and run

IIP and IUCLID instances in the ECHA cloud

The IIP requires a live connection to a running IUCLID instance and communicates via the REST API (Application Programming Interface) provided by ECHA. Unfortunately, this API is not supported by ECHA for IUCLID instances in the ECHA cloud.

Therefore, the IIP has to be used in conjunction with an on-premises / inhouse installation of IUCLID:

Installation options

There are two installation options:

  • Server installation (for version 1.1.0 and later) – recommended
    This installation is done once for a company on a server (similar to IUCLID itself, if not the Desktop version is used) and then can be accessed by all users. Maintenance and updates are done by local IT staff. It is strongly recommended to install own company SSL certificates, see section below
  • Local PC / desktop installation – not recommended, but technically possible

Server installation

The IIP is a Java application based on the WildFly application server and is usable on any platform that supports Java. It was developed and tested on Windows 10.

Installation as a Windows service

We recommend that you use the scripts that Wildfly provides to install the IIP as a service on Windows.

You will need the following steps:

  • Firstly, move to the folder “wildfly-*\docs\contrib\scripts\”.
  • Next, copy the “service” directory to wildfly-*\bin
  • Then, open an Admin Shell and navigate into the “service” folder
  • Run “service.bat install“

See http://www.mastertheboss.com/jbossas/jboss-configuration/installing-wildfly-on-windows/ for additional info.

Before running the service.bat you may adjust settings in the script, e.g. the display name of the service.

The service will be installed in a way that wildfly-*\bin\standalone.bat is used for the server process execution. You may influence the runtime settings, e.g. max memory, by changing the JAVA_OPTS environment setting in wildfly-*\bin\standalone.conf.bat

Local PC installation

The process of downloading, installation and running the IUCLID Integration Platform on your local PC is nearly identical to the one of the CropLife Europe eSubmission builder, as the technical architecture is identical. Also, the installation and runtime requirements are identical (e.g. supported browser types).

Therefore, please read the respective information for the eSubmission builder first. You can then apply those instructions one by one, by modifying the information respectively (e.g. the path name, the name of the startup scripts etc.). Please note that the version of the application server WildFly can differ between the two programs, which is not relevant to the installation procedure.

After starting the IIP with the startup script in the root directory, a successful startup looks like this:

Please minimize this window and pay attention that you do not click inside of it. Do not close this window, as this will stop the application.

How to open the IIP and enter user credentials

Dependent on the installation option, the process of opening the IIP differs:

For a server installation, your IT administrator should supply you

  • with a URL to access the IIP
  • with remote folder paths where you can access the export and import directories of the IIP

Open the URL in your web browser, no need to log on. It is recommended to make a bookmark.

For a local desktop installation, you need to make sure to apply and record the required configurations first (see below). Then you can start the server and click on the shortcut supplied in the root installation folder to open the application in the standard browser.

For both installation options you need to open the administration perspective and enter

  • the URL to your IUCLID instance (e.g. “https://test-iuclid6.myintranet.com”)
  • the same user name and password you use when accessing IUCLID via the IUCLID web interface

The user name and password is being saved in the local browser storage and not in the IIP server, so your credentials are stored safely. They are transmitted encrypted to the IIP and used by the IIP to connect with your credentials to the IUCLID server. Therefore, you can only do specific operations in IUCLID when you are set up accordingly in IUCLID – the IIP does not have its own user management and access rights system.

Using the IIP – advanced options

You can open one or multiple browser tabs to connect to the IIP. Each tab is a completely separate session and activities do not propagate on the other tabs. Within a new tab you can update the IUCLID connection information (eg. different user, or different IUCLID instance) and then this session uses the updated settings. Other tabs continue to use their previous settings, which are displayed next to the connection status icon. However, only one setting of URL / username / password is currently permanently stored in your browser cache, so make sure you are connected to the right system (see name in browser tab or hover with the mouse over the connection icon in the lower left corner).

In case multiple users use the very same IUCLID connection settings from different clients at the same time, their session would also not interfere. Of course, changes done to IUCLID data could not be distinguished in the IUCLID modification history.

Installation configuration

Most configurations are to be made in the Wildfly file “standalone.xml” which can be found in “wildfly-23.0.0.Final\standalone\configuration\standalone.xml” below the root installation directory.

IUCLID connection

Please configure the connection to IUCLID in the “Administration” perspective of the running IIP web interface: Take the URL you use to open the IUCLID dashboard and remove the last part ““/iuclid6-web/dashboard” and then enter this resulting URL value (starting with “https://:” into the URL field, so usually this looks like “https://<servername>/”, with eventually an additional port.

Demo mode (default:off)

The IIP supports a demo mode for IEF upload. This means that a specific annotation is used to “tag” instances created by the IIP. The same single annotation is linked to all respective IUCLID entities and has the following field values:

  • Name: Created by IUCLID Integration Platform – DEMO MODE – please do not delete
  • Authority: IUCLID Integration Platform

The demo mode allows to

  • quickly see the instances created / updated by the IIP (eventually use the Advanced Search in the IUCLID web interface)
  • delete all instances created in demo mode – to repeatedly test the functionality of the IIP (see the Administration perspective). Please note that the deletion will only affect the instances with the respective fixed string, not any other instances.

The demo mode can be turned on / off using the property “iuclid.demoMode” with values true/false:

    <system-properties>
        <property name="iuclid.demoMode" value="${iuclid.demoMode:false}"/>
        ...
    </system-properties>

IEF import directory

For the IEF import functionality, the respective IEF files have to be put below import directory that is both accessible for the user and the IIP. The user first puts IEF files (plus eventually referenced attachments) to be processed below this directory by normal file system operations (e.g. in the Windows Explorer), which subsequently can be picked up via the IIP browser interface in the import operation. Further subfolders can be created as needed. The IIP cannot upload files to this directory or for direct processing via the web browser.

For a server installation this directory has to have the following characteristics and has to be set up by IT admins:

  • accessible from the local PCs for all intended users (e.g. via the Windows Explorer)
  • directory considered local for the IIP server, either as local directory or drive letter (windows) / mounted drive (Linux)
  • access rights to create, modify and delete files for all intended users

For the IIP this directory needs to be configured in “standalone.xml”. The default setting for this “import.dir” is the directory “import” below the default data directory “wildfly-26.0.0.Final\standalone\data”:

   <property name="import.dir" value="${jboss.server.data.dir}\import"/>

This property can be changed to any other directory accessible for the machine (server or local PC) where the IIP is installed. If the shared directory is a network directory, it needs to be accessible locally to the IIP server, e.g. for Windows by mapping it to a drive letter; or for Linux mounting it. During testing on Windows mounted drives with letters (e.g. “Z:\import”) have worked, but not UNC paths (e.g. \\DataServer\import).

All “*.ief” files in the directory structure are then selectable for import by users via the IIP browser interface.

The administration can use a specific property “import.help” in the standalone.xml to have a specific help text displayed in the import mask of the IIP, to support the user to find this directory. The default is:

<property name="import.help" value="To select IEF files for IUCLID import by the IIP, please first copy your IEF data plus linked attachments into the IIP import folder (mounted as directory '${import.dir}\%s' in the IIP). Then, they can be selected for processing in this dialog. For questions on how this folder is accessible and named from your local PC please contact your local IT admininstrator."/>

This help text should ideally name the import directory as it is accessible for all users from their local PCs.

IEF export directory

In the very same way, an export folder can be configured, where the IIP creates all exports that have attachments. (Exports without attachments are created in the Downloads folder of the browser.)

<property name="export.dir" value="c:\temp\export"/>
<property name="export.help" value="The IEF files with attachments are exported into the IIP export folder (mounted as directory '${export.dir}\%s' in the IIP). For questions on how this folder is accessible and named from your local PC please contact your local IT admininstrator."/>

SSL certificates

For server installation, it is strongly recommended to install own company SSL certificates on the Wildfly application server, as the IUCLID connection settings including username and password are transferred to the IIP. This task is not specific to the IIP. Please check the Wildfly documentation or a tutorial like this one.

The SSL configuration structure is already prepared in the standalone.xml, but uses a generated self-signed certificate by default for the host “localhost”.

To change the self-signed certificate, the “tls.generate.host” can be changed:

<property name="tls.generate.host" value="localhost"/>

To properly configure a SSL certificate to use, a JKS Keystore needs to be prepared in the standalone/configuration directory, with the keystore password and the private key password of the certificate:

<property name="tls.keystore.path" value="iip.keystore"/>
<property name="tls.keystore.password" value="iip"/>
<property name="tls.key.password" value="changeit"/>

As soon as a valid keystore is configured, the attribute “generate-self-signed-certificate-host” needs to be removed to prevent automatic self-signed certificate creation.

       
<key-manager name="applicationKM" key-store="applicationKS" generate-self-signed-certificate-host="${tls.generate.host}">

Ports

By default the port 8100 is used for HTTP and port 8463 is used for HTTPS.

To change the default ports, the environment variables “jboss.http.port” and “jboss.https.port” in the standalone.xml can be changed:

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    ...
    <socket-binding name="http" port="${jboss.http.port:8100}"/>
    <socket-binding name="https" port="${jboss.https.port:8463}"/>
    ...
</socket-binding-group>

HTTP Proxy server configuration

If the IIP and the IUCLID instance are in different networks separated by a proxy server, the IUCLID connection may fail. In this case, the proxy information for an HTTP proxy has to be supplied in the “standalone.xml” configuration file: Example settings are:

<system-properties>
   <property name="http.proxyHost" value="10.0.0.1"/>
   <property name="http.proxyPort" value="8800"/>
...
</system-properties>

The configuration proxy setting is shown as part of the IUCLID connection settings as a readonly information.

Please note, that the IIP only support HTTP proxies, not HTTPS proxies. The connection to IUCLID may still be HTTPS.

Accept all certificates

In case you enter the IUCLID connection information and you receive an error of type

Iuclid request failed: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

then this means, that the certificate of IUCLID is not trusted and not part of the local Java certificate cache “cacerts”. Please ask your admin to add the IUCLID certificate to the Java trust store of the machine, where the IIP is installed.

For testing purposes only:

You can configure the IIP to accept all incoming certificates by setting the configuration parameter “security.trustall” in the standalone.xml to “true”. It is set to “false” by default.

    <system-properties>
        <property name="security.trustall" value="true"/>
        ...
    </system-properties>