Administrative Interfaces

To manage Blue Prairie Forms, several administrative interfaces are available.  You will notice that some administrative interfaces provide function that may overlap other administrative interfaces that are available.  Over time, you’ll choose the interface that best suits your style and preferences and develop your own ways of administering the BPF MultiValue-side and OO/LO-side processes.

What you will administer

Because BPF performs some of its tasks on the MultiValue host and some on the Linux Open Office server and because a BPF configuration shares resources between the two servers, it can sometimes be a bit confusing as to where certain tasks are being performed and which interfaces should be used to monitor and administer the components.

To keep things organized in your mind, remember the following rules:

  1. Everything related to the creation of a document is performed on the MultiValue host
  2. Everything related to printing the document is performed on the Linux Open Office server

Because the directory which stores the templates and final documents is kept on the MultiValue host but shared to the Linux Open Office server, it can appear (wrongly) that documents are stored on the Linux Open Office print server.  In a short period of time, the organization of BPF will become clear and as you fall into your normal administrative patterns, all will become second nature.

Table of most common administrative tasks

Interface

Server

Start / Stop Phantoms

Check Logs

Samba

Admin Printer

Admin Print Job

General Admin of OO/LO

Support

BPIFORMS ACCOUNT

MultiValue

Yes

Yes

No

No

No

No

Blue Prairie

SWAT

MultiValue

No

No

Yes

No

No

No

Community

GUI Console

Linux OO

No

No

No

Yes

Yes

Yes

Community

CUPS Page

Linux OO

No

No

No

Yes

Yes

Yes

Community

Webmin

Linux OO

No

No

Yes

Yes

Yes

Yes

Community

 * note: While we provide some tips/advice within these pages regarding community supported utilities, these utilities change often and may even be deprecated by the community.  Blue Prairie, inc. will try to assist but time-consuming support related to community products may incur additional support fees.

The BPIFORMS account

The BPIFORMS account is the MultiValue account where the Blue Prairie Forms basic code and control files live.  It is also used to run the bpi.form.phantom.menu administrative menu.  No user data should be created or stored in this account.  Blue Prairie reserves the right to overlay programs and data kept in this account without advance warning.

Location

The BPIFORMS account is usually located aside your other MultiValue accounts but it may also reside elsewhere on the server depending on your requirements

Directories:

 

/bpi.bp.form  Contains basic source code for the Blue Prairie Forms utilities and libraries
/bpi_forms

This is the main storage directory where Blue Prairie Forms stores:

  • Queued documents
  • Archived documents
  • templates
  • help files
  • ini files
/BPI.FORM.PHANTOM.CONTROL This is a directory containing definitions for Blue Prairie Forms phantom threads.  Note, on D3 systems BPI.FORM.PHANTOM.CONTROL may reside as a hashed file within the D3 blob and will not be exposed as a unix-level directory or file
   
   

BPI.FORM.PHANTOM.CONTROL record definition

BPI.FORM.PHANTOM.CONTROL is a file containing records that define phantoms that will poll directories where finished forms are dropped and send the form to the Print Server.  On most MultiValue Systems, BPI.FORM.PHANTOM.CONTROL will exist as a directory in the BPIFORMS account directory.  On D3 Systems, BPI.FORM.PHANTOM.CONTROL will exist as a D3 hashed file within the BPIFORMS account.

The Blue Prairie Forms account (usually called BPIFORMS).  Each record in BPI.FORM.PHANTOM.CONTROL defines a single phantom.  We call each of these phantoms a thread.  Each phantom will poll a directory then when it finds a document, it will send an instruction to the Print Server defined for that thread.  This will cause Open Office to start up on the print server and it will access and print the document.

You may have an unlimited number of phantom threads.  Each record in BPI.FORM.PHANTOM.CONTROL names the Printer Server ip address or host name that this thread should communicate with and it will also define the Linux user name on the Print Server that should be used to run Open Office to print the document

While it is customary to run only a few threads for a typical installation, the architecture allows for a virtually unlimited number of threads.  This allows documents to be processed in parallel and for various documents to be processed by specific threads.   Because a thread record also defines a Linux user name on the Print Server that will run Open Office, the print server may run many instances of Open Office and process documents in parallel.  This design allows for massive scaling and even for the definition of multiple threads per queue directory.

