Appendix A. Caching Support for Node.js

Node Package Manager (npm) is a package manager for the WebFOCUS Reporting Server Node.js® caching server run-time environment. Node Package Manager and Node.js are third-party software packages that should, preferably, be installed before you install the WebFOCUS Reporting Server so that automatic configuration and usage occurs.

On Windows, npm and Node.js are packaged together. Other platforms typically require npm to be installed first and then for npm to install Node.js second.

Note: Throughout this topic, the npm software and Node.js caching server environment are referred to as Node.js.

Node.js Installation and Configuration

When Node.js is installed and running, and a WebFOCUS Reporting Server is configured to use it, In-Document Analytics reports are cached under Node.js and can be accessed independent of the WebFOCUS Reporting Server.

If Node.js is installed on Windows or Linux/UNIX and is detected as available during WebFOCUS Reporting Server installation time, the In-Document Analytics Caching feature will automatically be configured in the EDACONF etc/ar_v2 directory and registered in the edaserve.cfg file, using a port in the reserved port range for the WebFOCUS Reporting Server (HTTP port number plus 5).

The In-Document Analytics Caching feature can also be configured post-installation, with a few simple steps as outlined below, if:

  • Node.js was not detected during installation, due to not being installed or not added to the PATH environment variable.
  • Node.js configuration failed during automatic configuration.
  • WebFOCUS Reporting Server binaries were upgraded to a level that supports Node.js caching and the earlier WebFOCUS Reporting Server did not support Node.js caching or was not configured.

Node.js Process

Starting the WebFOCUS Reporting Server checks if the configured Node.js port is already available, and therefore Node.js is already running. If the Node.js process is not running, the WebFOCUS Reporting Server will start the Node.js caching server process. The Node.js caching server process has the name node or node.exe, depending on your platform. If the WebFOCUS Reporting Server starts the Node.js process, it will also stop the process on server shutdown. In this way, you may control your own Node.js usage or let the WebFOCUS Reporting Server be in control.

By default, the WebFOCUS Reporting Server process is configured to point to a URL for a local Node.js In-Document Analytics Caching process. As such, the Node.js URL may be reconfigured to run against a remote machine, provided the remote machine is properly configured and running. If a remote URL is used, you are expected to start the remote Node.js server process before the local WebFOCUS Reporting Server, as the local server cannot start a remote Node.js process. The simplest form of remote configuration is to point to another WebFOCUS Reporting Server Node.js In-Document Analytics Caching URL and let that server's start-up control the Node.js start-up. A more complex variation is to create a freestanding Node.js In-Document Analytics Caching environment with no WebFOCUS Reporting Server involved and then point any number of Reporting Servers to it. For more information, see Manually Configure a Freestanding Node.js In-Document Analytics Caching Environment on a Separate Machine.

Note: On Linux/UNIX, if the installation ID has a non-writable root-owned $HOME/.npm directory tree, the automatic configuration, as well as manual configuration, will fail for both the internal npm install step and the WebFOCUS Reporting Server's Node.js startup. The solution for this is to delete the $HOME/.npm directory tree or use an installation ID that does not have a $HOME/.npm directory.

Node.js Prerequisites

The following are the prerequisites for Node.js:

  • For Windows. Download and run the Node.js Windows 64-bit installer from https://nodejs.org/en/download. You can use any recent release. Take the default installation options. Do not deselect the Add to PATH option and do not check Automatically install the necessary tools option, unless you have need for this option for other software that may also be using this Node.js instance.
  • Linux/UNIX. Most Linux/UNIX vendors will have their own npm and Node.js installer. Any recent release may be used. The installation steps may be found by performing an internet search on install nodejs on {distribution name such as RedHat or Ubuntu}. The npm portion is typically a separate step, but noted within the Node.js package instructions.

Verify the Node.js In-Document Analytics Caching Environment is Running

    Procedure
  1. Start the WebFOCUS Reporting Server, if it is not already running.
  2. Sign in to the WebFOCUS Reporting Server browser interface using any ID that has open (create) procedure authority.
  3. Click the plus button and select Procedure from the menu to create a new procedure, as shown in the following image.

  4. In the procedure text window, type the following command:
    EX ADAPTIVP NODEJS

    An example of the procedure text window is shown in the following image.

  5. Click the run button .

    Note: There is no need to save the procedure first.

