Common Label Augmentations
Create common augmentations for shipping labels.
About common label augmentations
Your organization may need to customize labels to enable minor changes or insertions on carrier labels. Shipium advises using caution when augmenting labels as you'll likely need to obtain approval from any carriers whose labels you're augmenting. This document provides a few basics about Zebra Programming Language (ZPL) printing and details about common use cases and examples for creating label augmentations.
Label Augmentations
If you haven't already looked at Label Configuration , specifically the section "Maintain and make changes to label properties and augmentations", then start there to get additional label background. Likewise, Label Customization maybe be useful for additional context.
ZPL basics
- Don't know ZPL? Download Zebra's ZPL tutorial and read through at least the first few pages to get some basics.
- Here's a quick and easy ZPL Command listing. You might need to look up details after that, but this is a good starting place to quickly find what's available.
- Need to get into command details? No problem. Take a look at the Official Zebra ZPL Guide, which has more details than you will ever need.
When you add ZPL to a label augmentation, you DO NOT include
^XAor ^XZ. Those are handled by our template engine.
ZPL anti-patterns
The most important thing to know about ZPL commands is that some of them can impact other labels.
For that reason, be careful not to include anything in a label that permanently changes settings on the printer. As an example, the ^PO command sets label orientations. This is handy if you need to print a label (or a portion of a label) inverted. However, as the documentation states, Once the ^PO command is sent, the setting is retained until another ^PO command is received or the printer is turned off. This means if you don't re-set the direction of printing, EVERY FUTURE LABEL WILL ALSO BE INVERTED. Thus, if you don't want this type of setting applied to all future labels, you'll need to make sure that you undo anything permanent.
If you're not sure, you can check the ZPL documentation to understand the scope of a given command.
Common augmentations
Some of the most common label augmentations are described below.
Direction / Orientation
A common task is to flip the vertical orientation of the label so that it is printed in the desired direction for either a user station or a printer that is part of a material handling system (MHE), like a tamper or other print-and-apply (PNA) equipment. ZPL provides two ways to do this, which you should generally do as a pre augmentation:
^PON- force "normal" orientation^POI- force "inverted" orientation
Position of elements
In order to position elements in ZPL, you generally wrap them in an ^FO...^FS pair, which sets the top-left position of the next command to be produced.
The format of the pair is ^FO<x>,<y>,<alignment> ... ^FS:
<x>is the x position starting from 0 on the leftmost position.<y>is the y position starting from 0 on the topmost position.<alignment>can be generally ignored and defaults the currently set value configured via^FWor defaulted for the label.
Fonts and text
The ^CF command can be used to set the default font for the remainder of the label or until another ^CF command is used. Some fields allow setting a font for that field only also.
The format of the command is ^CF<fontName>,<height>,<width>.
- Examples:
^CF0,50,50or^CF0,50(specifying only height)
The ^FD command is the field data command and is mostly used to provide text in the context of another command.
- Example:
^FDI am some text
Sample
^XA
^CF0,60
^FO50,50^FDFont using CF 0, 60^FS
^CFA,40
^FO50,200^FDFont using CF A, 40^FS
^CFA,30,25
^FO50,350^FDFont using CF A, 30, 25^FS
^XZ
^CF command sample
Shapes
ZPL provides several shapes that you can include in a label, but the most common ones are lines, rectangles, and ellipses.
Lines
Horizontal lines can be produced using the ^GB graphical box command and providing a width value as long as the line you want to create and a length value of 0 (zero). Combined with a line thickness value, you can then produce a horizontal line at a position and length of your choosing.
The format of the command is ^GB.
- Vertical line example:
^F0100,50^GBO,400,4^FS
Sample
^XA
^FO50,50^GB400,0,4,^FS
^FO50,150^GB400,0,10,^FS
^FO50,250^GB400,0,20,^FS
^FO50,350^GBO,400,4^FS
^FO150,350^GBO,400,10^FS
^FO250,350^GBO,400,20^FS
^XZ
Horizontal and vertical line sample
- Basic box:
^FO50,200^GB200,200,2^FS
Barcodes
If you want to add a barcode, ZPL has many different options for you.
Images
You can embed an image that has been appropriately encoded.
Access label and shipment data in an augmentation
If you need to access data that exists in a portion of the carrier selection or carrier label response that comes back from Shipium, you can access this data using Shipium's variable access technology, which allows you to utilize portions of the data we return in a response object directly in your label modification.
For example, if you wanted to print the plain text of the carrier tracking ID somewhere in a label modification, you could access it using the variable $!{carrierLabel.carrierTrackingId} in your label modification.
$! vs $
If you reference data using
$!{variableName}, this will return a value if it exists or leave it empty if it does not. This might be preferable for many production use cases, but may be harder to debug when you are testing something.If you reference data using
${variableName}and there is no value associated with the variable name, then it will print out the actual string${variableName}into the label, which can help you to debug any problems, such as misspelling the variable or some other issue. This is recommended during testing, but not in production.
Common elements and examples
In the table below, we do not include the ${} around the variables for ease of reading, but don't forget that you will need to include that when adding these into a label modification. For example, the table has carrierLabel.carrierTrackingId, but in a label augmentation, you will need to use ${carrierLabel.carrierTrackingId}.
| Data of interest | Variable | Examples |
|---|---|---|
| Carrier Tracking ID | carrierLabel.carrierTrackingId | This example would produce a barcode with the carrier tracking label ID contained within it.^FO60,215^BY3^BCN,130,N,N,N,N^FD$!{carrierLabel.carrierTrackingId}^FS |
| Partner Shipment ID | carrierLabel.partnerShipmentId | This example would produce the text of the partnerShipmentId value as text at the bottom left of the label.^CF0,30 ^FO20,1180^FD${carrierLabel.partnerShipmentId}^FS |
| Purchase Order Identifier | purchaseOrderIdentifier | This example would produce the text of the purchaseOrderIdentifier value as text at the bottom left of the label.^CF0,30 ^FO20,1180^FD${purchaseOrderIdentifier}^FS |
| Reference Identifier | referenceIdentifier | This example would produce the text of the referenceIdentifier value as text at the bottom left of the label.^CF0,30 ^FO20,1180^FD${referenceIdentifier}^FS |
Resources
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
Updated 1 day ago