Printing

Feature code: SAC::PRINT

The Printing feature enables users to generate physical print materials — Kanban Cards, Shelf Labels, and Breadcrumbs — for items managed in Arda. Users select one or more items, choose the material type to print, and the system produces a PDF document via the Documint rendering service. The PDF opens in a new browser tab for the user to send to their printer.

Printing serves the daily operations of inventory management: cards travel with bins on the shop floor, labels identify shelf positions, and breadcrumbs provide compact identification strips. Each material type supports multiple template sizes to accommodate different media stocks and printers.

Personas:

• Primary: Irene Itemsworth — prints cards, labels, and breadcrumbs during initial setup and ongoing maintenance.
• Secondary: David Dealsworth — reprints cards during order processing when cards are damaged or lost.
• Secondary: Keisha Clerkson — reprints cards after receiving deliveries when restocking shelves.

Related diagnostics: Print Diagnostics covers API-level debug and preview capabilities for the Charlie Supportson persona.

---

Print Material Types

The system produces three types of printed materials, each associated with a different entity relationship and template family:

Material	Entity	Size Field	Print Endpoint	ID Type
Kanban Card	KanbanCard (child of Item)	Item.cardSize	POST /v1/kanban/kanban-card/print-card	Card Entity ID (eId)
Shelf Label	Item	Item.labelSize	POST /v1/item/item/print-label	Item Record ID (rId)
Breadcrumb	Item	Item.breadcrumbSize	POST /v1/item/item/print-breadcrumb	Item Record ID (rId)

Key distinction: Kanban Cards are separate entities with their own lifecycle (creation, state transitions, print status). Labels and Breadcrumbs are printed directly from the Item record — they have no independent entity.

---

Template Model

Each material type uses a configurable template system that maps a size enum value to a Documint template ID, column layout, and description.

Available Print Sizes

Each item stores three independent size fields — cardSize, labelSize, and breadcrumbSize — that determine which template is used when printing. The user selects a size from the available options when configuring an item. Only sizes marked as active are available for selection in the UI; inactive sizes are reserved for future use.

The available sizes and their template mappings are system configuration values determined at build time. The canonical reference is the Template Mapping Spreadsheet.

Kanban Card Sizes

Size	Description	Columns	Default	Active
X-Small	Quarter-Index	1		Yes
Small	Half-Index	1		Yes
Medium	Business Card Stock	2		Yes
Large	3 x 5	1	Yes	Yes
X-Large	4 x 6	1		Yes
Special 01	3 x 5 - Large QR Code	1		Yes
Special 02-10	(reserved)	1		No

Shelf Label Sizes

Size	Description	Columns	Default	Active
X-Small	3x1 (Label Printer)	1		Yes
Small	Quarter-Index	1		Yes
Medium	Half-Index	1	Yes	Yes
Large	3x2 (Label Printer)	1		Yes
X-Large	Business Card Stock	2		Yes
Special 01-10	(reserved)	1		No

Breadcrumb Sizes

Size	Description	Columns	Default	Active
X-Small	3 x 1 (xs Label Printer)	1		Yes
Small	3 x 1 (Label Printer)	1		Yes
Medium	3 x 2 (Label Printer)	1		Yes
Large	Business Card Stock	1		Yes
X-Large	Half-Index	1	Yes	Yes
Special 01-10	(reserved)	1		No

The Columns value determines the grid layout of the PDF: a 2-column template prints two items side by side per row, while a 1-column template prints one item per row.

Template Configuration

Each size maps to a Documint template ID, column layout, description, default flag, and active flag. This configuration is maintained in pdf-templates.json in the backend and must match the Template Mapping Spreadsheet.

Template Resolution

When a print request is received, the system resolves the template for each item based on its stored size field. If a size is not set or not found in the configuration, the system falls back to the default size for that material type (MEDIUM for labels, LARGE for cards, X_LARGE for breadcrumbs).

---

Single-Item Printing

A user prints a single item’s material from the Item Detail panel. The workflow:

1. User opens an item’s detail view.
2. User selects a print action (Print Card, Print Label, or Print Breadcrumb) from the actions menu.
3. The system sends a print request with the single item’s ID to the appropriate endpoint.
4. The backend resolves the template from the item’s size field, constructs the Documint payload, and calls the Documint API.
5. Documint renders the PDF and returns a pre-signed URL.
6. The frontend opens the PDF URL in a new browser tab.
7. The user prints from the browser’s print dialog.

For Kanban Cards, this is equivalent to printing one specific card by its Entity ID. An item may have multiple kanban cards; the user selects which card to print.

---

Multi-Item Printing

Users select multiple items from the list view and trigger a bulk print action. This is the primary workflow for initial setup (printing all cards for a new inventory area) and periodic maintenance (reprinting damaged or lost cards).

Current Behavior (Single-Template Constraint)

The backend currently requires all items in a single print request to use the same template. If items have different sizes configured, the request fails. The frontend handles this differently per material type:

• Cards: The frontend groups selected cards by cardSize and sends one print request per size group. Each request produces a separate PDF.
• Labels and Breadcrumbs: The frontend sends all item IDs in a single request. If items have different sizes, the backend rejects the request with an error.

Target Behavior (Multi-Template Grouping)

The system will group items by their configured template size and produce one PDF per group, all within a single API request-response cycle:

1. User selects multiple items and triggers a bulk print action.
2. The frontend sends all selected item IDs in a single request to the print endpoint.
3. The backend fetches the items, groups them by their print size/template, and sends one Documint rendering request per group (in parallel, up to a configurable concurrency limit).
4. The backend collects all results and returns a composite response containing one PDF URL per template group, plus any errors for groups that failed.
5. The frontend opens one browser tab per successfully returned PDF URL and displays an error notification for any failed groups.

Requirements

ID	Requirement
SAC::PRINT::FR-0001	When a bulk print request contains items with different template sizes, the system shall group items by template and produce one PDF per group.
SAC::PRINT::FR-0002	Template groups within a single bulk print request shall be rendered in parallel, up to a configurable maximum concurrency limit.
SAC::PRINT::FR-0003	The bulk print response shall contain one result entry per template group, each with the template ID and PDF URL on success, or an error description on failure.
SAC::PRINT::FR-0004	A failure in one template group shall not prevent other groups from being rendered and returned.
SAC::PRINT::FR-0005	The frontend shall open one new browser tab per successfully returned PDF URL.
SAC::PRINT::FR-0006	The frontend shall display an error notification for each template group that failed, identifying the template and the error.

---

Batch Size Limiting

Large print requests can overwhelm the Documint rendering service. The system enforces two independent limits to protect service reliability:

Limit	Scope	Purpose
Per-call limit	Maximum items in a single Documint API call (within one template group)	Prevents individual Documint requests from timing out or exceeding payload limits
Per-request limit	Maximum total items across all template groups in a single user print request	Prevents a single user action from monopolizing the rendering service

When a template group exceeds the per-call limit, the system splits it into multiple sequential Documint calls and concatenates the results. When the total items in a request exceed the per-request limit, the system rejects the request with an error indicating the limit.

These limits are system configuration values determined at build and deploy time. They are not user-configurable. Future configurability via the system OAM console is planned but out of scope.

Requirements

ID	Requirement
SAC::PRINT::FR-0007	The system shall enforce a configurable maximum number of items per Documint rendering call.
SAC::PRINT::FR-0008	When a template group exceeds the per-call limit, the system shall split it into multiple Documint calls and produce one PDF per sub-batch.
SAC::PRINT::FR-0009	The system shall enforce a configurable maximum total items per user print request. Requests exceeding this limit shall be rejected with a descriptive error.
SAC::PRINT::FR-0010	Batch size limits shall be system configuration values. They are not user-configurable in the current release.

---

Print Status Lifecycle

Print status tracking applies to Kanban Cards only. Labels and Breadcrumbs do not have print status — they are stateless print-on-demand materials.

State Machine

The print status of a Kanban Card is independent of the card’s operational state (Available, Requested, In Process, etc.). A card can be in any operational state and any print state simultaneously.

