14 May 2015

1. TIF Installation

The TIF application is packaged into two separate parts, namely.

The TIF Server

Contains the server side code of TIF, where all integration jobs are executed among others. This package also contains the ENOVIA/3DExperience connector (might change in a future release), which allows processing jobs requested from the ENOVIA/3DExperience application OR to process jobs that updates the ENOVIA/3DExperience database.

The client side part of the ENOVIA/3DExperience connector inside TIF

Contains a small schema to be installed in the ENOVIA/3DExperience database along with a JAR file containing the necessary code used by the client. Also contains some web related files

The TIF server is currently packaged into a ZIP archive, tif-server.zip.

The ENOVIA/3DExperience client is bundled as an installer, one for Windows and one for Linux/UNIX.

All of these files are downloadable from https://products.technia.com.

2. Installation Overview

TIF can be installed in a few different ways. Starting with the easiest setup, TIF can be installed on the same server as the ENOVIA/3DExperience application is running at. This is visualized in the image below. This setup is often selected in development or test environments.

image
Figure 1. Installation Alternative 1

The preferred setup in a production system, is to have the TIF instance on its own server. This requires also that ENOVIA/3DExperience server binaries to be installed at the same machine in order for TIF to be able to connect with ENOVIA/3DExperience database.

This setup is illustrated in the image below.

image
Figure 2. Installation Alternative 2

The last setup alternative is to have TIF running on a separate server like described above, but instead of connecting to the ENOVIA/3DExperience database directly, instead connect via HTTP/XML to a running Tomee instance.

This setup does not require a ENOVIA/3DExperience Server installation, however, it still requires you to ensure that the necessary JAR files required to connect with ENOVIA/3DExperience is present for the TIF server.

image
Figure 3. Installation Alternative 3

If you connect to ENOVIA/3DExperience over HTTP, remember that you need to define the ENOVIA/3DExperience connect string in the following file:

${TIF_HOME}/modules/envoia/etc/tvc.custom.properties

The property should be defined like shown in the example below:

enovia.host=http://host.docker.internal:8080/enovia

3. TIF Database

By default, TIF uses an embedded database to persist all data related to the integration jobs, but it is also possible to use an external database.

Using an external database is the preferred option especially if there are multiple TIF server instances. This allows to decide whether to use a dedicated database per instance or share it with multiple instances. Sharing a database allows to query data from multiple instances via any TIF Admin UI instance.

See details how to configure the database from here.

4. Upgrade Notes

Currently, the TIF server does not have an installer that automates the complete installation process.

One thing to remember between two upgrades, is to remove all JAR files from the TIF server installation directory if you perform the upgrade into the same directory as the previous version.

5. Installing the Server

First, extract the tif-server.zip into a new and empty directory, for example c:\apps\tif-server. The root folder for the TIF server is from now on referred to as ${TIF_ROOT}.

Within the ${TIF_ROOT}/bin directory, you will find a couple of files that will be used to start/stop (manage) a TIF instance but also other helpful files such as example script that illustrates how to install the TIF server as a service within Windows OS.

Table 1. Table Title

File

Description

tif.bat

Start/stop script for TIF on Windows. Note that this script might require some additional environment variables to be set prior to running.

Take a look into the start_example.bat script how to do so.

tif.sh

Start/Stop script for TIF on UNIX. Note: Ensure that this file has the +x flag set on UNIX.

This script might require some environment variables to be set prior to starting TIF. See notes below.

These scripts most likely requires some additional environment variables to be set prior to starting TIF, this has been exemplified within the "start_example.bat" script on Windows and within the "setenv.example.sh" file for Unix.

Note that this file should be renamed to setenv.sh in order to work, the provided file is just there for convenience and will never be executed by the tif.sh start script.

The script you use needs to be changed to match your own environment. So on Windows, you should copy the file start_tif.bat into your own. On Unix, you should create a file called setenv.sh.

So, create a file called start_tif.bat, which will set the following properties:

set JAVA_HOME=d:\apps\jdk64\latest
set ENOVIA_HOME=d:\apps\ENOVIA\V6R2012X\Server
set WEBAPP_ROOT=D:\Projects\DEV-2012X\enovia
call tif.bat run

The JAVA_HOME variable points out the JDK that will be used for running TIF. TIF is compiled with Java 8 and thus requires at least Java 8 runtime.

Use the same bit size of the JVM as your ENOVIA/3DExperience requires, nowadays 64-bit is the main architecture for most OS’es.

The ENOVIA_HOME variable (if set) will result in that the bin directory is added to the PATH. You can omit this if your global PATH variable already is setup correctly.

