Choose Your Interface

Your Blue Prairie Forms Open Office Print Server is configured with a number of administrative interfaces that can be used to manage various aspects of your forms system.  For a detailed description of the various Administrative Interfaces available, please reference the topic Administrative Interfaces.  This section describes in greater detail the specific interfaces that can be utilized to manage your print jobs. We recommend that you familiarize yourself with each of the provided interfaces and then decide which interface you prefer.

Console

The console is normally access via VNC.  Once you have access to the console, you may use thePrinters or Print Setting utilities. Follow the directions for accessing VNC and use the desktop and its admin utilities to manage printers by accessing the menu System > Administration > Printing.

Just like Windows printer manager, a list of printers will appear.  You can modify a printer by simply right clicking on it and choosing “Properties”.  A window like this will appear:

From this window you may change characteristics and behaviors of printers.  To add a new printer, assuming that your network is configured to allow discovery, Linux will find the available printers and allow you to simply choose them and assign them a printer name on the Linux print server.

Example Add a Printer

Choose New > Printer from the menu

As you can see in the example above, the Network Printer menu it Linux will present a list of printers that it finds on your network.  If network discovery is not working for you, simply follow the Add printer wizard and CUPS will walk you through the prompts to manually configure the printer.

Print Jobs

To see print jobs for a specific printer, right click on the printer and choose “View Print Queue”. A dialog box like this will appear:

The CUPS Page

CUPS stands for the Common Unix Printing System and is the printing system for UNIX and Linux systems (and even Macintosh).  T

Connecting to the CUPS Printer Page

To access the CUPS page, you simply need to have a Browser.

Point your browser at http://ipAddressOfOpenOfficeServer:631

Using the tabs at the top of the page, you can browse through the available printers and jobs.  If you have been granted privileges, you can add, change and remove printers, jobs, etc. 

Example 'Printers' Page

Example 'Jobs' Page

The CUPS printer page listens on port 631 of the open office server. 

There are several ways to modify form templates for Blue Prairie Forms.  You can use OpenOffice or LibreOffice installed on the Linux print server to edit the templates..  This is possible because OpenOffice/Libre Office is already installed and because the server already has access to the templates using the Samba shared directory from the MultiValue host.  Here’s an example of a procedure used to load, modify and save a template:

You can use the GUI console as a handy way to navigate to and modify the document templates used by BPF.  Remember that BPF templates are simply Open Office / Libre Office odt documents so you can edit them with Open Office, Libre Office.  While it is technically possible to view documents in Microsoft Word, we do not recommend creation or modification of .odt templates in Microsoft Word.  Differences in internals can cause unpredictable behaviors within the templates.  The handy aspect of modifying templates using the GUI console is that OpenOffice is already installed there so you don’t need to install OpenOffice on your PC.

Navigate the menus to Applications > System Tools > File Browser  (using VNC to access to BP Forms Console see Administrative Interfaces)

Click on the left menu under “File System” then all of the directories will appear on the right.  The directory shared from your MultiValue Host can be found under the directory “mnt”.  So, go ahead and click on that directory and the window will refresh and will look like this:

You should see a folder called bpi_forms.  Click on it

A folder called ‘templates’ will be shown. This is where the templates are stored.  Remember that we’re actually navigating a folder that lives on your MultiValue server. 

By scrolling down, you should see our document templates.  In the example above we’ll be viewing/editing a template file called wallwork_pickticket_1.odt.  If we click on it, Open Office (or Libre Office if you are using that product) will be summoned and you can edit and re-save the document.

Remember that you are saving ‘live’ templates so be careful when ‘playing around’.  You may wish to make a backup copy of the template you intend to change so that if you make a mistake, you can easily restore it.

You may also browse to queue directories or other directories shared from the MultiValue host.  Keeping a queue directory open might be a nice way to see documents being dropped onto the queue directory by Blue Prairie Forms.

Tip:

If you stop a phantom and then generate a document from the MultiValue host, you can then navigate to the queue directory where the application drops the document then call up the generated document using Open Office.

If the phantom is running and the phantom thread definition record is defined to move the printed document to an archive location, then you can use the samba connection and explorer to navigate to the archive directory and to view the generated file.

Using the console can be very handy to manage your Blue Prairie Forms installation.

Other ways to edit templates:

1. Configure a Windows drive letter on your PC and then edit the templates using Open Office, Libre Office, or Microsoft Word
2. Use FTP to download the template file to your PC then edit it on your PC and upload it back to the MultiValue Host when finished

Blue Prairie Forms allows for a wide array of configuration options.   To allow documents to be processes in parallel, additional phantom threads can be defined so that many job scan be sent to your printers simultaneously.  To understand how to properly configure threading, you should understand what it does.  The following diagram will be referenced below.

Document Creation Flow (from left to right)

1. Your program calls the BP Forms API to generate a document.
2. The document is written to a queue directory. 
3. The queue directory is normally a path on the MultiValue server such as /dbms/BPIFORMS/bpi_forms/queue/bpiform1
4. One or more phantoms may poll the queue directory and attempt to process the documents placed into it in first-in, first out order.  The first phantom to find and lock the document is the winner and will process the document.  The other phantoms will observe that the document has been locked by the winning phantom and will skip the locked document and move onto the next available document.
5. The winning phantom will communicate with the BP Forms server.
   1. It will check to see that the server is alive
   2. It will check to ensure that the printer name to which the document is to be directed exists on the BP Forms server (in CUPS)
   3. It will check to ensure that the mount that allows the BP Forms server to reach into the queue directory is working
   4. If all of these checks are successfuil, the phantom will send a command to the BP Forms server to start open office, load the document and print it to the targeted printer.
6. Open office loads the document and prints it to the specified printer
7. CUPS (Common Unix Printing System) communicates with the printing device (e.g., PDF printer, Physical printer, etc) and delivers the print job to the printer.  Note that in release 4.2 of BP Forms (2025), you can now render directly to PDF without going through the CUPS PDF printer driver. 
8. Open office closes and notifies the phantom thread that the print was successful
9. The phantom returns to polling the queue directory.

What can be done to improve print performance?

Some printing problems are at the printer hardware or network level.  It is best to run printing tests independent of BP Forms to ensure that the performance problem is not network, WAN or printer device related.

If these tests show that the printer is working well, then the problem could be the speed at which the system can deplete the queue directory.  BP Forms allows for one or more phantoms to process a single queue directory.  Remember that if you place most of your documents into the same queue directory and have only one phantom polling it, then the document printing time may be impacted because BP Forms must process the printing of the document serially in first-in, first out order.  If a large document is queued, it may take some time for open office to open , print and deliver it to CUPS. This can cause documents queued after the large document to 'back up' in the queue leading to the perception that the printing is 'slow'.

Threading to the Rescue

To speed up processing, you may run several phantom threads all polling the same queue directory.  In doing so, printing will be parallelized and documents will not become 'stuck' behind a large print job.  If a large print job is being processed, the other phantoms that process that queue will simply run ahead to the next available document and process it.

If your print jobs must be processed in the order that the print jobs are created by your application, then it is best to have a single phantom thread processing that queue.  But for most printing, the order of the print jobs appearing on the printer(s) is less important than the speed of the printing.

A thread requires a unique user

Blue Prairie Forms achieves threading by calling LibreOffice on the print server.  To run multiple simultaneous instances of LibreOffice on the print server at the same time, each instance of Libre Office must be run as a different user.  This is much like running Microsoft Word or Excel on Windows.  If you login to your PC as user 'bruce' and then launch Word, it will bring up word.  But if in the same session you bring up Word again, it does not launch a new instance of Word, but rather, simply brings the existing instance into the foreground.

Libre Office and Linux work the same way.  BP Forms is designed to launch many LibreOffice instance simultaneously.  To cause multiple instances of Libre Office to launch, each instance is launched using a different (unique user).   For parallelization/threading of tasks, BP Forms requires that a unique user name, for that thread be created on both the jBASE server and on the Print Server.  While BP Forms does not care which user names are used, it is common practice to name the user(s) based on the queue they will be servicing.  For example, if your queue is /db/accts/BPIFORMS/bpi_forms/queue/bpiform1, then your username is recommended to begin with bpiform1.  By following this practice, it makes it easy to instantly recognize a process, running as a specific user, is processing that queue. 

In our example above, we have a queue named bpiform1 with a user named bpiform1.  But, if we want to have the queue bpiform1 processed by three threads (phantoms) for parallel processing, then we would:

1) Create three threads named bpiform1.1, bpiform1.2, bpiform1.3 that all process the queue bpiform1.

2) Create linux/unix users called bpiform1.1, bpiform1.2, and bpiform1.3 on both the MultiValue server and on the print server(s)

3) Establish a passwordless ssh shared key between each username on the MultiValue server and the same username on the print server.

With this done, BP Forms can freely launch simultaneous instances of LibreOffice (each with a unique user name).  This allows for parallel processing and, because of the structured and uniform naming conventions used for these users, we can observe the libre office processes running on the print server and instantly understand for each instance:

1) Which queue it is processing; and

2) which thread/phantom launched it.

For more information about configuring phantom threads, see Administrative Interfaces.

bpi.form.phantom.menu (pre version 4.1 May 2025)

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

Actions

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.

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