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"}}}

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.

  [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

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": ... } ] }