Papers

"Papers" are all documents and labels that Boxture produces: carrier labels (waybills), packing lists, pick lists, SSCC labels, container and tote labels, commercial invoices and any other document you design yourself. Boxture stores every paper it produces with the record it belongs to, and can send it straight to a printer in the warehouse.

There are two sources of papers:

• Carrier labels come from the carrier integration. When a shipment gets its waybill, the label returned by the carrier is stored as a paper and printed.
• Template papers are generated from templates you set up under Admin › Papers › Templates. A template says: "when this event happens on this kind of record, generate this document". Templates for labels are written in Liquid (for example ZPL code for Zebra label printers), templates for documents in Ruby using the Prawn PDF library.

Boxture does not come with standard templates: each account sets up the documents it needs. Templates of a parent account also apply to all its child accounts.

Where papers appear

• The Papers screen (the Admin › Papers menu item, or the Printed tile on the dashboard, which shows the papers you generated) has two tabs: Papers, all papers, and Print jobs, every attempt to print a paper with its state.
• The order page, shipment page, pick list page, and the container and tote edit pages each have a tab listing the papers of that record (for an order: also the papers of its shipments and parcels).

Every paper in these lists has these actions:

Action	What it does
Preview	Opens the paper. PDF documents open as they are; labels (ZPL) are converted to a PDF image of the label, using the label size of the template.
Print	Sends the paper to your own printer. If someone else generated the paper, a copy is made with you as owner and printed on your printer.
Regenerate	Generates the paper again from its template with the current data of the record, for example after you corrected an address.
Print consolidation	For papers produced as part of a batch (see Print consolidation), prints the whole batch again as one job.

When papers are generated

Templates are linked to a Klass (the type of record) and an Event. These are the record types and events you can choose:

Klass	Events
Shipment	paperwork_generated, pending, hold, release, label, labelled, ship, shipped, deliver, cancel, plus create, update, save, destroy
Order	confirm, pending, allocate, unallocate, backorder, picking, pick, unpick, pack, unpack, ship, expect, receive, build, complete, cancel, hold, release, plus create, update, save, destroy
PickList	assign, unassign, start, pick, unpick, reallocating, reallocate, cancel, complete, redo, plus create, update, save, destroy
Container	pick, unpick, pack, unpack, transit, receive, retire, unretire, plus create, update, save, destroy
Tote	activate, disable, plus create, update, save, destroy
Parcel	create, update, save, destroy

A state event fires when the record makes that transition, for example complete when a pick list is completed. create fires when the record is created, update when it is changed, save on both, destroy when it is deleted.

The most important events in practice:

• Shipment › paperwork_generated fires right after the carrier label of a shipment has been created (see Labels and documents), and after the paperwork of a return shipment has been created. This is the moment for packing lists, commercial invoices, customs documents and SSCC labels: the shipment then has its parcels and tracking numbers.
• Order › hold fires also when an order is put on hold by hand, see Holds.
• PickList › complete is used for a pre-pack list that shows what was actually picked from which container and bin location.
• Container › create and Tote › create are used for labels of new containers and totes.

Carrier labels

When Boxture requests a waybill from the carrier, the label in the carrier's response is stored as a paper with use label and purpose waybill, attached to the shipment. ZPL labels are stored as raw label data, other labels as PDF. The paper is printed like any other paper, on your label printer. After that the shipment moves to labelled and the paperwork_generated event fires. See Shipments and Carriers.

Printing

Boxture prints through PrintNode, a service that connects printers on a warehouse computer to the web. The PrintNode client is installed on the computer that the printers are connected to. Boxture fetches the computers and printers from PrintNode every 15 minutes.

Setting up your printers

Each user sets up their own printers in their profile, on the Printing tab:

1. Select the Current computer: the computer you are working at.
2. Add a preferred printer for each use: one for Document (for example an A4 laser printer) and one for Label (for example a Zebra label printer). For each, choose the computer and the printer.

What gets printed where

When a paper is created, Boxture prints it automatically if:

• the paper has an owner, which is the user whose action generated it, and
• that user has a preferred printer for the paper's use (Document or Label) on their current computer.

A paper generated by a background process without a user, or by a user without a matching printer, is stored but not printed. You can print it later with Print.

The number of Copies set on the template is printed.

Print jobs

Each print attempt is a print job. Its state is:

pending → printing → printed, or error when PrintNode reports a problem.

Print consolidation

