TVC Installation Guide

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:

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

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.

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

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

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:

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:

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:

The Win32 installer has a graphical user interface that will guide you through the installation of the TVC Software. The installer also has a built-in help that will give you detailed information about each step.

In order to install TVC successfully, you must ensure that the computer you do the installation from have following software setup and working properly:

Following decisions needs to be taken during the execution of the installation:

NOTE: The installer will by default rely on the ematrix.ini file.

For UNIX environments, the tvc-<VERSION>-setup.sh installer should be used. This installer is command-line based, and can be ran on a head-less environment that lacks a window system.

Before running this installer, ensure that the executable flag is set. E.g. run a command similar as below:

When the installer starts, it will look for a valid Java VM under the JAVA_HOME environment variable. If no such variable is set, or the variable is incorrect the installer will terminate.

NOTE: This file contains binary data; don’t transfer this file via FTP in ASCII mode. This will result in a broken installer.

In order to install the TVC components, you must ensure that the computer you do the installation from have following software setup and working properly:

Following decisions needs to be taken during the execution of the installation:

Once the installer has started successfully, you will on the terminal see a screen similar as below:

Before the actual installation starts, you will be asked to verify the entered values.

The TVC installer adds a servlet definition to the web.xml file.

To configure certain aspects of TVC one can add so called init-parameters to the servlet.

Note 1: Since the web.xml file must conform to the J2EE web application DTD, the application server will not start if aren’t careful. Review all changes you made to this file before starting the application server.

Note 2: Some application servers require you to re-deploy the application after changing the content of the web.xml file.

Explanation of the numbered items in the table above

The TVC installer also adds a servlet mapping in the web.xml file. This should look like:

NOTE: You should not change the URL pattern.

The installer can be run in an unattended (silent) mode, without going through the GUI.

When TVC is used in a production environment, you should ensure that TVC is running in production mode.

This is important, as TVC in production mode will not check for modifications of administrative objects and/or configuration objects at runtime.

This feature is of course useful in a development environment, where changes are frequently made to configuration objects and having to reload the TVC cache’s all the time after doing these modifications are time consuming, but in a production environment, these changes are rarely done and this overhead should be avoided.

The initialization parameter that controls the production mode setting is defined in web.xml as below:

If this parameter is missing from the web.xml file, TVC will by default assume production mode.

In a production environment, the amount of log output should be reduced. In TVC, the log output is controlled by setting the log-level to a certain value. Possible values for the log-level are

The log level is set in the web.xml file as shown below:

A reasonable value for this parameter in a production environment is either FATAL or ERROR. In development environments, you might want to set this value to INFO or DEBUG. However, please remember that the latter log-levels will generate a larger amount of output.

If you are using Weblogic as application server, you should carefully review the settings of the parameters discussed below as these will have severe negative impact of the performance if they are not defined accordingly.

If you see the error message shown below, when trying to install the schema – Then modify your ematrix.ini/matrix.ini file to contain the following setting:

When using Apache as a front-end to Weblogic, the Apache server must be configured to pass the requests matching /tvc-action/* to the application server.

Typically, this is made in the httpd.conf file under the conf directory in apache.

For the Weblogic proxy module, the example below illustrates how this is accomplished.

This can happen either because of a memory leak or because the application simply is trying to store more stuff in memory than you have space for. Another reason could be that the JVM cannot load the classes since the memory area where the static data, such as class definitions are stored, is too low.

The below information is not valid for Java 8 and later:

There are two parameters, -XX:PermSize and -XX:MaxPermSize, that control the size of the permanent area. This area may need to be increased if large numbers of classes are being loaded.

Increase the –XX:MaxPermSize parameter to, for example 64M, and see if this resolves the issue.

If you encounter problems with the TVC cache, for example your update of a command in a toolbar is not updated automatically when you execute the structure browser, please verify the following:

The following examples from a 10.5 MQL client illustrate the timestamp problem:

or

E.g. the modified timestamp is not updated correctly when adding or modifying a setting or when adding a command to a menu. This is a bug in core matrix.

The TVC log files are by default written into a directory provided by the Application Server.

You can override this directory by applying an init-parameter in web.xml within the TVC Servlet definition:

Internally in TVC, URL’s are built based upon the information available from the HttpServletRequest API provided by the application server (server host/server port/scheme).

In cases when you have a proxy server, the application server must be configured to be aware of this in order to return correct information on the HttpServletRequest class; otherwise the URLs that are generated won’t point correctly.

The proxy server typically passes the correct values behind the request headers:

This filter will then honor the values set there. If no such header is present, this filter will fall back to the default value obtained via the HttpServletRequest API.

In TVC, we have provided a servlet filter will be able to override the return values for server-host, server-port and scheme on the HttpServletRequest instance based upon the above request headers.

The filter is added to web.xml by the TVC Installer, and will look like this:

If no init parameter is provided, the default request headers "X-Forwarded-Host", "X-Forwarded-Port" and "X-Forwarded-Proto" will be used. To specify other request header, you can add init parameter with names host, port and/or scheme and provide the name of the header as value.

Example below:

If you specify empty value for the parameter, it will then take the "default" value. E.g.

You can specify static values using "static:" prefix as shown below:

Sometimes, it can be useful to force the client into showing the web application in a specific language, even though the browser is set to another one.

For example, if the client browsers are using German as their default language, then all the labels in the web application will be shown in German, wherever a specific label exists, and if not, it will default to English. However, if not all labels have been translated, then there will be a mix of the default language, usually English, and German. This may not be the desired behavior of the application.

In TVC, we have provided a servlet filter, which if configured to be used, will be able to override the locale used on the HttpServletRequest instance. When this filter is set, the locale specified will always be used, regardless of client setting.

To configure this, modify your web.xml file and add the filter and its mapping as shown below:

The init-param values also need to be adjusted.

The mapping to this filter should be created as below:

In order to reduce the consumption of licenses, you can replace the default super-user used by TVC, called "TVC Shadow Agent", with the super-user used by the ENOVIA application.

This can be done in a couple of different ways, see explanation below:

Some of the features in TVC that handles file uploads has support for FCS enabled (File Manager, Collaboration, Mobile Access). This will cause cross domain request which by default is blocked by modern browsers. There are possibilities to enable this via usage of the so called CORS (Cross Origin Resource Sharing) mechanism. This can be done by adding a servlet filter enabling CORS support to ALL FCS instances. Such servlet filter is provided with TVC Core and can be applied like shown below:

This is needed for Applet based clients, which needs to be able to download the JAR files.

TVC can use Service Workers to cache some static resources (.js, .css, .png etc.) so that they are served from the cache instead of making network requests. Add following properties to enable this -

tvc.core.clientsidecache.enabled=true - Used to enable client side caching (default = false)

tvc.core.serviceworker.enabled=true - Used to enable TVC static resource caching (default = true)

In addition, following step is needed to inject Service Worker within the emxNavigator.jsp (resides in the common folder in your application directory) or any top level entry page, e.g. emxLogin.jsp. Add following line immediately after the <head> tag.

Note 1: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The licenses mentioned in the tables in the previous chapters are abbreviated. The abbreviations are: