QPR UI Windows Installer

Windows installer for QPR UI can be downloaded from the downloads page. If there is an earlier version already installed in the computer, the QPR UI installer will make an upgrade to the old version. When an upgrade is done, the installer doesn't show any settings, and all the settings in the previous version are preserved. Note: upgrade installation is not available when upgrading between QPR UI 2019.4 and QPR UI 2019.5 (reason is that the Payara web server version has been updated) - you need to uninstall the previous version before installing new.

Usually upgrading QPR UI also requires changes to the QPR UI database (database upgrade). The changes are made automatically, when the new version of QPR UI first time starts (Payara is started) and detects an old database version. Note that when the database upgrade has been made, it's not possible to use the database with an older version of QPR UI any more. The database cannot be downgraded back an older version.

Before Running Installation Wizard

Before running the installation wizard, check the following:

Install Microsoft OLE DB Driver 18 for SQL Server

Microsoft OLE DB Driver 18 for SQL Server can be downloaded from https://www.microsoft.com/en-us/download/details.aspx?id=56730.

Install .Net 3.5 from Windows Features

Go to Turn Windows Features on or off in the Windows Control Panel.
Check that .Net Framework 3.5 (includes .Net 2.0 and 3.0) > Windows Communication Foundation HTTP Activation and .Net Framework 3.5 (includes .Net 2.0 and 3.0) > Windows Communication Foundation Non-HTTP Activation are installed. If they are not, check them, and click OK.

QPR Web Service Accessibility

Check that, QPR Suite Web Service is available by using the QPR Web Services Servicetester.

Server TCP Ports

Make sure that there are no other (server) applications listening on ports 4848, 8080 and 8181 during the installation, as this will cause the installation to fail. Note that even though the QPR UI installation wizard allows changing the ports 8080 (http) and 8181 (https) to other ones, all of the ports 4848, 8080 and 8181 still need to be free during the installation. The http and https ports can also be changed after the installation under the network-listeners section in the <Path to QPR UI Installation>\Glassfish\glassfish\domains\domain1\config\domain.xml file, e.g. C:\Program Files\QPR Software Plc\QPR UI\Glassfish\glassfish\domains\domain1\config\domain.xml. The QPR UI service needs to be (re)started after changing the port configuration. It's possible also to change the port 4848, but only after the installation in the Payara Admin Console.

Overall, if there are any other applications using one of the three aforementioned ports, the installation should proceed as follows:

Shutdown any other application using ports 4848, 8080 or 8181.
Run QPR UI installation wizard as described in Running installation wizard.
Change the ports 8080 and 8181 to other ones in the QPR UI installation wizard or alternatively in the domain.xml file as described above.
Change the Payara port from Payara Administration Console.
Start the other application.

JAVA_HOME and PATH environment variables

Before a new installation, remove any existing reference(s) to older Java versions from PATH and any existing JAVA_HOME environment variable.

Running installation wizard

To start QPR UI installation wizard, double click the QPR_UI.exe file and go through the steps described below.

