Goal

Enable multi-template bulk printing (cards, labels, breadcrumbs) where selected items may prescribe different templates/sizes, and resolve existing bugs in the PDF printing functionality.

Goals

1. Multi-template bulk printing — When printing a batch of items that have different template sizes assigned, the system should handle them correctly (e.g., grouping by size and opening separate tabs/jobs) rather than erroring out.
2. Bug fixes — Resolve known defects in the current printing pipeline: wrong field mappings, missing debug capabilities, and UX issues around print status.

Summary of Current Printing Functionality and Required Extension for multi-printing

Current Behavior

Initiation

The user selects one or multiple items in the Items List View in the system or in the details view and apply an action to print Cards, Labels or Breadcrumbs.

Front-End Behavior

• The FrontEnd uses the printing routes in the kanban and item endpoints (see API Guide) to print either a list of Cards by EId or a list of items by RId.
• The Front-end opens a window (or tab) in the browser with the PDF file url in the response from the API.

Back-End Behavior

• The system determines the printing template to use based on an arbitrary internal criteria (likely the one selected for the first id of the list. Verify this assertion against the code first)
• The Back End operations component calls Documint with the information and the mapped template and returns a url to the generated PDF.

Desired Changes

Initiation

The initiation of the printing workflow is the same with the user selecting a number of items (cards) and selecting what to print. The API request also remains the same.

Front-End Behavior

• No changes in how the Front End collects information from the user interaction and invokes the back-end
• Upon return from the back-end, the Front-end will open one window/tab per successfully returned URL and an error message for any errors returned.

Back-End Behavior

The back end will now collate the elements recovered from the database into groups by the printing size that they have configured and will call the documint server once per group. It is O.K. to do this in parallel with a maximum concurrency number (configurable in the printing configuration properties). Once the results are returned by Documint, the back-end needs to compose them into a response from the API that has a shape like:

{
  "job": "<uuid>",
  "asOF": {
    "effective": "1234567890",
    "recorded":  "1234567890"
  },
  "results": [
    {
      "template": "<documint-template>",
      "url": "<pdf file url>,
    },
    <error-result>
  ]
}

Where:

• <error-resut> is the current error result when the documint rendering fails for a single batch.
• One entry in results for each collation group by selected size/template

This description does not include the changes required by all Github tickets. Only for the ones that directly request the multiple formats in printing directly. All GH tickets need to be reviewed to make sure that all requirements are covered.

Deliverables and Reviews

This project needs to deliver a complete feature end-to-end:

The project needs to:

1. Obtain Requirements Details and clarifications from the user based on the information provided in the references, in this file, and in the code of the relevant repositories.
2. Write Drafts of Feature Requirements in documentation/src/content/docs/product/features/reference-data/items and if needed in documentation/src/content/docs/product/features/resources/kanban (new directory) that will be reviewed by the user.
3. After #2 is reviewed and approved by the user, create detailed Use cases in the appropriate sections of documentation/src/content/docs/product/use-cases to be reviewed again by the user.
4. Once #2 & #3 are reviewed and approved, update documentation/src/content/docs/current-system/functional/reference-data/item/printing.md with the new information, including sequence diagrams showing the interaction between User, FrontEnd, BackEnd (operations component through the API) and the Documint Server.
5. Create a plan to implement and execute it, including unit tests, api tests and e2e UI tests.
6. Update the requirements and design documents depending on design decisions made during planning and implementation.

Reference

GitHub Tickets

Multi-Template / Bulk Printing

• Arda-cards/management#519 — Iterative Bulk Printing: Break prints >40 cards/labels/breadcrumbs into multiple jobs to prevent Documint errors. Requested by customer success.
• Arda-cards/management#575 — Bulk printing: send different card sizes to different tabs: When bulk-printing items with different sizes, open a separate tab per size instead of erroring. Includes Loom video.

Printing Bugs

• Arda-cards/management#815 — Documint payload sends notes instead of card_notes: The notes field in the Documint payload contains order history (e.g., “Ordered: 3/3/26…”) instead of the item’s card_notes value. Bug confirmed via CloudWatch logs.
• Arda-cards/management#816 — Do not print notes on cards when card_notes is empty: Cards should not display any notes text when card_notes is empty. Currently order notes leak into the printed output.

Print Debug & History

• Arda-cards/management#762 — Add option to return JSON body sent to Documint: Add a flag to the print API that returns the constructed JSON payload for troubleshooting. Requested by Arda Support.
• Arda-cards/management#792 — Print Job Debug & History API: Expose print job history and/or dry-run capability so support/CS teams can self-serve debugging. Two options proposed: history API and debug flag.

Print UX

• Arda-cards/management#595 — No way to unmark a card as “printed”: Once a card is marked as printed, there is no way to reset the status.

