trueChart Help

Installation of the trueChart service

System requirements

Server

  • Windows Server 2008 (R2) or later,

  • Java Runtime Environment (JRE) version 8 or later,

  • MySQL (version 5.7 or later) or Microsoft SQL Server (version 2008 or later)

Java Runtime Environment (JRE)

The minimum requirement for the Java Runtime Environment (JRE) is version 8.
We recommend to use the latest Java 12 version (JRE 12).

You will need the 64-bit JRE for trueChart you can download at http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Firewall settings

As the Qlik Sense® web server uses port 443 and the trueChart web service uses port 8080 (by default, can be changed during the installation process), it is suggested to set your firewall to allow these ports.

Qlik Sense Deployment

In case of direct deployment and usage with Qlik Sense no specific port needs to be open, since the service communication then goes through Qlik Sense new broker server infrastructure. This requires that you’re not using the "cross domain"-setting during the installation progress. Further more, you need to restart the Qlik Sense Service Dispatcher service for changes on the broker service take effect.

Qlik Sense Broker Service: acts as an interface to and an intermediary between services started by the Qlik Sense Service Dispatcher(QSD). The service is launched and managed by the Qlik Sense Service Dispatcher (QSD) when required. For more information see here.

Database

For saving the Notation Manual and various trueChart-specific settings, a database is required. Currently the following database systems are supported:

  • MySQL (from version 5.7 or later)

  • Microsoft SQL-Server (from Version 2008).

Since the Oracle database is no longer supported from trueChart version 3.2, we offer support for migration to a supported database system. Please contact us in the case need.

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) should also be defined.

At present it is not possible to obtain the database-user from an active directory, but rather has to be deposited locally in the particular database management system.

Client

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

Browser support

At present trueChart-Menubar supports the browsers listed below:

  • Microsoft Internet Explorer 11

  • Microsoft Edge (lastest version - v42, at the time of writing)

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

  • Google Chrome (latest version – v73, at the time of writing)

  • iOS 11.2 or later

The indicated versions are the minimum conditions. In each case, the latest version is to be preferred.

We recommend to use Google Chrome, since this is the fastest available browser.

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:

trueChart installation 01
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 path name into the textfield (1). The install directory is by default C:\Program Files\High Coordination.

Basicly you can jump through the steps of the dialog by clicking Back (2) or Next (3). To abort the installation just click on the Cancel (4) Button at the bottom of the modal anytime.

trueChart installation 02
Figure 2. trueChart installation folder

Domain settings

If you have already installed a version of trueChart into the seleted folder, an UPDATE process will be triggered. If you have not installed the trueChart service yet, a new INSTALLATION will be started.

  • (1) Cross-Domain: possibility to use different urls for the service and the root system

  • (2) Use SSL: set SSL certificate (https) to use client server communication (recommended)

  • (3) Service Host: set the host (IP-Adress or machine name)

  • (4) Service Path: set the name of the trueChart Service which is by default trueChartService

  • (5) Service Port: set the port of the trueChart Service which is by default 8080

  • (6) Hub Host: set the host (IP-adress without Port) of the (BI-)system from which trueChart is delivered.

  • (7) [Qlik Sense] Qlik Sense directory: browse or enter the full qualified system directory of the Qlik sense installation. The target directory is called 'Qlik'.

To run the trueChart service in cross-domain mode, you need to check the corresponding option (1). Now choose between SSL secured or none secured data exchange with clicking the Use-SSL checkbox (2). In case you have the Cross domain (1) option unchecked a SSL secured connection is required. You can not change the activated Use-SSL (2) checkbox and need to apply a SSL certificate in the next dialog sequence step.

trueChart installation 03
Figure 3. Cross-domain and installation location settings (install)
For some BI systems (like Microsoft Power BI) a custom trueChart resource path can be defined. This is the location from which trueChart itself is being loaded by the BI system. The default behavior is to load trueChart from the HighCoordination server.

SSL settings (optional)

To use a SSL secured HTTPs data exchange connection from the client to the trueChartService, browse a valid .pfx, or .pem file by clicking Browse (1) or enter the full qualified system path of the file into the textfield of the SSL certificate location (1) option.

Qlik Sense: If you choose cross domain as deactivated in the previous step, you need to upload the Qlik Sense internal SSL certificate, which can be exported from the QMC. Please find additional information here Export internal ssl cerficate from Qlik Sense.
trueChart installation 05
Figure 4. SSL settings.
Certificate files must be used by a local directory. The use of network drives is currently not supported.

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

trueChart installation 06
Figure 5. browse a ssl certificate file

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

The password of the key file is not validated. Entering the wrong keys here will cause problems with ssl connection even the service gets installed sucessfully.

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.

The database schema specified in Database (default: hicoservicedb) needs to be created in advance.
Currently, it is not possible to obtain the database user from a user directory but rather has to be created locally in the particular database management system.

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:

trueChart installation 08
Figure 6. Specify database configuration

Finish installation

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

install 05
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.

Please find here additional information for Installation of trueChart within Qlik Sense.
install 07
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 there was a problem while installing trueChart, you may open the log file by clicking on Show Logs!. Also consult the Troubleshooting section in this document.

Troubleshooting

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

Client connections to the trueChart service fail

If the trueChart Service is available on the server itself via localhost but external connection fail, 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:

invalid port
Figure 9. Error message when 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:

no database connection
Figure 10. 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 an error diagnosis. Therefore please have your log-file prepared.

Download server logs

As of version v3.2, 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.

You can download the log files within the settings area.

logfiles
Figure 11. The Log files section in the trueChart Management Console.

Here, you have the following three download options:

Latest

Download all log files with the latest modification date

Last 7 Days

Download all files that have been modified in the last 7 days.

All

Download all existing log files

If you confirmed the settings for the domain/encryption with Next, carry on with the specifications for the database (see also section Preparation).

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.

trueChart installation 05
Figure 12. 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:

security exception
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 uninstall trueChart and reinstall it on the same server. The only difference is that you will have to check Use SSL and located the certificate and keyfile 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. There you should find an entry called trueChartService. This service should also already been started.

truechartservice
Figure 14. The trueChartService in the Windows Services overview.

You can then also check you 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.de:8080/trueChartService.

There you can see the following logon page:

tcmc login
Figure 15. Login of the trueChart Management Console.

Here you enter the user name and the password you specified in the final step of the installation process. After that you reach the overview. Navigate across the following points: “Server Configuration [#1] → License [#2]”:

apply license
Figure 16. The License information tab in the trueChart Management Console.

Take a note of your server-id and send it to our support. The best thing you can do is to copy the license key and afterwards send it via e-mail to: support@highcoordination.de. Prior to this you should already have received and confirmed a corresponding proposal by other means.

As soon as your license was registered (at best you register your installations with us in advance and make an appointment with our support so the lapse of time is reduced to a minimum), you receive a signature in the following form as response:

apply license2
Figure 17. Applying the License.

Enter this signature into the field of the “Signature” [#3] and confirm it by clicking “Apply License” [#4]. In the field “Details” on the right side you can then see your license information. This means the trueChart installation is activated and can now be fully used.

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 (default: http://localhost:8080/trueChartService) 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.

newuser
Figure 18. Creating a new user in the trueChart Management Console.

In the New User dialog enter the requested information about the new user as well as the desired permission group from the Permissions list and click on Save to create the user.

edit user
Figure 19. Editing an existing user in the trueChart Management Console.

Any user account can be altered afterward by clicking on edit in the Users list.