Print statuses:

Status	Meaning
NOT_PRINTED	The card has never been printed, or has been unmarked after a failed print
PRINTED	The card has been printed and the physical card is in use. Tracks a version history of print events
DEPRECATED	The card has been printed and is still on the shop floor but should not be used in operations
LOST	The card has been printed but has been misplaced or damaged and is not usable
RETIRED	The physical card has been removed from operations

Each status transition records a print event with a timestamp and the author who triggered it.

Automatic Status Update on Print

When a card is successfully printed, the system automatically records a PRINT (or REPRINT for cards already in PRINTED status) event and updates the card’s print status. This happens server-side after the Documint API returns a successful response.

Unmark as Printed

Currently, once a card is marked as PRINTED, there is no user-facing action to reset it to NOT_PRINTED. This creates problems when a print job fails at the physical printer (paper jam, wrong media loaded) but the system has already recorded the print event.

The system will provide a mechanism to reset a card’s print status. The specific interaction design (button in the card management UI, bulk action, or other) will be defined in the use case phase.

Requirements

ID	Requirement
SAC::PRINT::FR-0011	The system shall automatically update a Kanban Card’s print status to PRINTED when the card is successfully rendered by Documint.
SAC::PRINT::FR-0012	The system shall provide a mechanism for users to reset a Kanban Card’s print status from PRINTED to NOT_PRINTED.
SAC::PRINT::FR-0013	Print status changes shall record a print event with timestamp and author.

---

Payload Mapping

The system constructs a JSON payload for each item being printed and sends it to Documint for rendering. The payload maps item (and card) fields to template placeholders.

Notes Fields

The system maintains two distinct notes concepts:

• Item.notes: General-purpose notes on the item record. Typically contains order history, administrative annotations, or free-text descriptions. This is the notes field displayed when printing Labels and Breadcrumbs.
• Item.cardNotesDefault: Default notes for new Kanban Cards created from this item. Provides the initial value for KanbanCard.notes when a card is created.
• KanbanCard.notes: Per-card notes that can evolve independently from the item. Gets its initial value from Item.cardNotesDefault ?: Item.notes but can be edited independently per card. This is the notes field displayed when printing Kanban Cards.

The backend has intelligent sync logic: when an Item is updated, if a card’s notes still match the previous Item defaults, they auto-update to the new defaults. If the card’s notes have been independently edited, they are preserved.

Note

The frontend does not currently expose a UI for editing KanbanCard.notes independently of the Item. The backend API endpoint exists (PUT /v1/kanban/kanban-card/{eId}/notes) but is not wired to any UI component. Adding this UI is out of scope for this project.

Correct Mapping

Documint Field	Kanban Cards	Labels	Breadcrumbs
notes	KanbanCard.notes	Item.notes	Item.notes
card_notes	Item.cardNotesDefault	Item.cardNotesDefault	Item.cardNotesDefault

Requirements

ID	Requirement
SAC::PRINT::FR-0014	When printing Kanban Cards, the Documint notes field shall contain KanbanCard.notes.
SAC::PRINT::FR-0015	When printing Labels or Breadcrumbs, the Documint notes field shall contain Item.notes.
SAC::PRINT::FR-0016	When KanbanCard.notes is null or empty, the Documint notes field for cards shall be an empty string. Notes from other sources (order history, item notes) shall not leak into the card print output.

---

Summary

Aspect	Detail
Feature code	SAC::PRINT
Requirements	SAC::PRINT::FR-0001 through SAC::PRINT::FR-0016
Use cases	SAC::PRINT::0001 (5 scenarios), SAC::PRINT::0002 (8 scenarios), SAC::PRINT::0003 (5 scenarios)
Cross-cutting dependencies	REF::ITM (Item entity, size fields), RES::KAN (Kanban Card entity, print status)
Personas	Irene Itemsworth (primary), David Dealsworth (secondary), Keisha Clerkson (secondary)
Related features	Print Diagnostics (API-level debug for Charlie Supportson)

---