# The concept of Report History Records Every render request tells VeloxFactory what to produce. A `ReportHistoryRecord` remembers exactly what was asked for, what came back, and what the result looked like, permanently, until you decide otherwise. It is the foundation for traceability, debugging, and on-demand reprinting in VeloxFactory.

**Screenshot placeholder:** `report-history-record.index.filtered.png` Report History Record overview with filters applied and status badges.

---

### What Gets Stored A `ReportHistoryRecord` is created at render time when `createHistoryRecord: true` is set in the request, or automatically when a print task is dispatched. It captures a complete snapshot of the rendering event:

Field	Description
`traceId`	Unique identifier shared across the render request, the history record, and any linked print task. Used to correlate events in logs and across systems.
`reportConfig`	Reference to the `ReportConfig` that was rendered.
`outputType`	The output type used: `base64`, `url`, or `none`.
`apiPayload`	The complete render request body: parameters, data, flags, everything sent to the render endpoint. Stored as JSON.
`apiResponse`	The complete API response returned by VeloxFactory, including any errors and, unless the render was laconic, the input it actually worked with. Stored as JSON.
`reportPdf`	The rendered PDF, Base64-encoded. Present on successful renders; `null` on failure.
`reportPdfFileName`	The UUID-based filename assigned to the rendered PDF.
`reportExcelFileName`	Filename of the xlsx export, present when a mailing asked for one. The file hangs on the record, is downloadable from it and is deleted with it.
`reportThumbnail`	A thumbnail image of the first page of the rendered PDF. Generated asynchronously in the background after the record is created.
`status`	Automatically calculated from the stored response. See below.
`reportPrintTasks`	Every print job dispatched from this record, with printer, copies and status. A record can hold any number of them.
`reportMailTasks`	Every mail sent from this record, with recipients, subject, the rendered body and the attachment names.
`audit`	Who created the record and when, who last updated it, and which API token was used in either case. VeloxFactory derives `creationMethod` and `updateMethod` from it, `Frontend` or `API`, depending on whether a token was present on the request.

The audit block is what turns a history record into an answer to "who printed this". A render triggered by an integration carries the token it was made with, a render triggered in the browser carries the user. #### How It Comes Back from the API The record is stored in full, but a response only carries what you ask for. Four query parameters control this, and they matter, a history record with an embedded PDF is a large object:

Parameter	Default	Effect
`withApiPayloads`	`true`	Includes `apiPayloadBase64` and `apiResponseBase64`. Both are Base64-encoded, so the stored JSON survives transport unchanged.
`withMedia`	`false`	Adds the `media` block with `reportPdfBase64`, `reportPdfFileName` and `thumbnailBase64`.
`withRelations`	`false`	Adds the full `reportConfig`, plus `reportPrintTasks` and `reportMailTasks`.
`withAudit`	`false`	Adds the `audit` block described above.

Without any of them a record comes back as a compact summary: ID, trace ID, output type, status and the payloads. That is the right shape for a list view, and it is what the frontend's history overview uses.

---

### Status The status of a `ReportHistoryRecord` is calculated automatically every time the record is saved, based on the content of the stored API response:

Status	Meaning
Ok	No errors in the response and a PDF was produced. The render completed successfully.
Error	The response contains one or more errors. The render failed, the error messages are stored in the API response payload.
Render Fail	No errors in the response, but no PDF was produced either. An edge case indicating something unexpected occurred during rendering.
Unknown	Status could not be determined from the stored response.

History records are created for both successful and failed renders. A failed render still produces a complete record, including the error messages, which is often more useful than a successful one when something goes wrong.

---

### The Thumbnail When a history record is created, VeloxFactory dispatches a background job that converts the first page of the rendered PDF into a thumbnail image using `pdftoppm` (part of `poppler-utils`). The thumbnail is stored on the record and displayed in the history list and the report card grid, giving you an immediate visual of what was produced without opening the PDF.

ℹ️ **Thumbnail generation runs asynchronously.** The history record is available immediately after rendering; the thumbnail appears once the background job has completed. This requires the Laravel queue worker (Supervisor) to be running. If the queue is down, thumbnails will not be generated until it is back up.

---

### Traceability and Debugging The most valuable aspect of a history record is not the PDF, it is the payload. Every record stores the exact request that triggered the render and the exact response that came back. This means you can answer the following questions at any point in the future, without touching the calling application:

- What parameters were passed to this render? - What data was submitted, and which rows the report was actually filled with? - Was the render triggered via the frontend or the API? - What did VeloxFactory return, and did it succeed? - If it failed, what was the exact error message?

The `traceId` ties everything together. It is present on the history record, on any linked print task, and in the server logs. When something goes wrong in production and you have a `traceId`, you can pull the history record and reconstruct the entire event in seconds.

**Screenshot placeholder:** `report-history-record.show.png` Report History Record detail page with status, payload, PDF preview and the actions.

---

### Reprinting from a History Record A successful history record holds the rendered PDF. That PDF can be dispatched to a printer at any time, without re-rendering the report, using the dedicated print endpoint: ``` POST /api/v1/report-history-record/{id}/print ``` ```json { "printerName": "WarehousePrinter01", "numberOfCopies": 1 } ``` VeloxFactory creates a new `ReportPrintTask` from the stored PDF, assigns it a derived trace ID (the original trace ID with a short random suffix), and dispatches it to the print service. The original history record is linked to the new print task. This is useful in several scenarios: a print job failed and needs to be retried, a physical document was lost and needs to be reprinted, or a record needs to be dispatched to a different printer than the one originally used.

ℹ️ **Reprinting uses the stored PDF, it does not re-render the report.** The document produced is identical to the original. If the report template or its data has changed since the original render, those changes are not reflected in the reprint.

This endpoint is also available directly from the frontend, the history record detail view has a **Print** button that opens a modal to enter the printer name and number of copies.

**Screenshot placeholder:** `report-history-record.print.modal.png` Print dialog of a Report History Record with the printer picker and the copies field.

---

### Mailing from a History Record The same idea applies to mail. A stored rendering can be sent to anyone at any time, without re-rendering: ``` POST /api/v1/report-history-record/{id}/mail ``` ```json { "mailer": "Office SMTP", "mailTemplate": "Report Delivery", "to": ["disposition@example.com"], "includePdf": true, "includeExcel": false, "sendAsync": false } ``` VeloxFactory creates a new `ReportMailTask` from the stored PDF, gives it a derived trace ID, and sends the mail through the chosen mailer. Recipients, contact name and attachment names accept the same placeholders as a mailing in the render request, resolved against the parameters and rows stored on the record. If `includeExcel` is set and the record does not have an xlsx yet, VeloxFactory builds one on the fly and attaches it to the record. The export uses the rows the report was actually filled with, which includes the rows an SQL adapter fetched at render time: they travel back in the render response and are stored on the record, so a report that gets its data from a live connection exports just as well as one whose rows came in the request.

⚠️ **One case has nothing to export.** A render made with `laconicResponse: true` stores a response without its input segment. If that request carried no `data` of its own either, the record holds no rows, and a later export answers with a clear error instead of an empty sheet. Render with the mailing segment, or without `laconicResponse`, when an xlsx may be wanted afterwards.

In the frontend the detail view has a **Mail** button next to **Print**, opening a dialog with mailer, template, recipients, attachments and the background switch. Every mail sent from this record is listed on the record itself, and in the Mail Queue.

**Screenshot placeholder:** `mailing.history-record-modal.png` Mail dialog of a Report History Record with mailer, template, recipients, attachments and the background switch.

ℹ️ **Mailing uses the stored PDF too.** The document that arrives is identical to the original rendering. The full reference is on [Report Mailing](https://docs.veloxfactory.kiwi-software.dev/books/veloxfactory/page/report-mailing-sending-renderings-by-mail).

---

### Retention and Deletion #### Automatic Purging History records are cleaned up by the **Purge Job**, the consolidated cleanup schedule of the Job Scheduler. How long a record is kept is a retention on that schedule, editable in the frontend or through the API; an empty value switches the step off entirely. The `PURGE_HISTORY_DAYS` environment variable supplies the value the schedule is created with, nothing more. #### Deletion Constraints A `ReportHistoryRecord` cannot be deleted while any `ReportPrintTask` or `ReportMailTask` still references it. The linked tasks must be removed first. VeloxFactory provides a dedicated endpoint for the print tasks: ``` DELETE /api/v1/report-history-record/{id}/delete-all-report-print-tasks ``` This removes all print tasks associated with the record in one call. Mail tasks have their own retention on the Purge Job, which runs before the history records for exactly this reason, and they can be deleted individually from the Mail Queue. Once no task references the record any more, the history record itself can be deleted, which also removes its PDF and its xlsx from disk. #### Impact on ReportConfig Deletion A `ReportConfig` cannot be deleted while any history records reference it. This is a deliberate constraint: the history exists as a permanent trace of what was rendered using that configuration. To remove a report configuration entirely, its history records and their linked print tasks must be cleared first, either manually or by waiting for the automatic purge to run.