Result

 

An In-Document Analytics-based report should appear, as shown in the following image.

If the Node.js process is not working, a refuse to connect message containing the URL host name will appear.

If the test fails, check for nodejs startup failed in the edaprint file, during initial startup of the WebFOCUS Reporting Server. This typically happens if Node.js was not installed, Node.js is not on the PATH, or the initial automatic or manual configuration failed. Follow the steps in Add Node.js Configuration to ibi WebFOCUS Reporting Server Not Originally Configured With Node.js to investigate and correct.

Another possible failure is the Node.js process is no longer running. To check:

  • On Linux/UNIX, issue the following command to limit output:
    ps -edf | grep "node"

    Look for processes, such as:

    webfocus 122264 122253 0 10:20 ? 00:00:00 sh -c set DEBUG=http,express:* & node --max-old-space-size=16192 server.js "--PORT=8126"
    
    webfocus 122266 122264 0 10:20 ? 00:00:00 node --max-old-space-size=16192 server.js --PORT=8126

  • On Windows Task Manager, find the process icon and turn on the Task Manager command line column, which will show something similar to the following:
    node --max-old-space-size=16192 server.js --PORT=8126
    
    "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\\node_modules\npm\bin\npm-cli.js" run mystart --prefix=c:\ibi\srv93\wfs\etc\ar_v2\cachemanager -- --PORT=8126
  • Check for issues, such as a wrong port number or the process is not running. If not running, check the EDACONF edatemp/npmrun.trc file for the possible reason.

Add Node.js Configuration to ibi WebFOCUS Reporting Server Not Originally Configured With Node.js

Note: Be prepared to recycle the WebFOCUS Reporting Server as part of this procedure. You may want to do this during scheduled maintenance down time.

    Procedure
  1. Sign in to the WebFOCUS Reporting Server browser interface, using the server administrator ID.
  2. Click the plus button and select Procedure from the menu to create a new procedure.
  3. In the procedure text window, type the following command:
    EX ADAPTIVP NODEJS,REBUILD
  4. Click the run button .

    Note: There is no need to save the procedure first. It is normal to see warnings and npm update failed messages. Any other fail messages should be investigated and reported.

  5. Navigate to the Workspace page by clicking the Tools icon in the banner and selecting Workspace, as shown in the following image.

  6. Under Data Services on the tree, open the Configuration Files folder, and double-click Workspace - edaserve.cfg to edit the file.
  7. In the [Workspace] section add, if not already present, or correct the following nodejs_url line:
    nodejs_url = http://{hostname}:{port}

    where:

    hostname

    May be localhost or a specific host name, with or without the domain portion. The host name does not need to be the same machine as the WebFOCUS Reporting Server, but the automatic Node.js start feature will not work if it is not on the same machine. If a remote Node.js configuration is in use, it is expected to be running before the WebFOCUS Reporting Server is started.

    port

    Is typically the WebFOCUS Reporting Server HTTP port number plus 5, if automatic configuration was successful. For example, HTTP port number 8101 would be 8106 for Node.js, but it may be any free port. The Node.js default port number is 8090, if you wish to skip the "–PORT=####" parameter in the manual start instructions.

  8. Click the Save button , which will save and restart the WebFOCUS Reporting Server. If the nodejs_url line was already present and did not need edits, still click the Save button to force a restart of the WebFOCUS Reporting Server.

Manually Start and Stop Node.js In-Document Analytics Caching

To manually start Node.js In-Document Analytics Caching, you will need to know:

  • Where the npm command is installed on your machine if it is not on $PATH (Linux/UNIX) or %PATH% (Windows) and add that path to the npm commands below (for example, /usr/local/bin/npm).
  • Full path directory for the server EDACONF etc/ar_v2/cachemanager directory.
  • A writable directory for output. This is normally in the EDACONF edatemp directory when a WebFOCUS Reporting Server starts Node.js. This directory is not advisable in a privately started environment. From an organizational perspective, EDACONF would be a reasonable location.

The following are examples of starting Node.js In-Document Analytics Caching. Replace the applicable paths and port number with your paths and port number.

