Tags:
create new tag
view all tags

APPX HTML Client

This page gives installation instructions and an overview of the Appx HTML client.


Overview

The Appx HTML client is designed to allow you to connect to an Appx server and run Appx applications using a browser, either on the desktop, a tablet or a smartphone. When running the client in a browser, no software is required on the desktop, tablet or smart phone. When the user logs on, the necessary code is downloaded to their device as required.

In this release, you can only run the applications, you cannot design them. Specifically, the ILF editor, old ILF Debugger and Image Editor are not supported. You may be able to work in Application Design so long as you avoid those.

The client will support SSL connections if your web server is configured appropriately. If not, the client will use its own built in AES encryption but be aware that this is not sufficient to protect sensitive data.

The Appx HTML client consists of two modules:

  • Web Server Files (webhost.zip). These are the javascript libraries and style sheets that make up the HTML client. This also contains the optional Local Connector for Windows, Mac and Linux clients. These must be installed in your web server's document directory.
  • APPX Server connector (serverConnector.zip). This is a javascript library that connects the client running in your browser to the actual Appx engine.
Note that Appx does not have to be running on the same server as your web server, and the APPX Server Connector does not have be on the same server as either Appx or your web server. This gives you maximum flexibility in configuring your installation.

Once the HTML client is working, you can connect to any Appx 5.4+ server, just as you can with the Appx Desktop Client. Due to the engine changes that were made in 5.4 to support the HTML client, you cannot connect to an earlier Appx engine.

We have tested the HTML client on current versions of IE, Chrome, Firefox and Safari.

Note that due to an incompatibility between Open SuSE 42.3 and the node package, the HTML client will NOT run on that platform. Use a different Linux version (Red Hat/Centos recommended) or Windows. If changing the Linux version is not an option, consider installing an alternate O/S in a VM on the SuSE server using a product like Virtual Box (https://www.virtualbox.org).

Prerequisites

In addition to a 64 bit Operating System (Windows or Linux), the server that will run the APPX Server Connector requires some additional software:

See below for details on installing these packages.

Local Connector vs Web Browser

There are 2 ways the HTML client can interact with processes on the APPX Server (uploading/downloading/displaying files, invoking programs on the client).

Local Connector

The Local Connector is a small 'helper' program that allows you to upload/download and open files on the users desktop, similar to the way it can be done with the APPX Desktop Client. By default, the HTML client will check to see if the local connector program is running when the user logs in. If it is not running, it will offer to install it, and if the user cancels they will be nagged the next time they log in. If your application does not require the ability to upload/download/open files on the users device or invoke programs on the user's device you can turn this off (see Installation below).

The Local Connector is a 64 bit application that only runs on 64 bit Windows, OS/X or Linux based desktops or tablets.

There is a 'Connectivity' indicator in the lower right corner of the browser window with the words 'Remote' and 'Local'. If 'Local' is in green with a "+", it means the local connector is installed & running. Red means the connector is not installed. You can click the 'Local' sign to manually download and install the connector. If the 'Local' icon is blue, it means the requirement for a local connector has been turned off via metas["appx-local-required"]["value"] = "false"; in the your 'appx-client-settings.js' file (see below).

Web Browser

The other option is to use the Web Browser's built in ability to handle files. With this option, the APPX Server Connector stores the file in the Mongo database, then passes a URL to the Web Browser. The Web Browser will either display the file in a new tab if it knows how display that file type, or offer to save the file if it does not know how to display it. This is a better choice if you are planning to deploy your applications on non Windows tablets or smartphones.

The file only remains in the Mongo Database for 5 seconds after it is retrieved, so if the user refreshes that tab they will get error 404.

When uploading files, the web browser uploads the file into the Mongo database and returns a file path to your APPX process. You can use this path with .CLIENT UPLOAD FILE to transfer the file out of Mongo to the final destination. Note that using this method means you will not get the original path and file name as it existed on the user's computer. If you need this information, then you will have to use the Local Connector method. Files will stay in the Mongo database until the session ends, then they will be removed.

The Web Browser option does NOT allow you to invoke programs on the user's device (see .CLIENT LOAD URL). If you need this capability, you will have to use the Local Connector option.

NOTE: This option only works if you are connecting to an APPX server running Release 5.4.5 or higher.

Differences between ADC and HTML Clients

The HTML client has a different presentation for most non-Appx elements such as Date Choosers, File Upload/download dialog boxes, Tables, etc. The goal of the HTML client was to replicate the presentation of your screens as accurately as possible as far as the Appx elements are concerned (i.e., the widgets and fields you use in the Image Editor). Since we use different 3rd party tools and runtimes for other elements, they will look slightly different compared to the Appx Desktop Client.

Requirements

You will need a web server, either Linux or Windows based (64 bit). If you are going to use the Apache web server and you want to use a forwarding proxy, it must be version 2.4 or higher. We have tested IIS on Win 7 with success, earlier versions of IIS have not been tested.

The web server does not have to be on the same server as Appx.

If you configure the appxConnector and appxMongoConnector to use SSL, then you will need an SSL certificate either from your organization's certificate authority or from a commercial or public certificate authority. The certificate components (cert and key) must be in Apache format. Apache formatted certificates are PEM files, usually seen with the extensions .crt, .pem, .cer, and .key (for private keys). In contrast, Windows IIS server certificates are usually in formatted as either PKCS#7 or PKCS#12. PKCS#7 (also known as P7B) usually has an extention of .p7b or .p7c. PKCS#12 (also known as PKCS12 or PFX) usually has an extension .pfx or .p12. If you have certificates in PKCS#7 or PKCS#12 format, you'll need to either convert them to PEM format, or you'll need to request PEM (Apache) formatted certificates from your certificate authority. Here's a document with instructions if you need to convert the your certificate to a PEM formatted .crt, .pem, .cer, and .key (for private keys).

If you are going to run the APPX Server Connector on a Windows server, make sure all patches have been applied. In particular, https://support.microsoft.com/en-us/kb/2731284 will break tables if it is not applied

Installation - Web Server Component

1) Extract the Web Server File (webhost.zip) into the document folder for your web server. Depending on your web site layout, you may want to put this in its own folder within the web server documents, i.e., /var/www/html/appx.

2) If this is a new installation, you must rename the appx-client-settingsTemplate.js file to appx-client-settings.js. This file is in the 'js' subdirectory. For example: 

[root@localhost]# cd js
[root@localhost js]# mv appx-client-settingsTemplate.js appx-client-settings.js

This file is where you will configure your site specific settings, similar to 'appx.env' in an APPX server installation.

3) If this is a new installation you must set the name of the host running the Appx Server Connector in the 'appx-client-settings.js' file you just renamed:

metas["appx-proxy-host"]["value"] = "localhost";

Change locahost to the name or IP address of the server running the Appx Server Connector. Do not use localhost unless you plan to run the HTML client on the same server as the Appx Server Connector, i.e., a testing/evaluation environment.

You can also set any other meta tags that are unique to your installation. The 'appx-client-settings.js' file will never be replaced during an update, so the settings will remain until you change them. For example, you can set the name and login port of the APPX server, the default rows & columns, whether to use the Local Connector or not, etc. Consult the 'appx-client-settings.js' file for the full list of meta tags that can be set.

Installation - APPX Server Connector Component

The APPX Server Connector is the software that connects the HTML clients and the APPX server. This can be installed on the same server as the web server, or the APPX Server, or a completely different machine. If you are not using tunnneling via the web server, then ports 3014/3015 (the default port) needs to be open between the server connector machine and your HTML clients.

Prerequisites

The server that will run the APPX Server Connector requires some additional software:

  • The Mongo Database (https://www.mongodb.org/). Instructions for downloading and configuring the database can be found at https://docs.mongodb.org/manual/tutorial/
  • If the server is running Windows, you also need to install .NET Framework 3.5. Quick install instructions:

    Press the Windows key on your keyboard, type Windows Features, and press Enter. This brings up the Turn Windows features on or off dialog box. ...
    Select the .NET Framework 3.5 (includes .NET 2.0 and 3.0) check box, press OK, and reboot your computer if prompted.

Installation

1) The NPM modules installed via the "npm install" command are third party dependencies of the APPX HTML client. These modules are authored and supported by someone other than APPX Software, Inc. If you encounter security or warning messages when installing third party modules, the notice will usually tell you to run "npm audit" for details. The audit report will typically provide you with CVE numbers or project advisory URLs that you'll need to research. After considering your unique situation along with the information contained in the security notice you'll be better equipped to decide whether or not the risk applies to your situation and to make a final determination of what your direction will be.

2) If you are upgrading from a prior release, you must uninstall the old Server Connector first by running 'appxConnector-uninstall.js'. You must do this before installing the new connector. This should be run as 'root' on Linux/Unix systems, and as an Administrator on Windows systems. To run the script, open a terminal or DOS window and navigate to the folder where you installed the Appx Server Connector, then invoke the script via 'node'.. 

[root@localhost appxConnector]# node appxConnector-uninstall.js 
Using default mode: systemd
Uninstall complete.
The service exists: false
[root@localhost appxConnector]#

3) Extract the Appx Server Connector to a location of your choice. A folder in the /opt directory would be a good choice on a Linux server.

4) Configuration will occur via modification to three files ( four I guess, but mostly three ). The three files are appx-client-settings.js (found in webhost.zip bundle), appxConnector.js, and appxMongoConnector.js (both found in serverConnector.zip bundle). A forth one is index.html/client.html if you modify those - I don't recommend it. And now that I think about it, you could go crazy and include a fifth --> the css file(s).

Encryption configuration occurs in all three of those .js files. There is coordination required among the parameters, flipping one parameter requires modification of another parameter at times.

Here are a few of the parameters from those three files that users may sometimes encounter a configuration error.

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "aes"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • metas["appx-proxy-path"]["value"] = "/appxws/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "3014"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "3015"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - - the default port number of the appxmongoconnector service**/
  • appxConnector.js

    • const sslEnabled = true; // Are we using SSL for our connections?

    • const cryptoEnabled = false; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = true; // Are we using SSL for our connections?

Updated installation command line parameters for nodeJS version > 16 (as of 10-30-2023)

Beginning with version 6.2.0.24041811 (published on 4-18-2024), the Appx Server Connector configuration has been simplified and is now done with two files instead of three.

Installing the Appx Connector on nodeJS version > 16 has changed. For those versions, the installer script should be run, as a minimum, as follows: node --dns-result-order=ipv4first appxConnector-install.js. And any other needed command line parameters should be appended to that minium command line.

Updated configuration file (as of 4-18-2024)

Beginning with version 6.2.0.24041811 (published on 4-18-2024), the Appx Server Connector configuration has been simplified and is now done with two files instead of three.

Instead of modifying the files ‘appxConnector.js’ and ‘appxMongoConnector.js’ a single file is used for both and by default that file is named ‘default.json’.

The file has two sections, one for each connector. The Appx Connector section is named 'appxConnectorConfig' and the Mongo Connector section is named 'mongoConnectorConfig'. Each section has a key/value pair where the key name is the same as the variable name that exist in the appxConnector.js and appxMongoConnector.js files as shown above and in the examples below.

The default configuration file ‘default.json’ can be modified and used to configure the connectors as is but, the preferred method (since that file will be overwritten during a AppxConnector upgrade) is to use the ‘default.json’ as template in creating a file named ‘appxconnector.json’.

If for some reason the configuration file needs to be named something other than ‘appxconnector.json’ or ‘default.json’, an environmental variable named NODE_CONFIG_ENV can be used to specify a different configuration file name. For example, setting NODE_CONFIG_ENV=MyConfig will cause each connector to look for a file named ‘MyConfig.json’ on startup to configure that connector.

Here are a few common scenarios and their values.

I want no reverse proxy, no encryption at all. ( Just a very simple configuration )

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "none"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • // metas["appx-proxy-path"]["value"] = "/appxws/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "3014"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "3015"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - the default port number of the appxmongoconnector service **/
  • appxConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

    • const cryptoEnabled = false; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

I want no reverse proxy, AES encryption ( Don't want hassle of reverse proxy configuration. I want encryption, but don't want the hassle of SSL certificates )

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "aes"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • // metas["appx-proxy-path"]["value"] = "/appxws/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "3014"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "3015"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - the default port number of the appxmongoconnector service **/
  • appxConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

    • const cryptoEnabled = true; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

