Templates & Field Maps

A Template is a stored ZPL body with placeholders instead of hard-coded data. A Field Map names those placeholders, so you fill them in by meaningful names like asset_id rather than raw printer codes.

What#

Think of a Template as a rubber stamp with blank lines on it, and the Field Map as the labels next to each blank telling you what goes where.

Why#

Most teams print the same label thousands of times with different data. Re-sending the full ZPL every time means copy-pasting a large string, string-replacing values by hand, risking a typo that breaks the barcode, and re-uploading the design on every change. A Template lets you store the design once and send only the data that changes.

How#

Placeholders: ^FN#

In ZPL, ^FN<number> marks a numbered blank — a "field number". A Template body is just normal ZPL where the variable parts are ^FN1, ^FN2, and so on:

^XA
^FO50,50^A0N,30,30^FN1^FS          <- FN1: a text line
^FO50,100^BY2^BCN,80,Y,N,N^FN2^FS  <- FN2: a Code-128 barcode
^XZ

The Field Map: names → numbers#

Filling in ^FN1 and ^FN2 by number is error-prone. The Field Map assigns each number a human name:

{
  "asset_id":         1,
  "asset_id_barcode": 2
}

Now you supply data by name, and the API translates names back to the right ^FN slots:

{
  "fields": {
    "asset_id":         "MER-04821",
    "asset_id_barcode": "MER-04821"
  }
}

Filling a Template: Values#

The data you hydrate into a Template is called Values. One Template plus one set of Values produces one concrete Asset Label (the rendered PNG). The same Template with different Values produces a different label — same design, new data.

Where Templates Live: Scope#

A Template is addressed by a template_id and exists at one of two scopes:

If you and a global template share the same id, your tenant copy wins — your overlay shadows the global. List what's available with GET /v1/templates.

Putting it together#

1. Get a Template#

   Synthesize one from legacy ZPL, or list existing ones.

2. Commit It#

   Store the draft under a template_id so it's addressable.

3. Render with Data#

   POST /v1/labels/from-data with { template_id, fields } to produce a PNG — sending only the data that changes, by name.