1. Introduction

This guide covers the installation process of trueChart as well as the installation of the trueChart extension and the HiCo Converter.

2. System requirements

2.1. Server

It is assumed that Windows Server 2008 (R2) or higher is the server operating system. The different variations of the operating system (Standard, Enterprise, Data Center, etc.) are of no importance for the functioning of trueChart.

Qlik Sense® Server

trueChart has to be installed on the same machine (virtual or physically) as the Qlik Sense server (built-in or IIS), so the Qlik Sense Hub as well as the trueChart service can be called using the same URL.

trueChart is suitable for the Qlik Sense version 3.0 and higher. The latest version of Qlik Sense, June 2018 has been intensively tested and is supported explicitly from trueChart version 2018.2.x onwards.

Java Runtime Environment (JRE)

The minimum requirement for the Java Runtime Environment (JRE) is version 8 (JRE 8u171). We recommend the latest version JRE 8 Update 171.

Currently Java 10 is not supported and recomended last version of Java 8 must be used. Support for Java 10 will come in our summer release.
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.

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)

MySQL 8 is not supported, this will come in our summer release.
  • 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 case of 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.

2.2. Client

Because the access of the Qlik Sense Hub is carried out by a web browser, the use of trueChart is basically operating system independent. However, it has been shown that the use of Qlik Sense and trueChart are resource-intensive, wherefore 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 - v41, at the time of writing)

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

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

  • iOS 10.3.2 or later

    • We recommend upgrading to iOS 11.2.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.

3. Preparation

3.1. Database

During the installation of trueChart, you will be asked for a connection to a database. This database has to be created before starting the installation. An empty database (also called “schema”) without tables is sufficient.

Furthermore a user with appropriate authority has to be assigned to the created schema. In the ideal case this user corresponds to the “database-owner (briefly: DBO)”. If this assignment is not possible, at least the authorizations for SELECT, INSERT, UPDATE, DELETE and ALTER TABLE should be granted.

The answers to the following questions should already be available before starting the installation:

  • Which database system are you using?

    • E.g.: Microsoft SQL Server 2008 R2

  • What is the host-address of the database server?

    • E.g.: database.company.com (DNS) or 172.17.62.90 (IP address)

  • Which port is used?

    • MySQL uses port 3306 by default, MS-SQL uses port 1433 by default.

  • What access data is used for the access to the database?

    • User name and password (local user account, no AD-user!)

  • How was the database (resp. the schema) named?

    • E.g.: trueChartServicedb

3.2. Authority

Administrator authorization is necessary for the installation.

4. Installation process

4.1. trueChart4Sense Server

Once the preparations are completed, you can start with the installation. This includes initially copying the setup file (trueChart-Setup-x.x.x.exe) onto the server where also the Qlik Sense Server installation was executed. Run the file as administrator (right click, “Run as administrator”). There upon the installation program opens:

setup 01 welcome
Figure 1. The first pane of the installer.

Simultaneously a file with the name trueChart-Setup.log is generated. Possible error messages are saved in this file. If the installation is unsuccessful, you should preserve this file to forward it to the support in case of need. Carry on by clicking on “Next >”.

setup 02 location
Figure 2. Setting the installation directory and cross-domain option.

In the first step of the installation process you decide if you want to install trueChart for crossdomain and specify the desired directory of trueChart (this directory will be created during the installation).

If you performed a default installation without specifying other drivers or directories than the given ones, you can keep the already entered values. Otherwise make the corresponding adaptations in this step and confirm them with “Next >”.

setup 03 domain
Figure 3. Domain, port and AccessPoint settings.

Next you specify how the users of Qlik Sense (and trueChart) access the Qlik Sense Hub. If cross-domain was selected, all fields will be changeable. When cross-domain is not selected, Service host is automatically the same host as sense uses for the hub. Otherwise, if cross-domain is choosen then, you need to specify a valid host where the trueChart backend is located.

All other fields have to be filled with your desired values. For example, if you enter the following URL into your browser: http://application.company.com/hub, you need to enter the domain (application.company.com) into the field for the Hub host.

With the field “Service path” and “Service port” you can configure the access to the trueChart-backend and the "trueChart Management Console". In this example you would reach the trueChart service under the URL http://application.company.com:8080/trueChartService. It should be noted, that the specified port is not allowed to already be used by a different application, i.e. the port needs to be open (p.r.n. also consider the firewall settings).

Using SSL (optional)

setup 04 ssl

For using SSL you will have to deliver one PFX file or a CRT file and a KEY file. When a PFX file is used the keyfile row will be greyed out, because the row is not needed when using PFX.