Finally, the WEBAPP_ROOT directory is used to point of the ENOVIA/3DExperience application. The reason why you need to point out the ENOVIA/3DExperience web-application, is because TIF needs to be aware of the JAR files and other class/properties files found from WEB-INF/classes and WEB-INF/lib.

You may choose to not set this environment variable. In that case, you must copy the content of WEB-INF/classes and WEB-INF/lib from your ENOVIA/3DExperience web-application into the ${TIF_ROOT}/modules/enovia/lib/custom directory.

The least required JAR file you need to copy depends on the ENOVIA/3DExperience version you use, but the list below may give a hint:

  • eMatrixServletRMI.jar

  • enoviaKernel.jar

  • FcsClient.jar

  • FcsClientLargeFile.jar

  • Mx_jdom.jar

  • search_common.jar

Note 1: The "tif.bat" script takes one argument, which can be any of "run", "start" or "stop".

Note 2: The difference between "run" and "start" is that run starts the server in the same window while "start" opens a new window.

Note 3: To stop the TIF server, use a stop script that launches "tif.bat" with stop as argument. Don’t stop the server using CTRL-C or similar, because that causes an unclean shutdown of TIF with unexpected result.

Note 4: By default, the tif.bat script reads an environment variable called HEAP_SIZE to set the Java heap size. This value is default set to 1024MB.

5.1. JDK Version

The lowest JDK version that you can use with TIF is currently JDK 8. This is the version, which the TIF source code is compiled with.

But you should preferably select the same version of the JDK as your ENOVIA/3DExperience application uses.

Note on Java 15+:

If you use Java 15 or later and utilize the scripting capabilities within TIF, e.g. having some code in a JavaScript file, then you need to add some additional JAR files into ${TIF_ROOT}/lib/custom. This because the scripting engine have been removed from the JDK bundle as of JDK 15 and onwards.

Adding scripting capabilities to the JVM can be done in a couple of different ways. The absolute easiest solution is to add the Nashorn scripting engine, which was the engine part of the JDK earlier. There are some dependencies to the Nashorn engine that also needs to be added. At the time of writing this document, the latest version of the Nashorn engine was 15.4 and that version came with a dependency to the asm 7.3.1 library. So for this version to work, you then needed the following JAR files.

  • nashorn-core-15.4.jar

  • asm-7.3.1.jar

  • asm-commons-7.3.1.jar

  • asm-tree-7.3.1.jar

  • asm-util-7.3.1.jar

All of these artifacts can be downloaded from the Maven Central.

5.2. TIF as a Linux systemd service

If you want to define a service to be administrated via the systemd manager, you need to create a so called systemd unit file describing the service.

Below is an example of such service.

[Unit]
Description="Technia Integration Framework (TIF) systemd-style service."
After=local-fs.target network-online.target

[Service]
Type=exec
ExecStart=/opt/tif/bin/tif.sh start
ExecStop=/opt/tif/bin/tif.sh stop
Restart=on-failure
User=tif

[Install]
WantedBy=multi-user.target

The service can be put in for example /etc/systemd/system/tif.service.

After adding the service file, reload the systemd cache via systemctl daemon-reload

To start the service, run systemctl start tif.service.

To enable, e.g. ensuring that it is started when the server is rebooted, the service run systenctl enable tif.service

5.3. TIF as a Linux init.d service

Below is an example of a script suitable for putting into the init.d folder as a Linux service. This is only an example and can be considered as a starting point for your own service.

The variables TIF_HOME and TIF_USER needs to be set in the script.

#!/bin/sh
# chkconfig: 2345 95 20
# description: Starts and stops the tif daemon
# This is the init script for starting/stopping tif
# processname: tif
TIF_HOME=
TIF_USER=

start() {
    echo -n $"Starting tif service: "
    su -s /bin/bash $TIF_USER -c $TIF_HOME/bin/tif.sh start
    echo $?
}
stop() {
    echo -n $"Stopping tif service: "
    su -s /bin/bash $TIF_USER -c $TIF_HOME/bin/tif.sh stop
    echo $?
}
restart() {
    stop
    start
}
status() {
    ps -aef | grep tif
}
# Handle the different input options
case "$1" in
    start)
    start
    ;;
    stop)
    stop
    ;;
    status)
    status
    ;;
    restart)
    restart
    ;;
    *)
    echo $"Usage: $0 {start|stop|restart|status}"
    exit 1
esac
exit 0

5.4. TIF as a Windows Service

There is a sample BAT (service_example.bat) file found from ${TIF_ROOT}/bin showing how to register the TIF as a Window service.

This requires you to download a separate application called prunsrv from the Apache Commons site.

Below is an example illustrating what parameters that may be needed to be set for the service:

