Substitutions

Compatibility

• ✅ 2.2 | ⛔ 2.1 | ⛔ 2.0 | ⛔ 1.9 | ...

Contents

Since QZ Tray 2.2.4, clients have the ability to make advanced client-side overrides to the JSON websocket data. This low-level control for clients is in a direct response to lack of flexibility by website developers.

For resiliency purposes, the JSON substitution is limited only to trivial traits of a print job, such as page size, printer name, although this behavior can be altered slightly by loosening the security of certain restricted keywords.

Usage

Basic Usage

Basic usage is as follows:

1. Create a file called substitutions.json

2. Use the keywords use and for to instruct QZ how to perform JSON substitution replace and search, respectively.

   [
     {
       "use": {
         "config": {"size": {"width": "100", "height": "150"}, "units": "mm"}
       },
       "for": {
         "config": {"size": {"width": "4", "height": "6"}}
       }
     }
   ]

3. Drag and drop the file into the About dialog (QZ Menu -> About)
   

4. Submit a print job and check the logs to confirm (QZ Menu -> Advanced -> Diagnostics -> View Logs)

   [DEBUG] 2024-04-24T14:26:42,669 @ qz.ws.substitutions.Substitutions:76
   +    Matched JSON substitution rule: for: {"params":{"options":{"size":{"width":"4","height":"6"}}}}, use: {"params":{"options":{"size":{"width":"100","height":"150"},"units":"mm"}}}

5. The above example substitutes all print commands for the paper size 4x6 (in) to 100x150 (mm).

Printer Substitution

To instruct QZ Tray to send a print job to a different printer, use the "printer": { ... } directive:

[
  {
    "use": {
       "printer": "XPS Document Writer"
    },
    "for": {
       "printer": "PDFwriter"
    }
  }
]

[DEBUG] 2024-04-24T14:26:42,672 @ qz.ws.substitutions.Substitutions:76
+    Matched JSON substitution rule: for: {"params":{"printer":{"name":"PDFwriter"}}}, use: {"params":{"printer":{"name":"XPS Document Writer"}}}

Size Substitution

• The most common reason for JSON substitutions is unwillness of a website provider to modify their application for custom paper sizes. Although justifications for this are generally warranted (e.g. strict shipping regulations), the resulting impact to the end-users can crippling. Examples are provided with and without quotations for convenience.

  US Letter vs. A4

  [
    {
      "use": { "config": {"size": {"width": 210, "height": 297}, "units": "mm"} },
      "for": { "config": {"size": {"width": 8.5, "height": 11}, "units": "in"} }
    }
  ]

Restricted Keywords

• By default, certain keywords cannot be modified such as "copies": or nested "data": { "data": ... } elements. This is to ensure that the content and quantity being printed matches that intended by the website.

• This behavior can be disabled by setting property security.substitutions.restrict to false.

  Restrict (true)

  [WARN] 2024-04-24T14:26:42,672 @ qz.ws.substitutions.Substitutions:132
  -    Use of { "options": { "copies": ... } } is restricted, removing
  [WARN] 2024-04-24T14:26:42,672 @ qz.ws.substitutions.Substitutions:148
  -    Use of { "data": { "data": ... } } is restricted, removing

  Restrict (false)

  [DEBUG] 2024-04-25T13:27:23,844 @ qz.ws.substitutions.Substitutions:79
  +    Matched JSON substitution rule: for: {"params":{"options":{"copies":1}}}, use: {"params":{"options":{"copies":3}}}
  [DEBUG] 2024-04-25T13:27:23,844 @ qz.ws.substitutions.Substitutions:79
  +    Matched JSON substitution rule: for: {"params":{"data":[{"data":"https://google.com"}]}}, use: {"params":{"data":[{"data":"https://yahoo.com"}]}}

• Justification for these default restrictions:

  • Due to the wide adoption of QZ Tray for strictly monitored items such as ticket sales, "copies": ... is considered to be a risk and is disabled by default.
  • Modifying data blobs (such as URLs, base64, raw content), materially changes the print job and would otherwise defeat the purpose of digitally signing the content.

Sanitization

• For convenience and consistency with the api, keywords such as config, printer, data, are offered over their verbatim JSON counterparts (See table).

• To make the JSON slightly more human-readable/human-writable implied arrays, such as data will be automatically converted to an array before matching (See table).

• Sanitization applies automatically, but is not required; the expanded/verbatim versions are always supported.

  keyword	sanitized/expanded
  "printer": ...	"params": {"printer": {"name": ... } }
  "config": ...	"params": {"options": ... }
  "data": {"options": ... }	"params": {"data": [ { "options": ... } ] }