Note: These commands must be typed on a single line.

For Linux/UNIX:

npm run mystart --prefix=/webfocus/ibi/srv/wfs/etc/ar_v2/cachemanager -- --PORT=8126 > /webfocus/ibi/srv/wfs/npmrun.trc 2>&1 & 

For Windows:

npm run mystart --prefix=c:\ibi\srv93\wfs\etc\ar_v2\cachemanager -- --PORT=8126 > c:\ibi\srv93\wfs\npmrun.trc 2>&1

On Linux/UNIX, a ps -edf command will show something similar to the following:

webfocus 122264 122253 0 10:20 ? 00:00:00 sh -c set DEBUG=http,express:* & node --max-old-space-size=16192 server.js "--PORT=8126"

webfocus 122266 122264 0 10:20 ? 00:00:00 node --max-old-space-size=16192 server.js --PORT=8126

On Windows Task Manager, find the process icon and turn on the Task Manager command line column, which will show something similar to the following:

node --max-old-space-size=16192 server.js --PORT=8126

"C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\\node_modules\npm\bin\npm-cli.js" run mystart --prefix=c:\ibi\srv93\wfs\etc\ar_v2\cachemanager -- --PORT=8126

The following are examples for stopping Node.js In-Document Analytics Caching. Replace the applicable paths and port number with your paths and port number.

Note: These commands must be typed on a single line.

For Linux/UNIX:

npm stop mystart --prefix=/webfocus/ibi/srv/wfs/etc/ar_v2/cachemanager > /webfocus/ibi/srv93/wfs/npmrun.trc 2>&1 &

For Windows:

npm stop mystart --prefix=c:\ibi\srv\wfs\etc\ar_v2\cachemanager > c:\ibi\srv93\wfs\npmrun.trc 2>&1

Manually Configure a Freestanding Node.js In-Document Analytics Caching Environment on a Separate Machine

Note: This assumes Node.js is already installed and on the PATH of the separate machine.

    Procedure
  1. Navigate to the EDAHOME etc/etc/ar_v2 directory on a WebFOCUS Reporting Server where Node.js In-Document Analytics Caching is supported.
  2. Archive, using zip or tar, the following files for transfer to the target new machine:
    • ar_v2/cachemanager/*.js
    • ar_v2/cachemanager/package.json
    • ar_v2/cachemanager/template/stored.html
  3. Restore the files to a writable directory on the new machine, for example, on Linux/UNIX:
    $HOME/webfocus/ar_v2
  4. Edit the ar_v2/cachemanager/config.json file.
    • On the redirect_host line, change the redirect_host http value, usually localhost, to the actual full DNS machine name, for example:
      "redirect_host":"http://mymachine.mycompany.com"
    • On the cache_port line, change the cache_port number to the port number you want to use for the configuration, matching the port used by the WebFOCUS Reporting Server nodejs_url value.
  5. Change the directory to the cachemanager directory, for example, on Linux/UNIX:
    cd $HOME/webfocus/ar_v2/cachemanager
  6. Run the following command:
    npm install
  7. Review the installation for any errors. It is normal to see warnings and npm update failed messages. Any other fail messages should be investigated and reported.

    Note: A root-owned $HOME/.npmrc directory is typically a reason for failure and should be deleted beforehand or, another ID, without a root-owned $HOME/.npmrc directory, should be used.

  8. Start and stop the environment, as described in Manually Start and Stop Node.js In-Document Analytics Caching, using the applicable paths and ports.

Block Automatic Node.js Startup By the ibi WebFOCUS Reporting Server

If you want to stop the server from attempting automatic Node.js startup, even though it is configured, you can set the BLOCK_NODEJS environment variable to a value of Y.

The best place to do this is in the EDACONF bin/edaenv.cfg file by adding the "BLOCK_NODEJS=Y" line, and saving and restarting the WebFOCUS Reporting Server. It may also be set as an environment variable, and exported on Linux/UNIX, before WebFOCUS Reporting Server startup, although this is less convenient for Windows Reporting Servers running as a service, as it needs to be set up at a system level.

Note: The edaenv.cfg file may not exist. If this is the case, create the file and add the "BLOCK_NODEJS=Y" line.