...

...

...

...

...

...

...

The PC Integration API allows you to integrate your browser screens with PC applications. For example, you may have the need to call up your PC-based imaging or document management application to view an invoice, part image, etc., based on a user action in the browser screen. The  The PC Integration API also allows you to copy data to the PC's clipboard. Genie's STRPCCMDcommand support also makes use of the PC Integration API.

For obvious security reasons, the browser vendors have made it so that Web-based applications cannot call programs on the PC under normal security settings. This makes it challenging to integrate your browser-based screens with other applications in your environment. The  The PC Integration API solves this challenge by running the PC commands in either a separately installed PC program (PC Command Listener or PC Command Launcher) a Java applet (PC Integration Applet). 

One of the following alternatives must be configured on the end user PC's before the PC Integration API can be used.

When Possible, use Hyperlinks, IFrames, or JavaScript

...

There are at least three ways to use the web approach. Each method below involves binding a field in the Rich Display File, changing the server-side program to write the URL to that field instead of calling STRPCCMD, and letting some client-side code handle the bound field data.

1. Bind a Hyperlink widget's "hyperlink reference" property to a field, and change the server-side program to write the URL to the field. Then, the user can click on the hyperlink to load the URL. Set the hyperlink widget's "target" property to "_blank" to open in a new browser tab/window.

2. Bind an IFrame widget's "iframe url" property to a field, and change the server-side program to write to the field. This make a page inside a page. You may need to re-arrange the Rich Display File so that there is space to show the IFrame.

3. Bind a hidden output field's "value" property to a field, and change the server-side program to write the URL to that field. Write custom JavaScript code in the record-format's "onload" property to call window.open.

The widgets can be hidden conditionally until ready by binding the "visibility" property.

...

This is a standard Windows program installer that works in the typical way. The program is installed for all PC users and registers itself to run on Windows startup. The program runs in the System Tray. The tray icon has a context menu that can be used to start/stop the listener and to configure the port number.

Image Modified  Image Modified

PC Command Listener Command-line Installation

The MSI installation package can also be run from a command prompt or script using the Windows 'msiexec' command. When installing using 'msiexec' the configuration data can be passed on the command line using the -- CONFIG parameter. The configuration will be written to the PC's program data directory, which is shared by all PC users. For example, to set the listen port to 8100, disable notification messages, and disable logging:

msiexec /package pccommand-listener-setup.msi CONFIG={\"notifications\":false,\"port\":8100}

To avoid seeing a graphical user interface and have the installer run in the background, then from an Administrative command prompt you can do:

msiexec /quiet /package pccommand-listener-setup.msi CONFIG={\"notifications\":false,\"log commandsport\":false8100}

PC Command Listener Logging

By default, PC Command Listener does not log any information regarding the commands it receives. As of Launcher version 1.0.10, the Listener can be configured to log the commands received. Logging can be enabled via the Listener's System Tray context menu under "Configure...". Alternately, the "log commands" property can be passed in an argument to the "msiexec" command as indicated in the section above.

...

%APPDATA%\Profound UI\pccommand-listener-log.txt

Configuring the Server for the PC Command Listener

In the latest versions of Profound UI set the configuration option, PC Command Mode, to the Listener; e.g. pui["pc command mode"] = 2;

In Profound UI versions Release 6 Fix Pack 6.0 and earlier, the default mode of operation for the PC Integration API is to use the Java applet. In those versions the configuration option pui["use pc listener"] must be set in order to use the Listener.

...

With all versions, optionally pui["pc listener port"] must be set in order to use the Listener, depending on which TCP port your Profound UI instance expects the listener on. Options to configure the PC Command Listener are also provided in the Genie Administrator. If specified, these will take precedence.Image Removed

...

(Profound UI Version 5, Fix Pack 12.0 and earlier)

PC Command Listener on HTTPS (SSL) Servers

To enable a Rich Display session running on HTTPS to send commands to the Listener, the configuration optionPC Command Mode must be set to the listener mode 2 (e.g. pui["pc command mode"] = 2). Genie automatically detects when the site is using HTTPS, so that option isn't necessary for Genie.

(In older versions of Profound UI the SSL option for the Listener was PC Listener Mode.)

PC Command Listener Security

...

A sample script below is provided for generating RSA key pairs on an IBM i system in the PASE environment that already has "yum" and "openssl" installed.

...

gen-pccmd-rsa.sh

#!/bin/bash
# Generate private and public key pair for the PC Command Listener. 

# Stop on error
set -e

privkeydir="/profoundui"
pubkeydir="/www/profoundui/htdocs"

[[ ! -d "$privkeydir" ]] && mkdir "$privkeydir"
cd "$privkeydir"

# Generate a 4096-bit private RSA key.
echo -n "Generating Private RSA key. This will take a few seconds..."
openssl genrsa -out "$privkeydir/pccmd-priv.pem" 4096
echo "done"

# OpenSSL "genrsa" outputs in the ASCII PEM format. Profound UI requires the key 
# to be in a binary DER format.
# Convert the PEM key to the DER format so that Profound UI can use it.
#
openssl rsa -inform PEM -outform DER -in "$privkeydir/pccmd-priv.pem" -out "$privkeydir/pccmd-priv.der"
# The HTTP server must have read access for the private key in order for a PUI CGI program to read it.
# Make sure the key directory is in a location that is outside the DocumentRoot.
chown qtmhhtp1 pccmd-priv.der
  
# Next, export the public key so that the PC Command Listener can use it. The PC
# Command Listener expects a public key in a PEM format. Store the public key in 
# a location that the Listener clients can download when they run.
openssl rsa -inform DER -in "$privkeydir/pccmd-priv.der" -outform PEM -pubout -out "$pubkeydir/pccmd-pub.pem"

echo "  Private key: $privkeydir/pccmd-priv.der"
echo "  Public key: $pubkeydir/pccmd-pub.pem"
echo "Finished."

exit 0

...

• "public key"

  • "" – (default) A blank string. The Listener does not attempt to verify command signatures. Any command sent to it is run.

  • "local" – The listener attempts to find a file named "pccmd-pub.pem" in the %ALLUSERSPROFILE%\Profound UI\ or %APPDATA%\Profound UI\ directories.

    • If the file does not exist, then the Listener will reject the command.

    • The user/admin is responsible for obtaining the public key and storing it in the correct location on each end user's PC.

  • A public key in PEM form, formatted to fit in a JSON string.

    • e.g. "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQ ... AwEAAQ==\n-----END PUBLIC KEY-----\n"

    • The key string can be distributed via the "CONFIG" parameter for the MSI installation (see section on installation above).

  • A URL pointing to a file where the public key can be downloaded.

    • e.g. "http://

      yourServer

      yourServer:8080/profoundui/pccmd-pub.pem"

    • When it starts, the PC Command Listener downloads the key file from that URL and keeps it in memory.

    • This is the easiest public key distribution approach.

    • The key file is not cached, allowing system administrators to generate new keys periodically if desired. (Though, note that guessing a private key using many bits, such as 4096, would take billions of years using current computing technology.)

    • The configuration value can be set via the "CONFIG" parameter for the MSI installation (see section on installation above).

• "verify algorithm" – When public keys are used, then the this option specifies an algorithm to use as part of verifying the signature. Not only must the private and public keys match, the hashing algorithm used to verify a signature must be the same algorithm used to generate the signature. Few people will need to change the algorithm. Typically, older algorithms are less secure.
  

  • "" – (default) a blank string. In this case, the algorithm used is SHA-512 ("sha512").

  • Other options that can be specified: "sha512", "sha384", "sha256", "sha224", "sha1", "md5"

Server-side Hash Algorithm

...

Once the PC Command Launcher program is installed on a PC, the Launcher will handle any requests to a custom protocol. The Integration API will open a custom URL containing some encrypted information with the command, and the browser will attempt to run the Launcher. There is no interface to the PC Command Launcher. However, the first time a PC Command is sent via the Launcher mode, the browser will prompt the user before running the launcher:Image Removed

...

If your web browser supports it, the user can check the "Always open these types of links in the associate app" checkbox and then click the "Open..." option, so that they will no longer be prompted before the command runs. 

...

The installer package can be installed from a Windows command line without displaying an interface. For example, do an install with no UI:

Example

msiexec /i pccommand-launcher-setup.msi /quiet

...

The log is saved to the Windows "All Users" folder, %ProgramData%, which is usually c:\ProgramData and hidden from most users. The log file is %ProgramData%\Profound UI\Logs\pccommand-launcher.txt. The date and the PC user's username appear first, then the unencrypted command or filename received. If the command fails, then an error code is also recorded.Image Removed

...

Uninstalling the PC Command Launcher from the PC

The launcher can be uninstalled like any other program, using Windows' Add/Remove Programs:Image Removed

...

Or the Windows Control Panel:
Image Removed

...

PC Integration Applet

The applet was the original mode of operation. However, this is being phased out as browser vendors drop support for the Java plug-in. The  The applet is digitally signed so the end-user's PC can trust the applet to call programs on the PC. The  The applet is a piece of Java code, but no Java programming is required to use it. The applet is packaged into a JAR file that is placed on your server's file system, and downloaded by the user's browser through the HTTP server. There  There is a JavaScript function provided that you can use to easily load the applet in your browser page. Once this is done, you can access the applet's functionality using simple JavaScript API that are provided.

PC Requirements

The PC Integration applet runs in the Java Virtual Machine's browser plug-in on the end user's PC. The only current browser that supports the Java plug-in is Internet Explorer. Chrome, Firefox, and Edge do not support the Java plug-in. 

...

As mentioned above, the Sun plug-in is required. The user can verify the version and install it if necessary at this URL: http://www.java.com.

1. Click on the "Do I have Java?" hyperlink to test the version.

2. This brings up the verification page. If the latest version of Sun Java is installed, a "congratulations" message will appear.

Related Videos

...

...