1. Welcome Page
This is the starting point of the QPR UI installation wizard. Click Next to continue.
2. License Agreement
Here you can see the End User Software License terms for the software that is about to be installed. You will need to accept these terms before continuing the installation. Select I accept the terms in the license agreement and click Next to continue in the case you accept the license terms. Otherwise you'll need to cancel the installation.
3. Destination Folder
In this page you can see the folder where QPR UI is will be installed. If you want to install to a different folder, click on the Change button and define a new target folder.
4. Database Server
In this page you need to supply information to connect to Microsoft SQL Server where the QPR UI database is located. The Database server drop-down list contains found SQL Servers. If the desired SQL Server is not found, input the SQL Server hostname (DNS name) and the possible instance name in the form HOSTNAME\INSTANCENAME. For named instances, the TCP port is not defined, because it is queried from the SQL Server Browser. If you are using a default instance with other than the default port number 1433, define the port in the following form: HOSTNAME:PORTNUMBER. For connecting to the SQL Server, you can use either: Windows authentication (Windows domain account defined below) or SQL Server authentication (SQL Server login defined below) After inputting Login ID (username) and password, click on Validate to verify that the account can be used for connecting to the defined database server. The Next button is enabled only after a successful validation of credentials. The validation only checks that the account can be used to login to the SQL Server - it doesn't check that the account has enough rights to operate the database. Note for Windows authentication: The account supplied here will be used for database connection when QPR UI is running in the Payara. Also the user account running this installation wizard needs to have access to the database to create the necessary tables there during the installation. Name of database field defines QPR UI database name (that must already exist). If the database contains information from a previous version, the database is converted to the current version automatically when the Payara server starts up.
5. Server Locations
Define where the QPR Suite Web Services can be accessed. For QPR Suite Web Service, the endpoint is given in the format: http://<your host>/<your IIS application>/Portal/QPR.Isapi.dll/wsforward/MainService.svc/webHttp/. The suggested url for QPR Suite Web Services points to QPR 2019.1 instance in the same server computer. localhost can be used if QPR Suite and QPR UI are on the same server computer. Also note that when using SSL, both QPR Suite should be set to ignore client certificates in their IIS configuration. Click Next to continue.
6. Payara Configuration
Define the HTTP and HTTPS port numbers of the Payara application server used to host QPR UI. Make sure that the ports are not in use by other applications. To see see if a port is in use, you can use for example the following Netstat command executed in an elevated Command Prompt: netstat -an \| find ":port_number_here" Click Next to continue.
7. QPR Suite System User
Here you need to define the user credentials of an administrator user that's found in QPR Suite. The user account defined here is used to synchronize user information from QPR Suite to QPR UI. Click Next to continue.
8. Common QPR Authentication Setup
If you have other QPR Suite products in use, with these settings you can configure Common QPR Authentication to work between the products. To add a URL: select the Service type (e.g. "QPR Portal") define the Service URL (e.g. http://<service_hostname>/QPR2019-1/Portal/QPR.Isapi.dll/) click Add If you need to change an existing definition, you can either remove the latest definition by clicking Remove last or remove all the definitions by clicking Clear, and then start adding again. Note that with the settings defined here, you can define the Common QPR Authentication to work when linking to QPR UI. If you need to link from QPR UI to some other QPR Suite product, you need to do define the settings in the other product. Click Next to continue.
9. Federated Authentication Configuration
This page allows configuring login to QPR UI using federated authentication, i.e. external identity provide (IdP). If there is no federated identity provider in your organization or you wish to configure it later, this page can be left blank. See the federated authentication page for more information how these settings are configured. Click Next to continue.
10. Ready to Install
The installer is now ready to start. If you need to change any settings, click Back and make the necessary changes. Once you are satisfied with the settings, click Install to start the installation.
11. Complete
The installation is now complete. Check the Launch QPR UI checkbox to open the QPR UI login page. If you choose not to launch the login page straight away, you can access it later on at: http(s)://<your_server_dns_name>:8080/ui. Click Finish to close the installer.

Installation Troubleshooting

Q: Windows service for QPR UI does not start.
A: If this happened just after installing or updating QPR UI, restarting the server machine helps. In that case, the issue appears in a way that in the Windows Task Manager the java.exe process doesn't start at all.

Q: Opening QPR UI login page gives an Internal Server Error message, and the following error message appears in Payara log: org.glassfish.deployment.common.DeploymentException: Error in linking security policy for EnticeServices -- Inconsistent Module State.
A: Solution is to delete Payara cache as follows: Stop the QPR UI Windows Service, delete contents of folder C:\Program Files\QPR Software Plc\QPR UI\Glassfish\glassfish\domains\domain1\generated\ (but not the generated folder itself), and start QPR UI Windows Service again. (Technical description for the error is that the EnticeServices application deployment failed in Payara due to outdated information in cache.)

Q: Error message java.lang.OutOfMemoryError: Java heap space or java.lang.OutOfMemoryError: GC overhead limit exceeded appears as a popup message in QPR UI or the error message appears in QPR UI Payara server log.
A: There is not enough memory allocated to Java virtual machine to run Payara server (heap memory in this case). Memory limits can be set in file C:\Program Files\QPR Software Plc\QPR UI\Glassfish\glassfish\domains\domain1\config\domain.xml. Find section domain > configs > config (the one where name="server-config) > java-config > jvm-options. There are several jvm-options nodes - find a one starting with -Xmx. See here how to change the maximum heap memory: https://stackoverflow.com/questions/14763079/what-are-the-xms-and-xmx-parameters-when-starting-jvms. Note also that there needs to be enough physical memory in the server computer.

Q: The Validate button in the Database Server page does not validate my database credentials even though they are correct.
A: Even though the validation should work in the majority of scenarios, you can supply a SKIPDBVALIDATION=1 parameter to the installation from the command line (QPRUI.exe /v"SKIPDBVALIDATION=1"). However, when skipping the validation you need to pay some extra attention to the correctness of the credentials as all parts of the software cannot be deployed to Payara if the database credentials are incorrect.

Q: I have QPR Suite running with SSL enabled and my QPR UI installation is SSL-enabled too. Now QPR Suite is not available as a data source.
A: In the QPR Suite, check in the Microsoft IIS web server that the application (e.g. QPR2019-1) is set to ignore client certificates in its SSL settings.

Q: I have QPR Suite running with SSL enabled and I can access them both using a web browser, but when trying to log in to QPR UI I get "Verify that server locations configurations are correct, the target machines are reachable, and QPR services are running" error.
A: Check the Payara log for error about "Already connected". If such an error is found, it's highly likely that Payara doesn't accept the SSL certificate in use by QPR Suite. In this case, import the SSL certificate to Payara.