I want no reverse proxy, SSL encryption ( Don't want hassle of reverse proxy configuration, but want the best encryption )

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "ssl"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • // metas["appx-proxy-path"]["value"] = "/appxws/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "3014"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "3015"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - the default port number of the appxmongoconnector service **/
  • appxConnector.js

    • const sslEnabled = true; // Are we using SSL for our connections?

    • const cryptoEnabled = false; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = true; // Are we using SSL for our connections?

I want a reverse proxy, no encryption al all. ( I want a Reverse Proxy because a reverse proxy often allows for a simpler firewall ruleset. Unfortunately, a reverse proxy requires configuration in your web server - Apache, Nginx, IIS. Keepin it simple regarding encryption. )

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "none"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • metas["appx-proxy-path"]["value"] = "/appxws/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "80"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "80"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - the default port number of the appxmongoconnector service **/
  • appxConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

    • const cryptoEnabled = false; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

I want reverse proxy, AES encryption( I want a Reverse Proxy because a reverse proxy often allows for a simpler firewall ruleset. Unfortunately, a reverse proxy requires configuration in your web server - Apache, Nginx, IIS. I want encryption, but don't want SSL certificate hassle )

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "aes"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • metas["appx-proxy-path"]["value"] = "/appxws/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "80"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "80"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - the default port number of the appxmongoconnector service **/
  • appxConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

    • const cryptoEnabled = true; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = false; // Are we using SSL for our connections?

I want reverse proxy, SSL encryption ( I want a Reverse Proxy because a reverse proxy often allows for a simpler firewall ruleset. Unfortunately, a reverse proxy requires configuration in your web server - Apache, Nginx, IIS. I also want the best encryption possible )

  • appx-client-settings.js
    • metas["appx-encryption"]["value"] = "ssl"; //** Encryption type to use, valid values are "aes", "ssl", or "none". SSL is most secure, none is least secure.
    • metas["appx-proxy-path"]["value"] = "/appxwss/"; //** If you have configured a reverse proxy, enter the value that triggers the reverse proxy. Typical values are /appxws/ for Non SSL proxies, and /appxwss/ for SSL**/
    • metas["appx-proxy-port"]["value"] = "443"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3014 - the default port number of the appxconnector service **/
    • metas["appx-mongo-port"]["value"] = "443"; //** The port number that the proxy is accessible to the user on, typically 80 in non-SSL configuration or 443 for SSL configurations. If you are not reverse proxying then leave it at 3015 - the default port number of the appxmongoconnector service **/
  • appxConnector.js

    • const sslEnabled = true; // Are we using SSL for our connections?

    • const cryptoEnabled = false; // Are we using Crypto to encrypt traffic? Must be off if SSL is on

    • const useoldsocket = true; // If set to true, the non SSL capable APPX engine socket and logic are used

    • const appxLocalConnectorCert = null; // If local connector needs certificate authority point to it here

  • appxMongoConnector.js

    • const sslEnabled = true; // Are we using SSL for our connections?

Parameters I didn't really dive into, but are worth mentioning. appxLocalConnectorCert is used if you have your own organizational certificate authority. useoldsocket is used if you enabled mandatory SSL logins with your appxLoginMgr and your appxLoginMgr is <5.5.0. If you are in a 5.5.0 environment, useoldsocket should probably be set to false.

5) Run the appxConnector-install.js script. This should also be run as 'root' on Linux/Unix systems, or as an Administrator on Windows systems. This will check your system for the required modules. To run the script, open a terminal or DOS window and navigate to the folder where you installed the Appx Server Connector, then invoke the installation scripts via 'node': 

[root@localhost ~]# cd /opt/appxConnector
[root@localhost ~]# npm install
<serveral node packages will be downloaded and installed> 

[root@localhost appxConnector545]# node appxConnector-install.js
Checking for required modules...
 No arguments received, using default settings for install
 Module: crypto - Installed.
 Module: fs - Installed.
 Module: hexy - Installed.
 Module: http - Installed.
 Module: https - Installed.
 Module: mime - Installed.
 Module: mongodb - Installed.
 Module: net - Installed.
 Module: node-cryptojs-aes - Installed.
 Module: string - Installed.
 Module: string_decoder - Installed.
 Module: url - Installed.
 Module: ws - Installed.
 
 Using default mode: systemd
 Installing service on /etc/systemd/system/appxconnector.service
 Running systemctl daemon-reload...
 Installing appxConnector3014 service...
 Done... Waiting on service to start...
 Running systemctl start appxconnector...
 Service appxConnector3014 started
 Using default mode: systemd
 Installing service on /etc/systemd/system/appxmongoconnector.service
 Running systemctl daemon-reload...
 Installing appxMongoConnector3015 service...
 Done... Waiting on service to start...
 Running systemctl start appxmongoconnector...
 Service appxMongoConnector3015 started

6) Confirm the service is running. In Linux/Unix you can use 'ps -ef|grep appx', and in Windows you can use the 'Services' control panel.

Assuming the web server to which we installed the client is 192.168.0.15, and that we installed everything into an 'appx' folder on the web server, then we should be able to get a client login dialog box via:

http://192.168.0.15/appx/client.html

You must open ports 3014/3015 on the server running the APPX Server Connector for this connection to work. If you do not want to open any new ports on your firewall, see the section on 'Tunneling/Forwarding'.

Post Installation if upgrading an existing HTML client installation

If you are upgrading an existing HTML client installation, then you should check the following:

  • If you have customized 'client.html' you will have to re-do your customizations as it will be replaced when the new files are installed.
  • If you have created your own login page based on the standard 'client.html', compare your page and the standard 'client.html' for any changes that might be required.

Installing Multiple Server Connectors

You can install multple server connectors, each listening on different ports.

There are various reasons why you would want to do this:

  • You have development, model and production installations of APPX all on the same server. In this case, you would install a matching server connector in 3 different folders and configure each one to use a different set of ports. When a new release is available, you could install it in the test folder without affecting the model or production versions.
  • Load balancing. You could install multiple connectors as above and configure multiple ports and have different users connect on different ports by setting up different 'appx-client-settings.js' files on the web server. In this case, you would install the web server component multiple times into different folders then customize the 'appx-client-settings.js' file in each folder. For example, all users in a certain department use a settings file that uses ports 3014/3015, another department might use use a settings file that uses 3020/3021, etc. Each department would have it's own login page on the web server.
By default the installer will install a server connector on port 3014 and a mongo connector on port 3015. The installer accepts the following arguments:

node appxConnector-install [appx | mongo] [appxport] [mongoport]

Examples: 

node appxConnector-install appx 3020

Installs a server connector listening on port 3020 

node appxConnector-install mongo 3021

Installs a mongo connector listening on port 3021 

node appxConnector-install 3020 3030

Installs a server connector on 3020 and a mongo connector on 3030.

You can then create different folders to contain the client.html pages using the different ports via setting "appx-proxy-port" and "appx-mongo-port" in each appx-client-settings.js file in each folder. If you are using port forwarding, then you'll have to create unique names and use those names instead (they all would use port 80).

Local Connector or Web Browser Configuration

As mentioned above, you have a choice on how the HTML client should handle files sent to/from the browser.

By default, the HTML client will try to use the local connector. You can suppress the requirement for the Local Connector by uncommenting the following line in your appx-client-settings.js file:

//metas["appx-local-required"]["value"] = "false";

Remove the leading // to uncomment the line.

If you do not turn off the Local Connector requirement as above, then when the 'client.html' page is loaded it will check to see if the local connector is running on the users desktop. If not, they will get a dialog box offering to download the local connector. The actual installation of the local connector varies by the O/S on the user's desktop:

  • Windows: Once the download is complete, run the installer. The local connector will be installed, started and Windows will be configured to automatically start on a reboot. No further action is required.
  • Mac O/S: Once the download is complete, open the disk image and double click the installer. The local connector will be installed and started. The local connector will have to manually started after each login by opening a terminal window and entering the command "cd AppxLocalConnector;open node-webkit.app". Alternatively, the user can add 'node-webkit.app' in their AppxLocalConnector folder to their Login Items in System Preferences.
  • Linux: Once the download is complete, open a terminal window and enter:
    • cd Downloads (or wherever the file was saved to)
    • sh LocalConnector _linux32.sh or sh LocalConnector _linux64.sh, depending on whether you have 32 or 64 bit Linux. The connector will be installed.
    • Start the connector running by:
      • cd $HOME/AppxLocalConnector
      • sh ./start-nw.sh
    • The user has to manually start the local connector every time they log in, or they can add the script to their programs that start automatically when they log in. The steps vary by Linux distribution, consult your documentation.
If you are going to use the Web Browser to handle files instead of the local connector, then turn off the requirement for a Local Connector as above, and uncomment the following line in your appx-client-settings.js file:

//metas["appx-upload-without-local"]["value"] = "true";

Remove the leading // to uncomment the line. The '+Local' connector icon will be blue in this case.

The Application Designer can also control this. Each file chooser widget can be individually set to not use the local connector by using the macro: @FULC=F, however setting "appx-upload-without-local" = true will override this, even if the macro specifies the local connector should be used (@FULC=T).

Tunneling/Reverse Proxy

If you do not want to open ports 3014/3015 and would rather use port 80, you can use forwarding instead. Doing so also requires modification of four parameters in the appx-client.settings.js file — appx-proxy-port, appx-mongo-port, appx-proxy-path, and appx-encryption. Reverse proxy configuration is web server specific, but here are some points to get you started. For example, to configure Apache 2.4 on Linux you would do the following:

  • In /etc/httpd/conf.modules.d/00-proxy.conf, add (if not already loaded):

    LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so

  • Create the /etc/httpd/conf.d/appx.conf file with the following lines (or just add these to httpd.conf):

  • <VirtualHost *:80>
    ServerName <enter your server name>
    ServerAdmin <enter the webmaster email>

    DocumentRoot /var/www/html

    <Directory "/var/www/html">
    Options FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
    Require all granted
    </Directory>

    ProxyPass "/appxwss" "wss://localhost:3014"
    ProxyPassReverse "/appxwss" "wss://localhost:3014"
    ProxyPass "/appxws" "ws://localhost:3014"
    ProxyPassReverse "/appxws" "ws://localhost:3014"

    ProxyPass "/appxhttps" "https://localhost:3015"
    ProxyPassReverse "/appxhttps" "https://localhost:3015"
    ProxyPass "/appxhttp" "http://localhost:3015"
    ProxyPassReverse "/appxhttp" "http://localhost:3015"
    </VirtualHost>

  • Change the following in your appx-client-settings.js file:

    appx-proxy-host = hostname of httpd server (i.e., 192.168.1.11)
    appx-proxy-port = “80"
    appx-mongo-port = “80"
    appx-proxy-path = /appxws/

  • Restart your web server