@echo off
set PRUNSRV_HOME=c:\Apps\commons-daemon-1.3.3\amd64
set TIF_HOME=c:\apps\tif
set JAVA_HOME=c:\apps\jdk-17
set ENOVIA_HOME=c:\apps\enovia\V6R2013X\server
set DLL_PATH=%ENOVIA_HOME%\win_b64\code\bin
set WEBAPP_ROOT=c:\apps\enovia\V6R2013X\webapp
set NODE_ID=%COMPUTERNAME%
set INSTANCE_ID=TIF-1
set HTTP_PORT=8181
set HTTPS_PORT=-1
set SHUTDOWN_PORT=9010
set MEM_SIZE=1024
set TIF_LOG_LEVEL=DEBUG
set TIF_PRODUCTION_MODE=false

%PRUNSRV_HOME%\prunsrv.exe //IS//%INSTANCE_ID% ^
        --DisplayName="%INSTANCE_ID%" ^
		--Startup=auto ^
        --Description="TECHNIA Integration Framework" ^
        --Install=%PRUNSRV_HOME%\prunsrv.exe ^
        --Jvm=%JAVA_HOME:\=/%/bin/server/jvm.dll ^
        --StartMode=jvm ^
        --StopMode=jvm ^
        --StartClass=com.technia.tif.core.BootLoader ^
        --StartParams= ^
        --StopClass=com.technia.tif.core.BootLoader ^
        --StopParams=-stop ^
        --Classpath=%TIF_HOME:\=/%/lib/tif-bootloader.jar ^
        --JavaHome=%JAVA_HOME% ^
        --LogPath=%TIF_HOME%\data\%NODE_ID%\%INSTANCE_ID%\logs ^
        --LogPrefix=commons-daemon-%INSTANCE_ID% ^
        --LogLevel=Debug ^
        --StdOutput=auto ^
        --StdError=auto ^
        --PidFile=pid_%INSTANCE_ID%.txt ^
        --JvmMs=%MEM_SIZE% ^
        --JvmMx=%MEM_SIZE% ^
        --LibraryPath="%DLL_PATH:\=/%" ^
        ++Environment="MX_CHARSET=UTF8" ^
        ++Environment="NLS_LANG=_.UTF8" ^
        ++Environment="LANG=C" ^
        ++Environment="DSLS_CONFIG=C:\data\config\DSLicenseServer.txt"
        ++Environment="TNS_ADMIN=D:\apps\oracle\product\19.3.0\dbhome_1\network\admin" ^
        ++JvmOptions9="-Dtif.productionMode=%TIF_PRODUCTION_MODE%" ^
        ++JvmOptions9="-Dtif.home=%TIF_HOME:\=/%" ^
        ++JvmOptions9="-Dtif.loglevel=%TIF_LOG_LEVEL%" ^
        ++JvmOptions9="-Dfile.encoding=UTF-8" ^
        ++JvmOptions9="-Dtif.instance.id=%INSTANCE_ID%" ^
        ++JvmOptions9="-Dtif.http.port=%HTTP_PORT%" ^
		++JvmOptions9="-Dtif.https.port=%HTTPS_PORT%" ^
        ++JvmOptions9="-Dtif.shutdownListener.port=%SHUTDOWN_PORT%" ^
        ++JvmOptions9="-Denovia.webapp.dir=%WEBAPP_ROOT:\=/%" ^
        ++JvmOptions9="-Denovia.lib.dirs=%WEBAPP_ROOT:\=/%/WEB-INF/classes';'%WEBAPP_ROOT:\=/%/WEB-INF/lib"

6. Installing the ENOVIA/3DExperience Client

The ENOVIA/3DExperience client is installed via an automated installer.

When starting the installer, you will be prompted for the following information:

  • JAVA_HOME directory. Must be of version 1.7 or greater.

    • The JVM is used to run the Schema installer so it has to match the bit-size of ENOVIA/3DExperience (32/64 bit)

  • ENOVIA/3DExperience Server Installation Directory

  • Your bootstrap file (MATRIX-R)

  • Database credentials (username / password of ENOVIA/3DExperience system user)

  • Other database settings (depending on selected database)

  • The ENOVIA/3DExperience web application directory

The installer will add a few entities to the ENOVIA/3DExperience data model, in order to be able to handle the TIF jobs and queues.

Running the installer from a network location may cause different problems. Ensure the installer is copied to a local directory before running. Installation from a network location is not supported.

On Windows, the EXE installer tries to locate the JRE to use for running the installer.

If this fails you can start the installation in the following way:

c:\path\to\my\jdk\bin\java -jar tif-enovia-client-2021.5.1-setup.exe