When many papers are created in one go, Boxture collects them and sends them as one print job instead of dozens of separate jobs. This happens with Bulk pack and ship, where the labels of an order are printed together, and with Imports, where all papers generated by the rows of an import are printed together when the import has finished.

Templates

Go to Admin › Papers › Templates and click New. The Basics tab has these fields:

Field	Description
Enabled	Only enabled templates are used.
Account	The account the template belongs to. It applies to that account and its child accounts.
Description	Name of the template. Also used as the default file name.
Purpose	Free text describing what the paper is, for example packlist, sscc_label or commercial_invoice. Shown with the paper.
Kind	PDF for documents written in Ruby with Prawn, Liquid for text-based output such as ZPL labels.
Use	Document or Label. Determines which of the user's preferred printers is used.
Copies	How many copies to print.
Klass and Event	When the template is used, see When papers are generated.
Condition	Optional Liquid. If it outputs false, f, 0 or off (in any case), the template is skipped. If it is empty or outputs anything else, the template is used.
File name template	Optional Liquid for the file name, without extension.
Data	The template itself: Ruby (Prawn) for PDF, Liquid for labels.

Other tabs:

• Media: upload files the template needs, such as a logo or fonts. A PDF template opens them by file name with open('logo.png').
• Example data: JSON with example values. When filled in, a Preview button generates the paper from it, so you can test without triggering the event.
• Metadata: YAML with options. For labels, width and height (in inches) and dpmm (dots per mm) set the label size used for the preview; the defaults are 4 × 8 inches at 8 dpmm. For PDF templates the metadata is passed to Prawn as document options, for example the page size.
• Papers: the papers generated with this template.

WARNING

A template set up on a parent account applies to every child account. Use a Condition or set the template up on the child account when it should only apply to some.

Condition examples

Only for B2B orders on a pick list:

{% assign business_models = pick_list.orders | map: "business_model" %}{% if business_models contains 'b2b' %}true{% else %}false{% endif %}

Only for export shipments:

{% if shipment.export? %}true{% else %}false{% endif %}

Label templates (Liquid)

A Liquid template produces text, typically ZPL for a Zebra printer. The record is available under its name: shipment, order, pick_list, container, tote or parcel.

Example: an SSCC label for each parcel of a shipment, with Klass Shipment, Event paperwork_generated, Kind Liquid and Use Label:

{% for parcel in shipment.parcels %}
^XA
^CF0,40
^FO20,50^FD{{ shipment.origin.company_name }}^FS
^CF0,30
^FO20,115^FD{{ shipment.origin.address_lines }}^FS
^FO20,155^FD{{ shipment.origin.postal_code }} {{ shipment.origin.city }}^FS
^FO450,50^FD{{ shipment.destination.company_name }}^FS
^FO450,115^FD{{ shipment.destination.address_lines }}^FS
^FO450,155^FD{{ shipment.destination.postal_code }} {{ shipment.destination.city }}^FS
^CFA,30
^FO20,280^FDSSCC:^FS
^FO20,320^FD{{ parcel.sscc }}^FS
^FO200,700^BY4^BCN,256,Y,N,Y,N^FD>;>{{ parcel.sscc }}^FS
^XZ
{% endfor %}

The SSCC of a parcel contains the account's GLN (company prefix), set on the account. Without a GLN that part of the SSCC is zeros. See Accounts.

A container label with Klass Container and Event create:

^XA
^CF0,60
^FO50,50^FD{{ container.name }}^FS
^FO50,150^BY3^BCN,200,Y,N,N^FD{{ container.name }}^FS
^XZ

Document templates (PDF)

A PDF template is Ruby code that draws the document with Prawn on the pdf object. The record is available as a method with its name (pick_list, shipment, order, …). Useful helpers:

• open('file name') opens a file from the Media tab (images, fonts).
• t('key') translates using Locales; l(date, format: '%d-%m-%Y') formats a date.
• pdf.barcode('code_128', value) draws a barcode.
• method(:name) { ... } defines a helper you can reuse in the template.

A short example of a packing list for a shipment:

logo = open('logo.png')
pdf.image logo, width: 40.mm if logo
pdf.text 'Packing list', size: 24, align: :right
pdf.move_down 10.mm

pdf.text "Shipment: #{shipment.name}"
pdf.text "Reference: #{shipment.customer_reference_number}"
pdf.text "Date: #{l(Date.today, format: '%d-%m-%Y')}"
pdf.move_down 5.mm