These records are read by the bpi.form.phantom.menu process which you will use to start, stop and administer the phantom threads.

The records in the BPI.FORM.PHANTOM.CONTROL file/directory can be arranged as the user sees fit using a tag=value param file format.

Tag Names

Description

key

Key of phantom.  Usually a word to describe the thread (e.g., LOC1) to define the phantom for Location 1

order

This is a right justified numeric value that is used by the bpi.form.phantom.menu process to sort the phantom threads into right-justified ascending order when displayed in the menu.

status

Current status of the phantom (e.g. active)

description

A text description of the phantom

account

MultiValue account in which this phantom will run

 

 

queuePath

Path to the directory where queued documents will be placed by the app (directory to poll) and where this phantom thread should look for them

archivePath

Path where documents will be moved after processing.  If not specified, document will be deleted and not moved to archive.

ooServerAddress

hostname or ip address of the OpenOffice server to be used for this thread.

user

unix username to be used when phantom communicates with OpenOffice server to issue ssh directives.

remoteDefaultPrinter

printer name on the OpenOffice server to which print jobs from this thread will be sent.

remoteQueuePath

the path on the remote OpenOffice server where it will find the document to be printed (the mount point and path on the OpenOffice server).  Usually, this is a directory on the Linux OpenOffice Printer Server (LOOPS) under the /mnt directory.  To this directory is mounted a CIFS/SAMBA share exposed on the MultiValue host. 

killSignal

On release > 3.2 (Mar 2020)

Now, you can specify a full path to a record such as

/db/accts/BPIFORMS/BPI.CONTROL/KILL-FORMPHANTOM-%ident%

The last segment (KILL-FORMPHANTOM-%ident% will be the filename (record id) and the prior part of the path will be the filename where the record is stored.  Even if the filename is a hashed file, this syntax will work.

On all releases

Item ID of a record in the CONTROL file.  The phantom will check for the existence of this record during its polling cycle.  Phantom will terminate if this record ID is found in CONTROL.  (aka the Kill record)

phantomWait

If specified is the number of second the phantom will sleep when there are no records found in the queue before it will check the queue again.  Note, as long as records are present, the phantom will not sleep again until zero records are found in the queue directory.  Default is 5 seconds.

1/25/2018: on jBASE releases of BP Forms, you may optionally specify a unix/linux command to run instead of a numeric value for sleep.  For example, "sleep 2" and it will invoke the unix sleep command rather than using the jBASE JBC SLEEP function.   Using the *nix sleep command is preferred if your company routinely changes the system clock as it works more efficiently in these situations and prevents the phantom from sleeping for longer periods than specified.

postCommand

Not yet implemented

localTestPageDirective

A unix command to issued on the MultiValue host to place a test document into the queue directory.  Generally, you’ll copy a .odt file from the template directory to the queue directory and this will cause that document to print.

remote TestPageDirective

Not yet implemented

switches

Switches that will be added to to the directive used to start the phantom.  -v2 is often added to tell the phantom to use extreme verbose messaging in the log file.

 

Example BPI.FORM.PHANTOM.CONTROL record:

 

key=bpiform1
order=1
status=active
description=bpiform1 form print
account=MYACCOUNT
 
queuePath=/uddata/accts/BPIFORMS/bpi_forms/queue/bpiform1
archivePath=/uddata/accts/BPIFORMS/bpi_forms/archive/bpiform1/%filename%
ooServerAddress=192.168.001.001
user=bpiform1
remoteDefaultPrinter=Q0
remoteQueuePath=/mnt/prodserver.bpi_forms/queue/bpiform1
killSignal=/db/accts/BPIFORMS/BPI.CONTROL/KILL-FORMPHANTOM-%ident%
phantomWait=1

localTestPageDirective=!cp /uddata/accts/BPIFORMS/bpi_forms/templates/bluePrairieFormsTestPage.odt /uddata/accts/BPIFORMS/bpi_forms/queue/bpiform1/remotePrinter___bluePrairieFormsTestPage.odt

switches=-v1

Note: The phantom thread must be restarted (bounced) in order for changed parameters to take effect.

The Phantom and Threads

Document creation and scheduling procedure

  1. Application calls BPI_FORM api to create document and store it in /queue/xxx directory
  2. Phantom monitors /queue/xxx directory and finds document placed there by app.
  3. The phantom checks a lock table to ensure that no other thread is currently processing the document and if it is free, it sets a lock so that no other phantom thread can process the record.
  4. The phantom checks the OpenOffice server, target remote printer, remote mount point and the document on the remote server
  5. The phantom also checks the remote server to ensure that OpenOffice is not busy for this user on the remote server.
  6. If all of these checks pass successfully, then the Phantom issues a sudo directive to become user x and ssh connects to the OpenOffice print server
  7. ssh directive executes on print server to check status of OpenOffice and to direct OpenOffice to retrieve document created by app stored in remoteQueuePath directory (samba mounted on OpenOffice Print Server) and render it to printer
  8. (optional) phantom moves document from remoteQueuePath to archivePath if archivePath is defined.
  9. Phantom looks for next document or sleeps for prescribed period

bpi.form.phantom.menu

The bpi.form.phantom.menu utility lives in the BPIFORMS account.  It can be invoked at TCL by typing bpi.form.phantom.menu.  The screen display will look something like this

Screen Shot of bpi.form.phantom.menu

A help screen can be invoked by typing h.  You may navigate up and down using the appropriate keys then press spacebar to select one or more threads.  The most common action will be ‘s’ to start a phantom and ‘k’ to kill a phantom.  Additional functions are available and will be described below.

The numbered lines in the menu above are populated from records found in the BPI.FORM.PHANTOM.CONTROL file/directory that lives in your Blue Prairie Forms account (this is usually called BPIFORMS).  You can modify existing BPI.FORM.PHANTOM.CONTROL records via the menu above by chosing v)iew then e)dit or you can edit them directly in the directory using your preferred text editor.  To create new phantom threads, you will create a new record in BPI.FORM.PHANTOM.CONTROL by either copying and modifying an existing record or creating a new one from scratch.

