BP Forms interface programs are written in MultiValue basic and may include some unix scripts.   These will be found in the BPI account in the bpi.bp.form directories.  These routines should be cataloged into each account where it may be used  (except on UniData systems where the policy is to catalog all programs using GLOBAL mode cataloging in which case, cataloging in each account is not required).  Some low level libraries in bpi.bp may be called although most low level routines are now renamed and found in bpi.form.bp to isolate them from other modules.

Note: on Unidata, programs should be compiled with the -D switch and cataloged GLOBALLY

General Approach

Blue Prairie Forms can be utilized in a number of ways.  Each approach trades ease of implementation and functionality.  The easiest approach is to capture an entire print job and simply toss it onto a template.  The drawback of this approach is that the content of the print job is one large object and, as such, no specialized styling can be done with specific parts of the print job.  To have the capability of applying unique styling (e.g., fonts, colors, etc.), you must separate the elements of the print job.  For example, if the customer’s name was its own object and given a name such as %customer_name%, the, you could insert the placeholder tag %customer_name% into the template and apply unique styling just to that placeholder tag.

Preferred Approach

In order to gain maximum control over the styling of your printed output, we prefer the technique of breaking the print job into many placeholders.  This approach requires more time up front.  With a form of moderate complexity, the easier approach might require less than an hour of programming/integration while the preferred approach might take a few hours, the benefit of having full control to style each element make the moderate amount of additional effort worth while.

Using Legacy Printing Logic

Forms development requires two fundamental steps:

• Painting of a form template using Open Office
• Creation of host-side logic to generate the print job

Step two, the creation of host side logic, can be approached in a number of ways:

Fresh Program

You can create a program or subroutine from scratch that gathers information and calls Blue Prairie Forms to print it.  While this results in a clean, streamlined program, it requires that the developer more fully research and understand the rules that produce the output.

Modify Legacy Program

Another approach is to copy the legacy print program that currently produces the legacy printed output and modify it to use Blue Prairie Forms API calls.  The downside of this approach is that your print program will retain some of the programming style of the legacy program.  The degree of this downside will be determined by the quality of the legacy code.

The upside of this approach is that all of the specialized logic within the legacy print program will be retained and used.  As a developer, you will not need to research and understand what the print program does or why it makes certain decisions about what to print.  You simply follow the design pattern of the legacy code and replace legacy PRINT directives with Blue Prairie Forms api calls.

Changes to Legacy Code

In order to ensure that you do no harm to the legacy print programming system, we suggest that you make a copy of the legacy print program or subroutine then make the Blue Prairie Forms modifications to the copy.

We recommend that you follow these best practices when making modifications to the copy of the legacy program:

Commenting Convention

1. Never remove or alter an original instruction. If it is to be disabled, you may comment it out in its unaltered state.  We recommend adding a descriptive comment tag like *|||BPIFORMS||| to clearly indicate to a future reader that you intentionally commented out the instruction for the purpose of integrating Blue Prairie Forms
2. For all added instructions, please suffix the instruction with a comment like ;*|||BPIFORMS||| to indicate that this instruction was added for Blue Prairie Forms integration.

Other Conventions

• Name the copy with a standard prefix. For example, of the legacy program was called INVOICE.PRINT, then your copy would be called <prefix>.INVOICE.PRINT.  Prefix may be anything you wish so long as it is unique and would not collide with other existing programs.  The author uses the prefix BPI (which stands for Blue Prairie, Inc.) for all Blue Prairie programs.
• Follow commenting convention rules defined above.
• Look for and comment-out all PRINTER ON, PRINTER CLOSE, PRINTER OFF directives in the program. If the print program does not contain any of these, then you may need to look into the calling program to determine if it performs the PRINTER directives.  Using the preferred integration method, we do not want to send any printed output to the spooler.
• Look for and comment-out all PRINT statements.  Below each commented PRINT directive there should be a Blue Prairie Forms API call added.  The general idea is that rather than printing a value to a large print job, you will instead assign that same printed value to a placeholder tag name that will be injected into the form template.
• Add the Blue Prairie Forms subroutine block to the bottom of the program. These internal subroutines provide a stock template that can be modified to perform common tasks such as referencing a template, declaring output form filenames and converting repeating arrays (e.g., repeating lines in a form) into properly formatted repeating tag (see repeat tags).

Testing

Once the integration routine has been written and compiled, you will need to test it.  Many MultiValue users do not have a development system so care must be taken to ensure that you do not disrupt legacy printing while you are debugging and testing your new Blue Prairie Forms integration.

To facilitate this testing, the author generally defines a new printer queue on the MultiValue system that is design only for testing.  We then add logic into the legacy program which determines whether a print job should be routed through the legacy print program or to the new Blue Prairie Forms integration.  A  useful API is provided called bpi.checkEnabledQueue which allows you to create simple parameter files stored in MultiValue directories or hashed tables.  These param files can be a great aid as you work to test the integration with minimal disruption to your production workflows.