NOTE: If you are running selinux security on your server, you will have to configure it so that apache can initiate an outgoing network connections to the web socket server port. Use the following command:

# setsebool -P httpd_can_network_connect 1

For Windows IIS server. You’ll need to install the Microsoft Request Routing tool. You’ll also need a web.config file with the following contents. Save the web.config file into your IIS web server’s document root. 

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
     <system.webServer>
          <rewrite>
               <rules>
                    <rule name="ReverseProxyInboundRule1">
                         <match url="(appxws.*)" />
                         <action type="Rewrite" url="http://localhost:3014/{R:0}" />
                    </rule>
                    <rule name="ReverseProxyInboundRule2">
                         <match url="(appxhttp.*)" />
                         <action type="Rewrite" url="http://localhost:3015/{R:0}" />
                    </rule>
                    <rule name="ReverseProxyInboundRule3">
                         <match url="(appxwss.*)" />
                         <action type="Rewrite" url="https://localhost:3014/{R:0}" />
                    </rule>
                    <rule name="ReverseProxyInboundRule4">
                        <match url="(appxhttps.*)" />
                        <action type="Rewrite" url="https://localhost:3015/{R:0}" />
                    </rule>
               </rules>
          </rewrite>
     </system.webServer>
</configuration>

SSL

If you are running a secure web server (https), you can configure the Appx HTML client to use your SSL connection. Your web server must be configured to accept both SSL (https:) and non-SSL (http:) connections.

Change the following in your appx-client-settings.js file:

appx-proxy-host = hostname of httpd server (i.e., 192.168.1.11)
appx-proxy-port = “443"
appx-proxy-path = /appxwss/
appx-encryption = “ssl”

Change your "appxConnector.js" as follows (this file is located on your APPX Server Connector server):

var sslEnabled = true;

For Unix/Linux hosts
var sslPrivateKey = "/etc/pki/tls/private/example.key";
var sslCertificate = "/etc/pki/tls/certs/example.com.crt";
var sslCertAuthority = "/etc/pki/tls/certs/gd_bundle.crt";

For Windows hosts
var sslPrivateKey = "c:\\appx\\SSL\\example.key";
var sslCertificate = "c:\\appx\\SSL\\example.crt";
var sslCertAuthority = "c:\\appx\\SSL\\gd_bundle.crt"

Make the same changes to "appxMongoConnector.js" (located in the same folder as "appxConnector.js").

The SSL key values above are examples, you will need to change the file paths to point to your own SSL certificates.

Once you have made the above changes, restart the Server Connector and refresh the Appx Login page in your browser (if it was still loaded when you made these changes).

NOTES:

  • You still use 'http://' to connect to the client page. The client will switch to the SSL connection once the page is loaded.
  • If you are trying to use SSL with the local connector running you will receive an error saying that part of your connection is not secure. The local connector does not have the functionality to talk to the browser using SSL.

Styles

Many aspects of the presentation of the Appx Client are controlled by the APPX.css style sheet in the 'css' folder. If you are familiar with working with style sheets, feel free to experiment with different settings, however those changes will be lost the next time the client is updated.

Instead, you can add a CUSTOM.css style sheet with your own settings. This should be located in the same folder as APPX.css and will override the standard settings in the HTML client.

Some settings that were controlled in Preferences in the Desktop Client are now controlled via a CUSTOM.css file.

colorEditBg is controlled by the 'input' style. For example:

input {background-color: pink;}

will set the background color on all modifiable fields to pink.

colorFocusedFieldBg is controlled by the 'input.focus' style. For example:

input.focus {background-color: yellow;}

will set the background color the field that has the focus to yellow.

colorStdBg is controlled by the .appxbox style. For example:

.appxbox {background-color: white;}