Explanation

The example above has three phantom threads defined. As a phantom is started, its pid will appear in the pid column.  This is the indication that the phantom is running.  To get help for the menu, press h.

Navigation

Key Action
up arrow or U will move the selection line up  (note, up/down arrows are not mapped for all terminal types)
down arrow or D will move the selection line down
spacebar will select the highlighted line causing a > character to appear to the left
*  will select all or deselect all lines

Actions

Key Action
S will start the selected phantom(s)
K will kill the selected phantom(s) by writing a record to a file that the phantom monitors (a signal)
L show the log files for the selected phantoms.
C
clear the queue for selected phantoms.
P Ping the OpenOffice server for selected phantoms (to see if it is alive.)
< Will send the test .odt document named in the thread’s BPI.FORM.PHANTOM.CONTROL record to the threads queue directory.  If the phantom is running and all is well, the test document will be rendered on the OpenOffice server.  If not, more in-depth diagnostics may be required.

Administrative Actions

The following actions are shown in the help file and on the menu but will only function if the user id you have used to login is a member of the bpiformadm unix group.  Normal users are not normally members of this administrators group.  In addition, a param file controls which of these administrative actions are available and optionally, whether a password will be required to access the function.

Key Action
$  Will ssh connect you to the OpenOffice server as the user defined for the selected phantom.  Once connected, you are now logged into the OpenOffice server as that user.  You can use any command for which you are privileged.  Type exit at the shell prompt to close the connection and to be returned to the MultiValue host (the menu).
L Will show the log being generated by the phantom.  The level of detail written to a phantom’s log is determine by the ‘switches’ param in the BPI.FORM.PHANTOM.CONTROL record for a phantom.  The -v switch controls level of verbosity.  The number following the -v indicates the level of verbosity.  The higher the number, the more verbose the detail in the log.  (not currently supported in D3)
C Clear the queue.  This will remove all queued documents
P Ping the OpenOffice server for selected phantoms (to see if it is alive.)
V View and edit the phantom control record.  Options for vi and your default editor (ED, JED, etc) are provided.
< Will send the test .odt document named in the thread’s BPI.FORM.PHANTOM.CONTROL record to the threads queue directory.  If the phantom is running and all is well, the test document will be rendered on the OpenOffice server.  If not, more in-depth diagnostics may be required.
? List OpenOffice processes running on the OpenOffice server for the user associated with this phantom thread.
B This will search the OpenOffice server looking for open office (soffice) processes owned by the users associated with selected phantoms and will attempt to kill -15 these processes on the OpenOffice server.  This effectively, cleans up orphaned or hung OO processes.  If you need to get more harsh, you can use the $ command and ssh to the server to investigate and kill processes as needed.

Configuring the menus via the ini file

The menus may be configured using the parameters file.  The menu param file is stored at BPIFORMS/bpi_forms/ini/bpi.form.phantom.menu.ini.

Here is an example where all functions are enabled with passwords for each function

menuLog=enabled
menuLogPassword=bluepinc
menuSsh=enabled
menuSshPassword=bluepinc
menuPs=Enabled
menuPsPassword=
menuBump=enabled
menuBumpPassword=bluepinc
menuView=enabled
menuViewPassword=
menuEdit=enabled
menuEditPassword=bluepinc

SWAT [The Samba Web Admin Tool]

This utility runs on the MultiValue host and is convenient for defining and for managing the Samba Service.  The Samba service must be running on your MultiValue host.  This is how the Linux OpenOffice/Libre Office print server receives documents to print.  If the services is not running, you will see errors in the BPF log indicating that the mount could not be established by the Linux Open Office / Libre Office print server.

Connecting to SWAT

You can access the SWAT tool (if installed) by pointing your browser to http://ipAddressOfMultiValueServer:901

We recommend that you login as root with the root password of your MultiValue server. You’ll need root/super user privileges in order to manage the Samba services and resources.  After you login, you will receive an administrator page that looks like this:

If SWAT is installed and permissions are properly set, a web page which looks like this will be presented:

Samba Status Information

(note: Samba support is not included with BP Forms Support Fee, see Community support policy)

This information may become obsolete at some point.  Consult community forums for the latest on Samba SWAT

Click on the Status button and you’ll receive a page that shows the current status of the Samba service running on your MultiValue host

 

Samba Status Indicator

The area circled in red is the samba service indicator.  If the Samba service is not running, one or more of the indicators will say “not running’ instead of “running”.  It’s not important for the winbindd service be in a status of “running” but the others (smbd and nmbd) must be running in order for BPF to operate normally.

Stop Samba Control

The area circled in dark blue represents buttons that can be pressed to stop the Samba services.

Start/Restart Samba Control

The area highlighted in yellow represents buttons that can be pressed to start the samba services.  We recommend using the ‘Start All’ or ‘Restart All’ buttons to start all Samba services.

Active Connections / Active Shares

These areas of the page show you the ip addresses currently accessing Samba and the shares that are currently being access from which IP addresses.  This is extremely useful information in the event that BPF stops working (rare).  It may be because the power was lost to the Linux server or that the network connection was disrupted.

Samba Shares Information

Click on the SHARES button and information about currently configured Samba shares will be presented.  You can browse to various shares and look at their definitions.  In the example below, the share called bpi_forms points to the directory on the MultiValue host of /dbms/BPIFORMS/bpi_forms/.  When the remote machine connects to this share, it will have visibility to this directory and (according to the options selected) all of the directories under that directory.

 

Connecting to the Share from your PC

This is a fantastic feature of Samba that is very useful.  Just like the Linux Open Office Server connects to your MultiValue server and to this share via Samba, you can connect to the share directly from your PC.  This makes it possible for you to navigate the templates, documents archives and queues used by Blue Prairie forms directly from your PC!   And think about it, would it be nice to be able to browse to your HOLD file to bring up spooled print jobs in U2 or jBASE right on your PC using windows explorer?  This is possible with Samba by simply configuring another share to point at the spooler directory. (sorry D3 users, this feature is not offered in D3).

To connect your PC to the share

Open up Windows Explorer on your PC.

Click on Map Network Drive

 

Enter the ip address of your MultiValue server and the share name as shared from Samba into the Folder field and press ‘Finish’

