Print emails and requirements

Lesson 27 of 28 7 min read

Give each print its own email subject and body, use Liquid templates and link placeholders correctly, and gate a print with a requirement so it only runs when it should.

A despatch that produces a delivery note and pallet labels shouldn't send both under the subject "Delivery note". And some prints should only run in certain cases. This lesson covers both: per-print emails and requirements.

How the subject and body are chosen

Each print entry can carry its own subject and body. Supply Lens resolves each one down a chain, stopping at the first value that is set:

Rendering diagram...

The body follows the same chain with the body settings.

Null falls through, empty stops

A setting that is absent (null) passes to the next in the chain. An empty string is an answer: it stops the chain and the email goes out with nothing there. Remove a setting rather than blanking it if you want the fallback.

Templates or plain strings?

There are two ways to write a subject or body, and they can do different things.

Templates (emailSubjectTemplate, emailBodyTemplate) use Liquid, a simple templating language where values go inside double braces. They are rendered when the PDF is created and can read printKey, reference, filename, documentNumber, documentType and documentDate:

"emailSubjectTemplate": "Delivery note {{ documentNumber }} for {{ reference }}"

Plain strings (emailSubject, emailBodyText) reach the email sender unrendered and keep numbered placeholders, which is where the links are:

Placeholder	Meaning
`{0}`	The combined reference
`{1}`	The reference
`{2}`	The source reference
`{3}`	The id
`{4}` (body only)	The file's URL
`{5}` (body only)	The Document's URL

Which to use

A template cannot link to the document or the file, because those URLs are built when the email is sent, long after the template has run. Use a template for anything that reads the document (its number, date, type), and a plain string for anything that needs a link.

Requirements: only print when it applies

An entry's requirement is a boolean map expression: a small rule written in the same language as a config-driven map's condition, reading the Document from the $.document root. Leave it out and the print always runs.

This requirement prints pallet labels only when the Document has at least one container:

{
  "printKey": "pallet-label",
  "requirement": {
    "op": "compare", "operator": "gt",
    "left": { "op": "path", "path": "$.document.containers.length()" },
    "right": { "op": "literal", "value": 0 }
  }
}

Rules to remember:

Anything but true is a no. An expression reading a field the document doesn't carry produces nothing, and nothing does not print.
op need not come first. Stored settings come back with keys reordered, and that's fine.
Unknown fields are refused, not dropped, and that is caught when the settings are saved, not on the first despatch. So half a requirement can't silently decide what prints.

You may not need a requirement

A print with nothing to render (such as pallet labels for a despatch with no pallets) already produces no output and no error. Use a requirement for business rules, such as "only for this customer", rather than to avoid empty prints.

Two prints, two subjects

Sandpiper's despatches produce a delivery note and pallet labels for the 3PL's goods-out team. The implementer sets:

integration emailAddresses: the goods-out mailbox;
integration emailBodyText: "View the document: {5}", so every email links back;
on the delivery note entry, emailSubjectTemplate: "Delivery note {{ documentNumber }}";
on the pallet label entry, emailSubjectTemplate: "Pallet labels for {{ reference }}".

Each email now has a subject that says what it is, and both still carry the link from the shared plain-string body.

Recap

Subject and body each resolve entry template → entry plain → integration template → integration plain.
Null falls through; an empty string stops the chain.
Liquid templates read document values but cannot include links; plain strings keep the numbered placeholders, including the file and Document URLs.
A requirement gates a print with a boolean map expression; anything but true means no print.
Invalid requirements are refused when the settings are saved.

Quick guides for this topic

Complete and continue

Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.

How print integrations work The print catalogue and pallet labels