Template Builder

SimulScan 1.1

Overview

Template Builder is a web-based tool for creating templates, which define the information captured by SimulScan and determine how it will be processed and made available to applications. Templates are the key to controlling SimulScan data-capture features and for processing the acquired data.

This guide provides step-by-step instructions for using the drag-and-drop interface of Template Builder to create Templates and deploy them to the devices. A familiarity with SimulScan concepts and terminology is required. If necessary, please watch the short video below and review the SimulScan Glossary and About SimulScan pages before proceeding.

More SimulScan videos

Before You Begin

Before attempting to create a Template, the following assets are required:

About Templates

Most acquisition tasks involve capturing data from printed documents. These "target" documents often vary in size, shape and layout, and present a challenge for accurate data acquisition. Templates solve this problem by "teaching" SimulScan about the documents it will encounter, and defining how to scan and process data for each instance of that target document.

img

SimulScan Templates define "Form Regions of interest" on Documents to be scanned, "Field Regions of interest" within forms, and the types of data (barcode, text, etc.) to be extracted from each Field. Templates are used in all SimulScan modes. They control its ability to decode and parse data, and determine how acquired data can be consumed by an application.

A typical barcode-only form, a common and effective SimulScan usage scenario.

Structured vs. Unstructured

A Template can either be Structured or Unstructured, and generally would be created to match a structured or unstructured Target.

A Structured Template is used when the Document to be scanned (aka "Target") has a fixed layout--one that doesn't change from one instance of the form to another. Structured Templates are used to acquire mixed types of data at once (barcodes, text, images, etc.), and are generally used for Document Capture. For example, a company that often encounters a fixed-format form such as the Postal/T&L example (shown below) would create a Structured Template to identify: 1) the location of each field to be captured and 2) the type of data to be processed from each identified field.

Structured Templates are used to:

  • Scan barcodes, text and other data types from a single form
  • Invoke OCR to acquire alpha/numeric characters
  • Invoke OMR to determine the status of checkboxes
  • Detect and capture signatures and other images
  • Invoke MRZ to extract data from passports and other travel documents
  • Extract data from other key fields of interest

Unstructured Templates are predominantly used for capturing a single data type (for example, data from barcodes only). Unstructured Templates allow for target Documents that vary in layout and for target data that's located anywhere on the form. These are generally best for Multi-barcode use cases (as for the barcode-only form above).

Unstructured Templates are used to:

  • Capture only barcode data or only text
  • Scan multiple barcodes/symbologies simultaneously
  • or...
  • Use OCR to capture a single line of alpha/numeric text
  • Use OCR to capture multiple lines of alpha/numeric text

For step-by-step instructions on Template creation, see Using Template Builder, below.

Structured Templates

Structured Templates work on the principle that the location and type of data in each field of a target form (i.e. barcodes, alphanumeric characters, signatures, etc.) will remain consistent whenever the form is used, and that only the data will change with each new instance of the form. By creating a SimulScan Template to uniquely identify each region and data type, SimulScan learns what to expect from each region of a form, which allows the developer to map the data from each region to specific fields of an application.

For example, if a form like the one below was encountered regularly, a Structured Template using Mixed Data-type mode could be created to acquire the barcode, numbers, text, checkboxes and signature in a single pass. For a demonstration using this form, see the SimulScan Demo App.

Example form for a Structured Template using Multi Data-type mode.

Notes:

  • Zebra recommends using the camera for Mixed Data-type capture.
  • The camera is automatically selected when a Mixed Data-type Template is used.
  • Structured Templates are generally associated with Mixed Data-type mode.

Unstructured Templates

Unstructured Templates are useful for Multi-barcoding use cases in which the target Document varies, or when acquiring a single type of data--such as barcodes or text--from a form.

Companies could help improve scanning performance and workflow by creating an Unstructured Template that's configured only for the types of barcodes it receives on a regular basis. Multi-barcode mode can simultaneously handle a large number of 1D/2D barcodes of the same or differing symbologies, but works most efficiently if the universe of potential symbologies is narrowed to just a few.

Example form for an Unstructured Template using Multi-barcode mode.

Notes:

  • Zebra recommends using the 2D imager for capturing in Multi-barcode mode.
  • The device imager is automatically selected for Barcode-only Templates.
  • The camera is automatically selected for OCR Templates.
  • All Zebra devices that support SimulScan are equipped with 1D/2D imagers (except early TC70 models).