Repositories

• operations — Main implementation of printing features (Kotlin/Ktor)
  • Local Worktree: ../../../../../../../operations/
• api-test — API-level tests and requests (Bruno)
  • Local Worktree: ../../../../../../../api-test/
• ux-prototype — User Experience Components. Not expected to be modified, for reference only.
  • Local Worktree: ../../../../../../../ux-prototype/
• arda-frontend-app — Fron-end system (BFF & React SPA)
  • Local Worktree: ../../../../../../../arda-frontend-app/
• documentation — Project files, features, requirements, and use cases
  • Local Worktree: ../../../../../../../documentation/
• api-proxy — TypeScript API proxy; updated to match new print API contracts
  • Local Worktree: ../../../../../../../api-proxy/
• common-module — Shared library; no planned changes (only if discovered during implementation),
  • Read Only Reference (main): ../../../../../../../../../common-module/
  • Local Worktree (only if needed): ../../../../../../../common-module/

Related Prior Work

• Extra Printing Options project — Added X_SMALL and SPECIAL_* sizes, template configuration, and protobuf mappings. Directly relevant as the baseline for the current printing infrastructure.

Current System Documentation

• Item Module — Entity model, API endpoints, service layer, persistence, printing sequence diagrams
• PDF Render Module — PdfRenderService interface, DocumintProxy, Documint API contract

Required Design Changes

#	Change	Module	Traces To
1	Multi-template grouping: Replace single-template enforcement with group-by-size logic. Fetch items, group by resolved template, call Documint once per group in parallel (up to concurrency limit), return composite response.	item (ItemPrintingService)	SAC::PRINT::FR-0001, FR-0002, FR-0003, FR-0004; SAC::PRINT::0002::0002, 0004, 0006; #575
2	Composite print response: New response shape with job, asOF, and results[] array (one entry per template group with template ID + URL or error). Replaces current single RenderResult.	item (ItemEndpoint, ItemPrintingService), pdfRender (RenderResult or new type)	SAC::PRINT::FR-0003; goal.md § Desired Changes
3	Per-call batch splitting: When a template group exceeds the per-call limit, split into sub-batches and call Documint sequentially per sub-batch.	item (ItemPrintingService)	SAC::PRINT::FR-0007, FR-0008; SAC::PRINT::0002::0007.FS; #519
4	Per-request limit enforcement: Reject requests exceeding total item count limit before any Documint calls.	item (ItemPrintingService)	SAC::PRINT::FR-0009, FR-0010; SAC::PRINT::0002::0008.FS; #519
5	Configurable batch limits: Add maxItemsPerCall and maxItemsPerRequest to item module configuration.	item (Module.kt, application.conf)	SAC::PRINT::FR-0007, FR-0009, FR-0010
6	Configurable concurrency limit: Add maxParallelRenders to item module configuration for parallel Documint calls.	item (Module.kt, application.conf)	SAC::PRINT::FR-0002
7	Fix notes mapping (cards): In KanbanCardPrinter, map KanbanCard.notes to Documint notes field instead of item.notes.	kanban (KanbanCardPrinter)	SAC::PRINT::FR-0014, FR-0016; #815, #816
8	Fix notes mapping (labels/breadcrumbs): In ItemPrinter, verify item.notes maps to Documint notes field correctly (the bug is card-specific).	item (ItemPrinter)	SAC::PRINT::FR-0015; #815
9	Unmark as printed: Add a print event type or endpoint to transition a card from PRINTED back to NOT_PRINTED.	kanban (PrintLifecycleImpl, KanbanCardEndpoint)	SAC::PRINT::FR-0012; SAC::PRINT::0003::0002; #595
10	Debug payload return: When debug=true, include the constructed Documint payload in the API response alongside the normal result.	item (ItemEndpoint, ItemPrintingService), pdfRender (PdfRenderService)	SAC::PRINT-DX::FR-0003, FR-0004, FR-0005; #762
11	Dry-run mode: When dry-run=true, construct payload but skip Documint call. Return payload without side effects.	item (ItemEndpoint, ItemPrintingService), pdfRender (PdfRenderService)	SAC::PRINT-DX::FR-0006, FR-0007, FR-0008, FR-0009; #792
12	Live-print parameter passthrough: Already implemented in endpoints but needs documentation alignment and consistent defaults.	item (ItemEndpoint), pdfRender (PdfRenderService)	SAC::PRINT-DX::FR-0001, FR-0002

Changes 1-6 are the bulk of the new work (multi-template grouping and batching). Changes 7-9 are bug fixes. Changes 10-12 are diagnostic capabilities. The pdfRender module needs minimal changes (primarily to support debug/dry-run passthrough); most work is in item and kanban.