If the key file needs a password, you will have to fill the password in Keyfile Password. If there is no Password needed, just leave Keyfile password blank.

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

As a last step you choose your access data for the trueChart-backend. You will need this after the installation to activate your trueChart version via license key.

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 file trueChart4Sense.zip.

4.2. trueChart4Sense Desktop

As of version v3.2, trueChart can also be installed in a desktop variant. The desktop version does not require the installation of a trueChart service or a database. This is possible because all relevant information of the trueChart definition is now also stored within the QVF files (Sense Desktop & Server). This means that the QVF files, including all the corresponding trueChart definitions, can now be copied, renamed, or imported to other servers, and the trueChart definition will be available without further additions.

As part of the use of trueChart4Sense Desktop, there are the following limitations in functionality:

No comments can be saved for published apps!
  • No versioning of the trueChart definitions

  • No historicization of comment changes

  • No user administration, each user always has Designer and Notation Manual rights

  • There is no central notation manual, there is always one per app.

In conjunction with using the comment functionality of trueChart, we strongly recommend that you always use the server version of trueChart to use the full functionalities.

In order to install trueChart4Sense locally in the Sense Desktop, the complete directory must be copied to the extension directory. This directory can be found in Windows Explorer: %USERPROFILE%\Documents\Qlik\Sense\Extensions. After successful installations, you can use the new trueChart extension in the Edit mode as usual.

4.3. Extension installation on Sense server

The extension zip file has to be uploaded as extension in the Qlik Sense Management Console (QMC) under the tab Extensions, probably http(s)://localhost/qmc.

setup qmc 01

You will have to press Import (blue box) and select the trueChart4Sense.zip, located at C:\temp (no password required).

setup qmc 02

Migration for published apps

In the context of new versions, necessary adjustments within the apps are usually carried out automatically during loading. This is transparent for the users. An indication of this are corresponding logging entries in the development console of the browser.

Since changes to published apps cannot be saved, these automatic changes must be made at every load, which can have a negative effect on the loading speed of the visualization.

To avoid permanent migrations of the apps, we therefore recommend opening the corresponding apps as soon as possible in an unpublished mode, so that migration is then performed once and the changes are saved automatically. These apps should then be published again.

4.4. HiCo Converter

As an important part of trueChart it also needed to install the HiCo Converter service besides the installed trueChart Service on the same system. HiCo Converter provides the export functionality for the trueChart Client, which can be accessed through the context menu as you can see in the screenshot below.

setup converter 01

HiCo Converter can be easily installed through execution of the installer file trueChart_converter-[major.minor].exe.

setup converter 02

To check the installation, switch to the overview of the Windows services. There you should find an entry called “HiCoConverter”. This service should also already been started.

setup converter 04

By default, the HiCo Converter runs on port 30090. If you want to adjust the port after installation, you can do this by adjusting the config files. The port for HiCo Converter can be edited in the hico.conf file in the installation directory. After you have adapted this file, you must also edit the trueChart Service config files. This concerns the files config.xml in the installation directory of the trueChart service and the file hicoservice.xml in the Tomcat directory of the trueChart installation.

Update process

The HiCo Converter must be updated together with each trueChart update. Follow the next steps to update the HiCo Converter properly:

At first the existing installation must be removed from the system. To remove the HiCo Converter open the Programs and Features dialog from Windows, locate the program and click in the header on uninstall.

Afterwards the new HiCo Converter can be installed as described further above.

4.5. Cluster installation

Cluster node installation

The trueChart Service also supports installation in clustered environments, therefore on each Qlik Sense server node a separate instance of a trueChart service must be installed and afterwards the cluster setting must be done, to ensure that each cluster instance of trueChart will be correct in sync.

At first on each node a separate instance of trueChart Service must be installed. Please use the installation instructions from the previous chapter.

For a clustered setup make sure that all installations use the same information, also the same database configuration. The Create tables option on the "Setup your Database" page should only be active for the first installation, otherwise the created tables will be overridden.

setup clustering 01
Figure 4. The Create Tables option during the installation.

Setting up clustering

After you have successfully installed each trueChart service and entered the licenses for each service we can now proceed to setup the clustering.

When you log into the trueChart Management Console you see the My Profile page. Click on the Settings button on the top right panel and on Cluster Servers in the Category tab.

settings cluster
Figure 5. The Cluster Servers section in the trueChart Management Console.

After the initial setup you will see one entry. This is the service, which also created the database tables in the installation process.

If you want to add an additional server to the cluster click on “New Slave”.

new server slave
Figure 6. The New Server Slave dialog in the trueChart Management Console.