For example, a company that receives regular shipments accompanied with a label like the one above could create a Multi-barcode Template to map the part number and supplier number from the barcodes in the upper row, and the quantity-received information from the lower row to the corresponding fields of an application.

Using Template Builder

Template Builder is free for Zebra partners and other registered users. Existing Zebra customers, partners and ISVs with access to Partner Central can use their existing credentials to gain access to Template Builder. Others must register using the instructions below. Credentials are generally sent within one or two business days.

Note: SimulScan can be used without a License only to scan barcodes through an app using DataWedge. A SimulScan License is required for access to OCR and OMR features and/or SimulScan APIs. For more information, please see the Licensing page.

Quick Steps

Below is a summary of the steps for creating a Template. The process is explained in detail in the section that follows.

  1. Log in to the Template Builder web site.
  2. Select the Template type required.
  3. Upload an image of the Target Document to be scanned (bmp, jpg, png or PDF; 5MB max.).
  4. Identify regions of the Document and the data types (barcodes, text, etc.) of each.
  5. Save and download the completed Template(s) to the development host (local PC).
  6. Copy Template(s) to the device that will be performing the scans.
  7. Activate the Template from within DataWedge or other scanning app.

1. Create an Account, Log In

  • Visit the Zebra SimulScan registration page, follow prompts to create a free account and enter all requested information. Once an account is created, Zebra administrators will send login information to the registered address. **Zebra recommends planning ahead; this process could take several days.

  • Point a browser to simulscan.zebra.com and enter the login credentials. A screen appears similar to the image below: The Template Builder login screen at simulscan.zebra.com

2. Select Target Type

2a. Select "Structured Targets" for layouts that do not change from one instance to another (see image 2, below).

Then:

  • An Open... dialog appears
  • Select and upload an image of the Target Document for which to create the Template, observing the following parameters:
    • Supported file types: bmp, jpg, png or PDF
    • Min. res: 640x480
    • Max. res: 6000x6000
    • Max. file size: 5MB
    • For a PDF, select page number from the drop-down (if necessary)
  • Confirm that the "AutoCrop" feature (enabled by default) has accurately identified the Document boundaries (image 3).
  • If boundary adjustments are necessary, click "Disable AutoCrop" and set the Blue bounding box so that it's just outside the borders of the Document. Click "OK" when done. This creates the "Form Region of Interest" for the Document.
  • Click OK and Save the Template to proceed (image 4). Note: The Template name prefix "Default -" is reserved for system use. All other alpha/numeric combinations are accepted.
  • After saving the new Template, the uploaded image appears (image 5). Drag a box from the upper-left corner to the lower-right corner over each Region of the Document that contains data to be acquired. This creates the Field Regions of Interest.
  • When finished, configure Field settings as required.

img Click image to enlarge

Field Creation Guidelines:

  • Barcode Regions must include only the bars and spaces; no surrounding characters should be included.
  • OCR Regions should include surrounding white space equal to about two characters in width and height.
  • OMR Regions should be kept tight to Bounding Boxes. A separate OCR Region can be created to capture the name or description of the region, if needed.

Alternative ways to create Fields:

  • Select Edit --> Create New Field, enter a name for the field and draw a box around the corresponding Region.
  • Click the Add Field button (arrow, below), enter a name and draw a box around the corresponding Region.

img

2b. Select Unstructured Targets for layouts that might change from one instance to another or to acquire a single type of data.

Then:

  • Select "Multi-barcode" to capture barcodes or "OCR" for alpha/numeric text:
    • If selecting Multi-barcode, upload an image of the target Document to define the Fields and help SimulScan identify the form (image 4, below).
    • If selecting OCR, Template Builder generates a static image automatically (image 5, below).
  • Configure settings as described below.

img Click image to enlarge

3. Configure Settings

Provide (or confirm) the following required settings for each Field created:

  • A name for the field, if desired
  • Properties (length/width and X-Y coordinates)
  • The required Processing mode (barcode, OCR, etc.)
  • Specific processing-mode settings (decoder type, text type, etc.)
  • Select at least two "Anchor Elements" (explained in Step 4)

Save work often! Unsaved changes could be lost if the screen is dismissed or a session timeout is reached.

img Click image to enlarge

Field Properties Panel

In the image above, the Field Properties panel is visible in the far-left column, and presents the Properties of the selected Field. Field Properties can be configured as follows:

