Difference between revisions of "QPR UI Windows Installer"

From Mea Wiki
Jump to navigation Jump to search
(403353)
 
(116 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
Windows installer for QPR UI can be downloaded from the [[QPR_Product_Downloads|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.
 +
 
__TOC__
 
__TOC__
  
−
== Prerequisites ==
+
== Before Running Installation Wizard ==
−
There are four major dependencies for QPR MobileDashboard:
+
Before running the installation wizard, check the following:
−
* Java Runtime
+
 
−
* Glassfish server
+
=== Install Microsoft OLE DB Driver 18 for SQL Server===
−
* Microsoft 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.
−
* QPR Suite 2016.1 Web Services accessible in the network
+
 
−
<br>
+
=== Install .Net 3.5 from Windows Features ===
−
In addition, for installation Microsoft .NET Framework 4.5.1 or newer needs to be enabled on the target computer. The framework will be installed by the QPR MobileDashboard installation if it is not found on the target computer.<br>
+
* Go to '''Turn Windows Features on or off''' in the '''Windows Control Panel'''.
−
<br>
+
* 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'''.
−
Java Runtime (if it does not already exist) and Glassfish server will be installed by the QPR MobileDashboard installation, but a working instance of Microsoft SQL Server is needed either locally or accessible via the network in order for the installation to succeed. The following configuration is required for Microsoft SQL Server:
+
 
−
* If named instances are used, a TCP port needs to be assigned to the instance and the SQL Server Browser Service needs to be running
+
=== QPR Web Service Accessibility ===
−
* Mixed mode authentication or Windows authentication. Note that for Windows Authentication the user performing the installation also needs to have access to SQL Server even if some other account is used for the actual database connection.
+
Check that, QPR Suite Web Service is available by using the [http://kb.qpr.com/qpr2017-1/index.html?qpr_web_services_foundation_in.htm 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|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.
 +
# [[Payara Configuration in QPR UI#Changing Payara TCP Ports|Change the Payara port]] from Payara Administration Console.
 +
# Start the other application.
  
−
== System Requirements ==
+
=== JAVA_HOME and PATH environment variables ===
−
See [[QPR MobileDashboard System Requirements]].
+
Before a new installation, remove any existing reference(s) to older Java versions from PATH and any existing JAVA_HOME environment variable.
  
−
== Installation ==
+
== Running installation wizard ==
−
Follow the instructions below to install QPR MobileDashboard:<br>
+
To start QPR UI installation wizard, double click the '''QPR_UI.exe''' file and go through the steps described below.
−
<br>
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|colspan="2" style="font-size: 17px"|'''1. Welcome Page'''
 
|colspan="2" style="font-size: 17px"|'''1. Welcome Page'''
 
|-
 
|-
−
|This is the starting point of the QPR MobileDashboard installation wizard.<br><br>Click '''Next''' to continue.
+
|This is the starting point of the QPR UI installation wizard.
 +
 
 +
Click '''Next''' to continue.
 
|[[File:Pic_installation_welcome.png|400px]]
 
|[[File:Pic_installation_welcome.png|400px]]
 
|-
 
|-
 
|colspan="2" style="font-size: 17px"|'''2. License Agreement'''
 
|colspan="2" style="font-size: 17px"|'''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
+
|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.
 
|[[File:Pic_installation_licenseagreement.png|400px]]
 
|[[File:Pic_installation_licenseagreement.png|400px]]
 
|-
 
|-
 
|colspan="2" style="font-size: 17px"|'''3. Destination Folder'''
 
|colspan="2" style="font-size: 17px"|'''3. Destination Folder'''
 
|-
 
|-
−
|In this page you can see the folder where QPR MobileDashboard is going to be installed. If you want to install to a different folder, click on the '''Change''' button and define a new target folder there. Click '''Next''' to continue when the destination folder is correct.
+
|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.
 
|[[File:Pic_installation_destinationfolder.png|400px]]
 
|[[File:Pic_installation_destinationfolder.png|400px]]
 
|-
 
|-
−
|colspan="2" style="font-size: 17px"|'''4. Database Configuration'''
+
|colspan="2" style="font-size: 17px"|'''4. Database Server'''
 
|-
 
|-
−
|Here you select whether to create a new database for QPR MobileDashboard or to use an existing database. In most scenarios the "Set up a new database" option should be used. Using an existing database is useful mainly in server migration scenarios. Click '''Next''' to continue after selecting the desired option. The installation proceeds similarly with both options, but with an existing database the database initialization script is not run at a later stage during the installation.
+
|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'''.
−
|[[File:Pic_installation_databaseconfiguration.png|400px]]
+
 
 +
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.
 +
 
 +
|[[File:Pic_installation_dbconfig.png|400px]]
 
|-
 
|-
−
|colspan="2" style="font-size: 17px"|'''5. Database Server'''
+
|colspan="2" style="font-size: 17px"|'''5. Server Locations'''
 
|-
 
|-
−
|In this page you need to supply the information necessary to connect to the Microsoft SQL Server where you're going to install QPR MobileDashboard. The Database server drop-down contains compatible servers that were discovered locally, but if you are using a remote database server, you can input the host name and the possible instance name here.<br><br>You can use either Windows authentication or SQL Server authentication for connecting to the target SQL Server. Select the authentication mode, input the corresponding login ID and password to their respective fields, and click on '''Validate''' to verify that the account can be used for connecting to the defined database server and database. The '''Next''' button gets enabled only after a successful validation of credentials. Note that domain accounts should be supplied without and domain-specific prefix or suffix, i.e. the username alone. Also note that when using Windows Authentication, the account supplied here will be used for communication between Glassfish and QPR MobileDashboard, but also the user account running the installation needs to have proper access to the database to create the necessary tables there during the installation.<br><br>In the '''Name of database''' field you can define what the database for QPR MobileDashboard will be called in the target server. This should be the database to which the user has rights to. However, with extensive rights a database with the defined name will be created on the server if it doesn't exist.<br><br>Click '''Next''' to continue.
+
|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/'''.<br>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.
−
|[[File:Pic_installation_dbconfig.png|400px]]
+
 
 +
Also note that when using SSL, both QPR Suite should be set to ignore client certificates in their IIS configuration.  
 +
 
 +
Click '''Next''' to continue.
 +
|[[File:Pic_installation_serverlocations.png]]
 
|-
 
|-
−
|colspan="2" style="font-size: 17px"|'''6. Server Locations'''
+
|colspan="2" style="font-size: 17px"|'''6. Payara Configuration'''
 
|-
 
|-
−
|Here you can define where the QPR Suite and QPR ProcessAnalyzer Web Services can be accessed. If QPR Suite installations are found on the target computer, the web service endpoint of the newest version is suggested by default, but you should verify that this value points at the installation where your QPR MobileDashboard data should come from.<br><br>If you have QPR ProcessAnalyzer available, define its endpoint URL to the corresponding field. NOTE: If your QPR MobileDashboard installation is running in a clustered environment, set UseXForwardedForAsClientIp to true in the web.config of the QPR ProcessAnalyzer instance that is used.<br><br>Also note that when using SSL, both QPR Suite and QPR ProcessAnalyzer should be set to ignore client certificates in their IIS configuration.<br><br>Click '''Next''' to continue.
+
|Define the HTTP and HTTPS '''port numbers''' of the Payara application server used to host QPR UI.
−
|[[File:Pic_installation_serverlocations.png|400px]]
+
<br>
 +
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 [https://technet.microsoft.com/en-us/library/bb490947.aspx Netstat] command executed in an elevated Command Prompt: <pre>netstat -an | find ":port_number_here"</pre>
 +
 
 +
Click '''Next''' to continue.
 +
|[[File:Pic_installation_glassfish_ports.png|400px]]
 
|-
 
|-
 
|colspan="2" style="font-size: 17px"|'''7. QPR Suite System User'''
 
|colspan="2" style="font-size: 17px"|'''7. QPR Suite System User'''
 
|-
 
|-
−
|Here you need to define the user credentials of a QPR Suite Administrator user.<br><br>Click '''Next''' to continue
+
|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.
 
|[[File:Pic_installation_suite_credentials.png|400px]]
 
|[[File:Pic_installation_suite_credentials.png|400px]]
 
|-
 
|-
−
|colspan="2" style="font-size: 17px"|'''8. Single Sign-on Setup'''
+
|colspan="2" style="font-size: 17px"|'''8. Common QPR Authentication Setup'''
 
|-
 
|-
−
|If you want to use links from other QPR Suite web clients (i.e. QPR ProcessAnalyzer Web Client, QPR Portal) to access QPR MobileDashboard, define the URLs used for QPR Suite Single Sign-on Authentication, the single sign-on system between different QPR Suite product web clients (i.e. QPR ProcessAnalyzer Web Client, QPR Portal, and QPR MobileDashboard). When the QPR Suite Single Sign-on Authentication is in use linking from the other QPR web clients to QPR MobileDashboard can be done without the need of a separate login for the product that is the link target.<br><br>To add an URL, select the '''Service type''' (e.g. "QPR Portal") , define the '''Service URL''' (e.g. "http://<service_hostname>/QPR2016-1/Portal/QPR.Isapi.dll/"), and click Add.<br><br>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 define the definition(s) again.<br><br>Click '''Next''' to continue.
+
|If you have other QPR Suite products in use, with these settings you can configure [[Common QPR Authentication|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 <u>to</u> QPR UI. If you need to link <u>from</u> QPR UI to some other QPR Suite product, you need to do define the settings in the other product.
 +
 
 +
Click '''Next''' to continue.
 
|[[File:Pic_installation_sso.png|400px]]
 
|[[File:Pic_installation_sso.png|400px]]
 
|-
 
|-
 
|colspan="2" style="font-size: 17px"|'''9. Federated Authentication Configuration'''
 
|colspan="2" style="font-size: 17px"|'''9. Federated Authentication Configuration'''
 
|-
 
|-
−
|This page allows configuring Single Sign-On (SSO) login that enables logging in to QPR MobileDashboard using the existing credentials provided by your organization's federated identity provider. If there’s no applicable federated identity provider in your organization or you wish to configure it later, this page can be left blank. See the [[Installing_QPR_MobileDashboard#Configuring Federated Authentication (SSO)|Configuring Federated Authentication (SSO)]] section for more information and instructions on how the login scheme can be switched later.<br><br>
+
|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 in QPR UI|federated authentication]] page for more information how these settings are configured.
−
*For all SSO configuration scenarios, the '''SAML consumer URL''' should be defined, e.g. "http(s)://<your_QPR_MobileDashboard_servername>:8080/EnticeServices/rest/authenticate/saml"
+
 
−
<br>
 
−
There are two Federated Authentication Configuration scenarios available. Select an option that’s available in your organization:
 
−
# Using metadata:
 
−
#* Enter the metadata URL to the '''Federation metadata URL''' field, e.g. "https://<your_federated_identity_provider_servername>/<path>/<metadata_file_name>.xml"
 
−
#* If it’s known that the metadata contains multiple server entries, the '''Server entity identifier''' field must also be filled. The input is a server entity identifier URL, e.g. "http://<your_federated_identity_provider_servername>/services/trust"
 
−
# Using a public key:
 
−
#* Enter the redirect URL to the '''Federated authentication provider's redirect URL''' field, e.g. "https://<your_federated_identity_provider_servername>/saml/http-post/sso"
 
−
#* Fill in the '''Federated authentication provider's signing certificate''' field with <X.509 Certificate> contents. The input item is the actual encoded public key contents.
 
−
<br>
 
−
* '''User id attribute field''' can be left blank in most scenarios where the login names used in the organization are your local domain email addresses. In these scenarios, the NameID of the SAML subject is used as User ID. In other scenarios, please enter the name of the SAML attribute in the assertion. The related values will be used as user's login names.
 
−
* Select '''Automatic federated authentication''' check box if users must be automatically redirected to the identity provider's login page as they enter the QPR MobileDashboard login page.
 
−
<br>
 
 
Click '''Next''' to continue.
 
Click '''Next''' to continue.
 
|[[File:Pic_installation_federated_authentication.png|400px]]
 
|[[File:Pic_installation_federated_authentication.png|400px]]
Line 82: Line 118:
 
|colspan="2" style="font-size: 17px"|'''10. Ready to Install'''
 
|colspan="2" style="font-size: 17px"|'''10. Ready to Install'''
 
|-
 
|-
−
|The installer is now ready to start copying the application files to the computer. If you need to change any settings, click Back and make the necessary changes.<br><br>Once you are satisfied with the settings, click '''Install''' to start the installation
+
|The installer is now ready to start. If you need to change any settings, click '''Back''' and make the necessary changes.<br><br>Once you are satisfied with the settings, click '''Install''' to start the installation.
 
|[[File:Pic_installation_readytoinstall.png|400px]]
 
|[[File:Pic_installation_readytoinstall.png|400px]]
 
|-
 
|-
 
|colspan="2" style="font-size: 17px"|'''11. Complete'''
 
|colspan="2" style="font-size: 17px"|'''11. Complete'''
 
|-
 
|-
−
|The installation is now complete. Check the "Launch QPR MobileDashboard" checkbox to have your default browser opened to the QPR MobileDashboard login page.<br><br>If you choose not to launch the site straight away, you can access it later on at:  
+
|The installation is now complete.
−
http(s)://<your_server_dns_name>:8080/mobiledash.<br><br>Click '''Finish''' to close the installer.
+
 
 +
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.
 
|[[File:Pic_installation_completed.png|400px]]
 
|[[File:Pic_installation_completed.png|400px]]
 
|}
 
|}
  
−
== Upgrading ==
+
== Installation Troubleshooting ==
−
When upgrading to a new version of QPR MobileDashboard, a database upgrade may be needed. In those cases, a direct upgrade is prevented and you should uninstall the old version of QPR MobileDashboard. After that, install the new version, and select the "'''Use an existing database'''" option during installation. The database is then upgraded after the installation is finished and the QPR MobileDashboard service starts.
+
'''Q''': Windows service for QPR UI does not start.<br>
 +
'''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.
  
−
== Maintenance ==
+
'''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'''.<br>
−
If you need to repair QPR MobileDashboard installation for whatever reason, restart the "domain1 Glassfish Server" service after the repair before using the product.
+
'''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.)
  
−
== Intenet Information Services Configuration ==
+
'''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.<br>
−
To enable more meaningful and relevant error messages in QPR MobileDashboard user interface when data from QPR Suite web services is queried, the default IIS setting for error code 500 in the QPR Suite web services needs to be changed.<br>
+
'''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.
−
<br>
 
−
To change the error setting:
 
−
# On the server machine running QPR Suite web services, go to '''Control Panel''' -> '''Administrative Tools''' -> '''Internet Information Services (IIS) Manager'''.
 
−
# Select the '''Server name''' > '''Sites''' > '''Default Web Site''' > '''<Your QPR installation application (e.g. QPR2016-1)>''' section.
 
−
# Double-click '''Error Pages'''.
 
−
# Click '''Edit Feature Settings...'''
 
−
# Select '''Detailed errors''' and click OK:
 
−
:: [[File:Pic_iis_detailed_errors.png|400px]]
 
  
−
== Glassfish Configuration ==
+
'''Q''': The Validate button in the Database Server page does not validate my database credentials even though they are correct.<br>
−
By default Glassfish is using port 8080 for the front-end and port 4848 for the administration UI. If these ports cannot be used, they can be changed by accessing the administration UI at http://<servername>:4848. Expand Configurations -> server-config -> Network config -> Network listeners, select the listener to configure and change the Port value.<br>
+
'''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.<br>
−
<br>
 
−
It is also highly recommended to change the default administrator password for Glassfish at Domain -> Administrator Password.
 
−
 
 
−
=== SSL Configuration ===
 
−
In order to configure your installation to use SSL for encrypting the communication, follow the instructions below. Note that the instructions assume that your SSL certificate is in the .pfx format. For other formats some commands have to be altered accordingly.<br>
 
−
 
 
−
# Make sure your Java JRE bin folder is in the environment's PATH setting, so that keytool will be found.
 
−
# Launch two elevated command prompts, navigate one to <QPR MobileDashboard installation root>\Glassfish\bin and the other to <QPR MobileDashboard installation root>\Glassfish\glassfish\domains\domain1\config
 
−
# Make backup copies of keystore.jks, cacerts.jks, and domain.xml in <QPR MobileDashboard installation root>\Glassfish\glassfish\domains\domain1\config
 
−
# Open the Glassfish administration panel at http://<hostname>:4848. If you haven't done so, change the administrator password. Use a password longer than six characters here.
 
−
# In the Glassfish admin panel, go to server (Admin Server) -> Secure Administration -> Enable secure administration. Note that at this point the secure admin will still be using a self-signed certificate, which will cause warnings in browsers. As we know the reason for the warning, we can ignore it this time and proceed to the secure administration despite the certificate error.
 
−
# Stop the domain from the server (Admin Server) page or by running the following command line in the bin folder:
 
−
#: <pre>asadmin stop-domain</pre>
 
−
# With the command line in the bin folder, run:
 
−
#: <pre>asadmin change-master-password --savemasterpassword=true</pre> and define a new password to replace the default "changeit" password. NOTE: This should be a different password than the admininistrator password used for regular logins. This is basically a master key to the installation and also the certificate will be using this password in a later stage, so choose an appropriately strong password that is known only by those who have access to the SSL certificate password.
 
−
# Change to the command line in the config folder. Run:
 
−
#: <pre>keytool -importkeystore -srckeystore <your_pfx_file_name_and_path> -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype JKS</pre> You'll be asked for the destination keystore password, input the password defined in previous step here. Use the same password when you're asked to re-enter the new password. Source keystore password is your SSL certificate's password. Copy the alias to e.g. Notepad, you'll be needing this later.
 
−
# In the config folder, import the certificate also to the cacerts.jks keystore, i.e. run:
 
−
#: <pre>keytool -importkeystore -srckeystore <your_pfx_file_name_and_path> -srcstoretype pkcs12 -destkeystore cacerts.jks -deststoretype JKS</pre>
 
−
# In the config folder, run the following commands:
 
−
#:<pre>keytool -keypasswd  -alias <key alias from step 8></pre>
 
−
#:<pre>-keystore keystore.jks keytool -keypasswd  -alias <key alias from step 8>  -keystore cacerts.jks</pre>
 
−
#: You're asked for the keystore password, this is once again the password defined in step 7. When the key password is requested, enter the original SSL certificate password and then enter the password from step 7 as the new key password.
 
−
# Start the domain by running the following command line in the bin folder:
 
−
#: <pre>asadmin start-domain</pre>
 
−
# Access the Glassfish admin panel at  https://<servername>:4848
 
−
# Expand Configurations -> server-config -> Network Config -> Network Listeners -> http-listener-2
 
−
# Switch to the SSL tab and enable SSL3. Also change Certificate nickname to be the alias from step 8 and save the changes.
 
−
# You can now also disable http-listener-1 to prevent access without SSL, but that is safer to do after you have verified that the SSL config works.
 
−
# Stop the domain and open <QPR MobileDashboard installation root>\Glassfish\glassfish\domains\domain1\config\domain.xml into a text editor that's running as an administrator. Search and replace all references to s1as with the alias from step 8.
 
−
# Save the file and restart the domain. You should now be able to access the SSL instance at https://<servername>:8181/mobiledash/
 
−
 
 
−
== Configuring Federated Authentication (SSO) ==
 
−
QPR MobileDashboard supports Single sign-on login via federated identity providers (e.g. Shibboleth and Microsoft Active Directory Federation) that support the Security Assertion Markup Language (SAML) 2.0.<br>
 
−
<br>
 
−
The preferred way to enable Single sign-on is to define the following entries using the QPR MobileDashboard installer. The entries can also be added to the '''CONFIGURATIONENTITY''' table in the QPR MobileDashboard database after installing QPR MobileDashboard.<br>
 
−
{| class="wikitable"
 
−
! KEY_FIELD
 
−
! VALUE_FIELD
 
−
|-
 
−
|SAML_CONSUMER_URL
 
−
|"<Location of your QPR MobileDashboard installation>/EnticeServices/rest/authenticate/saml", e.g. "http://localhost:8080/EnticeServices/rest/authenticate/saml". This is the corresponding field for the "SAML consumer URL" in the Federated Authentication Configuration step of the installation.
 
−
|-
 
−
|SAML_METADATA_URL
 
−
|"<The metadata URL of the identity provider>", e.g. "https://your.federated.identity.provider.com/saml/metadata". This is the corresponding field for the "Federation metadata URL" in the Federated Authentication Configuration step of the installation.
 
−
|-
 
−
|SAML_SERVER_ENTITY_IDENTIFIER
 
−
|"<The server entity identifier URL>", e.g. "http://your.federated.identity.provider.com/services/trust". This entry is used if the metadata contains multiple server entries. This is the corresponding field for the "Server entity identifier" in the Federated Authentication Configuration step of the installation.
 
−
|-
 
−
|SAML_USER_ID_ATTRIBUTE
 
−
|The name of the SAML attribute in the assertion that will be used as the user's login name, e.g. "loginname". If the attribute is not given, the NameID of the SAML subject is used. If the user login name in your QPR Suite is the user's email address, the attribute definition is usually not needed. This is the corresponding field for the "User id attribute" in the Federated Authentication Configuration step of the installation.
 
−
|}
 
−
An alternative way is to is to define the following entries using the QPR MobileDashboard installer. The entries can also be added to the '''CONFIGURATIONENTITY''' table in the QPR MobileDashboard database after installing QPR MobileDashboard.<br>
 
−
{| class="wikitable"
 
−
! KEY_FIELD
 
−
! VALUE_FIELD
 
−
|-
 
−
|SAML_CONSUMER_URL
 
−
|"<Location of your QPR MobileDashboard installation>/EnticeServices/rest/authenticate/saml", e.g. "http://localhost:8080/EnticeServices/rest/authenticate/saml". This is the corresponding field for the "SAML consumer URL" in the Federated Authentication Configuration step of the installation.
 
−
|-
 
−
|SAML_REDIRECT_URL
 
−
|"<The redirect URL of the identity provider>", e.g. "https://your.federated.identity.provider.com/saml/http-post/sso". This is the corresponding field for the "Federated authentication provider's redirect URL" in the Federated Authentication Configuration step of the installation.
 
−
|-
 
−
|SAML_SIGNING_CERTIFICATE
 
−
|"<X.509 Certificate>". This is the corresponding field for the "Federated authentication provider's signing certificate" in the Federated Authentication Configuration step of the installation.
 
−
|-
 
−
|SAML_USER_ID_ATTRIBUTE
 
−
|The name of the SAML attribute in the assertion that will be used as the user's login name, e.g. "loginname". If the attribute is not given, the NameID of the SAML subject is used. If the user login name in your QPR Suite is the user's email address, the attribute definition is usually not needed. This is the corresponding field for the "User id attribute" in the Federated Authentication Configuration step of the installation.
 
−
|}
 
  
−
== Troubleshooting ==
+
'''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.<br>
−
'''Q''': My installation stops after Glassfish configuration, how could I get the installation to finish?<br>
+
'''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.
−
'''A''': The installation aborts if the Glassfish connection pool cannot be pinged after creating it. If the connection pool cannot be used, deploying the QPR MobileDashboard application there fails. Before attempting the installation again, please check the following things regarding SQL Server configuration:
 
−
* If named instances are used, a TCP port is assigned to the instance and the SQL Server Browser Service is running
 
−
* The user has sufficient rights to create tables to the target database.
 
  
−
In addition, if you have a separate Glassfish installation, shut it down for the duration of the QPR MobileDashboard installation so that the administration port 4848 is not reserved.
+
'''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.<br>
−
 
+
'''A''': Check the [[Payara_Configuration_in_QPR_UI#Opening_Payara_Log|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, [[Payara_Configuration_in_QPR_UI#Importing_SSL_Certificate_to_Payara|import the SSL certificate to Payara]].
−
'''Q''': The Validate button in the Database Server page does not validate my database credentials even though they are correct.<br>
+
[[Category: QPR UI]]
−
'''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 (QPRMobileDashboard.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 Glassfish if the database credentials are incorrect.<br>
 
−
<br>
 
−
'''Q''': I have QPR Suite and/or QPR ProcessAnalyzer running with SSL enabled and my QPR MobileDashboard installation is SSL-enabled too. Now QPR Suite and/or QPR ProcessAnalyzer is not available as a data source.<br>
 
−
'''A''': In the QPR Suite/QPR ProcessAnalyzer, check in the Microsoft IIS web server that the application (e.g. QPR2016-1 or QPRPA) is set to ignore client certificates in its SSL settings. In addition, if your QPR ProcessAnalyzer installation is older than QPR ProcessAnalyzer 2016.3, change the secureWebHttpBindingConfiguration binding in bindings_https.config to contain
 
−
<pre>
 
−
<security mode="Transport">
 
−
    <transport clientCredentialType="None"/>
 
−
</security>
 
−
</pre>
 
−
instead of
 
−
<pre>
 
−
<security mode="None" />
 
−
</pre>
 

Latest revision as of 11:36, 13 April 2021

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:

  1. Shutdown any other application using ports 4848, 8080 or 8181.
  2. Run QPR UI installation wizard as described in Running installation wizard.
  3. 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.
  4. Change the Payara port from Payara Administration Console.
  5. 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.

Pic installation welcome.png
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. Pic installation licenseagreement.png
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. Pic installation destinationfolder.png
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.

Pic installation dbconfig.png
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.

Pic installation serverlocations.png
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.

Pic installation glassfish ports.png
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.

Pic installation suite credentials.png
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:

  1. select the Service type (e.g. "QPR Portal")
  2. define the Service URL (e.g. http://<service_hostname>/QPR2019-1/Portal/QPR.Isapi.dll/)
  3. 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.

Pic installation sso.png
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.

Pic installation federated authentication.png
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. 		Pic installation readytoinstall.png
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.

Pic installation completed.png

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.

Retrieved from "https://wiki.onqpr.com/mea/index.php?title=QPR_UI_Windows_Installer&oldid=17898"