Installation Guide - Preface

29 April 2016

1. Preface

Technia Value Components, TVC, is a collection of software components that is installed into an existing ENOVIA/Matrix application.

TVC has been designed to have a very small impact/footprint to your existing application, in order to make it easy to install and upgrade TVC. The installer will not modify any existing JSP page or properties files from your ENOVIA installation. If any of the TVC components requires this to be done, this will be mentioned within the respective administration guide. The only file that the installer modifies, which are shared by the existing application, is the web.xml file. One servlet and a mapping to this servlet will be added.

Each component is shipped with its own set of web-application files and a set of MQL scripts for creating the necessary data model entities related to the component.

1.1. System Requirements

Server side

  • The supported ENOVIA versions as of this release are:

    • V6R2013x up to latest

  • The minimum Java version is 1.7

  • Application Server according to the ENOVIA core product requirements

Client side

  • Supported browsers are:

    • Internet Explorer

    • Firefox

    • Chrome

    • Microsoft Edge

Some exceptions regarding browser supports exist for certain features.

1.2. Installation

TVC is installed by using an installer, which is either an .exe file for use on Windows platforms or a .sh (shell script) file for use on a UNIX platform. In any of the cases, you must have a Java Virtual Machine (>= 1.6.0) installed on the computer where the installation is made from.

A complete installation of TVC consists of:

  • Installing the administrative objects into the database, e.g. the data model.

  • Copy the web-application files into either:

    • The staging directory

      • Deploying to the staging directory requires you to re-run the emxwarutil in order to create the WAR/EAR file.

    • The exploded web-application directory

  • Update the deployment descriptor (web.xml) with the TVC required registrations.

You need a valid license for TVC in order to perform the installation. This license is called technia.license and contains information about the Software/Components you have purchased.

1.3. Preparing the Installation

Following list shows a couple of things that you must have prepared prior to installing TVC.

  1. Whether to install into a staging directory or into an exploded web-application.

    E.g. where the web-application / staging folder is located.

    After installing to the staging directory, you must re-run the emxwarutil again to create a WAR/EAR or exploded web application.

  2. Table-space and index-space for the TVC Administration Vault, unless this is an upgrade of an earlier version (then this vault already exists).

    Even though it is recommended for performance reasons to have separate spaces for a vault, you can leave the table-space and index-space settings empty and use the default spaces.

  3. Username + password for the matrix user that the installation should be performed with (must be a user with system and business privileges).

1.4. After Installation

From TVC version 2021.3.0, some of the built-in 3rd-party packages are not part of TVC jars as they cause issues in latest JDK and 3DExperience version. Once the installation is done, please make sure below jars are present in web-application’s lib directory. Please use download links in case the jars are not present.

Depending on what kind of application server you have and which version it has, you might need to perform some additional action after the installation; such as re-deploying the application or clean some temporary folder etc.

For example, in Tomcat you should clean the work folder. The reason is that Tomcat extracts files from the JAR files into a different directory. If this work folder isn’t cleaned, there is a risk that these extracted files are not extracted again from the new JAR file.

In some Weblogic versions, you will need to find old TVC JAR files in a separate folder, as Weblogic internally are copying these, and ensure that those are deleted.

Websphere for example requires re-deploying the application.

Some components might require additional post installation action, which is not performed by the installer. Please consult the administration guide for each component you are installing.

When you have installed TVC into a production environment, you should read this chapter, which contains performance related topics that should be reviewed before taking the production environment into use.

1.5. The License File

The license file must be made available for the class-loader of the application server that you are using, e.g. this file is placed under the WEB-INF/classes folder of your application.

Also note: if you are using TVC from JPOs, and your Matrix installation uses RMI servers – then the license file must also be available somewhere inside a directory included in the MX_CLASSPATH variable.

If you are installing using the staging approach, put the license file under ${RMI_HOME}/staging/ematrix/WEB-INF/classes

1.6. Upgrading Notes

If you are upgrading an older TVC version, some additional actions must be carried out before the installation is made.

  1. Remove the old TVC JAR files starting with tvc- from WEB-INF/lib

  2. Remove all files starting with tvc- from the WEB-INF folder,

  3. Remove the tvc folder (containing JSP files) either under your $APPLICATION_HOME/ematrix directory or $STAGING_HOME/ematrix directory (depending on your installation method).

1.6.1. Notes about ENOVIA RPT

If you also have the ENOVIA RPT product, please read this information:

ENOVIA RPT is based upon TVC and is bundled with a specific TVC Core version. TECHNIA will always provide new Hot Fix versions of ENOVIA RPT that is based upon the latest TVC core version in order to be able to use TVC with ENOVIA RPT. So before installing a newer TVC release, make sure that you also have a proper ENOVIA RPT version available for upgrade. Please contact TECHNIA in case you have any questions about what hot fix version to be used.

1.6.2. Set the TVC Shadow Agent password

In case TVC Shadow Agent password was changed by the project, it should be set again post-installation or upgrade.

1.7. Configuring TVC

TVC can be configured in many different areas. There are both configuration objects that defines behavior on a per use-case level, but there are also configuration parameters that can be applied to TVC as such (global TVC system parameters).

The latter parameters are typically entered within the web.xml file (the application deployment descriptor file). And more specific, these parameters are added as init-parameters to the TVC servlet that is being added to web.xml by the installer.

Typically after running the TVC installer, you will in web.xml have these lines added:

<servlet>
    <servlet-name>tvcaction</servlet-name>
    <servlet-class>com.technia.tvc.core.TVCServlet</servlet-class>
    <init-param>
        <param-name>tvc.core.productionMode</param-name>
        <param-value>TRUE</param-value>
    </init-param>
</servlet>
...

<servlet-mapping>
    <servlet-name>tvcaction</servlet-name>
    <url-pattern>/tvc-action/*</url-pattern>
</servlet-mapping>

Throughout the different TVC Administration Guides, you will see instructions on how to apply so called init-parameters to change some behaviour. These are all added as init-param like shown in the example above.

As of version 2012.1.0 it is also possible to define the init-parameters in a properties file called tvc.properties available in the classpath. E.g. you could add a file called tvc.properties within the /WEB-INF/classes folder of your application that holds the init-parameters. The benefit is that you do not need to modify the web.xml file when applying new init-parameters and also, the properties file format is less verbose than when adding init-param elements in the web.xml.

The above example would have been written as below if defined in a tvc.properties file:

tvc.core.productionMode = TRUE
tvc.core.logLevel = ERROR
The init-parameters in web.xml takes precedence over the properties defined in the tvc.properties file.

As of version 2016.1.0, init parameters can also be specified as Java system parameters, e.g. as –D parameters provided via command line.

The order of precedence are:

  • tvc.properties file(s) read through the classpath

  • web.xml init parameters

  • System properties

While navigating to TVC page from Enovia OOTB table, sometimes leading and trailing white spaces gets added to the object Id parameter on the request to the server. This can now be trimmed using the below filter in web.xml. 
<filter>
    <filter-name>TVCObjectIdFilter</filter-name>
    <filter-class>com.technia.tvc.core.filter.TVCObjectIdFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>TVCObjectIdFilter</filter-name>
    <url-pattern>/common/emxTree.jsp</url-pattern>
</filter-mapping>