Field Information

Use Field to Identify Form - designates the field as an Anchor Element, which SimulScan uses to identify a form, match it with Template and configure its Field properties accordingly. By default, the data in this field is not output for Templates made for Structured Targets.

Also Read Value from Field - sets the Template to acquire data from a Field that is designated as an Anchor Element (the “Use Field to Identify Form” is checked). Enabled by default.

Field Adjustments

Width - the width of the field, in pixels Height - the height of the field, in pixels X - the horizontal position of the field, in pixels, relative to the left-most edge of the form Y - the vertical position of the field, in pixels, relative to the top of the form

Processing

Barcode - captures single or multiple barcodes in the field of view

OCR - captures alpha/numeric text

OMR - captures check marks and bubbles

Picture - captures signatures, photos or entire Documents as an image file. Minimum capturable image size is 128 x 128 pixels; maximum is 2600 x 2000 pixels.

Signature Presence - determines whether a signature is present in the selected region, displays an error to the user if none is found. Applies to Picture fields that use the OMR feature to detect a marked area.

Barcode’s location is fixed - specifies that a barcode will always be in the same location on the Document being defined by the current Template. Applies when the field processing mode is “Barcode" and the Barcode Type is set to a supported symbology (see table, below). Symbologies shown in gray are not recommended. To improve the accuracy of form identification, Zebra recommends enabling this feature whenever possible.

Fixed Barcode Supported Symbologies

img Grayed symbologies are NOT recommended for selection as fixed barcodes.

Barcode Options

Some barcode options vary based on the symbology selected. For a complete list of options, see the DataWedge Decoders guide.

Decode Data Options

Enable Character Checking - enables the barcode data to assist in the identification or verification of the barcode data being decoded. When selected, the following options become available:

  • Starts With... checks for the specified character(s) starting with the first character (index 0) of the acquired barcode data.
  • Contains - checks for the specified character(s) in the acquired data starting at the index specified in the "at" field (index 0 = the first character).
  • String Length - the number of characters the barcode data must contain. Leave blank to leave length unspecified.

Barcode Orientation -sets the orientation of the barcode relative to the scanner:

  • 0° - the barcode is right-side up on the form.
  • 90° - the barcode is rotated 90 degrees to the left (counterclockwise).
  • 180° - the barcode is upside down.
  • 270° - the barcode is rotated 270 degrees to the left (counterclockwise).

Orientation must be consistent across the entire Document.

Different or additional Field Property settings appear under certain conditions.

OCR Settings

To maximize the accuracy of character recognition in OCR regions, it's important to configure OCR parameters according to the expected input. Note: OCR capture requires the device viewfinder to be positioned directly over the text to be captured.

img Click image to enlarge

Character subsets - identifies the type of text that will be acquired:

  • All caps alphabets - text will contain all uppercase letters
  • All small alphabets - text will contain all lowercase letters
  • Only Alphabets - text contain only alpha characters (upper- and lowercase)
  • All digits - text contain only numbers
  • Alphanumeric (default) - text contain a combination of letters and numbers
  • Enter custom sub string set here - enter information about custom characters in the Custom Character Set text box

Regular Expressions - data will consistently be presented in a particular pattern (i.e. MM/DD/YYYY). Specify as a Regular Expression according to the table below:

img
Zebra recommends using this option only if the format defined can be guaranteed for the region.

SimulScan references the Perl Compatible Regular Expressions (PCRE) library for regular-expression pattern matching. Setting the character subset is easy but coarse; setting the regular expression is complex but precise. Specifying both the subset and the regex greatly narrows the range of possible candidates. Learn more by reading the Perl RegEx Man Pages.

Word Check - enables a spell-check in the selected language. Use on regions known to contain only words.

Language - English is the default. Switching to European will recognize characters typically found in European languages such as the digraph, circumflex and umlaut.

OMR Settings

The data type for optical mark recognition (OMR) is binary, resulting in the acquisition of a yes/no condition (i.e. "mark is present" or "mark is not present"). A third "undecided" state results when SimulScan is unable to recognize a mark. Use OCR to acquire the label that describes the mark, if desired.

Configure the Bounding Shape to ensure the most accurate result:

Bounding Box Shape - the shape of the object on the printed form that contains the mark to be acquired.

  • Circle - mark is inside of a circular boundary
  • Oval - mark is inside of an oval-shaped boundary
  • Square - mark is inside of a square boundary