You will prompted for the user name and password for the Samba share.  You’ll need to obtain these from your administrator and enter them when prompted.  In this example, the user name is bpiform1 and the password was {redacted for security reasons}. Your BP Forms Linux Open Office server has been configured with a mount that connects to your MultiValue server’s Samba share.  The user name and password can be viewed by examining the file /etc/fstab on the Linux Open Office print server.

Once you connect to the Samba share using your PC and Windows Explorer, you can browse all of your Blue Prairie Forms directories and manage my templates, documents archives and more.

The GUI Console

(note: BP Forms support fee does not include support for VNC.  See community forums for VNC for the latest information about VNC and for community support).  Use this information here at your own risk.

Your BPF installation should have included setup of a remote graphical desktop access. Normally, VNC is the preferred remote desktop access method.  To access it, you will need to install a special piece of software called the VNC Client onto your PC.  Once VNC Client has been installed, you can use it to ‘remote’ into the GUI desktop of your Open Office / Libre Office server.

[root@bpfserver_1 sysconfig]# rpm -qa |grep vnc
tigervnc-1.1.0-16.el6.centos.x86_64
tigervnc-server-1.1.0-16.el6.centos.x86_64
[root@bpfserver_1 sysconfig]#

The above display indicates that the tigervnc client and tiger vnc-server package have been installed.  TigerVNC is one of many available VNC packages and is common on Linux systems.  If you do not see some form of VNC server and VNC client installed, then you will need to either install vnc server onto the machine or contact support for assistance. 

 

We recommend tigerVNC.  VNC comes in two parts:

vnc client   -- (aka vnc)

This is an app that you run to connect to another vnc server.  It’s like the Windows RDP client.  You’ll install VNC client on your PC and then run it to connect to a VNC server.  When you see a ‘vnc’ package (i.e., a package with a name that has vnc in its name but is not vnc-server such as what is shown above on the first green line, this is a client package).  It’s okay to have a client package installed on the Print Server (Linux server) but we’ll probably not use it.  Instead, we’ll be installing our own VNC-Client on our PC and connecting from our PC.  Nonetheless, it does not hurt to have vnc client installed on the Print Server

vnc-server

This is what we must have installed and running on our Linux print server to allow a remote vnc-client to connect to this server and present a graphical desktop.  If we have no vnc-server package installed, you will need to install one in order to have remote access via VNC.  Blue Prairie Forms will function without VNC.  But it is handy to have VNC access to the print server to perform certain administrative tasks (as shown above) so we highly recommend having it installed and running.

If you do not have VNC server running

On the Linux Open Office / Libre Office Server (or you are not sure), you can refer to the section of this guide entitled “Installing, Configuring and Connecting to VNC or call Zumasys for help

Making the connection from your PC

If you have not already installed the vnc client (aka VNC Viewer) on your PC, then Google for a download site and install it.  We’ve had good luck with TightVNC.  With VNCserver installed and running on your Linux Print server, and assuming you have visibility to the ip address of the Linux Print server from your PC and that VNC server has been installed and is running on the Linux print server, simply run TightVNC on your PC.  For the example below, we’ll going to connect to the system shown in the above example and connect to VNC listener :2 which will connect us to the bpiform1 user

 

Fill in the Remote Host field with the ip address of your Linux Open Office / Libre Office server followed by “:1” as shown below.  “:1” is normally configured to connect you to the GUI desktop as root.  You’ll be challenged for a password and you’ll need to know the VNC password for this desktop to make access.  Not that the VNC password is normally NOT the same password as the Linux user password.  In the example above, the VNC password is not the same as the root password.  This can be confusing so keep it straight.

Assuming that you have connected properly, you’ll be presented with the GUI console for the machine which will look something like this:

 

What can I do with VNC?

Once you are connected to the graphical desktop on your Linux print server, you can now perform tasks to administer the server.  Common tasks involve setup of printers, managing print jobs and managing users, groups and passwords.  You can navigate the menus to see what administrative tasks are available to you.

Blue Prairie Forms server will on occasion require you to setup a new printer or to manage a print job.  The VNC console can be a very handy way to access easy to use administrative interfaces that make these tasks easy.