The dialog shown above is used to specify an additional slave to the cluster. Enter a name for the server. For the URL you need to use the following pattern in order to connect to the slave: http(s)://ip-address:port/trueChartService

For ip-address, use the address of the service you want to add. port specifies the used port of the service, for example http(s)://192.168.0.1:8080/trueChartService.

For the username field, specify a user that has the “Management Console” permission. Enter the corresponding password. Click on “Test connection”. When the test is successful you can save the slave. Now the slave has been added to the cluster.

Modifying the clustered servers

There are several options to modify a server. These include editing, deleting and setting another server as the master server. (Note: you need to move your mouse over the line of the corresponding server to see the actions)

settings cluster edit
Figure 7. Editing a Cluster Server in the trueChart Management Console.

To edit a server click on the “edit” button of the server you want to modify. You can then change all the specified information you entered previously. Click on “Test Connection”. When the test is successful you can then save the new entered information.

edit cluster server
Figure 8. The Edit Cluster Server dialog.

To delete a server click on the “delete” button and confirm the dialog.

In order to set a new master server click on the “master” button and confirm the dialog. The master server is only used during an update process of trueChart. The selected server will then update the database. Please update the servers in the clustering promptly in order for the clustering to work.

Notes and restrictions on cluster services

Database Updates only for the master service

In case of later updates which will be installed, only during the update of the master service database changes will be made through the installation process. Update processes for slave services won’t change the trueChart database! Therefore in cluster environments the master service should be updated first and then all following slave services!

Transport not supported functionality for cluster services

The transport functions are not supported for Cluster Services, if the services will be addressed on a common URL, which is provided for example by a load balancer. This restriction is necessary because in the case of transportation is not clear which specific Web service must be addressed for communication. In this case it is necessary to configure a concrete cluster service with its own individual URL as a remote system for transportation.

5. Post-installation steps

After completing the installation, some final steps are necessary to use trueChart. First of all check the installation:

5.1. 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 9. 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.

5.2. 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 10. 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 11. 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 12. 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.

5.3. 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 13. 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 14. Editing an existing user in the trueChart Management Console.

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

5.4. Security Rule Definition for trueChart (partial) reload action

To enable the (partial) Reload for an app via trueChart button action “Reload” also for published apps, it is necessary that the following Security Rule in the sense QMC is defined. This is necessary in order for previously published apps after loading the data, the new state can be stored by the extension.

partial reload
Figure 15. Defining the security role for partial reloads.
Action

Read & Update

Resource filter

App* (we suggest to enter only apps you want to support with reload action)

Condition

(user.name like "*" and resource.resourcetype="App" and !resource.stream.Empty( or (resource.resourcetype="App.Object" and resource

Context

Only in hub

Due to the definition of the rule, it is possible to change also published for all users Apps in edit mode, since hereby an update-right is granted.
security rule edit

5.5. First Use of trueChart in the Sense Hub

If you now open after the installation in the Qlik Sense Hub an App and also a (new) Sheet. If you enables now the edit-mode, you’ll find in the properties bar on the left side now also the trueChart-Extension.

To create a first object, and drop the trueChart object onto your sheet:

first truechart
Figure 16. Drag-and-dropping the trueChart extension onto a new sheet in Qlik Sense

Thereby you are ready to use trueChart. At this point it is recommended to familiarize yourself with the use and the “Best-Practices” in handling trueChart. In normal practice this is done by an appropriate training where we explain the range of features of trueChart in detail to you on the spot and elaborate corresponding examples together.

6. Troubleshooting

If the installation, contrary to our expectations, however, did not take place smoothly, the following sections should provide assistance. If you are not able to find anything suitable here, too, please contact the support!

6.1. Domain and port settings

If you get the following error message, this means that you selected a port that is already used by a different program.

invalid port
Figure 17. Error message when entered port is already used.

For this matter please contact your IT-Support!

6.2. Database settings

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

no database connection
Figure 18. 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.

6.3. 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 19. 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

6.4. No connection to the trueChart service when using SSL

When using SSL, after integrating Sense’s self-generated certificate into the trueChart Service, you may get a “No network connection” error message.

no network connection
Figure 20. Qlik Sense 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 21. 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 Qlik Sense and trueChart installation.

7. Switch 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.

At the Database Page you will have to uncheck „create Tables“ and use the same Database you have used before. After the Installation you will have to upload the new trueChart4Sense.zip again (located at c:\temp). Since Qlik Sense doesn’t allow to overwrite Extensions, you will have to delete the trueChart Extension and upload the new zip file afterwards (there will be no definition/data loss).