Custom transactional forms with Crystal Reports

Invoices, pick tickets, packing lists, purchase orders, order acknowledgements and statements are the parts of Prophet 21 your customers and suppliers see. Nearly every distributor customizes them: a logo, remit-to details, customer part numbers, terms and conditions, a barcode for the warehouse. The pattern below keeps those changes safe across upgrades.

Conceptual on purpose

The exact file names, folders and settings depend on your version, so confirm them in your own environment before you change anything.

How transactional forms work

When a user prints or emails a document from a transaction, Prophet 21 gathers the data for that document and passes it to a report design, built in Crystal Reports in most installs. The design decides the layout: where fields go, how numbers are formatted, what is suppressed and what repeats per line.

That separation is the most useful thing to understand about forms:

Part	Responsible for
Prophet 21 software	Which data is supplied
The form design	How that data is presented

When a form prints something wrong while the transaction is right on screen, the fault is almost always in the presentation layer: a formula, a format setting, a suppression condition or a field placed in the wrong section.

Change a custom copy, never the original

Prophet 21 ships standard form designs. To change a form safely, leave the standard design as shipped and work on a copy:

1. Copy the standard design to a custom file, following the naming and location convention your version expects for custom forms.
2. Point Prophet 21 at the custom copy for the document type, and where needed for the company, location or customer the change applies to.
3. Edit only the copy.

The standard design stays untouched, so an upgrade can replace it without destroying your work, and you always have a clean reference to compare against. If the custom copy misbehaves, pointing back to the standard design is a quick, low-risk way to confirm whether the problem is in your changes.

Do not edit the shipped design

Editing a standard design directly is the most common way form customizations are lost. An upgrade or repair can overwrite the file, and nobody notices until customers receive plain invoices.

Keep changes upgrade-safe

Upgrades can change the data Prophet 21 hands to a form: fields may be added, renamed or retyped. A custom form that leans on specific fields and clever formulas is more likely to break. These habits keep the risk low.

Change the minimum

Make the smallest change that meets the requirement. Moving a field, adding a label or adding a conditional section is easier to carry across versions than restructuring the whole design. If a form needs a complete redesign, treat it as a new form with its own documentation.

Prefer supplied data over extra queries

A form can be made to fetch additional data itself, with extra database connections or subreports that run their own queries. Sometimes that is necessary.

Every such addition is a dependency on the database structure. It also runs once per document, which can slow printing for large batches. Use the data Prophet 21 already supplies first, and document any additional query the form runs.

Keep formulas simple and named clearly

Formulas are where subtle defects live. Give them names that describe their purpose, keep each one short and avoid formulas that depend on other formulas several levels deep.

When a number must be formatted for display, do the arithmetic on numbers and format as the last step. Converting a number to text and back is a classic source of wrong totals.

Record every change

For each custom form, keep a short record:

Item	Example entry
Document type	Invoice
Custom file	The file name and location
Assigned to	All companies, or which company, location or customer
Change summary	Added customer part number column, remit-to block for second company
Requested by	Name and date
Last tested	Version and date

Keep the custom files themselves in version control or at least in a dated archive. A form design is a binary file, so you cannot diff it easily, but you can always restore the version that worked.

Retest after every upgrade

After an upgrade, print each custom form from the play environment before production users do. Compare it side by side with the same document from before the upgrade. Pay particular attention to totals, taxes and anything conditional.

Test a form change with documents chosen to break it

Test with documents chosen to break things, not with whatever order is handy. The table lists the cases we use.

Test case	What to look for
Large values	Lines and totals with thousands separators and many digits
Many lines	Enough to force two or three pages, so you see headers, footers and page totals repeat correctly
Zero and negative values	Credit memos, free goods and returns
Long text	Long item descriptions and notes that wrap
Every assignment	If the form varies by company, location or customer, print one of each
Every output	Print, email and any other delivery method you use. Fonts, margins and page size can behave differently

Do this in the play environment with realistic data, and have someone from the business, not the developer, sign off that the output is right.

Common pitfalls with custom forms

• Editing the shipped design. Always work on a custom copy.
• Hard-coded values. A phone number, address or tax rate typed into the form instead of read from data. It will change and nobody will remember where it lives.
• Suppression logic that hides problems. Suppressing a section when a value is zero can also hide a line that should have printed.
• Fonts that are not installed on the server. A form that looks right on a developer workstation can shift or substitute fonts where it runs.
• One giant form for every case. Past a certain number of conditions, separate forms assigned to the right companies or customers are easier to maintain than one design full of branches.

Next steps

If you inherit a system with customized forms and no documentation, start with an inventory: list each document type, whether it points to a standard or a custom design and where each custom file lives. That single table tells you what you are responsible for and what an upgrade will put at risk. For a broader view of where forms sit in the system, see How a Prophet 21 system fits together.