img Acceptable marks for optical mark recognition; OMR also is used to detect signature presence.

Template Settings

The Template Settings panel is used to configure settings such as input source, flash mode, user feedback and other settings that apply generally across the Template.

To access the Template Settings panel:

  1. Log into the Template Builder web site.
  2. Open the Template in need of settings adjustment.
  3. Select Edit --> Template Settings. A dialog appears similar to the image below. img Click image to enlarge
  4. Adjust settings as needed according to descriptions that follow the image below: img
Template Settings Panel

Input Source – used to specify the input source (Camera or Imager) to use for the Template. Selecting "Default" allows the system to choose the input source as follows:

  • Selects Camera for Structured and Unstructured targets
  • Selects Imager for Barcode-only targets
  • If no Imager is present, the camera is selected for all targets
  • If camera is disabled, Imager is selected for all targets
  • If no capture device is available, an error message is displayed

Flash Mode – enables/disables use of the flash during capture.

Audio Feedback – plays a sound when data is acquired (enabled by default).

Haptic Feedback – operated the vibrator when data is acquired (enabled by default).

LED Feedback – lashes the LED when data is acquired (enabled by default).

UI Result Confirmation - forces a user confirmation before sending acquired data to app (disabled by default for Barcode-only targets; enabled by default for Structured and Unstructured targets).

Identification Timeout – sets the maximum time allowed to attempt to identify a target Document.

Processing Timeout – sets the maximum time allowed to process a target Document after it has been identified.

Automatic Image Capture – automatically triggers form processing, once identified. Uncheck to force the user to manually trigger form processing (once identified) by tapping or pressing the trigger button.

Auto Capture Sensitivity – sets the sensitivity of the auto capture from 1-10 (most sensitive). Valid only when Automatic Image Capture is enabled.

Output Entire Form – outputs an image of the entire form along with the extracted data. Valid only for Structured Targets. Enabling this feature affects scanning performance.

Advanced Image Correction – enables image correction for parsing targets that are slightly curved or crumpled.

4. Select Anchor Elements

