Installation of the TRUECHART service

System requirements

Server

• Windows Server 2008 (R2) or later,

• Java

  • Oracle Java Runtime Environment (JRE) version 8 or later (64-bit)

  • Recommended: latest Java SE 11 (LTS) - 64-bit
    • get Java 64-bit: https://www.oracle.com/de/java/technologies/javase-downloads.html
  • Java OpenJDK is also supported (https://openjdk.java.net) 
    • see also: TRUECHART and Java licensing
    • get OpenJDK: https://jdk.java.net/archive/
• Either of these databases:

  • MySQL (version 5.7 or later)

  • Microsoft SQL Server (version 2008 or later)

Firewall settings

TRUECHART uses per default port 8080 and requires an inbound connection over the TCP protocol, so these settings need to be adjusted within the firewall. More information on  How-to: Scan Port How-to: Open Port

Database

For saving the Notation Manual and various TRUECHART-specific settings, a database is required. (For supported Databases and their versions see: Server → Database)

The database does not need to be installed on the same machine as TRUECHART, but it has to be accessible from the installation server via IP/DNS. An in-advance-defined schema (a database) as well as a user with a corresponding authorization (min. SELECT, INSERT, UPDATE, DELETE, ALTER (for installation)) should also be defined.

Client

• Windows 7 (x86_64) or higher is recommended to be used as an operating system.

Browser support

At present TRUECHART supports the browsers listed below. The indicated versions are the minimum conditions. In each case, the latest version is to be preferred.

We recommend using a current version of Google Chrome or Microsoft Edge!

• Google Chrome (latest version – v86, at the time of writing)
• Microsoft Edge (latest version - v86, at the time of writing and lowest recommended version is 80.0.361)

• Mozilla Firefox (latest version – v82, at the time of writing)

• Microsoft Internet Explorer 11
• Mobile

  • iOS 14.2 or later / iPadOS 14.2

  • Android 8.1 or later 

Installation / update process

To install the TRUECHART service, run the appropriate setup file for your BI system. Click Next at the bottom to start the installation:

Figure 1. The initial pane of the installation.

In the following step, you need to browse to your TRUECHART installation folder or enter the full qualified system pathname into the text field. The install directory is by default C:\Program Files\High Coordination.

Basically you can jump through the steps of the dialog by clicking Back or Next. To abort the installation just click on the Cancel Button at the bottom of the modal anytime.

Figure 2. TRUECHART installation folder

Domain Settings

If you have already installed a version of TRUECHART into the selected folder an UPDATE process will be triggered. If you have not installed the TRUECHART-Service yet, a new INSTALLATION will be started.

• Use SSL: Enable or disable SSL settings, but it is recommended to use SSL.
• Service Path: Defines a path where the TRUECHART-Service should be deployed to, Tomcat special names "ROOT" and "" are not allowed. The default is TRUECHART-Service. (Case sensitive)

• Service Port: Defines the port on which the TRUECHART-Service should listen on. A valid port configuration is required. Default is 8080

Figure 3a. Cross-domain and installation location settings (install) for TRUECHART for QlikSense

SSL settings (optional)

To use an SSL secured HTTPs data exchange connection from the client to the TRUECHARTService, browse a valid .pfx, or .pem file by clicking Browse or enter the full qualified system path of the file into the text field of the SSL certificate location option.

Figure 4. SSL settings.

If a .pfx file is selected, a Keyfile and its password is not needed. In case you choose a pem file, browse to a key file with the browse button of the Keyfile options, or enter a full qualified system path of the file.

Figure 5. browse an SSL certificate file

If the key file needs a password, you will have to fill the password in the Keyfile password (3). If the file is not password secured, just leave Keyfile password (3) blank.

Database settings

The next step is to specify the settings for the underlying database. The user you specify needs to have the rights to do SELECT, INSERT, UPDATE, DELETE on the database tables.

After that, you may define the information for the root user of the TRUECHART Management Console, i.e. First name, Last name, Username, and a Password:

Figure 6. Specify database configuration

Finish installation

Now that you provided all the necessary information, you may start the installation by clicking on Install.

Figure 7. Starting the installation.

After TRUECHART has been installed, you may get additional information on further actions to prepare TRUECHART for your BI system.

Figure 8. Finishing the installation.

If you also confirmed the user settings with Next >, the setup program collected all necessary information and you can start the installing process by clicking Install. Then wait until the process was fully completed and a new Explorer window is opened with the TRUECHART file for your BI system.

If you have installed TRUECHART for Qlik Sense, the ZIP-file (TRUECHART4Sense.zip) must be uploaded to the server via the management console (QMC - Extensions).

Troubleshooting

During the installation, a TRUECHART-Setup.log the file is created in the same directory as the installation executable. Error messages during the installation process are saved in this file.

If the installer does not start.

1. Please check if you have the correct Java version.
2. Please check if the JAVA_HOME variable is set correctly.
   1. https://javatutorial.net/set-java-home-windows-1

Client connections to the TRUECHART service fail

If the TRUECHART Service is available on the server itself via localhost but the external connection fails, make sure you have connections on the TRUECHART Service’s port configured as “allowed” in your firewall.

Domain and port setting issues

If you get the following error message, it is likely you selected a port that is already been used by another process:

Figure 9. Error message when the entered port is already used.

You may select a different port or contact your IT support.

Database setting issues

The most frequent error expresses itself as demonstrated in the following figure:

Figure 10. An error message indicating failed attempt to communicate with the database.

This can have different causes:

• The host-address and/or the specified port are erroneous and the program cannot reach the database

• The specified user does not exist or does not have the proper authorization

• The specified user originates from an active directory

• The password of the given user was wrongly spelled

• The database entered does not exist or was wrongly spelled

• Your database does not allow external access

• The firewall settings from the database server prevent a successful connection

You can also find more detailed information on the origin of the error in the log-file, which was automatically generated during the installation process.

In case of this error contact your IT-Support resp. your database administrator, he can send you the required parameters and p.r.n. make further settings on the database server.

Additionally, you can consult our support for error diagnosis. Therefore please have your log-file prepared.

Download server logs

You have the possibility to directly download the log information from the server as a zip file in the TRUECHART Management Console. In the event of a fault, this information can be easily made available to the support of HighCoordination.

More details here: Logfiles in TRUECHART Management Console.

No connection to the TRUECHART service when using SSL

When using SSL, after integrating a self-generated certificate from your BI system into the TRUECHART service, you may get a “No network connection” error message.

Figure 12. An error message indicating a problem with the connection to the TRUECHART service.

A quick workaround is to open the TRUECHART Management Console in another browser tab and add a security exception to your current session:

Figure 13. Adding a security exception in Internet Explorer. The process varies between different browsers.

To permanently solve this problem it is suggested to provide a valid, officially signed certificate (Class 4 and Class 3 SSL) to both your BI system and TRUECHART installation.

Switching from HTTP to HTTPS

The easiest method for changing TRUECHART from HTTP to HTTPS is to update TRUECHART on the same server. The only difference is that you will have to check Use SSL and located the certificate and key file in the next step.

In the database section of the installation, you have to uncheck Create tables and use the same database you have used before. After finishing the installation, you need to re-deploy the provided TRUECHART for your BI system.

Post-installation steps

Check installation

To check the installation, switch to the overview of the Windows Services control panel. There you should find an entry called TRUECHARTService. This service should also already been started. 

You can then also check your database. There you should discover several tables in the previously prepared and empty database schema. All tables have the prefix “hico_” (for example: “hico_doc_documents”, with the exception of the table “sequence”).

If these tables are present, you can carry on with the license activation.

License activation

To activate the license, open the TRUECHART Management Console. To do so, use the URL you configured during the installation process. This could be on the server: http(s)://localhost:8080/TRUECHARTService.

Read here for more details: Setting the license key.

Creating a new user

To create a new user, open the TRUECHART Management Console at http(s)://service-host:_service-port_/service-path as defined during the installation and after logging in, navigate to the User Administration page via the icon menu bar at the top and click on Create Local User below.

Read here for more details: TRUECHART User management.