.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _app-ppd-ext-job-ticket: Job Ticket Extensions --------------------- .. contents:: |RST_TABLE_OF_CONTENTS| :depth: 1 :local: Job Tickets are created with a dedicated Proxy Printer marked as Job Ticket Printer. As with any printer, a PPD extension file can be linked to this virtual printer. In the PPD Extension file, special extensions are available to define Job Ticket IPP options, including *Cost Rules*. These IPP options are generic and abstracted from physical printers. When handling the ticket, the operator interprets the option values, selects a suitable printer, assures the right media are present in the target tray, and redirects the job to it. Job Ticket IPP options can be defined for scope *Media* (single side of a page sheet), *Sheet* (single page sheet), *Copy* (sheet collection of a printed copy) and *Set* (the complete set of copies). The syntax is as follows: .. callout:: .. code-block:: text *SPJobTicket/: \ # <1> [*|+] ... # <2> .. annotations:: :1: The ``*SPJobTicket`` option with scope ``Media`` \| ``Sheet`` \| ``Copy`` \| ``Set``, and attribute name. :2: One or more option values. An ``*`` before a value marks it as default. A ``+`` prefix signifies an *extended* value, that is available for Job Ticket Operators only, so they can ad-hoc assign this value when editing a job ticket. .. note:: The ``+`` prefix can also be assigned to regular option values. For example, if a Job Ticket Creator is not allowed to select color mode, the following code snippet can be added to the PPD extension file: .. code-block:: text # Virtual print color mode, with dummy PPD option and values. *VPrintColorMode print-color-mode *VPrintColorMode dummy monochrome *VPrintColorMode dummy +color Cost Rules are introduced for each option scope in the sections below. .. important:: IPP Options defined in the Job Ticket context are *not* mapped to their PPD counterparts. Therefore, their chosen values will *not* be send with the print job. .. _app-ppd-ext-job-ticket-media: Job Ticket Media Options ~~~~~~~~~~~~~~~~~~~~~~~~ IPP attributes describing media characteristics, like ``media-color`` and ``media-type`` are supported. Each option is prefixed with ``*SPJobTicket/Media:`` Some examples: .. callout:: .. code-block:: text *SPJobTicket/Media: media-color *white int.colored # <1> *SPJobTicket/Media: media-type *paper transparency labels ext.letterhead-1 # <2> .. annotations:: :1: Option to select white and colored. ``white`` is an IANA media-color and is the default. ``int.colored`` is an internal IPP value extension, denoting a non-white color. :2: Other values could be ``blue``, ``red``, ``green``, ``orange``, etc. Option to select media types: ``ext.letterhead-1`` is an external IPP value extension. Media Cost is charged per media *side*, and specified for a combination of IPP values for media attributes. Each cost rule is prefixed with ``*SPJobTicket/Media/Cost:`` and formatted like this: .. callout:: .. code-block:: text *SPJobTicket/Media/Cost: \ # <1> /[!] ... \ # <2> /[!] ... \ # <3> .. annotations:: :1: Decimal point ```` and identifying ````. :2: One or more IPP ``/`` pairs. An optional ``!`` before a value negates it, and selects all other attribute values. :3: Optionally one or more IPP non-media ``/`` pairs. .. note:: The IPP ``/`` pairs referred to in ``*SPJobTicket/Media/Cost`` must either be automatically picked up from the PPD, or be defined as :ref:`PPD to IPP Mapping ` or ``*SPJobTicket/Media``. Some examples: .. callout:: .. code-block:: text *SPJobTicket/Media/Cost: 0.0430 white-A4-080-S \ # <1> media-type/ext.paper-80 \ media-color/white \ media/iso_a4_210x297mm \ sides/one-sided *SPJobTicket/Media/Cost: 0.0610 color-A4-120-S \ # <2> media-type/ext.paper-120 \ media-color/!white \ media/iso_a4_210x297mm \ sides/one-sided *SPJobTicket/Media/Cost: 0.0390 white-A4-080-D \ # <3> media-type/ext.paper-80 \ media-color/white \ media/iso_a4_210x297mm \ sides/!one-sided *SPJobTicket/Media/Cost: 0.0790 letterhead-A4-S \ # <4> media-type/ext.letterhead-1 \ media/iso_a4_210x297mm \ sides/one-sided .. annotations:: :1: Single-sided A4 print on 80 grams white paper: 0.0430 per side. :2: Single-sided A4 print on 120 grams colored paper: 0.0610 per side. :3: Double-sided A4 print on 80 grams white paper: 0.0390 per side. :4: Single-sided A4 print on letterhead: 0.0790 per side. .. important:: When ``*SPJobTicket/Media/Cost`` items are present, they acts as constraint. When a user sets print job properties, a cost rule must be present that matches chosen media options. When no rule is found, a warning message is displayed to the user. The calculated cost of the *first* cost rule, that applies to the Job Ticket option values, is used as media cost. .. _app-ppd-ext-job-ticket-sheet-options: Job Ticket Sheet Options ~~~~~~~~~~~~~~~~~~~~~~~~ Job Ticket Sheet options specify *finishing* actions, performed on a single printed sheet. Each option is prefixed with ``*SPJobTicket/Sheet:`` For example: .. callout:: .. code-block:: text *SPJobTicket/Sheet: org.savapage-finishings-ext *none laminate # <1> .. annotations:: :1: :ref:`org.savapage-finishings-ext ` option to select an extra finishing to be performed manually by Job Ticket operator. Sheet Cost is charged per media *sheet*, and specified for a combination of ``SPJobTicket/Sheet`` and other (``media*``) attribute values. Each cost rule is prefixed with ``*SPJobTicket/Sheet/Cost:`` and formatted like this: .. callout:: .. code-block:: text *SPJobTicket/Sheet/Cost: \ # <1> /[!] ... \ # <2> /[!] ... \ # <3> .. annotations:: :1: Decimal point ```` and identifying ````. :2: One or more IPP ``/`` pairs of type ``SPJobTicket/Sheet``. An optional ``!`` before a value negates it, and selects all other attribute values. :3: Optionally one or more other IPP ``/`` pairs. For example: .. code-block:: text *SPJobTicket/Sheet/Cost: 0.5000 laminate-A4 org.savapage-finishings-ext/laminate \ media/iso_a4_210x297mm *SPJobTicket/Sheet/Cost: 0.7500 laminate-A3 org.savapage-finishings-ext/laminate \ media/iso_a3_297x420mm .. important:: The calculated cost of *all* sheet cost rules, that apply to the Job Ticket option values, are *accumulated* as cost per sheet. .. _app-ppd-ext-job-ticket-copy-options: Job Ticket Copy Options ~~~~~~~~~~~~~~~~~~~~~~~ .. contents:: :depth: 1 :local: Job Ticket Copy options specify *finishing* actions, performed on a single printed copy. Each option is prefixed with ``*SPJobTicket/Copy:`` Some examples: .. callout:: .. code-block:: text *SPJobTicket/Copy: org.savapage-cover-type *no-cover ext.printfront-1 # <1> *SPJobTicket/Copy: org.savapage-finishings-ext *none laminate bind adhesive ext.binder # <2> .. annotations:: :1: :ref:`org.savapage-cover-type ` option to select a cover type. ``ext.printfront-1`` is an :ref:`External IPP extension `. :2: :ref:`org.savapage-finishings-ext ` option to select an extra finishing to be performed manually by Job Ticket operator. ``ext.binder`` is an :ref:`External IPP extension `. Copy Cost is charged per job *copy*, and specified for a combination of ``SPJobTicket/Copy`` and other (``media*``) attribute values. Each cost rule is prefixed with ``*SPJobTicket/Copy/Cost:`` and formatted like this: .. callout:: .. code-block:: text *SPJobTicket/Copy/Cost: \ # <1> /[!] ... \ # <2> /[!] ... \ # <3> .. annotations:: :1: Decimal point ```` and identifying ````. :2: One or more IPP ``/`` pairs of type ``SPJobTicket/Copy``. An optional ``!`` before a value negates it, and selects all other attribute values. :3: Optionally one or more other IPP ``/`` pairs. For example: .. code-block:: text *SPJobTicket/Copy/Cost: 0.5000 folder-A4 org.savapage-finishings-ext/ext.folder \ media/iso_a4_210x297mm .. important:: The calculated cost of *all* copy cost rules, that apply to the Job Ticket option values, are *accumulated* as cost per copy. .. _app-ppd-ext-job-ticket-copy-options-ext: Using External IPP Extensions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Job Ticket Copy Options are not confined to regular IPP attributes and :ref:`Internal IPP Extensions `. By utilizing :ref:`External IPP Extensions `, you can fully customize your Job Tickets Copy options and cost rules. For example: .. callout:: .. code-block:: text *SPJobTicket/Copy: org.savapage.ext-myoption \ # <1> *none ext.choice-1 ext.choice-2 *SPJobTicket/Copy/Cost: 0.1000 myrule-1 \ # <2> org.savapage.ext-myoption/ext.choice-1 media/iso_a4_210x297mm *SPJobTicket/Copy/Cost: 0.1500 myrule-2 \ # <3> org.savapage.ext-myoption/ext.choice-2 media/iso_a3_297x420mm .. annotations:: :1: Definition of External IPP extension ``myoption`` with two custom choices. The default choice ``none`` is a reserved internal value, indicating that the option is not selected. :2: Cost rule for ``ext.choice-1`` and A4 media. :3: Cost rule for ``ext.choice-2`` and A3 media. .. _app-ppd-ext-job-ticket-set-options: Job Ticket Set Options ~~~~~~~~~~~~~~~~~~~~~~ Job Ticket Set options specify actions performed on the complete set of copies [2]_. Each option is prefixed with ``*SPJobTicket/Set:`` For example: .. callout:: .. code-block:: text *SPJobTicket/Set: org.savapage-job-sheets \ # <1> +none *job-start-sheet *SPJobTicket/Set: org.savapage-job-sheets-media \ # <2> *iso_a4_210x297mm +iso_a3_297x420mm .. annotations:: :1: :ref:`org.savapage-job-sheets ` option to select a job-sheet. :2: :ref:`org.savapage-job-sheets-media ` option to select the job-sheet media. Set Cost is charged per *job*, and specified for a combination of ``SPJobTicket/Set`` and other (``org.savapage-job-sheets-*``) attribute values. Each cost rule is prefixed with ``*SPJobTicket/Set/Cost:`` and formatted like this: .. callout:: .. code-block:: text *SPJobTicket/Set/Cost: \ # <1> /[!] ... \ # <2> /[!] ... \ # <3> .. annotations:: :1: Decimal point ```` and identifying ````. :2: One or more IPP ``/`` pairs of type ``SPJobTicket/Set``. An optional ``!`` before a value negates it, and selects all other attribute values. :3: Optionally one or more other IPP ``/`` pairs. For example: .. code-block:: text *SPJobTicket/Set/Cost: 0.05 banner-A4 org.savapage-job-sheets/!none \ org.savapage-job-sheets-media/iso_a4_210x297mm .. important:: The calculated cost of *all* cost rules, that apply to the Job Ticket option values, are *accumulated* as cost per set. .. [2] The Job Ticket Set includes all copies, and therefore differs from the *Set* as defined in RFC8011, where it is “a logical boundary between the delivered Media Sheets of a printed Job. For example, in the case of a ten-page single Document with collated pages and a request for 50 copies, each of the 50 printed copies of the Document constitutes a Set. If the pages were uncollated, then 50 copies of each of the individual pages within the Document would represent each Set.”