pdf.text shipment.destination.company_name.to_s, style: :bold
pdf.text shipment.destination.address_lines.to_s
pdf.text "#{shipment.destination.postal_code} #{shipment.destination.city}"
pdf.move_down 10.mm

rows = [['Product', 'Name', 'Serial number']]
shipment.parcel_items.each do |item|
  rows << [item.product_number, item.product_name, item.serial_number]
end
pdf.table(rows, header: true, cell_style: { size: 8 })

If a template contains an error, the generated paper contains the error message instead of the document, so you can see what went wrong.

Available variables

Both kinds of templates use the same variables. The most used ones are listed below; the same objects are available in messaging templates, see Messaging › Liquid variables for orders, order lines, contacts, products and accounts.

Shipment

{{ shipment.name }} {{ shipment.state }} {{ shipment.kind }}
{{ shipment.tracking_number }} {{ shipment.return_tracking_number }}
{{ shipment.carrier.name }} {{ shipment.service_type.name }}
{{ shipment.ship_at }} {{ shipment.delivery_terms }}
{{ shipment.customer_reference_number }} {{ shipment.purchase_order_number }}
{{ shipment.origin }} {{ shipment.destination }} {{ shipment.billing }}
{{ shipment.importer }} {{ shipment.exporter }}
{{ shipment.order }} {{ shipment.orders }}
{{ shipment.parcels }} {{ shipment.parcel_items }}
{{ shipment.account.name }} {{ shipment.account.gln }}
{{ shipment.export? }}

Parcel and parcel item

{{ parcel.position }} {{ parcel.sscc }} {{ parcel.tracking_number }}
{{ parcel.physical_packaging }} {{ parcel.description }}
{{ parcel.human_weight }} {{ parcel.human_dimensions }}
{{ parcel.container }} {{ parcel.parcel_items }}

{{ parcel_item.product_number }} {{ parcel_item.product_name }} {{ parcel_item.kit_product_number }}
{{ parcel_item.serial_number }}
{{ parcel_item.price }} {{ parcel_item.price_currency }}
{{ parcel_item.customs_value }} {{ parcel_item.customs_value_currency }}
{{ parcel_item.hs_code }} {{ parcel_item.eccn }} {{ parcel_item.un_number }} {{ parcel_item.origin_country_code }}
{{ parcel_item.weight }} {{ parcel_item.weight_unit }}

Pick list

{{ pick_list.name }} {{ pick_list.state }} {{ pick_list.created_at }}
{{ pick_list.location }} {{ pick_list.user }}
{{ pick_list.pick_list_wave }} {{ pick_list.pick_list_plan }}
{{ pick_list.orders }} {{ pick_list.order_lines }} {{ pick_list.totes }}
{% for line in pick_list.pick_list_lines %}
  {{ line.position }} {{ line.product.number }} {{ line.bin_location.name }} {{ line.lot }} {{ line.status }}
{% endfor %}

Each pick list line also has line_details: per picked quantity, the order, container, bin location and quantity it was picked for.

Container and tote

{{ container.name }} {{ container.state }}
{{ container.location }} {{ container.bin_location.name }}
{{ container.packing_material.name }} {{ container.parent }} {{ container.children }}
{{ container.products }} {{ container.inventory_items }} {{ container.product_account }}

{{ tote.name }} {{ tote.human_weight }} {{ tote.location }} {{ tote.account }}

Bin location and packing material

{{ bin_location.name }} {{ bin_location.purpose }} {{ bin_location.zone }} {{ bin_location.aisle }}
{{ bin_location.rack }} {{ bin_location.shelf }} {{ bin_location.section }} {{ bin_location.walkway }}

{{ packing_material.number }} {{ packing_material.name }} {{ packing_material.level }}
{{ packing_material.physical_packaging }} {{ packing_material.weight }} {{ packing_material.weight_unit }}

In addition, owner is the user who generated the paper and locale the language.

Locales

Admin › Papers › Locales holds translations for paper templates, so one template can produce documents in several languages. Create a locale with a Key and the translations in Data as YAML, with the language code at the top:

en:
  packing_list: Packing list
  reference: Reference
nl:
  packing_list: Paklijst
  reference: Referentie

Use them with t('packing_list') in a PDF template, or with the t filter in a Liquid template:

{{ 'packing_list' | t }}

The paper is generated in the language of the session in which it was triggered.