In addition to its use of Document border dimensions, SimulScan can use Fields, company logos and other unique attributes of a Document to positively identify it and determine its orientation relative to the scanner (i.e. whether it's upside down). These so-called Anchor Elements also can contain data to be acquired, such as a barcode or image, though it is not required. Zebra recommends that at least two Anchor Elements be identified in accordance with the guidelines below.

Selection Guidelines:

  • Select two or three Fields per document as Anchor Elements.
  • Anchor Elements should be spread across the top, bottom and side(s) of the Document.
  • Draw Fields loosely around graphics and tightly around barcodes; white space helps with identification of graphics but can cause errors for barcodes.
  • For Structured Targets, static fields such as logos and preprinted content work well.
  • Anchor Elements need not contain data to be acquired; the "Also Read Value from Field" parameter is optional.
  • For Anchor barcodes:
    • Draw Fields tightly around barcodes; leave no gaps outside the bounding box.
    • Barcodes with a fixed location and size on all instances of a form work best.
    • Select the “Barcode’s location is fixed” option in the Properties panel.
    • Select symbologies with uniform numbers of digits to ensure consistent region size.
    • Avoid symbologies with multiple level/stack/region barcode combinations (which may vary in region size).
    • Zebra recommends using only the following barcodes for fixed-mode: img Grayed symbologies are NOT recommended for selection as fixed barcodes.

In the Postal T&L Document below, the logo in the upper-left corner and the barcode in the upper-right would identify this form adequately for SimulScan to activate its template. Notice that the graphic is loosely bounded and the barcode tightly. img Draw Fields tightly around barcodes and loosely around graphics for best results.

When using a fixed barcode as an Anchor Element, be sure to select “Barcode’s location is fixed” in the Properties panel, as below: img This attribute appears only in Templates for Structured Targets that use a non-postal symbology.

5. Test and Validate Template

Zebra recommends testing all Templates before deployment to devices to ensure proper operation. This can be done using the SimulScan Demo App. Template Builder also provides a Validation feature, which verifies template Fields and returns useful information about Field properties and settings. Both are explained below.

To test a Template using the Demo App:

After pushing the Template to a device...

8. Open the SimulScan Demo App, tap on the "Hamburger" menu, and select Menu -> Setup Custom Demo options, and navigate to the Template to be tested.

Verify that the Template works as expected.

To Validate Template:

9. Open the Template to be validated and select Edit...Validate Template.

img

A Validation Summary is displayed with one of more of the following messages:

Form Decoded:

  • The Template successfully identified the target Document.
  • At least two fields have been designated as Anchor Elements.
  • Barcode Field(s) designated as “Use field to identify the form" use a supported symbology and its length is within the supported range.
  • The uploaded image of the target Document is clear and its resolution is correct.

Key field(s) identified in template:

  • Required attribute(s) (i.e. name, number, x/y, width, height) found for each marked region.

Field setup and data parsing

  • Fields cover the valid vicinity of all data of interest.

Final result:

  • (√) = "Success!"
  • (X) = "Error!"

Validation Preview

Following validation, test results can be reviewed by clicking on “View Preview” button as in the image below.

img

The image below shows a validation preview. Clicking on any Field in the image area displays in the left-hand column the data that is parsed by that Field. In addition to decoded output, OCR data also shows the accuracy level (high, medium or low) for each line of the region parsed. Regions designated as OMR indicate their status (Checked, UnChecked or Undecided).

img Click image to enlarge

6. Deploy Templates

After settings are configured and validated, select File -> Download Template to download a copy to the local development host:

img

Once downloaded, the Template can be deployed to scanning devices.

Warning: Do not attempt to modify the Template file by hand. Templates contain machine-generated XML stored in Base64-encoded files, and are not intended to be edited manually.

How and Where to Place Files

If using SimulScan through DataWedge, Template file(s) must be in the directory shown below.

For DataWedge:

  • /enterprise/device/settings/datawedge/templates/

For the SimulScan Demo App:

  • /sdcard/simulscan/templates/

For a custom app:

  • Any device folder accessible by the app, or...
  • In /templates/release/ on the Template Builder server (see FetchTemplate(), below)

Note: All files in /enterprise/ on the device will persist following an Enterprise Reset.

Methods of Template deployment:

  • Manually via USB cable to the device using the Android Debug Bridge (ADB)
  • Remotely using StageNow and the UI Manager service
  • Remotely through a company's own mobile device management (MDM) system (if supported by that system)
  • Programmatically through EMDK for Android development tools

Using the FetchTemplate() method call

Templates saved to the /<accountID>/templates/release/ folder on the Template Builder server can be retrieved programmatically through EMDK APIs using the FetchTemplate() method. Use Template Builder to identify the exact path name when calling the method.

For example, the path to the server-based Templates folder from the image below would be:

  • /myAccount/templates/release/<template name>

img

To add a Template to the /release folder:

  1. Open the Template
  2. Select Edit --> Release Template

A copy of the Template is placed in the /release folder; the Template also remains in its original location. When the method is called, the specified Template is copied to the device.

Modify a Template

Existing Templates can be modified to address changes that occur to incoming Documents, to allow for workflow changes, to make adjustments to OCR or other settings based on input from the field, or for any other reason.

Warning: Do not attempt to modify the Template file by hand. Templates contain machine-generated XML stored in Base64-encoded files, and are not intended to be edited manually.

To modify an existing Template:

  1. Log into the Template Builder web site.
  2. Click the Open Template button or select File -> Open Template to Open the template to be modified.
  3. Edit Template settings as required.
  4. Save using File --> Save Template or File --> Save as... to create a new version.
  5. Test, Validate and Deploy as explained above.

img

Create a Multi-Template

The optional Multi-template feature allows as many as six (6) existing Templates to be grouped together and deployed to devices as a single entity. This simplifies deployment and can help boost worker productivity on devices that regularly use two or more Templates by automating Template selection. For example, if workers in a warehouse regularly encounter scan Documents from three specific suppliers, grouping the corresponding three Templates together quickens the selection of the appropriate Template whenever scanning is required.

To Create a Multi-template:

After creating the Templates needed for grouping...

1. Select File --> Create New...Multi Template: img

2. Enter a name for the Multi-template: img

3. Click "+ Add Template" button. A dialog appears similar to the image in Step 4. img

4. Select the location of the Template to be added: img If a new Template is required, click the "Create new template" button.

As Templates are added, thumbnails will appear in the far-left column and field names of the selected Template in the center column. Actions taken in this mode will apply to the selected Template. img

5. Repeat Step 4 until all required templates are added (max = 6).

6. To deploy Multi-template(s), see Deploy Templates section, above.

Related Guides: