This document is intended for two distinct audiences: users who plan to write reports for use with xTuple ERP and developers who plan to implement new windows or expand the bar code data entry capabilities of existing windows.

To make full use of this document, you need a printer capable of producing bar codes in several formats, a scanner that can read them, and access to the application and database. Most printers capable of producing graphics, such as ink jet and laser printers, will work. Developers also need a development environment. Directions on setting up a development environment can be found in Development Environment Setup.

OpenMFG Bar Code Basics

The key to understanding how the xTuple ERP application works with bar codes is that bar code scanners are connected to the user's computer or terminal as a second keyboard. The application needs extra information to distinguish between data scanned by the bar code reader and data entered manually.

When a person scans a bar code off a commercially available product, such as the UPC label on a grocery item, that bar code simply encodes a stream of letters and digits. If that person is running the xTuple ERP application, the bar code data are entered into the currently active field on the screen. This document will refer to these as "simple" bar codes.

For keyboard-free operations the bar codes to be scanned need additional information to tell the application that they are application-specific and what kind of information is embedded in the bar codes. This document will refer to these as "smart" bar codes.

Report Writers

OpenRPT, the report writing engine embedded in the xTuple ERP application, supports a number of bar code encodings, such as UPC A and 3 of 9. To put a bar code on a report, use the bar code field type on the form designer.

If the report is for external use, such as a packing list, then use a simple bar code. Make sure your query selects the field you want to represent. Click the bar code icon from the toolbar or select Insert -> Bar Code from the menu bar, then click on the report form to place the bar code in the desired location. Edit the properties of the bar code field to associate the field with the desired encoding scheme, query, and query column.

If you are writing a report for internal use then you should use a smart bar code. As with a simple bar code, insert your bar code field in the report and set its properties. However, the query needs to be different and the encoding scheme choices are restricted. You much choose a bar code format that handles control characters; xTuple recommends using the 128 encoding. The query must use one of the existing stored procedures that generates smart bar code values. At this time these are limited to the following:

If you want both simple and smart bar codes, the query should get the data in both forms. For example a report which will be used as both an in-house pick list and a packing list to be enclosed with a shipment should have two bar code fields and a SELECT statement that looks like this:

SELECT cohead_number, formatSoBarCode(cohead_id) AS cohead_barcode, ... WHERE cohead_id = <? value("cohead_id") ?>
...

This makes available to the report both the Sales Order Number for the recipient to scan and the smart bar code content for in-house use.

Application Developers

Window development

Just as there are simple and smart bar codes, the application window can be either naive in its handling of bar codes or sophisticated. To handle simple bar codes the application does not need any modifications, although this imposes a requirement on the user: s/he must focus on the correct field in the window before scanning. Smart bar codes require less user interaction but more software to make up for it.

There is a Qt event filter in the application that specifically anticipates smart bar code input. This is implemented in the InputManager class. The OpenMFG application instantiates only one InputManager object, which is available as omfgThis->inputManager(). A window that will receive smart bar code input must have a Qt slot to handle the input and a connection to the nputManager, such as the following:

windowClass::windowClass(QWidget* parent)
    : parentClass(parent)
{
    ...
    omfgThis->inputManager()->notify(cBCWorkOrder, this, this, SLOT(sWoidScanned(int)));
    ...
}
...
void windowClass::sWoidScanned(int pwoid)
{
... // do something interesting with the work order id
}

The slot to which the wo_id in this example is sent does not need to be implemented in the windowClass itself. It could just as easily be a slot in one of the widgets on the window:

    ...
    omfgThis->inputManager()->notify(cBCWorkOrder, this, _wo, SLOT(setId(int)));
    ...

The first argument of the inputManager's notify method is a symbolic constant. See the source file OpenMFGGUIClient/inputManager.h for a list of values.

Adding a new field to be barcoded

If the feature you are developing needs to define a new smart bar code, you write a new stored procedure to format the bar code and modify the InputManager class.

The new stored procedure is fairly simple:

ormatWhateverBarcodeintegerreturns text.

The integer parameter is the internal ID of the record you want bar coded. The return value is a text string with the following format:

• Signal character: \138

• Bar Code Type Identifier: A 4 character code that must uniquely identify the nature of this bar code's contents. These are defined and associated with the cBC* named constants in the _eventList array.

• Field Lengths: A list of integer values describing the length of the data to come. There must be one length value for each text field that will be embedded in the bar code.

• Text Fields: A list of text values representing the actual data to be embedded in the bar code.

The body of the stored procedure should build this text string and return it. In most cases this will be simply a matter of writing a SELECT statement that returns a single row, which consists of a concatenation of the desired data.

To change the InputManager class, add a new constant and a new read* signal to inputManager.h, choose a bar code type identifier string and add it to the _eventList array, modify the eventFilter method, and write a dispatch method.

[Need text here to describe how to do each of these things.]

Existing Bar Code Functionality

Here's how to use the existing smart bar codes: