Universal Print - Hole Punch

Question

We're trying to develop a custom Universal Print Connector. We think we've got everything hooked up properly, but we're running into issues with Print Preferences. We're following the steps outlined in the Universal Print Printer Registration and IP Infra spec, which says we can issue an IPP command for Update-Output-Device-Attributes to specify what our devices are capable of. We include many finishings in the command and have successfully tested that most finishings make their way into print jobs submitted to Universal Print that flow through our connector to our devices... except for Hole Punch. No matter what application we print from, we can see through Graph API that none of the "punch" finishings are making it into the print jobs in the Universal Print print queues. Other finishings such as bind and staple appear to work fine. It's just hole punch finishings that seem to be ignored.

Answer 1

Joe Z oh that seems like an excellent point that you made. If the punch options successfully populate in the Windows print dialog via your IPP commands, the initial translation from your connector into the local PrintCapabilities XML is functioning correctly. The breakdown is occurring on the return trip during job submission. When a user selects that finishing option, the operating system must serialize that choice into a PrintTicket XML payload and translate it back into an IPP job attribute to send to the cloud. The Windows print client might be able to render the UI element based on your input but fail to map the user's selection back into the outgoing network request.

To verify what is leaving the client machine, you should capture the outbound traffic using a web debugging proxy like Fiddler. By decrypting the HTTPS traffic originating from the Windows spooler, you can inspect the Graph API POST request used for job creation. If the JSON payload's finishings array lacks your specific hole-punch enumeration, the local Windows client is dropping the attribute before it ever reaches the cloud. Alternatively, you can pause the local print queue, submit a test document, and navigate to the C:\Windows\System32\spool\PRINTERS directory. Extracting and reading the raw .SPL spool file will allow you to view the embedded PrintTicket XML, which will immediately confirm whether the operating system successfully recorded the user's dialog selection in the first place.

VPHAN

Answer 2

Hello,

The issue lies in the translation matrix between the Universal Print cloud service and the local Windows Print Schema. When a client queries printer capabilities, the Universal Print class driver expects the IPP finishings-supported enumerations to be converted into a structured PrintCapabilities XML document. While standard IPP enums for stapling or binding map correctly to the standard Windows Print Schema namespaces, specific IPP hole-punch values currently lack reliable translation mappings in the Microsoft cloud layer. Consequently, the driver drops these unmapped capabilities, causing the hole-punch options to be entirely absent from the print dialog user interface. Because the user cannot select these options, the configurations are never written into the PrintTicket XML payload attached to the print job, explaining exactly why your Graph API queries show no punch attributes in the queue.

Since this is a backend mapping limitation within the Universal Print service itself, no custom IPP commands from your connector can force the native Windows UI to render these options. Until an official update patches this translation gap, the supported engineering workaround is to deploy a Windows Print Support App. By associating a Print Support App with your devices, you bypass the cloud translation limitations entirely. The app runs alongside the Universal Print class driver, allowing you to explicitly define the print dialog interface and inject the correct hole-punch schemas directly into the PrintTicket. This ensures the proper instructions flow intact from the client, through the Graph API, and down to your connector payload.

Hope this answer brought you some useful information. Should you have any questions, feel free to leave a comment.

VPHAN

Answer 3

Hi Joe Z,

Has your issue been resolved yet? If it has, please consider accepting the answer as it helps others sharing the same problem benefit too. Thank you :)

VPHAN

Answer 4

Hole punch finishings are ignored by Universal Print when they are not exposed through the connector’s PDC→IPP mapping using the exact option names and numeric finishings values that Universal Print recognizes. Other finishings (such as staple and bind) work in the connector because their mappings are valid; hole punch is dropped when the mapping does not match the documented expectations.

Key behaviors and requirements from the connector pipeline:

1. Capabilities must map from PDC to IPP, or they are dropped

• The Universal Print connector first retrieves the printer’s capabilities as Print Device Capabilities (PDC). If PDC is not available, it builds one from Print Capabilities (PC) and Print Ticket (PT).
• Universal Print then parses the PDC XML and maps elements/options to IPP Printer Description Attributes (PDAs).
• If a PDC element or option has no known mapping, that attribute is ignored and does not appear in the Universal Print printer options.
• This rule applies to hole punch: if the PDC option name or its mapping to finishings is not one of the known values, Universal Print will not surface it, and it will not appear in job tickets or via Graph.

2. Hole punch must use specific finishings values

Hole punch and related options are represented in IPP via finishings-supported and finishings-default using specific numeric values. The connector must map PDC options to these values. Examples from the documented PDC→IPP mapping include:

• Base hole punch:
  • HolePunch → finishings value 5
• Dual-hole punch:
  • HolePunchDualLeft → 74
  • HolePunchDualTop → 75
  • HolePunchDualRight → 76
  • HolePunchDualBottom → 77
• Triple-hole punch:
  • HolePunchTripleLeft → 78
  • HolePunchTripleTop → 79
  • HolePunchTripleRight → 80
  • HolePunchTripleBottom → 81
• Quad-hole punch:
  • HolePunchQuadLeft → 82
  • HolePunchQuadTop → 83
  • HolePunchQuadRight → 84
  • HolePunchQuadBottom → 85
• Multiple-hole punch (continuous/any position):
  • HolePunchMultipleLeft → 86
  • HolePunchMultipleTop → 87
  • HolePunchMultipleRight → 88
  • HolePunchMultipleBottom → 89
• Variants expressed as “*_PC” options:
  • TwoHolesLeft_PC → 74
  • TwoHolesTop_PC → 75
  • TwoHolesRight_PC → 76
  • TwoHolesBottom_PC → 77
  • ThreeHolesLeft_PC → 78
  • ThreeHolesTop_PC → 79
  • ThreeHolesRight_PC → 80
  • ThreeHolesBottom_PC → 81
  • FourHolesLeft_PC / FourHolesLeftSwd_PC → 82
  • FourHolesTop_PC / FourHolesTopSwd_PC → 83
  • FourHolesRight_PC / FourHolesRightSwd_PC → 84
  • FourHolesBottom_PC / FourHolesBottomSwd_PC → 85

If the connector’s Update-Output-Device-Attributes request uses different numeric values or different option names for hole punch, Universal Print will not treat them as valid finishings entries and they will not propagate into jobs.

3. Why hole punch does not appear in jobs while other finishings do

• Staple, bind, and other finishings that work are likely mapped by the connector to the correct finishings numeric values that Universal Print expects.
• Hole punch options, even if present in the Update-Output-Device-Attributes request, are ignored if:
  • The PDC option names do not match the documented names (for example, custom names instead of HolePunch, TwoHolesLeft_PC, etc.), or
  • The connector maps them to finishings values that differ from the documented numeric codes.
• When Universal Print cannot map a capability, it is dropped from the printer’s options. Consequently, clients cannot select it, and the job ticket will not contain any punch finishing values. This is why Graph shows no punch-related finishings on jobs, even though other finishings appear.

4. Steps to make hole punch flow end-to-end

To ensure hole punch finishings appear in Universal Print jobs and through Graph:

1. Confirm PDC option names
   • Ensure the printer driver’s PDC exposes hole punch options using the expected names (for example, HolePunch, HolePunchDualLeft, TwoHolesLeft_PC, etc.). If the PDC uses different or custom names, Universal Print will not map them.
2. Verify connector mapping to IPP
   • In the connector’s PDC→IPP conversion, map those PDC options to finishings-supported / finishings-default using the exact numeric values listed above.
3. Validate capabilities from Universal Print
   • Retrieve the printer capabilities as seen by Universal Print and check that finishings-supported includes the hole punch values (such as 5, 74–89, etc.). If they are missing, the mapping is still incorrect or incomplete.
4. Test job creation
   • After the capabilities are correct, print from a client that supports these finishings, select the appropriate hole punch option, and then inspect the job via Graph. The job ticket should now include the corresponding finishings value for punch.
5. General connector considerations

• Universal Print supports all IPP-defined printer description attributes and custom attributes, but only when they follow IPP templates and known mappings.
• Attributes that cannot be mapped from PDC are ignored; Universal Print may add mandatory attributes per Mopria IPP 2.0, but this does not compensate for missing or incorrect hole punch mappings.

In practice, the behavior observed—other finishings working while hole punch is ignored—indicates that the connector’s PDC→IPP mapping for hole punch does not align with the documented finishings values. Aligning the PDC option names and numeric finishings codes with the documented mapping is required for hole punch to appear in Universal Print jobs.

---

References:

• Getting capabilities for the printer registered through Universal Print connector
• Building a Universal Print connector