This will set the default background color to 'white'.

colorScrollSelectActive is controlled by the .appx-scroll-act style. For example:

.appx-scroll-act {background-color: #cc0000;}

will set the background color of the active record on a scrolling display to dark red.

colorScrollSelectOther is controlled by the .appx-scroll-act-new style. For example:

.appx-scroll-act-new {background-color: #00cc00;}

will set the background color of the 'other' record on a scrolling display to dark green.

Styles by website

It is possible to have different CUSTOM.css style sheets. Install the client web server files as normal, then follow these steps:

  • create sub folders for each of the different style sheets you want to use.
  • Edit your appx-client-settings.js file, changing 'appx-client-root' to point to the parent folder, i.e.:
    • metas["appx-client-root"]["value"] = "../";
  • Copy the appx-client-settings.js file to each js folder.
  • Create a 'css' folder in each subfolder, and put each unique CUSTOM.css file in that folder

Automatic Logins

Starting in Release 5.5.0, you can configure the client for automatic logins. This is a login where the user is not presented with a login screen, but is taken directly to the startup process. You control which user credentials will be used by configuring the server connector.

This is configured in the server connector for better security. Your configuration file will probably include a valid user id/password for your server, so we don't want it in the web server folder.

The settings are in the 'appx-client-automaticLogin.js' file in your server connector folder. The variables you can change are:

"appx-allow-noLogin" must be set to 'true'. If this is set to false, no matter what variables are provided the HTML Client will not allow automatic logins.

"appx-allow-specific" can be set to 'true' or 'false'. If this is set to 'true', then APPX will run either the process specified below or the process specified in the URL (if 'appx-use-specific' is also set to true). If this is set to false, the process specified as the User's startup process in APPX System Admin will be run.

The above settings CANNOT be overriden via the URL. This is by design and improves the security of the automatic login feature.

The following settings can be overridden via the URL (see keyword list below):

"appx-use-noLogin" can be set to 'true' or 'false'. If 'true' this tells the HTML Client that all logins are automatic login. If 'false', then the login URL must include 'requireLogin=true' to request an automatic login. The 'false' setting allows you to have both automatic and normal logins.

"appx-use-specific" can be set to 'true' or 'false'. If "true" APPX will automatically run the process specified by the application related settings below or by the URL. If 'false', the process specified as the User's startup process in APPX System Admin will be run.

"appx-auto-user" should contain the login user ld

"appx-auto-pswd" should contain the password

"appx-auto-host" should contain the APPX host

"appx-auto-port" should contain the port number for the APPX host

"appx-application" should contain the 3 character APPX application id

"appx-database" should contain the 3 character Database Id to use

"appx-procType" should contain the APPX process type to run (MENU, INPUT, JOB, etc)

"appx-process" should contain the name of the APPX process to run

"appx-browser-redirect" should be set to the URL of a web page to display when the user logs out. If you do not specify a page, the current page will be reloaded and the user immediately logged in again.

URL String variables

You can specify the following variables in the URL. These will override the settings in the 'appx-client-automaticLogin.js' file.

requireLogin ---- true/false value: true = user is required to login, false = you are using automatic login
specific ---- true/false value: true = you are logging user into a specific process, false = you are using normal login
user ---- Login Id
password ---- Password
host ---- Server
port ---- Port
application ---- application to run
database ---- database to use
procType ---- process type you are running
process ---- process to run


Examples:

Logging in as an automatic user, using all the settings ithe 'appx-client-automaticLogin.js' file:

http://<html client server>?requireLogin=false

Logging in as an automatic user but overriding the startup process:

http://<html client server>?requireLogin=false&specific=true&application=DMO&database=DMO&procType=MENU&process=MAIN%20MENU

This requires "appx-allow-specific" set to 'true'.

Logging in as a specific user via a URL:

http://<html client server>?requireLogin=false&specific=true&user=anon&password=password&host=<host name>&port=<port number>

Designer Defined Widgets

Starting in Release 5.5.0, you can extend the function of the HTML client by adding your own widgets. This assumes some familiarity with HTML and jQuery.

To start, in the web server folder copy or rename the appx-client-customTemplate.js to appx-client-custom.js.

This file is in the 'js' subdirectory. For example: 

[root@localhost]# cd js
[root@localhost js]# mv appx-client-customTemplate.js appx-client-custom.js


In this example we'll add a signature widget to an input process. First we add one of the standard APPX widgets to an input process, then we override it with our custom widget. The widget you choose to override must accept the input you are going to supply it with. For example, a picture widget doesn’t accept user input and so is not a good choice for the signature pad since it returns a file name.

In APPX:

  1. Place a file chooser widget on the image where you want a signature block. Size it appropriately.
  2. In the GUI attributes add the macro @SWT=999. 999 is a number that will be matched with a function in your appx-client-custom.js file. You can use any numbers in the range 201-999. 1-200 are reserved for standard APPX widget.
In appx-client-custom.js:

The example template already has a widget 999 defined, so you do not need to to anything special to activate it. For reference, here is the function: 

appx_session.createWidgetTag[999] = function widget_signature(widget, $tag) {
    $tag = $("<canvas>").addClass("signaturepad");
    $(function () {
        /*Need a little delay to let canvas get placed on screen*/
        setTimeout(function () {
            /*Creating global so button clicks have access to signature pad*/
            appx_session.signaturePad = new SignaturePad($(".signaturepad")[0]);
            const data = appx_session.signaturePad.toData();
            setTimeout(function () {
                var ratio = Math.max(window.devicePixelRatio || 1, 1);
                $(".signaturepad")[0].width = $(".signaturepad")[0].offsetWidth * ratio;
                $(".signaturepad")[0].height = $(".signaturepad")[0].offsetHeight * ratio;
                $(".signaturepad")[0].getContext("2d").scale(ratio, ratio);
                appx_session.signaturePad.clear();
            }, 0);
            appx_session.signaturePad.onEnd = function () {
                var fileBlob;
                appx_session.signaturePadID = $(".signaturepad").attr("id");
                if (HTMLCanvasElement.prototype.toBlob !== undefined) {
                    /*toBlob for all browsers except IE/Edge... Microsoft likes to create their own standards.*/
                    $(".signaturepad")[0].toBlob(function (blob) {
                        fileBlob = blob;
                    });
                } else {
                    /*IE/Edge version*/
                    fileBlob = $(".signaturepad")[0].msToBlob();
                }
                /*Need slight delay to let blob get built.*/
                setTimeout(function () {
                    var fileName = "signature.png" + Date.now();
                    uploadFileToMongo(fileBlob, fileName, function () {
                        $("#" + appx_session.signaturePadID).val("$(sendFile)\\" + fileName);
                        $("#" + appx_session.signaturePadID).addClass("appxitem dirty");
                    });
                }, 50);
            }
        }, 50);
    });
    return $tag;
  }
}

The function defines the signature box and clears it. When the user exits the box, the graphic is converted to a blob & uploaded to the Mongo database. The URL to the file is returned to the APPX process.

Upgrading

Here's a document explaining how to perform an upgrade of the APPX HTML client.

Troubleshooting

  • The most common problem when upgrading the client is browser cache. Your browser will cache the javascript from the old version instead of loading the new code. Clear your browser cache. The specific steps to do this vary by browser and platform, consult your browsers documentation.
  • If you have created your own login page based on 'client.html', make sure you update it with any changes to the standard 'client.html' when upgrading the HTML client.
  • If the client login dialog box does not display, check your web server error logs for any error messages & correct as required.
  • If you are getting "[proxy:error] [pid xxxx] (13)Permission denied:" errors, you might have a selinux security issue that prevents apache from initiating any outgoing network connections to the web socket server port. In that case, try the following command:
    # setsebool -P httpd_can_network_connect 1
  • Some browsers (like IE) will not run the client successfully if you double click the 'client.html' file. You should always access the web page via http://servername/client.html, even if the page is installed on your local system.
  • Check to make sure your Appx Server Connector is still running. If not, restart it.
  • If you can't display table data inside a browser and you are running Windows Server 2008R2, you might try installing this HOTFIX from Microsoft. Windows 2008R2 servers without that HOTFIX will sometimes zero-out the MongoDB data. https://support.microsoft.com/en-us/kb/2731284
  • If you're having trouble with Remote connections, this page has some tips
  • If the client seems to hang while loading images or tables, that its a very good indicator that MongoDB server has stopped. If MongoDB server needs to be started or restarted then make sure you restart the appxConnector service after MongoDB is running.
  • Your mongodb driver may be out of date. Use 'npm install mongodb' as root/Administrator to make sure you have the latest version
  • If the Local Connector gets stuck on 'Updating' after installing a new version, try terminating the 'nw' process and deleting the AppxLocalConnector folder in the user's home directory.

Comments

Read what other users have said about this page or add your own comments.


-- JeanNeron - 2020-02-27

Edit | Attach | Watch | Print version | History: r20 < r19 < r18 < r17 < r16 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r20 - 2024-06-20 - BrianRyan
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback