Setting Up Genie on IBM i

Genie and Profound.js

Genie is a Profound UI module that transforms 5250 interfaces to a browser-based HTML5 format on-the-fly. Genie allows users to start an interactive 5250 session directly within a browser. But beyond presenting 5250 information, Genie can also integrate directly with RPG OA Rich Display programs and Node.js modules.

Many features within the Profound.js Connector rely on Genie in order to facilitate a seamless transition between IBM i / 5250 functionality and Node.js. Genie provides a simple way to connect your Profound.js modules to IBM i. More information about Genie is available here.

Navigating to Genie

To start a Genie session, users have to navigate to the following URL:

http://puihost:port/profoundui/genie

Where puihost is the sever or host name for where Profound UI is installed and port is the port number used by Profound UI. Please note, this is not the same as the Profound.js server host name and port number.

Calling Node.js from Genie

Genie authenticates users by prompting for an IBM i user id and password by presenting the standard IBM i Sign On screen. Once a user is signed in and an interactive session is established, calls can be made to Profound.js modules either by using the PJSCALL command or by using a Proxy Program. In order for this to happen, Genie must be able to make a connection to the Profound.js server. Because it is possible to configure multiple Profound.js instances, Genie uses environment variables to control which server to connect to.

Environment Variables in Genie

The environment variable PROFOUNDJS_COMM_HOST specifies the Profound.js host name or IP address to connect to. The environment variable PROFOUNDJS_COMM_PORT specifies the port number to connect to. 

Both environment variables are automatically set at the system level when you first install Profound.js. If you only installed one copy of Profound.js, there is no need to work with environment variables as they should already point to the correct Profound.js instance.

Each interactive Genie session inherits the system environment variable values, which then become the initial job environment variable values. You can view your current environment variable settings by using the interactive command WRKENVVAR.

You can select option 2 (Change) or use the CHGENVVAR command on PROFOUNDJS_COMM_HOST and PROFOUNDJS_COMM_PORT to change which Profound.js instance to connect to. CHGENVVAR can be used from a command line or in a CL program. This enables you to switch between instances, such as Production, Development, and Test.

The environment variables are changed at the *JOB level by default. In that regard, it is similar to changing a job's library list, meaning that the change affects the current user's session only.

HTTPS in Genie

In order to specify that Genie should connect via HTTPS, you will need to use the PROFOUNDJS_COMM_SECURE environment variable. To use HTTPS, set PROFOUNDJS_COMM_SECURE to 1.

The default SSL CA (certificate authority) certificates that Profound.js trusts are bundled with the product. The bundle includes the well known CAs and so should work fine if your server SSL certificate is issued by a well known authority. If your server is using a certificate issued by an unknown authority (such as a local/self-managed authority) you can override the CA certificates by setting the PROFOUNDJS_COMM_KEYRING environment variable. This variable can be set either to a file path on the IFS or to the special value *SYSTEM to use the CAs from the Digital Certificate Manager's *SYSTEM store. The keyring file must be in the IBM key database (KDB) format. For example:

ADDENVVAR ENVVAR(PROFOUNDJS_COMM_KEYRING) VALUE(*SYSTEM)

ADDENVVAR ENVVAR(PROFOUNDJS_COMM_KEYRING) VALUE('/MyDir/MyCAs.kdb')

Note: It's recommended to use the built-in CA bundle (rather than the *SYSTEM store) if your server certificate is issued by a well known authority. The built-in CA bundle is more extensive and up to date than the default CAs configured by IBM.

By default, the Profound.js Connector will verify that the server's SSL certificate is issued by a trusted authority and that the host name used on the request matches the host name the server's certificate was issued for. This ensures secure communications. However, in some cases (i.e. when using a self-signed server certificate) it may be necessary to disable these verifications. The following environment variables can be used:

• PROFOUNDJS_COMM_VERIFYPEER: Set to '0' to disable SSL certificate verification.
• PROFOUNDJS_COMM_VERIFYHOST: Set to '0' to disable SSL host name verification.

Note: Disabling SSL certificate and host name verification makes communications insecure and is strongly discouraged! Do not disable these verifications unless you understand/accept the risks.

Connecting to a development instance on your PC

It is often convenient to setup a development instance of Profound.js on your personal computer. You can then use PC-based development and debugging tools, such as VS Code. The PJSMYIP command located within your Profound.js install library can automatically detect your PC's IP address and change the environment variable PROFOUNDJS_COMM_HOST for you. However, you may have to manually specify the port number of the Profound.js server running on your PC.

The following example shows how to point your Genie session to a Profound.js instance running on port 8081 on your PC.

Note: If your PC is on a different network than IBM i and not connected to VPN, the PJSMYIP command will not be able to determine your PC's IP address. The PC's network's edge router/firewall IP address will be returned instead. In this case the PC network must be configured to route the connections to the PC using port forwarding or NAT.