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)
Oracle Java Platform, Java SE 17 (LTS) supported - newer Standard Edition ( 18 up to currently 21 are not supported )
The lowest Version of OpenJDK we support is 11.
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.
To be able to download extensions from the installed service using a MySQL database, the "max_allowed_packet" setting must be increased. We suggest a value of at least "100M" to also support large extension definitions.
On Windows, the config file is located at "C:\ProgramData\MySQL\MySQL Server x.x\my.ini"
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 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
TRUECHART4PowerBI is not supporting IE11 and "old" Edge (the version before chromium support) due to new real-time commenting.
Background: Due to the visibility restrictions for custom visuals in PowerBI it is technically not possible to create the necessary communication channel (WebSocket communication not possible)
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
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.
More information here: Download extensions for various platforms.
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.
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 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.
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 successfully.
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.
To be able to download extensions from the installed service using a MySQL database, the "max_allowed_packet" setting must be increased. We suggest a value of at least "100M" to also support large extension definitions.
On Windows, the config file is located at "C:\ProgramData\MySQL\MySQL Server x.x\my.ini"
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.
Please find here additional information for the Installation of TRUECHART within Qlik Sense.
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).
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
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.
- Please check if you have the correct Java version.
- Please check if the JAVA_HOME variable is set correctly.
Common mistakes:
C:\Program Files\Java\jdk1.8.0_172\bin - is incorrect. The path should not have the "\bin".
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.